@!(data, className) @function header(){} @function body(){

# Textbox Filter Control

Textbox filter control is used to filter content by the specified CSS selector.

See the Pen jPList Textbox Filter Control by 1rosehip (@1rosehip) on CodePen.

## HTML Structure

Textbox filter control is defined by required `data-jplist-control="textbox-filter"` data attribute. The `data-group` attribute defines group of elements that should be filtered. The full list of data attributes can be found here.

    <!-- jplist styles - should not be added if bootstrap or other CSS framework is used -->
    <link href="jplist.styles.css" rel="stylesheet" type="text/css" />

    <!-- text filter control -->
    <input
         data-jplist-control="textbox-filter"
         data-group="group1"
         data-name="my-filter-1"
         data-path=".title"
         type="text"
         value=""
         placeholder="Filter by Title"
    />

    <!-- content to filter -->
    <div data-jplist-group="group1">

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

    </div>

    <!-- jplist library -->
    <script src="jplist.min.js"></script>
    <script>
        jplist.init();
    </script>

### Textbox with clear button

Clear button can be added using `data-clear-btn-id` data attribute that points to the button element:

    <input
         data-jplist-control="textbox-filter"
         data-group="group1"
         data-name="my-filter-1"
         data-path=".title"
         data-clear-btn-id="title-clear-btn"
         type="text"
         value=""
         placeholder="Filter by Title"
    />

    <button type="button" id="title-clear-btn">Clear</button>

### Top and bottom panels

Textbox filter control can be placed in both top and bottom panels for the better user experience. In this case `data-name` attribute with the same value should be added. All other data attributes should also have the same values:

    <!-- textbox filter control in the top panel -->
    <input
         data-jplist-control="textbox-filter"
         data-group="group1"
         data-name="title-text-filter"
         data-path=".title"
         type="text"
         value=""
         placeholder="Filter by Title"
    />

    <!-- content to filter -->
    <div data-jplist-group="group1">

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

    </div>

    <!-- textbox filter control in the bottom panel -->
    <input
         data-jplist-control="textbox-filter"
         data-group="group1"
         data-name="title-text-filter"
         data-path=".title"
         type="text"
         value=""
         placeholder="Filter by Title"
    />

### Jump to top

`data-jump` data attribute can be used to scroll page to the specified location when user changes textbox value. `data-jump="top"` scrolls page to the top. Any CSS selector can be used instead of top keyword.

    <input
         data-jplist-control="textbox-filter"
         data-group="group1"
         data-name="title-text-filter"
         data-path=".title"
         type="text"
         value=""
         placeholder="Filter by Title"
         data-jump="top"
    />

## Deep Linking

Deep links can be used to keep user changes and control state after the page refresh. To implement them `data-id` attribute should be added to HTML structure and deepLinking setting should be true in jPList parameters.

In the example below deep link may look like http://www.example.com/page#group=group1&title=a where group1 is taken from `data-jplist-group="group1"`, title is data-id value and a is current user input.

    <!-- jplist styles - should not be added if bootstrap or other CSS framework is used -->
    <link href="jplist.styles.css" rel="stylesheet" type="text/css" />

    <!-- textbox filter control -->
    <input
         data-jplist-control="textbox-filter"
         data-group="group1"
         data-name="title-text-filter"
         data-path=".title"
         type="text"
         value=""
         placeholder="Filter by Title"
         data-id="title"
    />

    <!-- content to filter -->
    <div data-jplist-group="group1">

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

    </div>

    <!-- jplist library -->
    <script src="jplist.min.js"></script>
    <script>
        jplist.init({
            deepLinking: true
        });
    </script>

## Storage

Local storage, session storage or cookies can be used to keep user selections and control states after the page refresh. To implement them `data-id` attribute should be added to HTML structure and storage setting should be passed to jPList constructor.

    <!-- jplist styles - should not be added if bootstrap or other CSS framework is used -->
    <link href="jplist.styles.css" rel="stylesheet" type="text/css" />

    <!-- textbox filter control -->
    <input
         data-jplist-control="textbox-filter"
         data-group="group1"
         data-name="title-text-filter"
         data-path=".title"
         type="text"
         value=""
         placeholder="Filter by Title"
         data-id="title"
    />

    <!-- content to filter -->
    <div data-jplist-group="group1">

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

        <!-- item -->
        <div data-jplist-item>
            <div class="title">Title value 1</div>
            ....
        </div>

    </div>

    <!-- jplist library -->
    <script src="jplist.min.js"></script>
    <script>
        jplist.init({
            storage: 'localStorage', //'localStorage', 'sessionStorage' or 'cookies'
            storageName: 'jplist'
        });
    </script>

## Ignore Special Characters

To ignore some characters during the search data-regex attribute can be use like in the example below. Here all names defined with underscore character instead of a space, for example Alejandro_Miles. To allow the user search for Alejandro Miles with space instead we may use the regex data-regex="[^a-zA-Z0-9]+" that ignores all characters except English letters and numbers.

See the Pen jPList Textbox Ignore Characters by 1rosehip (@1rosehip) on CodePen.

## Data Attributes

The full list of control data attributes.

Name | Description | Values
--- | --- | ---
`data-jplist-control` | Defines textbox filter control. | "textbox-filter"
`data-group` | Defines group of items that should be filtered. For example, if a control has data-group="group1" then items group should have data-jplist-group="group1" data attribute. | any text value
`data-name` | The data-name attribute is used to identify the same controls in different panels. Different controls should have different data-name attributes. By default, data-name attribute has default value. | any text value
`data-path` | CSS selector that defines the HTML element that should be filtered | "default" keyword for the initial value or any CSS selector
`data-clear-btn-id` | The ID of the clear button element. | ID of the button
`data-jump` | This data attribute can be used to scroll page to the specified location when user changes a textbox value. data-jump="top" scrolls page to the top. Any CSS selector can be used instead of top keyword. | top keyword or any CSS selector
`data-id` | This attribute is used for deep linking. | any text value that may contain letters, digits, underscores or dashes
`data-regex` | This optional data attribute defines characters that should be ignored during the filtering. For example, data-regex="[^a-zA-Z0-9]+" ignores all characters except English letters and numbers. | JavaScript regex
`data-or` | Defines a group of controls that should be filtered though the "OR" logic | any text value, for example data-or="bags"
`data-mode` | Defines text filter mode: contains - find all elements that contain user input startsWith - find all elements that start with user input endsWith - find all elements that end with user input equal - find all elements that equal to user input | contains (default), startsWith, endsWith, equal

} @render(process.cwd() + '/build/site/layouts/documentation.html', data, 'Textbox Filter Control', header, body, 'text-filter-controls', 'textbox-filter')