Backbone Forms Module

Overview

The OpenHMIS Backbone Forms Module is a collection of JavaScript libraries, REST Module extensions, and extensions to the Backbone and Backbone Forms libraries that facilitate building dynamic JavaScript UIs to interact through OpenMRS's REST interface.

Resources

Module Download: https://addons.openmrs.org/#/show/org.openmrs.module.openhmis-backboneforms
Source Code: https://github.com/OpenHMIS/openmrs-module-openhmis.backboneforms
API Documentation: http://openhmisafrica.org/doc/js/

Generic Models

The "generic" models are extensions of the Backbone Model and Collection classes that add extra features useful for interacting with OpenMRS.

GenericModel

This class functions in mainly the same way as a Backbone Model, with a couple extra features:

Meta Map

GenericModels can (read usually do) specify a meta map or object that specifies extra details about the Model such as its name and URL, which are used to generate string descriptions of the Model and determine REST URLs for fetching, saving, etc.

Schema

The Model's schema describes the standard attributes of the Model and is used by Backbone Forms to automatically generate HTML forms for adding and editing the Model, as well as during JSON serialization. The schema helps to define the type of data that is expected from the server, and what data the server expects when making client-side requests.

Here is an example of a more advanced Model with meta and schema defined:

openhmis.Bill = openhmis.GenericModel.extend({
	meta: {
		name: "Bill",
		restUrl: "v2/cashier/bill"
	},

	schema: {
		billAdjusted: { type: "Object", objRef: true },
		cashPoint:    { type: "Object", objRef: true },
		lineItems:    { type: "List", itemType: "NestedModel", model: openhmis.LineItem },
		patient:      { type: "Object", objRef: true },
		payments:     { type: "List", itemType: "NestedModel", model: openhmis.Payment},
		status:       { type: "Text" }
	},
	...
}

Specifying Model name and URL: As you can see, the name is defined in the meta map so that generic views know how to describe this Model when it is displayed. restUrl is also defined to make it easy to figure out the resource URL.

Model properties: Each property defined in the schema should have a type, following the available types in the Backbone Forms library. In this example, we have a type as simple as "Text" which will be serialized as a string. The "Object" type indicates a property that should be serialized as an object or map, and a "List"-type property will be serialized as an array. See Schema Definition from the backbone-forms documentation for built-in options.

Referencing an existing object: Of note in this example is the objRef designation of certain properties. This is an OpenHMIS extension (handled in GenericModel) to the schema which allows an object-type property to be serialized as a unique identifier string that references an existing object (the REST interface handles resolving the UUID string to the appropriate existing entity). This saves the trouble of serializing the entire representation of the existing object. The objRef option can also be enabled on a property that is a list of objects, in which case the property will be serialized to a list of UID strings.

OpenMRS-specific Model operations: The GenericModel includes helper methods to perform OpenMRS-specific Model operations such as (un)retire and purge.

GenericCollection

This class extends the Backbone Collection, providing a few extra facilities for dealing with OpenMRS objects.

Here is an example of using GenericCollection to fetch a list of bills from the REST interface:

var bills = new openhmis.GenericCollection([], { model: openhmis.Bill });
bills.fetch();

When instantiating a Backbone Collection, the first argument is a list of Models with which to initialize the collection. In many cases, we don't know what items are in the collection until we query the server, so we would pass in an empty list. The next parameter is a map of options for the collection. In the above example we specify the Bill Model. Since this Model has a restUrl specified in its meta map, the GenericCollection's url property will automatically be set up to use the Model-specific URL.

Resource URL: The GenericCollection provides several ways of determining the URL for resources when updating from the server. See the GenericCollection tests for a set of examples.

Generic Views

Generic views take care of many of the common, "boilerplate" operations for objects such as add/edit view, displaying a list of objects, paging, etc.

GenericAddEditView

The GenericAddEditView can be used to add a new object to a Collection or to edit an existing object. The view generates the add/edit form based on the schema of the current Model. GenericAddEditView requires a Collection option to be properly instantiated. Here is an example of setting up a GenericAddEditView:

var addEditView = new openhmis.GenericAddEditView(
    {
        collection: new openhmis.GenericCollection([], { model: openhmis.Bill })
    }
);
 
addEditView.render();
addEditView.$el.appendTo($("body"));

beginAdd method: Switch to "add" mode—prepare a form for adding a new object.

edit method: Takes a Model parameter—render a form for editing the passed Model.

GenericListView

GenericListView will render a list of Models in a Collection. The features of GenericListView include:

Default, custom, or no title
Hide list if empty
Specify the list of Model attributes to display as columns in the list
Built-in pagination support
Filter by retired/voided
Ability to override default item View
Ability to override the schema of the Collection's Models
Ability to choose item "actions"

Here is an example of how to instantiate a GenericListView:

var listView = new openhmis.GenericListView({
	model: new openhmis.GenericCollection([], { model: openhmis.Bill }),
	title: "My Custom List",
	listFields: ["cashPoint", "patient"]
});
 
listView.render();
listView.$el.appendTo($("body"));

View Options

Please see the API documentation for a list of supported options. What follows is some extra detail on the more nuanced options.

itemActions: A list of "actions" to enable for items in the list. Often a user will want to perform an action on an item directly from the list view, such as deleting the item. The GenericListView supports two: "remove" and "inlineEdit"

remove: Enables a remove/delete action for each item in the list.

inlineEdit: Enables the ability to edit the values of the attributes of items displayed in the list.

schema: By default the schema from the Model of the list's Collection is used to determine how to display the attributes of the list items, or the editor to use to edit them, in the case that the inlineEdit action is enabled. In order to avoid having to modify the Model's schema to suit the list display, it is possible to override part or all of the Model schema using this option.

Events

itemSelect: When an item in the list is selected, the View will fire an "itemSelect" event with the view of the selected item as a parameter.

FetchHelpers

GenericListView has a property called fetchable which is an optional list of views or objects that implement the FetchHelper "interface"—that is they implement a getFetchOptions function that returns a modified options map to be used by the list view when fetching the list of objects. Examples of FetchHelpers include the PaginateView which takes care of fetching only the items on the current page, and search views such as DepartmentAndNameSearchView which filters items based on their name and department.

FetchHelpers usually fire a "fetch" event which is handled by the list view that they affect to refresh the current items.

GenericListItemView

GenericListItemView is the default View used by GenericListView to render an individual item in the list.

Events

blur: When the item loses focus (especially when using inlineEdit), the view will fire a "blur" event with itself as a parameter.

change: If the underlying model of the list item changes, the view will fire a "change" event with itself as a parameter.

focus: When the item receives focus (especially when using inlineEdit), the view will fire a "focus" event with itself as a parameter.

remove: When an item is removed from the list, the view will fire a "remove" event with the removed model as a parameter.

select: When the item is selected, the view fires a "select" event with itself as a parameter.

GenericListEntryView

GenericListEntryView is an extension to GenericListView that supports interactive, inline adding/editing of list items. See the Cashier Module's bill screen for an example.