silverstripe-tagfield/docs/en/using.md
Will Rossiter 527c5b2224
FIX Selected tag is not shown when isMutliple is false (#201)
* doc: add note about `setTitleField` (Fixes #153)

* NEW Add support for saving tag value into has_one components

FIX Value not shown if isMultiple is false (#195)

* fix: don't default to ID column as pgsql throws an error if comparing string value
2022-06-07 13:00:12 +12:00

2.0 KiB

Using

The primary use, for this module, is as a custom input field interface. For instance, imagine you had the following data objects:

class BlogPost extends DataObject
{
	private static $many_many = array(
		'BlogTags' => 'SilverStripe\\Blog\\Model\\BlogTag'
	);
}

class BlogTag extends DataObject
{
	private static $db = array(
		'Title' => 'Varchar(200)'
	);

	private static $belongs_many_many = array(
		'BlogPosts' => 'SilverStripe\\Blog\\Model\\BlogPost'
	);
}

If you wanted to link blog tags to blog posts, you might override getCMSFields with the following field:

$field = TagField::create(
	'BlogTags',
	'Blog Tags',
	BlogTag::get(),
	$this->BlogTags()
)
	->setShouldLazyLoad(true) // tags should be lazy loaded
	->setCanCreate(true);     // new tag DataObjects can be created

Note: This assumes you have imported the namespaces class, e.g. use SilverStripe\TagField\TagField;.

This will present a tag field, in which you can select existing blog tags or create new ones. They will be created/linked after the blog posts are saved.

StringTagField

You can also store string-based tags, with the following field type:

$field = StringTagField::create(
	'Tags',
	'Tags',
	['one', 'two'],
	explode(',', $this->Tags)
)
    ->setCanCreate(true)
    ->setShouldLazyLoad(true);

This assumes you are storing tags in the following data object structure:

class BlogPost extends DataObject
{
    private static $db = [
        'Tags' => 'Text',
	];
}

In the above code example, the options available (whether lazy loaded or not) would be "one" and "two", and the user would be able to create new options. Whichever tags are chosen would be stored in the BlogPost's Tags field as a comma-delimited string.

Using TagField with silverstripe-taxonomy

TagField assumes a Title field on objects. For classes without a Title field use setTitleField to modify accordingly.

$field = TagField::create(
    'Tags',
    'Blog Tags',
    TaxonomyTerm::get(),
)
    ->setTitleField('Name');