heimrichhannot/contao-tagsinput

Contao port of Bootstrap Tags Input that provides an front and back end field to add custom values like tags to an field or database table.

3.0.0 2024-04-16 13:41 UTC

Requires

• php: ^7.4 || ^8.0
• contao-community-alliance/composer-plugin: ~2.4 || ~3.0
• contao/core-bundle: ~4.13 || ^5.0
• heimrichhannot/contao-encore-contracts: ^1.0
• heimrichhannot/contao-utils-bundle: ^2.233 || ^3.0@beta

LGPL-3.0-or-later

• Heimrich & Hannot

• tags
• input
• widget
• contao
• tagsinput

README

Contao port of Bootstrap Tags Input that provides an front and back end field to add custom values like tags to an field or database table.

Features

• Frontend and backend support (inputType : tagsinput)
• Free Input can be set to true or false on dca field config.
• typeahead.js support
• styled for front and back end
• fetch options asynchronously remote (optional)
• sort tags per drag & drop
• add new tags by the following actions: pressing tab/return/semicolon and comma or by leaving the field (as long as freeInput is enabled and a value was typed inside the field)

Setup / Examples

1. Tagsinput with options or options_callback and one possible tag selection

'locations'         => array
(
    'label'     => &$GLOBALS['TL_LANG']['tl_entity_lock']['locations'],
    'inputType' => 'tagsinput',
    'sql'       => "varchar(255) NOT NULL default ''",
    'options'   => array('boston', 'berlin', 'hamburg', 'london'),
    'eval'      => array
    (
        'freeInput'   => false
        'tl_class' => 'w50 autoheight'
    )
),

2. Tagsinput with options or options_callback and multiple possible tag selection and freeInput

'locations'         => array
(
    'label'     => &$GLOBALS['TL_LANG']['tl_entity_lock']['locations'],
    'inputType' => 'tagsinput',
    'sql'       => "blob NULL",
    'options'   => array('boston', 'berlin', 'hamburg', 'london'),
    'eval'      => array
    (
        'multiple'        => true,
        'freeInput'       => true,
        'multiple'        => true,
        'maxTags'         => 3,
        'maxChars'        => 12,
        'trimValue'       => true,
        'allowDuplicates' => true,
        'tl_class' => 'w50 autoheight'
    )
),

3. Tagsinput with freeInput and one possible tag selection

'locations'         => array
(
    'label'     => &$GLOBALS['TL_LANG']['tl_entity_lock']['locations'],
    'inputType' => 'tagsinput',
    'sql'       => "varchar(255) NOT NULL default ''",
    'eval'      => array
    (
        'freeInput'   => true,
        'tl_class' => 'w50 autoheight'
    )
),

4. Tagsinput with freeInput and multiple possible tag selection

'locations'         => array
(
    'label'     => &$GLOBALS['TL_LANG']['tl_entity_lock']['locations'],
    'inputType' => 'tagsinput',
    'sql'       => "blob NULL",
    'eval'      => array
    (
        'multiple'    => true,
        'freeInput'   => true,
        'tl_class' => 'w50 autoheight'
    )
),

5. Tagsinput with remote options and one possible tag selection

'locations'         => array
(
    'label'     => &$GLOBALS['TL_LANG']['tl_entity_lock']['locations'],
    'inputType' => 'tagsinput',
    'sql'       => "int(10) unsigned NOT NULL default '0'",
    'eval'      => array(
        'placeholder' => &$GLOBALS['TL_LANG']['tl_member']['placeholders']['locations'],
        'freeInput'   => false,
        'mode'        => \TagsInput::MODE_REMOTE,
        'remote'      => array
        (
            'fields'       => array('title', 'id'),
            'format'       => '%s [ID:%s]',
            'queryField'   => 'title',
            'queryPattern' => '%QUERY%', 
            'foreignKey'   => '%parentTable%.id',
            'limit'        => 10
        ),
        'tl_class' => 'w50 autoheight'
    )
),

As you can see, there must be a remote configuration, with the tags format and fields, taken from the foreignKey relation. The foreignKey must be a valid database table reference, by a given table name and field. It is also possible to reference the table name from a field within the current record, by adding percent sign before and behind the field name. This might be helpful for dynamic tagsinput fields. The queryField represents the lookup field for the given typeahead query. To provide a custom query pattern for the LIKE search, simply add a custom queryPattern and place percent sign where you want;

5. Tagsinput with remote options from relation table and multiple possible tag selections and freeInputs

'locations'         => array
(
    'label'     => &$GLOBALS['TL_LANG']['tl_entity_lock']['locations'],
    'inputType' => 'tagsinput',
    'sql'       => "blob NULL",
    'eval'      => array(
        'placeholder' => &$GLOBALS['TL_LANG']['tl_member']['placeholders']['locations'],
        'freeInput'   => true,
        'mode'        => \TagsInput::MODE_REMOTE,
        'remote'      => array
        (
            'fields'       => array('title', 'id'),
            'format'       => '%s [ID:%s]',
            'queryField'   => 'title',
            'queryPattern' => '%QUERY%', 
            'foreignKey'   => '%parentTable%.id',
            'limit'        => 10
        ),
        'save_tags' => array(
            'table'    => 'tl_calendar_events',
            'tagField' => 'title',
            'defaults' => array
            (
                'tstamp'    => time(),
                'pid'       => 1,
                'type'      => 'community',
                'published' => false
            )
        ),
        'tl_class' => 'w50 autoheight'
    )
),

If you want to add tags as entities within remote mode, you have to enable freeInput and provide a valid save_tags configuration like the one provided above. The tagField should be the field from the save_tags table where the user input from tagsinput should be stored in.

6. Tagsinput with remote options from options or options_callback and multiple possible tag selections and freeInputs and tags_callback

'locations'         => array
(
    'label'     => &$GLOBALS['TL_LANG']['tl_entity_lock']['locations'],
    'inputType' => 'tagsinput',
    'options'   => array('boston', 'berlin', 'hamburg', 'london'),
    'sql'       => "blob NULL",
    'eval'      => array(
        'placeholder' => &$GLOBALS['TL_LANG']['tl_member']['placeholders']['locations'],
        'freeInput'   => true,
        'mode'        => \TagsInput::MODE_REMOTE,
        'remote'      => array
        (
            'queryPattern' => '%QUERY%', 
            'limit'        => 10
        ),
        'tags_callback' => array(array('MyClass', 'addTagAttributes')),
        'tl_class' => 'w50 autoheight'
    ),
),

eval options

save_tags settings

remote settings

tags_callback

The tags_callback should be a valid callback that can be used to manipulate the tag object.

// tags_callback example callback
class tl_member_custom extends \Backend
{
    public function addTagAttributes($arrOption, DataContainer $dc)
    {
        $objTag = MyTagsModel::findByPk($arrOption['value']);

        if (!$objTag->published)
        {
            $arrOption['class'] .= ' new';
        }

        return $arrOption;
    }
}