Backbone was chosen for the Cashier module partially out of developer familiarity, but also out of the desire to create a very responsive screen for bill entry. The work on the Cashier UI will hopefully provide the basis for future responsive hospital management UIs.
The Cashier UI makes use of customized Backbone models, collections and views to support the manipulation and display of server resources in as generic a way as possible.
The openhmis.GenericModel (model/generic.js module) extends Backbone's Model class to provide support for OpenMRS-specific operations (e.g., (un)retire/(un)void, purge) as well for the REST module.
The GenericModel supports several ways of setting the URL for the server resource:
urlRoot: Manually set the full URL for the resource, overriding any settings in a collection or openhmis.config. This is an option that can be specified when instantiating a model.; for example:
restUrl and openhmis.config: Alternatively, the REST resource URL can be specified using a combination of the model's meta attribute and the openhmis namespace configuration (specified in init.js). See below for more information on the meta attribute. For example, if openhmis.config is set to_ /openmrs/rest/ and restUrl is _patient, the model's url property will evaluate to /openmrs/rest/patient(/uuid).
The meta property of a GenericModel is used to specify certain metadata about the model. Here is an example from the Bill model:
name and namePlural: The name of the model, and the pluralized name, respectively. Used by generic views for display purposes. (TODO: this could be done automatically in many cases and only be specified in exceptional cases)
openmrsType: "data" or "metadata"; certain behaviour (e.g. retire/void) changes based on this. If not given, GenericModel tries to guess.
restUrl: The name of the REST resource, which will be concatenated to openhmis.config.
The schema is used in the serialization of the model. If a schema is specified, only the attributes defined in the schema will be serialized. If no schema is specified, the model will be serialized by the default Backbone method.
Here is an example of a model schema:
This schema could also be used by backbone-forms to automatically generate a form for this model, but two attributes of the schema will affect how the model is serialized when it is saved to the server:
readOnly: Attributes marked readOnly will not be added to the serialized object that is saved to the server. This allows non-updatable attributes to be displayed in a form but not serialized during a save.
The openhmis.GenericModel (model/generic.js module) extends Backbone's Collection class to provide extra support related to the REST interface, including paging and search support.
A GenericCollection can help supply the resource URL when not available from the model.
baseUrl: Set the URL for models in this collection, overriding openhmis.config.restUrlRoot. Given as an option when instantiating a GenericCollection.
url: Set the resource name portion of the URL. This will either be concatenated to openhmis.config.restUrlRoot or baseUrl (if specified).
If no URL options are specified, the collection will attempt to discover a URL from its model attribute.
The openhmis.GenericListView (view/generic.js module) is a Backbone View that will display a GenericCollection in a list.
model: A GenericCollection to display
itemView: The view type to use to display each item in the list. Defaults to GenericListItemView.
schema: Can be specified to override the schema of the models in the collection.
listTitle: Title to be displayed for the list.
itemActions: A list of actions to enable for the items in the list. GenericListItemView supports "remove" and "inlineEdit".
includeFields: A list of attributes in the model's schema to display as columns in the list. Defaults to all the attributes in the model's schema.
excludeFields: A list of attributes in the model's schema to exclude from the list's columns.
showPaging: Whether to display pagination controls. Defaults to true.
pageSize: Set the initial number of results to show in the list.
showRetiredOption: Whether to display the option of showing/hiding retired/voided items.
hideIfEmpty: If true and the view's collection is empty, the entire list view will not be displayed. Defaults to false.