Charcoal Advanced Search

A Charcoal widget for creating tabbed filter interfaces.

Table of Contents

• Installation
  • Dependencies
• Configuration
• Usage
• Development
  • Assets
  • API Documentation
  • Development Dependencies
  • Coding Style
• Credits
• License

Installation

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

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

Dependencies

Required

• PHP 5.6+: PHP 7 is recommended.
• charcoal-admin ^0.14.2.

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

• The auto-generated phpDocumentor API documentation is available at:
  https://locomotivemtl.github.io/charcoal-contrib-advanced-search/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-contrib-advanced-search/master/

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:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

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

Credits

• Locomotive

License

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