-
Notifications
You must be signed in to change notification settings - Fork 46
Component Overview
The following describes each major component in Exhibit and how they tie together.
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 dispose method.
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 Collection-based extensions. Facets and Views and some Widgets require knowledge of the Collection API.
The UI Context ties together Collections, Formatters, and 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.
Exhibit Facets are primarily associated with Collections and 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 View: hasRestrictions, applyRestrictions, restrict, and clearAllRestrictions. They implement one main method for taking instruction from the Collection: update.
Collections and Facets communicate in terms of Sets. The Collection is initialized with a Set of 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. 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 Facet implementation.
The 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.
A 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 View.
Some 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 View-oriented 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 Collections, Lens creation, Formatters, Sets, History, and the Database, are all required. Since the View brings everything together, creating a View requires knowledge of almost everything in Exhibit.
The Lens Registry centralizes associating item types to their display template (or Lens) per 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.
Otherwise, the 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.
The 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.
A 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.