README

A responsive form field for SilverStripe v4, similar to CheckboxSetField... but with Font Awesome icons!

Requirements
Installation
Configuration
Usage
Issues
Contribution
Attribution
Maintainers
License

Requirements

SilverStripe Framework v4
SilverWare Font Icons (includes Font Awesome)
default CSS classes are configured for the Bootstrap grid

Installation

Installation is via Composer:

$ composer require silverware/iconsetfield

Note: forms on the website will automatically load the field requirements if the app is using SilverWare. If you are using a vanilla SilverStripe project, you'll need to load the module script and styles in your app bundle (jQuery is required):

silverware/iconsetfield: client/dist/js/bundle.js
silverware/iconsetfield: client/dist/styles/bundle.css

Configuration

As with all SilverStripe modules, configuration is via YAML. Extensions to LeftAndMain and ContentController are applied via config.yml.

Theme

The module supports a theme for both the CMS and forms on the website. To define the theme, use the following YAML configuration:

# Custom theme for CMS:

SilverStripe\Admin\LeftAndMain:
  iconsetfield_theme:
    hover-background: '<color>'
    hover-foreground: '<color>'
    checked-background: '<color>'
    checked-foreground: '<color>'
    checked-border: '<color>'

# Custom theme for website forms:

SilverStripe\CMS\Controllers\ContentController:
  iconsetfield_theme:
    hover-background: '<color>'
    hover-foreground: '<color>'
    checked-background: '<color>'
    checked-foreground: '<color>'
    checked-border: '<color>'

Replace each <color> with your desired color hex or rgba code.

Columns

By default, the field uses Bootstrap column classes. You can change the column classes by adding them to your YAML:

SilverWare\IconSetField\Forms\IconSetField:
  column_class_small: 'col-sm-%d'
  column_class_large: 'col-lg-%d'

Usage

Create the field either as part of a Form, or within your getCMSFields() method:

use SilverWare\IconSetField\Forms\IconSetField;

$field = IconSetField::create(
    'RelationName',
    'Title of field',
    [
        1 => [
            'icon' => 'envelope',
            'text' => 'Mail'
        ],
        2 => [
            'icon' => 'facebook',
            'text' => 'Facebook'
        ],
        3 => [
            'icon' => 'twitter',
            'text' => 'Twitter'
        ]
    ]
);

The first parameter is the name of the field or many-many relation to save to, and the second is the field title. The third parameter defines the source for the field, and is a nested array consisting of ID values mapped to arrays containing the icon code (i.e. fa-<code>) and the text for the option.

Maximum Height

You can define a maximum height (in pixels) for your field by using the setMaxHeight() method:

$field->setMaxHeight(200);

This will fix the maximum height of your field to 200 pixels, and add a scrollbar to view the remaining options.

Column Widths

The field supports custom column widths for small and large devices. By default, the field uses a value of 6 for small devices, and 4 for large devices. Based on the Bootstrap grid of 12, this means you'll see two options per row on small devices, and three options per row on large devices.

You can change these values by using:

$field->setSmallWidth(4);  // 3 options per row on small devices
$field->setLargeWidth(3);  // 4 options per row on large devices

Options will always be one per row on the smallest screens (i.e. mobile).

Issues

Please use the GitHub issue tracker for bug reports and feature requests.

Contribution

Your contributions are gladly welcomed to help make this project better. Please see contributing for more information.

Attribution

Makes use of Font Awesome by Dave Gandy.
Makes use of Bootstrap by the Bootstrap Authors and Twitter, Inc.

silverware / iconsetfield

Maintainers

Details