Frontend and SDK
To use the SDK, make sure it is ready for use. Use the code example below for this:
SDK events
SDK events are fired at the corresponding stages of the template's life. Some of the events can take responses and, based on them, make changes to the template
Any event is fired as follows:
Every event is fired for a certain template, so every "eventParameters" contains the base values:
The "init" event
This event notifies that the template has already been generated in the needed place on the page, and also that the functions related to this particular template are ready to be called via the SDK
The "prerender" event
This event is fired for every template structure item, during the template's generation and in the subsequent updates of its various parts
The following values are additionally passed to "eventParameters":
The dictionary the "entities" function returns is made of the keys the template elements add. Each key is added by the element whose description names it, and from there on the key is in the dictionary for every template structure item nested in that element. The possible keys:
"filter" - the filter: its "id" and "type" from "filters" of the Settings API response together with the keys of its field from "fields"
"filterOption" - the filter option, in the format of a field option of the Settings API response
"appliedFilters" - the list of all applied filters. Each of its items is a dictionary with the "appliedFilter" and "appliedFilterOptions" keys
"appliedFilter" - the applied filter, in the format of the "filter" key
"appliedFilterOptions" - the list of this filter's applied options, in the format of field options of the Settings API response. Absent for filters of the "Numeric" type
"appliedFilterOption" - one applied filter option, in the format of a field option of the Settings API response
"appliedFilterNumber" - the number of a filter of the "Numeric" type, as typed: the exact number, the minimum or the maximum
"sortOptions" - the list of sorting options, in the format of the sorting options of the Settings API response
"paginationItems" - the list of pagination items. Each of its items is in the format of the "paginationItem" key
"paginationItem" - one pagination item. The "itemType" key has the "page" value for a page number (the number itself is in the "page" key) or "ellipsis" for a separator
"object" - the search result object, in the format of an object of the Results API response
"objectSelector" - the option of the object's selector field the "Object field: Selectors" element is shown for: its identifier and label
"image" - the link to the image
Custom html can be returned as a plain string or as a Node. This function can be asynchronous. The "html" parameter can also be modified, but then no value needs to be returned, it is enough to apply the changes:
There are events that notify about applying a new value of the results display parameters. To "eventParameters" of each such event the "value" value is additionally passed - the new applied value:
The "filters" event
This event notifies about applying new filter values. The "value" value corresponds to the result of the "filtersApplied" function
The "sort" event
This event notifies about applying a new sorting value. The "value" value corresponds to the result of the "sortValue" function
The "page" event
This event notifies about applying a new page value. The "value" value corresponds to the result of the "pageValue" function
The "limit" event
This event notifies about applying a new value of the number of shown results. The "value" value corresponds to the result of the "limitValue" function
The "view" event
This event notifies about applying a new results view. The "value" value corresponds to the result of the "viewValue" function
The "scroll" event
This event is fired right before the page is scrolled up after applying new filters, sorting, page, number of shown results or results view - only when scrolling is enabled in the template settings and the target is found on the page. The following values are additionally passed to "eventParameters":
A new scroll position can be returned as a number (px from the page top), e.g. to take a custom header into account. The function must be synchronous. If a non-number is returned, the default position is used. The page is only ever scrolled up - if it is already above the returned position, it stays in place:
SDK functions
SDK functions have to be called manually when needed. Their task is to return data or to perform the corresponding actions for one template only
Any function is called as shown below. The "functionTemplate" parameter - the template's identifier, passing it is not required, if the value is not passed, the function is applied to the first initialized template that was generated on the page:
Calling functions for a template is available only after the "init" event has been fired. Below is the piece of code that guarantees that the function call actually happens:
The "filtersApplied" function
This function returns the applied filter values for a certain template. If filters are not set up in the template - "undefined" is returned
The "filtersCurrent" function
This function returns the selected but not yet applied filter values (if there are any) for a certain template. If filters are not set up in the template - "undefined" is returned
The "filter" function
This function applies the passed values to the filters. The dictionary passed to the function must contain the filter identifiers, and depending on the filter type each identifier must be of a certain format
A filter of the "Checkboxes" type - an array of the identifiers of the options to apply. All values must be passed as strings
A filter of the "Radio buttons" type - a string with the identifier of the new value. If an empty value needs to be set - an empty string is passed
A filter of the "Numeric" type - a dictionary with the keys "value", "min", "max", whose values must be passed as strings, if an empty value needs to be applied - an empty string must be passed. It is not required to pass all keys with values, only those that need to be applied
A detailed example of the dictionary passed to this function can be obtained with the functions: "filtersApplied" and "filtersCurrent"
The "sort" and "sortValue" functions
The "sort" function applies the passed sorting value. The value is a string with the identifier of a sorting option
The "sortValue" function returns the current sorting value for a certain template. If sorting is not set up in the template - "undefined" is returned
The "page" and "pageValue" functions
The "page" function applies the passed page value. The value is the page number, or a string with this number
The "pageValue" function returns the current page value for a certain template. If pagination is not set up in the template - "undefined" is returned
The "limit" and "limitValue" functions
The "limit" function applies the passed value of the number of shown results. The value is a string with the identifier of the corresponding option, an example of which can be obtained with the "limitValue" function
The "limitValue" function returns the current value of the number of shown results for a certain template. If pagination is not set up in the template - "undefined" is returned
The "view" and "viewValue" functions
The "view" function applies the passed results view. The value is a string with the key of the view, an example of which can be obtained with the "viewValue" function
The "viewValue" function returns the current results view for a certain template. If views are not set up in the template - "undefined" is returned