locomotivemtl/charcoal-contrib-property-filter

Charcoal service provider for a collection filtering widget that uses model properties as filters.

0.1.2.1 2020-01-21 20:08 UTC

Requires

• php: >=5.6.0 || >=7.0
• locomotivemtl/charcoal-admin: >=0.14.2

Requires (Dev)

• php-coveralls/php-coveralls: ^2.0
• phpunit/phpunit: ^5.7 || ^6.5
• squizlabs/php_codesniffer: ^3.0

MIT

• Locomotive
• Joel Alphonso

• filter
• charcoal

README

A Charcoal service provider my cool feature.

Table of Contents

• Installation
  • Dependencies
• Configuration
• Usage
• Options
• 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-property-filter

Dependencies

Required

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

Configuration

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

{
    "modules": {
       "charcoal/property-filter/property-filter": {}
    }
}

Usage

charcoal-contrib-property-filter can be used as a dashboard widget to filter all the filterable widgets included in the template. Define a structure like this one 👇 in a dashboard widget to create filters.

{
    "filters": {
        "type": "charcoal/property-filter/widget/property-filter",
        "property_filters": [
            "taxonomy_1",
            "taxonomy_2",
            "taxonomy_3"
        ],
        "properties_options": {
            "taxonomy_1": {
                "required": false,
                "multiple": true,
                "input_type": "charcoal/admin/property/input/select"
            },
            "taxonomy_2": {
                "required": false,
                "input_type": "charcoal/admin/property/input/radio"
            },
            "taxonomy_3": {
                "required": false,
                "input_type": "charcoal/admin/property/input/checkbox"
            }
        },
        "layout": {
            "structure": [
                {"columns": [1, 1, 1]}
            ]
        }
    }
}

Options

Key	Values	Default	Description
properties	Array	n/a	Defines which of the model's properties to use as filters.
properties_options	Array	n/a	Defines property customizations for the filter inputs
layout	Array	n/a	Arrange the filters in a layout using structures

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 insall

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-property-filter/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-contrib-property-filter/master/

Development Dependencies

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

Coding Style

The charcoal-contrib-property-filter 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.