Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
The following describes each major component in Exhibit and how they tie together.
DOM based creation
Two methods for creating every component are required, either from the DOM
createFromDOM or from JS objects
create. The JS object methods are a bit theoretical and are rarely used within Exhibit itself, but if you need to write an extension that doesn't or can't make its components DOM based, there is a way. Do note, however, that many components use jQuery events to bind and trigger with, and jQuery requires the DOM to do so, and several components have a member variable that is its corresponding DOM Element.
To keep from leaking memory, all components associated with the UI also have a
Collections sit atop the database as a defined subset of items from within the database. There is likely no need to know about implementing a
Collection, but its exposed API is extremely important for almost any other component.
Collections can mask much of the database operation but familiarity with the database API is still necessary for writing
Views and some
Widgets require knowledge of the
UI / UI Context
UI Context ties together
Lenses. There can and probably will be several
UI Contexts in an Exhibit, with one root
UI Context that other child
UI Contexts point to. Most components will create their own
UI Context in the course of being initialized, also pointing to the parent
UI Context. This is predominantly a way to properly nest UI / DOM elements within a
Collection, which isn't itself a graphical component or a DOM container element. Most methods concerning components will contain an argument of type
UI Context so the method can apply correctly based on the
UI Context's settings.
Facets are primarily associated with
UI Context. They can make use of a
FacetUtilities.Cache to generate an index evaluating the facet expression against the
Collection in the
Database. This masks the need to know much about the
Database API, though some methods, usually dealing with object retrieval for a subject-property, is needed. A
Facet builds its own UI, interprets UI interaction for UI changes, interprets interaction for building facet restrictions, notifies its
Collection of any changes, and listens to the
Collection for any changes there. In this sense,
Facets are inextricably tied to
Collections; in fact, a
Collection can act as a
Facet for another Collection`.
They implement four main methods for modifying the current
clearAllRestrictions. They implement one main method for taking instruction from the
Facets communicate in terms of
Collection is initialized with a
Database items, and the
Facet begins with an initial
Set of valid values and a default
Set of selected values (empty by default) where applicable - search, e.g., does not fit this paradigm. Changes to the
Facet add or remove from its selected value
Set, including the special case of missing values. The
Facet can answer for which items match its own restrictions, passing the
Set of matching items back to the
Collection takes all facet responses, then passes the
Set of all matched items to all restrictions back to each
Facet, which update their UI accordingly.
Facets do state-changing actions through the
History module to enable undo and redo features. UI should register interactions through jQuery to capture actions and pass them through.
There are some helper functions, especially those in
FacetUtilities, which help build the UI and maintain a values cache, but because
Facets can range so widely in operating axes, much of the heavy lifting must be written into each
View Panel provides UI and functions for selecting a
View. Internally, it is responsible for constructing a view along with its own UI. There is likely little need to implement the
View Panel, and its one method of interaction is to selectView based on the index of the
View. NB, the
View Panel is the exception that does create views based on their non-DOM method; this is because the views are parsed but not instantiated in the DOM until they're ready for display. Reparsing to create from the DOM each time would be wasteful.
View displays a
Collection to the user through the UI. A
View should ideally having various authoring settings that can be fed to the
SettingsUtilities to build up into parsers and accessors. The
View builds its own UI with some templating help. It should have an instance of a
Lens Registry to keep track of any
Lenses defined within the
Views operate on a paradigm of ab ordered list of items, for which there is an
Ordered View Frame to assist, which does the ordering and provides UI for changing the ordering and pagination, if enabled. The
Ordered View Frame requires keeping track of state through the
History module. Some
Views may benefit by displaying
Widgets like the
Toolbox, for exporting to data.
Building a new ordered
View requires knowledge of the
Ordered View Frame API and the templating library. If the
View gets away from the
Ordered View Frame API and can't use it, knowledge of
History, and the
Database, are all required. Since the
View brings everything together, creating a
View requires knowledge of almost everything in Exhibit.
Lens Registry centralizes associating item types to their display template (or
UI Context. There is little need to implement another
Lens Registry, though the API is used by views and by the single-item focus display to choose and generate the appropriate
Lens. There is likely little need to be familiar with its API, it is provided by Exhibit's internal mechanics.
Likewise, the implementation of the
Lens and its API are primarily internally focused.
Lenses are meant to be interfaced with primarily by a lens designer, developers can leave it to Exhibit's internal mechanics.
Coders bin object values according to the
Coder's schema, providing users a potentially helpful visual classification for related items. Color, size, and icon are provided by default. The
Coder basically stands alone, its chief function to
translate a value into the appropriate matching bin. Some knowledge of
Sets is required to
translateSets of values.
Formatters take in something from the database, perhaps a set, an item, or a value, and put out a string according to the type of value being passed in. A
Formatter operates within a
UI Context, and the
UI Context provides settings for format values and syntax. Familiarity with
UI Context settings is needed to format consistently and according to the author's use.
Formatters provides two methods,
formatText to take a value, which can have any type, and turn it into an appropriately formatted string, and
format, which helps put the resulting string back into the DOM for display.
Coordinator is associated with a
UI Context and helps tie view interaction together. There is likely little need to implement the
Coordinator or use its API.
Widgets are a miscellaneous category having little in common other than placing something in or modifying the UI. They may be associated with a
Collection, like the Collection Summary Widget, or they may not have anything to do with data at all, like the Logo Widget. All of the UI generation, interaction, and any functional heavy lifting will be the responsibility of the
Widget, though there are UI helpers and probably functional helpers available depending on its use.
Locale is composed of translated text, date representations, numeric standards, etc. associated with a particular written language. Exhibit uses the English locale by default but, thanks to the generous contributions of volunteers, also has several other localizations available. Contributions of new translations and language norms are encouraged and welcome.