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 returnstrue
if the results have been loaded, andfalse
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:
- The current results are hidden,
- The loading message is shown, and
- 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.
- The user searches for something, but nothing matched the
search. In this case the HTML with the
gs-search-failed
class will be shown. - 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. |