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

# Dropdown Filter Control

This is a dropdown control with custom styles that filters content by the specified CSS selector path.

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

## HTML Structure

Dropdown filter control is defined by required `data-jplist-control="dropdown-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" />

    <!-- filter dropdown control -->
    <div
        data-jplist-control="dropdown-filter"
        data-group="group1"
        data-name="name1"
        class="jplist-dd">

        <div data-type="panel" class="jplist-dd-panel">Filter by</div>
        <div data-type="content" class="jplist-dd-content">

        <div
                data-value="0"
                data-path="default"
                class="jplist-dd-item">Filter by</div>

        <div
                data-value="1"
                data-path=".title"
                class="jplist-dd-item"
                data-selected="true">Title</div>

        <div
                data-value="2"
                data-path=".desc"
                class="jplist-dd-item">Description</div>

        <div
                data-value="3"
                data-path=".likes"
                class="jplist-dd-item">Likes</div>
        </div>
    </div>

    <!-- 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>

### Top and bottom panels

Dropdown 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:

    <!-- filter dropdown control in the top panel -->
    <div
        data-jplist-control="dropdown-filter"
        data-group="group1"
        data-name="name1"
        class="jplist-dd">

        <div data-type="panel" class="jplist-dd-panel">Filter by</div>
        <div data-type="content" class="jplist-dd-content">

        <div
                data-value="0"
                data-path="default"
                class="jplist-dd-item">Filter by</div>

        <div
                data-value="1"
                data-path=".title"
                class="jplist-dd-item"
                data-selected="true">Title</div>

        <div
                data-value="2"
                data-path=".desc"
                class="jplist-dd-item">Description</div>

        <div
                data-value="3"
                data-path=".likes"
                class="jplist-dd-item">Likes</div>
        </div>
    </div>

    <!-- 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>

    <!-- filter dropdown control in the bottom panel -->
    <div
        data-jplist-control="dropdown-filter"
        data-group="group1"
        data-name="name1"
        class="jplist-dd">

        <div data-type="panel" class="jplist-dd-panel">Filter by</div>
        <div data-type="content" class="jplist-dd-content">

        <div
                data-value="0"
                data-path="default"
                class="jplist-dd-item">Filter by</div>

        <div
                data-value="1"
                data-path=".title"
                class="jplist-dd-item"
                data-selected="true">Title</div>

        <div
                data-value="2"
                data-path=".desc"
                class="jplist-dd-item">Description</div>

        <div
                data-value="3"
                data-path=".likes"
                class="jplist-dd-item">Likes</div>
        </div>
    </div>

### Bootstrap dropdown example

The following example demonstrates how to use jPList control with bootstrap framework:

    <div
            data-jplist-control="dropdown-filter"
            data-group="group1"
            data-opened-class="show"
            data-name="description"
            class="jplist-dd">

        <button
                data-type="panel"
                class="btn btn-primary dropdown-toggle"
                type="button">
            Filter by
        </button>

        <div data-type="content" class="dropdown-menu">

            <a class="dropdown-item"
               href="#"
               data-value="0"
               data-path="default">Filter By</a>

            <a class="dropdown-item"
               href="#"
               data-value="1"
               data-path=".description-content">With Description</a>

            <a class="dropdown-item"
               href="#"
               data-value="2"
               data-path=".description-content"
               data-inverted="true">Without Description</a>

        </div>
    </div>

### Jump to top

`data-jump` data attribute can be used to scroll page to the specified location when user selects a dropdown option. `data-jump="top"` scrolls page to the top. Any CSS selector can be used instead of top keyword.

    <div
        data-jplist-control="dropdown-filter"
        data-group="group1"
        data-name="name1"
        data-jump="top"
        class="jplist-dd">

        <div data-type="panel" class="jplist-dd-panel">Filter by</div>
        <div data-type="content" class="jplist-dd-content">

        <div
                data-value="0"
                data-path="default"
                class="jplist-dd-item">Filter by</div>

        <div
                data-value="1"
                data-path=".title"
                class="jplist-dd-item"
                data-selected="true">Title</div>

        <div
                data-value="2"
                data-path=".desc"
                class="jplist-dd-item">Description</div>

        <div
                data-value="3"
                data-path=".likes"
                class="jplist-dd-item">Likes</div>
        </div>
    </div>

## Deep Linking

Deep links 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, deepLinking setting should be true in jPList parameters and `data-value` should be added to each option.

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

    <!-- filter dropdown control -->
    <div
        data-jplist-control="dropdown-filter"
        data-group="group1"
        data-name="name1"
        class="jplist-dd"
        data-id="dd1">

        <div data-type="panel" class="jplist-dd-panel">Filter by</div>
        <div data-type="content" class="jplist-dd-content">

        <div
                data-value="0"
                data-path="default"
                class="jplist-dd-item">Filter by</div>

        <div
                data-value="1"
                data-path=".title"
                class="jplist-dd-item"
                data-selected="true">Title</div>

        <div
                data-value="2"
                data-path=".desc"
                class="jplist-dd-item">Description</div>

        <div
                data-value="3"
                data-path=".likes"
                class="jplist-dd-item">Likes</div>
        </div>
    </div>

    <!-- 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, storage setting should be passed to jPList constructor and `data-value` should be added to each option.

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

    <!-- filter dropdown control -->
    <div
        data-jplist-control="dropdown-filter"
        data-group="group1"
        data-name="name1"
        class="jplist-dd"
        data-id="dd1">

        <div data-type="panel" class="jplist-dd-panel">Filter by</div>
        <div data-type="content" class="jplist-dd-content">

        <div
                data-value="0"
                data-path="default"
                class="jplist-dd-item">Filter by</div>

        <div
                data-value="1"
                data-path=".title"
                class="jplist-dd-item"
                data-selected="true">Title</div>

        <div
                data-value="2"
                data-path=".desc"
                class="jplist-dd-item">Description</div>

        <div
                data-value="3"
                data-path=".likes"
                class="jplist-dd-item">Likes</div>
        </div>
    </div>

    <!-- 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>

## Data Attributes

The full list of control data attributes.

Name | Description | Values
--- | --- | ---
`data-jplist-control` | Defines dropdown filter control. | "dropdown-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-jump` | This data attribute can be used to scroll page to the specified location when user selects an option. 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-opened-class` | Optional data attribute that defines CSS class of opened dropdown with custom styles. | CSS class name, by default jplist-dd-opened
`data-or` | Defines a group of controls that should be filtered though the "OR" logic | any text value, for example data-or="bags"

### Inner elements

Data attributes of inner elements.

Name | Description | Values
--- | --- | ---
`data-type="panel"` | Defines a dropdown panel that contains selected text. | "panel"
`data-type="content"` | Defines a wrapper around dropdown options. | "content"
`data-path` | CSS selector that defines the HTML element that should be filtered | "default" keyword for the initial value or any CSS selector
`data-selected` | Specifies the initial selected value | "true" or "false"

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