Backlinks

Structures

Plugin Custom Search

This wiki plugin is available from Tiki8 for the purpose of creating custom user interfaces to search for objects within Tiki. This plugin makes use of the functionality of PluginList to show the results of the search. This plugin is intended for rather advanced customization and you will need to have a good understanding of PluginList as well as Unified Index and good knowledge of HTML, CSS, and Smarty in order to make good use of it.

What happens when the wheel spins forever?

That is likely the sign of an AJAX failure.
If you use the Firefox Firebug plugin in the HTML Response you should be able to see what the AJAX responds with.

The wiki page on which custom JavaScript is to be executed on return of Ajax results

8.0

destdiv

text

The id of an existing div to contain the search results

9.0

searchfadediv

text

The specific ID of the specific div to fade out when AJAX search is in progress,
if not set will attempt to fade the whole area or if failing simply show the spinner

8.0

autosearchdelay

digits

Delay in milliseconds before automatically triggering search after change
(0 disables and is the default)

0

8.0

id

alnum

A unique identifier to distinguish custom searches for storing of previous search
criteria entered by users

0

8.0

forcesortmode

(blank)01

Force the use of specified sort mode in place of search relevance even when there is a text search query

1

13.0

recalllastsearch

(blank)01

In the same session, return users to same search parameters on coming back to the
search page after leaving

0

8.0

requireinput

(blank)01

Require first input field to be filled for search to trigger

0

12.0

searchonload

(blank)01

Execute the search when the page loads (default: Yes)

1

9.0

searchable_only

(blank)01

Only include results marked as searchable in the index.

1

14.1

wiki

pagename

Wiki page where search user interface template is found

8.0

trimlinefeeds

(blank)01

Remove the linefeeds added after each input which casues the wiki parser to add extra paragraphs.

0

14.1

customsearchjs

(blank)01

Mainly keeps the search state on the URL hash, but also adds some helper functions like easier sorting and page size.

0

14.1

Basic Usage

You need two wiki pages, one for the search interface itself, and the other for the template to be used at the interface. From Tiki 13 onwards, it is possible to specify a .tpl file on disk instead of a wiki page for the second wiki page.

In case you want to limit the search to content found just on a single tracker field, you need to use the tracker field unique name to refer to that field (for instance in this example: my_permanent_name). This is because by default since Tiki8, unified search uses the permanent names for tracker field names instead of field IDs. Therefore, you could change this line:

Any text: {input _filter="content" type="text" }

for this other one with _field as tracker_field_ + my_permanent_name instead:

1.1.3. Grant permission to the tpl page

You need to grant permissions to the tpl page "Custom Search Tpl" to be used as a tracker template (or a template for unified search) by anonymous or registered users (or the group of your choice). Click on permissions for that page, and change permissions accordingly. Remember to restrict edit permissions to only admin users since then to that page.

1.1.4. Enable unified search

Ensure that you have Unified search enabled, under "Control Panels > Search".

1.1.5. Rebuild search index

Rebuild your search index after you have created some content in tracker 1, so that this content can be found by the search engine through the search index.

1.1.6. Use your custom search interface

Go to page 1 to use your new custom search interface.

Notes:

Assuming you have a tracker with id 1 with some items, that should work.

In fact if you remove the line

{filter field="tracker_id" content="1"}

it will work as a search over all your content. In fact just this line on it's own in a page will work!

Working Custom Search Example

More advanced usage

{CUSTOMSEARCH(wiki="Search-tpl" id="mysearch")}
{output template="/var/www/html/templates/my-custom-searchresults.tpl" pagination="y"}
<put whatever base filters and formatting things that you would do in the LIST plugin here>
{CUSTOMSEARCH}

Note that the pagination="y" is generally required so that you have the ability to paginate across multiple pages of search results. (There is a more advanced way of specifying the pagination manually within Smarty templates explained below).

Base filters are filters that you want applied regardless of what search parameters the user chooses in the search form.

See PluginList for more information about filters and formatting of output.

Creating your search interface

Creating the wiki page

You will need to create a template to be placed in the wiki page mentioned above. In this wiki page, you need to surround the contents with smarty literal tags so that the contents don't get parsed as Smarty tags.

{literal}
<contents of template>
{/literal}

In addition, if you want to use HTML in your template, you can use PluginHTML:

{literal}
{HTML()}
<contents of template>
{HTML}
{/literal}

It is important to make sure that this page has Permissions set so that it cannot be edited by non-admins

Creating form elements

Creating form elements are similar to creating standard HTML form elements, combined with using the filter parameters found in PluginList. Specify each element using plugin syntax. If you want to use a standard HTML supported attribute, simply use it and it will appear in the resulting HTML. All internal attributes that are meant for the LIST plugin to generate the search results should start with an underscore (_), so that they don't end up in the HTML (which would be invalid). For example, if you want to create a text search field that searches for the content entered:

{input _filter="content" type="text"}

You can add any HTML supported attributes if you want, for e.g.:

{input _filter="content" type="text" class="mysearchbox"}

If you want to specify a specific field/fields to search in as described in PluginList, for example:

From Tiki 14.1 onwards custom search will automatically populate the drop-down menu for ItemLink, UserSelector and Text tracker field inputs. You need to specify the _field and _trackerId params only (to be backported to 13 & 12 when tested)

{select _field="tracker_field_myFieldPermName" _trackerId="42"}

From Tiki 19.0 (and 18.3) you can use the _operator attribute to override the site-wide preference for default boolean operator for multiple select fields.

Checkbox example:

The most important thing to keep in mind about checkboxes is that they cannot take a normal "value" parameter like in HTML. Instead, use the _value (with underscore) parameter if you want to set a value. If you do not set a value, the values searched for will by default be y (if checked) or NOT y (if not checked). If you want the checkbox to be checked by default, specify _default="y" . For example.

Categories example:

In general, if there are just a few categories to search by, you can use radio buttons or checkboxes (in the following example 24 is the category ID you want to search for when the checkbox is checked):

{input _filter="categories" type="checkbox" _value="24"}

If you want the category search to not only search the specified category but also all of its sub-categories, specify the _deep attribute:

{input _filter="categories" type="checkbox" _deep="y" _value="24"}

In addition, to facilitate creating category selection elements for many categories, there is a special way to quickly show multiple checkboxes/radio buttons or a drop-down for multiple categories based on a parent category.

Note that if you are specifying a _style of checkbox or radio, _group is mandatory.

Other parameters include _categpath which shows the full category path category labels instead of just the category name, and _showdeep which shows not just the immediate children of the parent category specified but all the sub-children as well.

When specifying multiple="multiple" there is not first blank item, you can force a blank or labelled item (has no value) by using the attribute _firstlabel.

Adding a submit button

{input type="submit"}

Grouping elements together for the purpose of OR searching instead of AND

It has already been mentioned above that Radio buttons as well as categories (those using a _style attribute of checkbox and radio) need to use the _group attribute mandatory.

However, it is possible to use the _group attribute for other types of fields as well, if you want them to be searched using OR logic instead of AND which is how different filters are combined. So long as the filters you are trying to group together are exactly the same except for the search term, they can be grouped. For example, the following searches for either "apples" or "oranges" if both checkboxes are checked:

Range searches

Before you start, please be informed that the Unified search is a string based search. In other words, if you are trying to search between 2 numbers, make sure all your numbers are of the same number of digits. Otherwise 2 will be larger than 12. The only way to get around this for now is to make sure all numbers are entered in a padded form, for example, 0012 for 12.

However, from Tiki14 if you are using Elasticsearch as the unified search engine, then numeric tracker fields are indexed internally as float and therefore will provide for correct range searches for those fields, even without padding.

The way to generate a search for a value between two values is to use the _daterange attribute to group the 2 items that you want to search in between together. The following example searches a tracker field that contains all 4-digit years.

To do a range search on things like modification dates, which are "unix timestamps indexed as dates", use _daterange instead of _textrange. This will ensure than the comparison is correct despite the string based search since these timestamps are indexed in YYYYMMDDHHMMSS format.

Since Tiki 18.3 the end date uses the end of the day, as opposed to midnight at the beginning of that day. This is generally agreed to be more intuitive, but if you need to revert to the previous behavious add a parameter _toendofday="n". For instance this will find nothing:

Single-ended range searches

Before Tiki14, the user must enter both ends of the filter for the range search for the search to have any effect. Therefore it is important to make sure the user selects a value, or a _default is set.

From Tiki14 it is possible allow for doing range searches with user only specifying one end of the range and the other end left blank but still having default value. For example, the following code will generate 2 form fields for searching the tracker field duration. If the user keeps the first one blank and enters 20 in the second field, it will search for the range 0 to 20. If the user enters 50 in the first field but leaves the second field blank, then the range searched for is 50 to 9999. Note that in each of the fields, _emptyto OR _emptyfrom must be used TOGETHER WITH _emptyother for this to work. If you leave out _emptyother, unpredictable results can occur because browsers may not submit empty form fields (and so this is the only way to get the information on the other range endpoint if it's not filled in).

Setting default search parameters when first coming to the page

As already mentioned above, you can use the _default parameter on specific fields. However, in some cases you are coming from another page where you want to pass some input from there via the query string. To do this you can pass in the query string, for example:

tiki-index.php?page=Search&default[field]=value

The "field" here is the same as what you have in the _field attribute in your search template.

If you have categories filters defined, you can set the defaults as follows:

Note that if you are having problems using square brackets within link syntax in a wiki page, you may want to urlencode the square brackets, for example:

[tiki-index.php?page=Search&defaultcat%5b7%5d=3]

Advanced adding of jquery/javascript on AJAX loading of results

This is relevant only if you are implementing an advanced template for PluginList used in conjunction with Custom Search, and it contains jquery/javascript that affects the search results.

Because in IE prior to version 9 it is not possible (due to crappy DOM handling) to deliver jquery/javascript that affect the content of the AJAX response together with the AJAX response, instead of including such scripts in the template for PluginList, you will need to include such scripts as follows:

Create a wiki page as follows, enclosing your javascript/jquery, and specify the wiki page name as the callbackscript parameter to the CUSTOMSEARCH plugin.

For sort_mode, you can also set it inside your search template. Please be warned that sorting is based on string. if you are trying to sort by numbers, make sure all your numbers are of the same number of digits. Otherwise 2 will be larger than 12. The only way to get around this for now is to make sure all numbers are entered in a padded form, for example, 0012 for 12.

{sort mode="tracker_field_18_desc"}

Changing the settings after arriving at the search page

You will need a little Jquery/javascript for this. It is possible to set the javascript variables "customsearch_<id>.maxRecords", "customsearch_<id>.sort_mode", "customsearch_<id>.offset" programmatically and then resubmit the form by calling the submit() event handler on the form using the jquery. For example:

Customizing the interface with CSS

The final step is to customize the search interface with CSS. The search results is in a DIV with the ID customsearch_<id>_form. The search form is in a DIV with the ID customsearch_<id>_results Because you can assign your own CSS classes to each of the form elements above, you can customize it anyway you like.

Using Facets

Facets are dynamic search filters provided by the search engines. They allow to refine the user's search. Not all search engines support this feature. At this time, it is only supported by the Elasticsearch implementation.

Using facets with CustomSearch requires that hidden fields be added to the search form. These fields will be filled as the user selects filters. To simplify binding, make sure you set the ID explicitly.

Facets from Categories

To use categories as facet generators, go to the search control panel, and on the "search results" tab add the categories you will need to the "Generate custom facets from categories" preference, apply that and rebuild the search index.

Add the hidden fields to your search form as above, but using this special format for the id: deep_categories_under_XXX replacing the XXX with the category id

Facet Count

Since Tiki 14 (and backported to Tiki 12.4) you can specify the maximum number of facets returned. This defaults to 10, but can be changed globally using the "Facet result count" preference on the search results control panel, or per facet in the plugin like this:

Finally, you need to modify the results template. The $facets variable is available and contains all the facets returned by the search engine. It is important to verify that the results have been provided.

In this example, Chosen is used to render the facet elements nicely and each change to a facet causes the results to reload. The registerFacet() jQuery function binds the select element to the hidden field annotated by data-for.