Architectural overview

AJAX Solr loosely follows the Model-view-controller pattern. The ParameterStore is the model, storing the Solr parameters and, thus, the state of the application. The Manager is the controller; it talks to the ParameterStore, sends requests to Solr, and delegates the response to the widgets for rendering. The widgets, along with any theme functions, are the views, each rendering a part of the interface.

Manager

The Manager takes as a parameter either solrUrl – if talking to Solr directly – or proxyUrl – if talking to Solr through a proxy. (Usually, you want to talk to the instance through a proxy, so as not to expose the Solr instance to the Internet.) solrUrl must be the absolute URL to the Solr select servlet, or equivalent.

The servlet or the proxy should modify Solr parameters to prevent DOS attacks (by restricting rows to a reasonable maximum) and prevent the release of sensitive data (if Solr stores sensitive data).

Manager = new AjaxSolr.Manager({
  solrUrl: 'http://example.solrstuff.org/solrjs/select',
});

The ParameterStore and the widgets attach themselves to the Manager with the setStore and addWidget methods, respectively. The Manager is, effectively, a container for all AJAX Solr object instances.

Manager.setStore(new AjaxSolr.ParameterStore());

Manager.addWidget(new AjaxSolr.AbstractWidget({
  id: 'identifier',
  target: '#css-selector'
}));

Once these are attached, the Manager’s init method is typically called, to initialize AJAX Solr. init also calls the init methods of the ParameterStore and widgets:

Manager.init();

Having initialized AJAX Solr, the Manager’s doRequest method is typically called, to send the first request to Solr:

Manager.doRequest();

doRequest calls each widget’s beforeRequest method, in case any widget wishes to perform some action before the request is sent to Solr, e.g. display a throbber. It then calls the executeRequest abstract method to send the request. AJAX Solr is JavaScript framework-agnostic; it only requires an AJAX implementation to send requests to Solr. AJAX Solr is distributed with a Manager.jquery.js file, which implements the executeRequest method using jQuery. Once the Manager receives a response from Solr, it caches the JSON response in its response property, and calls each widget’s afterRequest method, in which widgets will inspect the response and update the interface accordingly.

Note that all the above code should only be run once the DOM is ready.

ParameterStore

The ParameterStore holds the state of the application.

Widgets

Widgets inspect the JSON response retrieved from Solr by the Manager and update the interface accordingly.

AbstractWidget is the base class from which all other widgets inherit.

Theming

Inheritance

You can easily take an existing widget and extend its functionality by writing a new widget class that inherits from the existing widget class. To inherit from any class in the AjaxSolr namespace, write:

AjaxSolr.ChildClass = AjaxSolr.ParentClass.extend({
  /* key/value pairs */
});

If you are not adding a significant amount of functionality to a parent widget, instead of creating a new widget class, you may instead choose to override or add to the parent widget’s properties during initialization:

Manager.addWidget(new AjaxSolr.PagerWidget({
  innerWindow: 1,
  renderHeader: function (perPage, offset, total) {
    /* override a method defined on the parent widget */
  },
  beforeRequest: function () {
    /* implement a method not defined on the parent widget */
  }
}));

File hierarchy

• core/ includes all framework-agnostic managers, parameter stores, and abstract widgets.
• managers/ includes all framework-specific managers.
• widgets/ includes all framework-specific widgets.
• helpers/ includes optional theme functions.

Each JavaScript “class”, e.g. AbstractManager, is defined it its own file.

Every AJAX Solr class, method, and property is implemented within the AjaxSolr namespace.