Search (I18N enabled)

The I18N plugin creates word and tag indizes of all pages and allows you to search for tags and words. The search results are weighted and ordered by relevancy scores. Pages with the same score are ordered by date (newest first).

It works together with the I18N plugin, however, the I18N plugin does not need to be installed.

Installation

Download the plugin from http://get-simple.info/extend/plugin/i18n/82/ and unzip it to the plugins directory of your GetSimple installation.

Usage

Go to the Plugins/Configure I18N Search/Settings page of your GetSimple administration and configure your preferred settings.

Create a page "search" and insert the following text:

(% searchform %)
(% searchresults %)

You can also include a search result in the template to e.g. include news (here the latest pages tagged with news):

<?php get_i18n_search_results(array('tags'=>'news','words'=>' ',
             'max'=>3,'numWords'=>10,'HEADER'=>null)); ?>

Make sure to set both tags and words to a non-empty string, for the parameters see your Plugins/Configure I18N Search page of your GetSimple administration.

Customization

All relevant information can be found on the Plugins/Configure I18N Search page of your GetSimple administration.

Examples:

  • To limit the search to specific pages, you can add a tag to be used during search:
(% searchresults addTags=product %)

  • If you use the I18N plugin, but only have one language, you can add the parameter i18n=0 to remove the language from the links:
(% searchresults i18n=0 %)
  • (2.6+) You can also add the virtual tag _parent_slug to limit the search to pages with a specific parent page, e.g. here to the children of page products:
(% searchresults addTags=_parent_products %)
  • (2.8+) You can also use the virtual tags _pub_yyyy, _pub_yyyymm and - if the creation date is known - _cre_yyyy, _cre_yyyymm. E.g. for all pages published in 2011 use:
(% searchresults addTags=_pub_2011 %)
  • (2.5+) You can enable live search (results are displayed as you type of select a tag), if your server is fast enough (see here for an example):
(% searchform live=1 %)
(% searchresults live=1 HEADER='' %)

Parameters

Parameters for the search form:

  • slug: Slug/URL of the page that displays the results (if the search form is in the side bar or search form and results are on different pages), e.g. search
  • showTags: Show tag cloud
  • minTagSize: Minimum tag size in percent of font size
  • maxTagSize: Maximum tag size in percent of font size
  • ajax: A value of 0 will switch off the AJAX functionality of the search form and tag cloud.
  • live: A value of 1 will switch on live search, displaying search results while selecting tags or typing words. You must set it for both the search form and the search result
  • GO: Search button text
  • PLACEHOLDER: Place holder text for search input field

Parameters for the search results:

  • live: A value of 1 will switch on live search, displaying search results while selecting tags: or typing words. You must set it for both the search form and the search result
  • tags: Tags (key words) to search for (instead of the submitted tags), separated by blanks. If you have a multi-word tag, replace its blanks with _
  • words: Words to search for - instead of the submitted words
  • addTags: Additional tags to be added to the search request
  • addWords: Additional words to be added to the search request
  • lang: If given, only results in this language will be returned, otherwise results in all languages of the user and the default language will be returned. E.g. "de"
  • order: Order of results: url = by slug/URL ascending, reverseurl = by slug/URL descending, date = by publishing date descending, created = by creation date descending (if available), default is by score descending. You can also specify a (special/custom) field name and optionally prefix it with '-' for reverse order.
  • max: Maximum number of results to show on one page
  • numWords: Number of words in excerpts (0 = none, -1 = whole content)
  • showLanguage: Show language of result entry (useful only on multilanguage sites)
  • showDate: Show publish date of result entry
  • showPaging: Show a page navigation, if there are more results
  • component: A component which is called for each search result
  • idPrefix: If you set this parameter, each search result will get an id with this prefix and a increasing number
  • tagClassPrefix: If you set this parameter, all tags will be added as CSS classes - prefixed with this value - to the search results. You can use this to style the results based on tags.
  • process, parameter: post-processing of the results, calls the process function with the results as first and the parameter as second parameter and uses the returned value as results, e.g. define <?php function skip($results, $parameter) { return array_slice($results, $parameter); } ?> in your template and use to skip the first 2 results.
  • HEADER: Header for search results, use for no header
  • NOT_FOUND: Message that no results were found
  • DATE_LOCALE: Locale to display the dates or multiple locales separated by comma, e.g. "de_DE.utf8,de_DE,de"
  • DATE_FORMAT: Date format, as specified for the PHP function strftime, e.g. "%A, %d.%m.%Y - %H:%M"
  • FIRST_TEXT: Paging, e.g. "<<"
  • FIRST_TITLE: Paging, e.g. "First page"
  • PREV_TEXT: Paging, e.g. "<"
  • PREV_TITLE: Paging, e.g. "Previous page"
  • NEXT_TEXT: Paging, e.g. ">"
  • NEXT_TITLE: Paging, e.g. "Next page"
  • LAST_TEXT: Paging, e.g. ">>"
  • LAST_TITLE: Paging, e.g. "Last page"

The all uppercase parameters are normally read from the language files of the plugin. Thus it is recommended to create or modify a language file (in /plugins/i18n_search/lang/) instead of using these parameters.

Marking the search terms

(2.9+) In the I18N Search Settings you can switch on marking the search terms on the pages. In this case you should add a rule like the following to your CSS file:

span.mark { background-color: yellow; }

You should also replace <?php get_page_title(); ?> with:

<?php echo i18n_search_mark(return_page_title()); ?>

The search terms will be marked, when you access a page from the search results page or from Google or Bing.

Attention: Currently this only works, if you have switched on Fancy URLs and the search page URL does not contain any parameters.

The FAQ plugin (version 1.1+) will automatically open all questions/answers containing the search terms.

API

Public functions:

  • return_i18n_search_results($tags=null, $words=null, $first=0, $max=10, $order=null, $lang=null)
    returns the search results $results as an associative array with the elements described below. The params are described on the plugin's configuration page in the GetSimple administration.

    • totalCount: number of total entries the search yielded, e.g. $results['totalCount']

    • first: zero-based index of the first entry, i.e. 0 for the first page, normally the same as the parameter $first, e.g. $results['first']

    • results: the entries of the search on the current page (if $max > 0) or all entries (if $max <= 0) as an array of objects each with the attributes url, parent, title, pubDate (UNIX timestamp), creDate (if used with I18N Custom Fields or I18N Special Pages), content (if numWords < 0), score (the higher, the better) and any other custom fields. To access the fields use e.g. foreach ($results['results'] as $entry) echo $entry->content; You can also get an excerpt by calling e.g. $entry->getExcerpt($entry->content, '20'), where '20' is the length in words and you could also use '1p' to specify one paragraph or '100c' to specify 100 characters. You can also get an excerpt of any other (custom) field.

  • return_i18n_tags()
    returns an ordered array, where the key is the tag and the value is an array of urls (slugs) using that tag. Tags starting with "_" are ignored.

Display functions:

  • get_i18n_search_results($params)
    outputs the search results. params is an associative array and includes keys like tags (to search for), words (to search for), max (number of results to display), ... If no tags or words are given they are taken from the request parameters tags and words. A $param['numWords'] < 0 will output the whole content of the page.
  • get_i18n_tags($params)
    outputs the ordered tags in spans with class "tag" and a font-size proportional to the percentage of pages using it (within the percentage range specified by the $params['minTagSize'] and $params['maxTagSize']). Tags starting with "_" are ignored. If you specify as a parameter 'slug' the search result page, the tags will be rendered as links to a result of a search for this tag.
  • get_i18n_search_form($params)
    outputs a search form. $params['slug'] is the URL of the result page.