JavaScript

This product provides a JavaScript module as a Zope browser resource. Any Zope or Plone project should be able to use this product by placing the following line in a page template:

<script type="text/javascript"
        src="/++resource++gs-search-base-js-20160201.js"
        defer="true"> </script>

Users of other systems are invited to copy the file gs/search/base/browser/javascript/search.js out of this product.

A minified version of the script is available, too:

<script type="text/javascript"
        src="/++resource++gs-search-base-js-min-20160201.js"
        defer="true"> </script>

JavaScript API

The API is provided by the GSSearch() class.

class GSSearch(widget, ajaxPage, offset, limit, additionalQuery, advancedSearchId)
Arguments:
  • widget (string) – The selector for the HTML widget (normally an ID-selector).
  • ajaxPage (string) – The page to query to get the AJAX results (see AJAX Page).
  • offset (int) – The initial offset into the search.
  • limit (int) – The number of results to show.
  • additionalQuery (object) – Extra items to pass to the ajaxPage as part of the query. Set it to {} if there are none.
  • advancedSearchId (object) – The Advanced Search link. This will be updated to reflect the current search.
load()

The load() method makes a query and load the results. The results are not loaded during the creation of the widget because in many circumstances (such as with the Posts [1] tab with GroupServer groups) the results do not need to be loaded when the widget is created.

results_shown()

The results_shown() method returns true if the results have been loaded, and false otherwise.

Behaviour

The JavaScript binds event handlers to the three buttons in the interface: Search, Next, and Previous (see HTML). Whenever these three buttons are pressed, or the load method is called, the following occurs:

  1. The current results are hidden,
  2. The loading message is shown, and
  3. A POST request is made to the AJAX Page.

Once the request returns the loading message is hidden, the results are shown, and an event is raised.

Both the Next and Previous buttons modify an internal counter, that keeps track of the current index into the search-results, which is passed to the AJAX Page. It is always a positive number; if it is 0 the Previous button is disabled, while the Next button is disabled when the number of search-results is less than the limit that is set during creation.

There are two cases of no results.

  1. The user searches for something, but nothing matched the search. In this case the HTML with the gs-search-failed class will be shown.
  2. There is nothing to search. In this case the HTML marked with the gs-search-empty class will be shown, and the search-entry will be hidden. It is good practice to mute this HTML, because this is not an error state.

The system determines the difference between the two cases by looking at the search-entry: if it has text and the AJAX Page returns nothing then it must be the first case; else it the second.

Event

After the search-results have been loaded the search-widget will trigger a resultsloaded event. External systems may bind to this event to add functionality. For convenience [2] a constant for this string, RESULTS_LOADED_EVENT, is exported by the class.

[1]See gs.group.messages.posts <https://github.com/groupserver/gs.group.messages.posts/>
[2]Convenience, and the fact that I prefer constants to strings.