silverware/iconsetfield

SilverWare IconSetField Module.

SilverWare IconSetField Module

, _(*1)

A responsive form field for SilverStripe v4, similar to CheckboxSetField... but with Font Awesome icons!, _(*2)

, _(*3)

Contents

• 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:, _(*4)

$ 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):, _(*5)

• 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., _(*6)

Theme

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

# 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., _(*8)

Columns

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

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:, _(*10)

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., _(*11)

Maximum Height

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

$field->setMaxHeight(200);

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

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., _(*14)

You can change these values by using:, _(*15)

$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)., _(*16)

Issues

Please use the GitHub issue tracker for bug reports and feature requests., _(*17)

Contribution

Your contributions are gladly welcomed to help make this project better. Please see contributing for more information., _(*18)

Attribution

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

Maintainers

Colin Tucker	Praxis Interactive

License

BSD-3-Clause © Praxis Interactive, _(*19)