Online example and docs
Refer to http://solrjs.solrstuff.org/ to view an online example and online jsdocs. Note that both example and docs can easily be created locally using ant.
Creating the documentation
Creating the distribution
After execution of "ant dist", a "dist" directory will be created containing 2 files:
- solrjs-1.4-dev.js -> an aggregated file composed of all *.js files in the src tree in correct order.
- solrjs-1.4-dev-templates.jar -> solrjs-1.4-dev-templates.jar velocity files used by server side widgets. This jar can be put into solr/lib when needed.
Creating the reuters example
To explore the code, it's best to investigate and debug the reuters single page example locally. To achieve this, the following steps are needed:
- ant reuters-start -> starts a testsolr instance under port 8983 including the schema for reuters business articles.
- ant reuters-import -> imports the sgm files into the running testsolr
There are two base types of widgets:
- server side widgets: They move the rendering logic to the server, using the VelocityResponseWriter (see https://issues.apache.org/jira/browse/SOLR-620. The widget then only "copies" the html reponse from the server into the target div.
To make the framework more clearly arranged, the every js "class" lies inside a single JS file, they are organized in "packages" like in a Java Application:
- core: The manager and other base classes.
- server: server side widgets
- client: client side widgets
For distribution, there is a small ant build script provided taht creates one single js file out of these snippets. Just run "ant dist". In the future, there might be some js compression steps included.
Examples and source code
The best way to get an idea how a widget may look like and how it can be integrated into html is to explore the documented source code and the test*.html example pages at http://solrstuff.org/svn/solrjs/trunk. Use "ant testsolr-import" to get some testdata and "ant testsolr start" to start the included testserver.
Despite this, I'll try to describe some important implementation further on this page.
:TODO: ... is this section still relevant? solrstuff.org and explanation of building the reuters demo are already mentioned in above sections.
? ? ?
Just include the following includes in the header section of your html:
After that, all SolrJS objects are accessible using $sj.solrjs.*
The manager object
The manager object acts as "Controller" for the user input. It holds a state of the current solr query. The current query is represented by QueryItems objetcs. A query item simply is a field:value pair. A user may select or deselect multiple items. In the current work in progress, all query itemsa are concatinated using "AND" operators. More complex query generation may be implemented in the future. The manager currently provides the following methods:
- addWidget: add a new widget
- addQueryItems: add a list of field:value pairs that restrict the current query
- removeQueryItems: remove the given items from the current query
- doRequest(start): performs the actual solr requests
- doRequestAll(): clears queryItems and requests all documents
How a query request works
Every widget implements a "getSolrUrl" method and performs its own http request. It also has to provide a "handleResult" method that gets the json data response to render. So if a user changes the selection:
- manager.doRequest(startindex) is called
- a q=... parameter is created by the manager according to the current selection
- the call is delegated to all the widgets. They may extend the query url in the getSolrUrl method (eg. adding facet=true..) and then make the http call to solr.
- json or html data is returned to the widget and widget.handleResponse(data) is called.
A main goal of the implementation was to create clean easy to understand code that can be easily extended by other developers. So I introduced a small OO inheritance pattern inspired by this thread http://groups.google.com/group/jquery-dev/msg/12d01b62c2f30671 and created the factory method:
jQuery.solrjs.createClass = function(subClassName, baseClassName, subClass)
An "AbstractWidget" class is provided that acts as base class for all further widget implementations. In the source code, all methods that should be implemented by the child class are documented and marked as "abstract methods". An example syntax for a simple widget may be:
To add this widget to your html page, just create this script tag:
Example for an easily customized widget: ExtensibleResultWidget
The ExtensibleResultWidget is a showcase of a flexible widget. It provides 2 abstract methods:
Ideas for widgets
Some of this widgets will be implemented during this years Summer of Code and weill be provided alongode the framework.
- Server and client side result views.
- Facet widget for datefields using a timeline chart
- Facet widget for hierarchical fields represented as a tree (category_0, category_1,..)
- fulltext search
- autocomplete box for facet values
- Geographical selection using google maps or the like.
- Facet widgets that depend on each other
- A single document view that shows similar documents
Feel free to extend this list.