Skip to content

Latest commit

 

History

History
342 lines (269 loc) · 11.8 KB

README.md

File metadata and controls

342 lines (269 loc) · 11.8 KB

Charcoal Advanced Search

License Latest Stable Version Code Quality Coverage Status Build Status

A Charcoal widget for creating tabbed filter interfaces.

Table of Contents

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-contrib-advanced-search

Dependencies

Required

Configuration

Include the advanced-search module in the project's config file. This will provide everything needed for charcoal-contrib-advanced-search to work properly. No need for metadata/views/action/routes path etc.

{
    "modules": {
       "charcoal/advanced-search/advanced-search": {}
    }
}

Usage

charcoal-contrib-advanced-search can be used as a dashboard widget to filter all the filterable widgets included in the template. Define a structure like these ones 👇 in a dashboard widget to create filters.

Basic Structure

With Tabs

{
    "advancedSearchNew": {
        "type": "charcoal/advanced-search/widget/advanced-search-tabs",
        "rowCountLabel": "Result",
        "rowCountLabelPlural": "Results",
        "sort_options": {
            "id": { "direction": "ASC" },
            "name": { "direction": "ASC" },
            "registrationDate": { "direction": "DESC" }
        },
        "tabs": [
            {},
            {}
        ]
    },
    "table": {
        "obj_type": "path/to/model",
        "type": "charcoal/admin/widget/table",
        "show_table_header": false
    }
}

Options

Key Values Default Description
row_count_label String "Result" Non-plural label to use for the heading count. ex. "User" will display as "24 Users"
row_count_label_plural String n/a (optional) plural label to use for the heading count.
sort_options Array n/a (optional) Defines sorting options
tabs Array n/a Defines filter tabs to use

Without Tabs

If tabs aren't needed, the widget type charcoal/advanced-search/widget/advanced-search can be used.

Instead of a "filters": [] array, use a "groups": [] array.

{
    "advancedSearchNew": {
        "type": "charcoal/advanced-search/widget/advanced-search",
        "rowCountLabel": "Result",
        "rowCountLabelPlural": "Result",
        "sort_options": {
            "id": { "direction": "ASC" },
            "name": { "direction": "ASC" },
            "registrationDate": { "direction": "DESC" }
        },
        "groups": [
            {},
            {}
        ]
    },
    "table": {
        "obj_type": "path/to/model",
        "type": "charcoal/admin/widget/table",
        "show_table_header": false
    }
}

Options

Key Values Default Description
row_count_label String "Result" Non-plural label to use for the heading count. ex. "24 Users"
row_count_label_plural String n/a (optional) plural label to use for the heading count.
sort_options Array n/a Defines sorting options
groups Array n/a Defines filter groups to use

Tabs

Tab Example

{
    "label": "First Tab",
    "groups": [
        {},
        {}
    ],
    "layout": {}
}

Options

Key Values Default Description
label String n/a Label to use for the tab
groups Array n/a Defines filter groups to use
layout Array n/a Arrange the groups in a layout within the tab using structures

Filter Group

Filter Group Example

{
    "label": "Filter Group Label",
    "filters": [
        "filter_one",
        "filter_two"
    ],
    "filters_options": {
        "filter_one": {},
        "filter_two": {}
    },
    "layout": {}
}

Options

Key Values Default Description
label String n/a Label to use for the group
filters Array n/a Defines filters to use in order
filters_options Array n/a Defines options for each filter to use
layout Array n/a Arrange the filters in a layout within the group using structures

Filter Examples

Filters can be defined like normal inputs. However, there are added options for select inputs.

Select Inputs

Use property choices as source

{
    "label": "Filter Label",
    "input_type": "charcoal/admin/property/input/select",
    "property_ident": "ident",
    "choices_source": {
        "type": "property",
        "model": "path/to/model",
        "property_ident": "ident"
    },
    "operator": "="
}

Use database values as source

{
    "label": "Author Filter",
    "multiple": false,
    "input_type": "charcoal/admin/property/input/select",
    "property_ident": "authors",
    "choice_obj_map": {
        "label": "displayName"
    },
    "choices_source": {
        "type": "database",
        "model": "charcoal/admin/user",
        "filters": [
            {
                "property": "roles",
                "value": "author"
            }
        ]
    },
    "select_options": {
        "liveSearch": true,
        "size": 5
    }
}

Options

These options are added in addition to all other input options.

Key Values Default Description
table String choices_source.table Can be a model or a table name
property_ident String n/a Property name to filter by
property_type String property_ident The type of property to use.
choice_obj_map Array n/a Maps a database column to the Label/Value of a select option
choices_source Array n/a See table below for choices_source options

choices_source options:

Key Values Default Description
type String n/a Either property (Use a model's property as choices) or database (Use database results as choices).
model String n/a Defines which model to use as a source
filters Array n/a database type only. Defines optional query filters
property_ident String n/a property type only. Property name to use as select options

Development

To install the development environment:

$ composer install

To run the scripts (phplint, phpcs, and phpunit):

$ composer test

Assets

To install assets build environment:

$ yarn install

To run the build scripts:

$ grunt watch

or

$ grunt

API Documentation

Development Dependencies

  • [php-coveralls/php-coveralls][phpcov]
  • [phpunit/phpunit][phpunit]
  • [squizlabs/php_codesniffer][phpcs]

Coding Style

The charcoal-contrib-advanced-search module follows the Charcoal coding-style:

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

License

Charcoal is licensed under the MIT license. See LICENSE for details.