Change log

Banners

Banners give you an easy way to display random banner ads, perhaps a random quote or really any other content required.

Quick Start

Searching Banner Items

Searching within Banners can be achieved with a search form and the module’s component tag configured with the isSearchResult parameter.

Simple keyword based searches can be set up as well as more advanced search forms with specific system and custom fields searchable along with range searches for date and price/number fields.

You can configure a Banner search with two parts; the search form and the module’s component tag. More on these parts below:

Component Tag with ‘isSearchResult’

To render the search results to the page and/or a collection, you need to configure the module’s component tag with the isSearchResult parameter set to true (see the Banner component documentation for technical details).

{% component type: "module", source: "Banner", layout: "List", isSearchResult: "true" %}

This will allow the component to reference search parameters in the resulting URL.

URL search parameters will override any corresponding parameters in the component. If no search parameters are present in the URL, isSearchResult will be ignored.

You may want to separate the search form from the component tag if you want a dedicated search results page, or where you have a search input in the header or footer of all pages as so searches could be made from any page.

This method also alleviates a side-effect of the isSearchResult configured component whereby it will output all indexed items by default if no search query has been specified (ie: when a user first navigates to a search page).

If you do want one single search page, with both search form and component and don’t want to initially list all results, another solution to this is to wrap the component tag in a Liquid condition which looks for the presence of the prop_KeyWords parameter in the URL, like so:

{% if request.request_url.params.prop_KeyWords %}
    {% component type: "module", source: "Banner", layout: "List", isSearchResult: "true" %}
{% endif %}

Basic Search Form

A basic keyword based search form for Banners would be constructed like the following:

<form>
    <input type="hidden" name="prop_ModuleId" value="1234">
    <label>Keywords</label>
    <input type="text" name="prop_KeyWords" maxlength="255" value="{{request.request_url.params.prop_KeyWords}}">
    <input type="submit" value="Search">
</form>

This form element includes a prop_KeyWords text input, prop_ModuleId hidden input, a submit button and no form action attribute.

The prop_ModuleId hidden input tells the search which module to search (replace ‘1234’ with the ID of your module).

The prop_KeyWords text input allows multiple keywords to be entered for searching.

The search logic combines multiple keywords with an AND operator, so items will be returned only if they include ALL keywords entered.

Currently, searching does not support any manual logic operators to be used in the keyword input field (such as; AND, OR, NOT...)

When the form is submitted, prop_ModuleId and prop_KeyWords, along with their values, will be passed as URL parameters for the isSearchResult configured component tag to interpret.

By default, the search form has no action attribute, so it will redirect to the current page with the URL parameter appended to the current page URL.

You can, instead, separate the search form from the ‘site_search’ component, having the module component on a separate page and sending the search query to that page instead of the current page.

To do this, you’d add the other page URL slug to the form element. So if the other page was “/search-results”, you’d adjust the form to include an action attribute as such:

<form action="/search-results">

Advanced Search Form

Building further on the basic form structure above, you can add Banner specific fields to search their contents, either individually or combined with other fields and/or keyword queries.

The search logic combines all field queries with an AND operator, so items will be returned only if they include ALL the queries entered.

The fields that can be search upon include:

  • Name
  • URL (Slug)
  • SKU Code
  • Release Date
  • Expiry Date
  • Site Search Keywords
  • Description
  • Any ‘Default Properties’ (eg: Categories, Tags, Author...)
  • Any ‘Custom Properties’
  • Module specific ‘System Properties’ (Price, Product Dimensions, Unit Type, Capacity...)

To add these fields to your search form, create an appropriate input with the name attribute configured like prop_PropertyName.

So, if you were adding a search field for a custom property called “Vehicle Colour”, the form input might look like this:

<input type="text" name="prop_VehicleColour">

Follow this same format for most other properties. Although you may like to change the input type to suit the type of data required.

For example, if our above “Vehicle Colour” property was actually a dropdown field with predefined colour values, you may choose to create a <select> element instead, like so:

<select name="prop_VehicleColour">
    <option value="Red">Red</option>
    <option value="Blue">Blue</option>
    <option value="Green">Green</option>
</select>

After the search form has been submitted, you might also like to keep the search queries filled in the search form fields, for better usability. So to do this you can pull the query parameters out of the URL and into the input values, like so:

<input type="text" name="prop_VehicleColour" value="{{request.request_url.params.prop_VehicleColour}}">

Search Within Number Ranges

For property types such as dates, prices and numbers, you can search with a to-from/min-max range by adding _Min or _Max to the property name.

So let’s say you want to search for items within a certain date range, based on their release/expiry dates.

<input type="datetime-local" name="prop_ReleaseDate_Min">
<input type="datetime-local" name="prop_ExpiryDate_Max">

And to populate these fields with the searched values:

<input type="datetime-local" name="prop_ReleaseDate_Min" value="{{request.request_url.params.prop_ReleaseDate_Min | date: "%Y-%m-%dT%H:%M"}}">
<input type="datetime-local" name="prop_ExpiryDate_Max" value="{{request.request_url.params.prop_ExpiryDate_Max | date: "%Y-%m-%dT%H:%M"}}">

Searching for a minimum release date will return all items with a release date newer (or the same as) the query date. And likewise searching for a maximum expiry date will return all items with an expiry date older (or the same as) the query date.

Programmatically Search (without a form)

There may be times when you require the search results for a module based on constructed data, other than that of a user’s input into a search form.

You can achieve this with the use of the searchScope parameter on the module’s component tag (see the Banner component documentation for technical details).

This parameter allows a search on the module without search parameters needed in the URL. Instead, search parameters are added to the value of this parameter. Therefore, this parameter can be used to output module specific search results from hard-coded (or Liquid constructed) values without the use of a search form.

The search queries are similar to that used in the above form based search method, but use JSON syntax for their construction.

Below is an example of a constructed searchScope configured component tag, with min/max release date search, keywords and multiple tags query:

{% component type: "module", source: "Banner", layout: "List", searchScope: "{'prop_ReleaseDate_Min':'2018-07-01', 'prop_ReleaseDate_Max':'2018-07-31', 'prop_KeyWords':'Your Keywords', 'prop_ItemTags':['tag1','tag2']}" %}

The search logic combines all field queries with an AND operator, so items will be returned only if they include ALL the queries entered.



Related Articles

  • module (Banner Group)
    This module component fetches data relating to Banner Groups. {% component type: "module", source: "Banner...
  • module (Banner)
    This module component fetches data relating to Banner items. {% component type: "module", source: "Banner",...

External Resources

There are currently no external resources available.

Please let us know if you have any other contributions or know of any helpful resources you'd like to see added here.


Questions?

We are always happy to help with any questions you may have.
Visit the Treepl Forum for community support and to search previously asked questions or send us a message at support@treepl.co and we will consult you as soon as possible.