Getting Started with Sift

Installing Sift

Sift is available for Umbraco V8 and Umbraco V9. The best way to install Sift is to use the NuGet package manager in Visual Studio, search for "StuartMullinger.Sift". For those who prefer the command line:

PM> Install-Package StuartMullinger.Sift8

or

PM> Install-Package StuartMullinger.Sift9

A package is also available on "our" which can be installed using the back-office of Umbraco V8.

Umbraco 8 Package

If content already exists then you may need to rebuild the Examine index in the Umbraco back office before all of the features of Sift can be used.

A Simple Example

Using Sift it is possible to create a filter on your Umbraco website by adding some HTML to your view. The HTML will need to include these elements.

An outer Sift <div> element that will contain all of the criteria and results for the filter
A criteria <form> element that renders the criteria fields
An empty results <div> element in which the search results are displayed
A <script> tag to include the Sift JavaScript library

@inherits Umbraco.Web.Mvc.UmbracoViewPage

<h1>Simple Filter</h1>

<div class="sift"
     data-sift-result-document-type="cinemaCento">

    <form class="sift-criteria">

        @Html.AntiForgeryToken()

        <label for="filmName">Name</label>
        <input type="text" id="filmName" name="filmName"
               class="sift-criterion"
               data-sift-match-property="nodeName" />
        <p></p>

        <input type="submit" value="Search" />

    </form>

    <div class="sift-result">
    </div>

</div>

<script src="~/Scripts/sift.js" type="text/javascript"></script>

The Sift Outer Div

All of a Sift filter will be contained within the outer <div> element. This must have a class of sift to identify itself to the Sift JavaScript library and will also define the document type that will be searched for, using the data-sift-result-document-type attribute.

In the above example, the filter will search for content with a document type of cinemaCento.

The Criteria Form

Within the outer <div> a form can be defined in which the criteria fields for the filter will be specified. The form must have a class of sift-criteria. The form must include an anti-forgery token, using Html.AntiForgeryToken().

The form can include any number of criteria, which can be text fields, select list dropdowns, checkbox lists or radio button lists. Further details of how to set each of these up can be found in this user guide. The above example defines a single text field.

Each criterion within the form must contain the class sift-criterion. It must also specify the document type property alias that the field will be matched too, using the data-sift-match-property attribute. In the above example the text field matches to the nodeName property, a special case which will match to the name of the content. Any other property alias could be used, as defined in the document type.

Any submit of a sift-criteria form will cause a search to be performed.

The Results Div

A Sift search will populate the results <div>. This should be an empty <div> element, within the outer <div> and it should have a sift-result class. This element will be cleared and re-populated after each search.

Sift includes a default partial view that is used to render the results. This can be overridden to provide whatever information is required.

The Sift JavaScript Library

The Sift JavaScript library needs to be included in the page after any Sift blocks, ideally just before the </body> tag. This will identify the Sift blocks with the classes and attributes described and add the filtering functionality as required.

The above example will render as follows. The front-end developer is free to add styling to render the page as desired.

Simple Sift text field filter

<< Back to User Guide