Fullscreen
[Show/Hide Right Column]

Create a custom search form for searching or listing items on the site
Print
English British

Plugin Custom Search


This plugin is available from Tiki8 for the purpose of creating custom unified search 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 Search Index and good knowledge of HTML, CSS, and Smarty in order to make good use of it.


Usage

Wiki syntax:
Custom Search
{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.


Parameter Values Description Required?
wiki wiki page name The name of the wiki page where you will be putting the search template. Yes
id alphanumeric (no spaces) A unique id so that the system can distinguish between multiple custom searches on the site. Not needed if you have only one. No
autosearchdelay integer Number of milliseconds to wait after every change in search options before automatically refreshing search results via AJAX. 0 means this feature is disabled No
searchfadediv proper HTML div ID HTML ID of the div to fade effect when loading search results, if specified No
recalllastsearch 1 or 0 If set to 1, will recall the last search made and return the user to that point when returning to the search page after leaving it No
callbackscript wiki page name The name of the wiki page where custom jquery or javascript is stored. No


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:
{input _filter="content" _field="tracker_field_20" type="text" class="mysearchbox"}
{input _filter="content" _field="tracker_field_28,tracker_field_22" type="text"}



Note how you can specify labels different from the values if you want
{select _filter="content" _options="1980,1981,1982" _field="tracker_field_104" multiple="multiple"}
{select _filter="content" _field="tracker_field_104" _options="1980,1981,1982" _labels="eighty,eighty-one,eighty-two"}

You can also set a default item to be selected using the "_default" element. To avoid the blank option from appearing, use the _mandatory attribute.
{select _filter="content" _options="1980,1981,1982" _field="tracker_field_104" multiple="multiple" _default="1980"}
{select _filter="content" _options="1980,1981,1982" _field="tracker_field_104" multiple="multiple" _mandatory="y" _default="1980"}


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.
{input _filter="content" _default="y" _field="tracker_field_58" type="checkbox"}

If you want the checkbox to behave in reverse, i.e. search for "NOT y" when it is checked and y when it is not checked, specify _value="n".
{input _filter="content" _field="tracker_field_58" _value="n" type="checkbox"}

If you want the checkbox to mean that you want to search for whatever term you want when checked, set _value to something arbitrary, for example:
{input _filter="content" _field="tracker_field_58" _value="tiki" type="checkbox"}


Radio button example:

The most important thing to remember about radio buttons is that they need a "_group" attribute. This "_group" attribute determines which radio buttons are together as a group. For example:
Version: {input _filter="content" type="radio" _field="tracker_field_20" _value="7" _group="20"} Tiki 7 {input type="radio" _filter="content" _field="tracker_field_20" _value="8" _group="20"} Tiki 8


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.
{categories _parent="10" _style="checkbox" _group="10"}
{categories _parent="22" _style="radio" _group="12"}
{categories _parent="30" _style="select" _group="12"}
{categories _parent="30" _style="select" multiple="multiple"}
{categories _parent="30" _style="select" _categpath="y" _showdeep="y"}

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:
{input _filter="content" type="checkbox" _value="apples" _group="15"} Apples
{input _filter="content" type="checkbox" _value="oranges" _group="15"} Oranges


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.


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.
Show content between {select _filter="content" _field="tracker_field_104" _options="2000,2001,2002,2003,2004,2005" _textrange="1"} and {select _filter="content" _field="tracker_field_104" _options="2000,2001,2002,2003,2004,2005" _textrange="1"}

The following example is an interesting twist, where you automatically set one end of the range through a hidden field.
Show only content after {select _filter="content" _field="tracker_field_104" _default="2000" _mandatory="y" _options="2000,2005,2010" _textrange="2"}{input _filter="content" _field="tracker_field_104" type="hidden" value="9999" _textrange="2"}

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.
Show content modified between {select _filter="content" _field="modification_date" _options="946684800,1104537600,1262304000" _labels="2000,2005,2010" _daterange="1"} and {select _filter="content" _field="modification_date" _options="946684800,1104537600,1262304000" _labels="2000,2005,2010" _daterange="1"}

Date Range Picker

In Tiki 9 there is also a date range picker you can use like this:
{daterange _field="modification_date" _from="1104537600" _to="1262304000" _showtime="y"}
{daterange _field="modification_date" _from="1104537600" _gap="31536000"}

You can also use "now" as a date. It will give you the current time/date.

You need to set a default filter in the customsearch as follows so that the user is not confused when first arriving at the page.
{filter range="modification_date" from="1104537600" to="1262304000"}
{filter range="modification_date" from="now" gap="31536000"}

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:
tiki-index.php?page=Search&defaultcat[parent]=value
e.g. tiki-index.php?page=Search&defaultcat[5]=2,7


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.
{HTML()}
<jquery/javascript goes here>
{HTML}

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


Advanced Pagination in Smarty Template

Advanced pagination not using pagination="y" but instead directly creating the pagination within the Smarty template, by specifying the customsearch ID manually as follows:
{assign var='customsearchid' value="xyz"}
{pagination_links offset_jsvar="customsearch_offset_`$customsearchid`" _onclick="$('#customsearch_`$customsearchid`').submit();return false;" resultset=$results}{/pagination_links}


Setting maxRecords, sort_mode, and offset

Overriding defaults that apply on arriving at search page

The defaults can be overridden by passing into the query string these variables. For example, if you want the number of search results to show to be set to 10, you can do:
http://yoursite.tiki.org/tiki-index.php?page=MySearch&maxRecords=10
(or with SEFURL on) http://yoursite.tiki.org/MySearch?maxRecords=10


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_maxRecords_<id>", "customsearch_sort_mode_<id>", "customsearch_offset_<id>" programmatically and then resubmit the form by calling the submit() event handler on the form using the jquery. For example:
customsearch_maxRecords_<id>;
$('#customsearch_<id>').submit();


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.


Contributors to this page: Nelson810 points  , Jonny Bradley1251 điểm  , lindon137 điểm  and Marc Laporte9146 points  .
Page last modified on Thursday 03 May, 2012 15:03:55 UTC by Nelson810 points .
The content on this page is licensed under the terms of the Creative Commons Attribution-ShareAlike License.

SourceHistorySlideshow

Site Language

Reference Guide

Keywords

These keywords serve as "hubs" for navigation within the Tiki documentation. They correspond to development keywords (bug reports and feature requests):



Tiki Newsletter

Delivered fresh to your email inbox!
Newsletter subscribe icon
Don't miss major announcements and other news!
Contribute to Tiki