Icônes Form Widget for October CMS

[ ? Release Notes]

ℹ️ Plugin version 3 is compatible only with Octobercms 3 (New Ajax framwork and the backend upgrade to bootstrap 5), please use version 2 of the plugin for OCMS 1 and 2. You cannot upgrade from v1 or v2 to v3.

Access thousands of SVG icons as a backend form widget.

One library, over 133,000 vector icons, Modern replacement for icon fonts. Fast, easy to use.

• 123+ icon sets powered by Iconify
• Browse the icons on Iconify or on Icônes

TOC

• Icônes Form Widget for October CMS
• TOC
  • Upgrading from version 1.* to 2.*
  • Installation
  • Composer
  • How to use
  • Field Options
  • Form field showName option
  • Form field showIconSetName option
  • Form field size option
  • Form field iconSets option
• Settings
  • Permissions
  • Usage in Twig template
  • Twig filter options
    • Options detail
  • Usage in PHP
  • Usage in Backend List

Upgrading from version 1.* to 2.*

Icônes Form Widget 2.0 depend on version 2 of Iconify Icon Sets. If you are upgrading from version 1. , you need to upgrade your Iconify Icon Sets to version 2. also. For that, run the following command in the root of your project:

composer require chkilel/icones-plugin --with-all-dependencies
# --with-all-dependencies will upgrade all dependencies also

then migrate the database:

php artisan october:up

Installation

Simply install the plugin from the marketplace, if you run into problems because of composer dependencies, please use composer.

Composer

If you prefer Composer or you run into problems when installing from the marketplace, run the following commands in the project’s root directory:

composer require chkilel/icones-plugin:^2.0.0 # For Octobercms 1 and 2
# ℹ️ OR
composer require chkilel/icones-plugin:^3.0.0 # For Octobercms 3
# Then
php artisan october:up

How to use

Icônes plugin registers a new backend form widget named iconesfinder.

You can access the Form Widget in your model's fields.yaml file or as Custom Page Fields for static pages by using iconesfinder as the field type.

• Usage example via yaml config:

    my_awesome_icon:
        label: My super awesome icon
        type: iconesfinder
        showName: true
        showIconSetName: true
        size: large
        placeholder: -- Choose your icon --
        iconSets: # Icon sets to choose from, the icon sets must be enabled in the settings area
            - mdi # Material Design Icons
            - ant-design # Ant Design Icons
            - emojione # Emoji One (Colored)
            - logos # SVG Logos

• Usage example via Custom page fields for Pages plugin:

    {variable   type="iconesfinder"
                name="my_awesome_icon"
                label="My awesome icon"
                showName="true"
                showIconSetName="true"
                size="large"
                iconSets="mdi|ant-design|emojione|logos|pages"
                placeholder="My placeholder"
                tab="My tab name"
                placement="secondary"
    }{/variable}

Please pay attention to the spaces for Custom Page Fields, there is no space between the option, the equal sign = and the value

Field Options

For each field you can specify these options:

Form field showName option

Show the name of the icon in the field.

Value	Appearance
true
false

Form field showIconSetName option

Show the name of the icon set in the field.

Value	Appearance
true
false

Form field size option

Set the size of the field.

Value	Appearance
small
(Defaul if not set)
large

Form field iconSets option

For iconSets option, you can choose one or more from the possible values below, if not set, the user can choose from all enabled icon sets in the backend settings:

Settings

After installation, go to Backend > Settings >icones or type icones in the search field.

Initially, none of the icon sets is installed, you need to install the icon sets you want to allow the end user to use.

• You can enable installed icon sets:

• Disable enabled ones:

• Or completely delete an icon set.

Please note that to delete an icon set, you need to disable it first.

Permissions

The plugin registers two backend permissions to manage Icônes.

• Access Icônes settings : allow the user to enable and/or disable icon sets.
• Manage icon sets installation end deletion : allow the user to install and/or delete icon sets.

Usage in Twig template

Icônes plugin register a new filter iconify() to use in your templates, the filter generate an SVG icon.

Twig filter options

iconify filter optionally accept an object with key:value paires to generate the SVG. It will use default if used as {{ my_var|iconify }} without providing any parameter, The options to use are listed below.

Examples of usages:

    {{ my_var|iconify }} {# Default options from stored value #}

    {{ my_var|iconify({'height': '24px', 'class':'w-10 h-10' }) }}

    {{ my_var | iconify({
                    'height' : '24px',
                    'width' : '24px',
                    'align' : 'center,middle,meet',
                    'color' : '#ff8000',
                    'rotate' : '90deg', // same as "'rotate' =>  1" or "'rotate' => '25%'"
                    'flip' : 'horizontal', // same as "'hFlip' => true"
                    'box' : true
                 });
       }}

   {#  Height and width will be set from viewBox attribute, using original icon's dimensions#}
   {{ my_var | iconify({ 'height' => 'auto'}) }}

Options detail

Usage in PHP

The icônes plugin value can also be used easily in PHP, with the obove options as follows:

use Chkilel\Icones\Classes\JsonIcon;

$icon = new JsonIcon($value);
$icon->iconify(['inline'=>true, 'height'=>36]);

Usage in Backend List

The icônes plugin can also be used on backend lists, it defines a new Column Types iconesthumb with the option to give a height (in px) to the output, e.g.

icon:
    label: My awesome icon
    type: iconesthumb
    height: 36

Upgrading from version 2.*

No upgrade path from version 2 to version 3, version 3 is not compatible with V2, it's intended to be used with OCMS 3 and above.

Upgrading from version 1.* ?

Icônes Form Widget version 2.* depend on version 2 of Iconify Icon Sets. If you are upgrading from version 1.* , you need to upgrade your Iconify Icon Sets to version 2.* also. For that, run the following command in the root of your project:

composer require chkilel/icones-plugin --with-all-dependencies
# --with-all-dependencies will upgrade all dependencies also

then migrate the database:

php artisan october:up