Tag Options
Model options define how a tag model behaves. They can
either be set in the model field arguments, or
in the tag model’s TagMeta class. Once defined, they are then stored in
a TagOptions instance on the tag model, accessible at
MyTagModel.tag_options
(and shared with tag model fields at
MyTaggedModel.tags.tag_options
).
Tagulous only lets you set options for a tag model in one place - if you use a
custom model you must set options using TagMeta
, and if you share an
auto-generated model between fields, only the first field can set options.
Form options are a subset of the model options, and are
also used to control tag form fields, and are also stored in a TagOptions
instance. If the field is part of a ModelForm
it will inherit options from
the model, otherwise options can be passed in the field arguments.
Model Options
The tag model options are:
initial
List of initial tags for the tag model. Must be loaded into the database with the management command initial_tags.
Value can be a tag string to be parsed, or an array of strings with one tag in each string.
To change initial tags, you can change the initial
option and re-run
the command initial_tags.
You should not find that you need to update initial
regularly; if you
do, it would be better to use the Tagulous admin tools to
add tags to the model directly.
If provided as a tag string, it will be parsed using spaces and commas, regardless of the space_delimiter option.
Default: ''
protect_initial
The protected
state for any tags created by the initial
argument -
see Protected tags.
Default: True
protect_all
Whether all tags with count 0 should be protected from automatic deletion.
If false, will be decided by tag.protected
- see Protected tags.
Default: False
case_sensitive
If True
, tags will be case sensitive. For example, "django, Django"
would be two separate tags.
If False
, tags will be capitalised according to the first time they are
used.
Note when using sqlite: substring matches on tag names, and matches on tag names with non-ASCII characters, will never be case sensitive - see the databases django documentation for more information.
See also force_lowercase
Note
MySQL struggles to offer string case sensitivity at the database level -
see the django documentation
for more details. Tagulous therefore offers no formal support for this
option when running on MySQL - the relevant tests are bypassed, and you
should assume that case_sensitive
is always False
. Patches welcome.
Default: False
force_lowercase
Force all tags to lower case
Default: False
max_count
TagField
only - this is not supported by SingleTagField
.
Specifies the maximum number of tags allowed.
Set to 0
to have no limit.
If you are setting it to 1
, consider using a SingleTagField
instead.
Default: 0
space_delimiter
TagField
only - this is not supported by SingleTagField
.
If True
, both commas and spaces can be used to separate tags. If False
,
only commas can be used to separate tags.
Default: True
tree
Field argument only - this cannot be set in TagMeta
If True
, slashes in tag names will be used to denote children, eg
grandparent/parent/child
, and these relationships can be traversed.
See Tag Trees for more details.
If False
, slashes in tag names will have no significance, and no tree
properties or methods will be present on tag objects.
Default: False
autocomplete_initial
If True
, override all other autocomplete settings and use the tags
defined in the initial
argument for autocompletion, embedded in the
form field HTML.
For more advanced autocomplete filtering options (ie filter tags by user), see the example Filtering autocomplete by related fields.
Default: False
autocomplete_view
Specify the view to use for autocomplete queries.
This should be a value which can be passed to Django’s reverse()
, eg the
name of the view.
If None
, all tags will be embedded into the form field HTML as the
data-autocomplete
attribute.
If this is an invalid view, a ValueError
will be raised.
Default: None
autocomplete_view_args
Optional args
passed to the autocomplete_view
.
Default: None
autocomplete_view_kwargs
Optional kwargs
passed to the autocomplete_view
.
Default: None
autocomplete_limit
Maximum number of tags to provide at once, when autocomplete_view
is
set.
If the autocomplete adaptor supports pages, this will be the number shown per page, otherwise any after this limit will not be returned.
If 0
, there will be no limit and all results will be returned
Default: 100
autocomplete_view_fulltext
Whether to perform a start of word match (__startswith
) or full text match
(__contains
) in the autocomplete view.
Has no effect if not using autocomplete_view
.
Default: False
(start of word)
autocomplete_settings
Override the default TAGULOUS_AUTOCOMPLETE_SETTINGS
.
For example, the select2 control defaults to use the same width as the form element it
replaces; you can override this by passing their width
option (see their docs on
appearance) as an autocomplete setting:
myfield = TagField(... autocomplete_settings={"width": "75%"})
Default: None
get_absolute_url
A shortcut for defining a get_absolute_url
method on the tag model.
Only used when defined in tag fields which auto-generate models.
It is common to need to get a URL for a tag, so rather than converting your tag
field to use a custom TagModel
just to implement a get_absolute_url
method, you can pass this argument a callback function.
The callback function will be passed the tag object, and should return the URL for the tag. See the Tag URL example for a simple lambda argument.
If not set, the method get_absolute_url
will not be available and an
AttributeError
will be raised.
Note
Due to the way Django migrations freeze model fields, this attribute is not available during data migrations. See Limitations of Django migrations for more information.
Default: None
verbose_name_singular
, verbose_name_plural
When a tag model is auto-generated from a field, it is given a
verbose_name
based on the tagged model’s name and the tag field’s
name; the verbose_name_plural
is the same, but with an added s
at the end. This is primarily used in the admin.
However, this will sometimes not make grammatical sense; these two arguments can be used to override the field name component of the model name.
The verbose_name_singular
will usually be used with a TagField
-
for example, the auto-generated model for MyModel.tags
will have the
singular name My model tags
; this can be corrected by setting
verbose_name_singular="tag"
in the field definition.
The verbose_name_plural
will usually be used with a SingleTagField
-
for example, the auto-generated model for MyModel.category
will have the
plural name My model categorys
; this can be corrected by setting
verbose_name_plural="categories"
in the field definition.
If one or both of these are not set, Tagulous will try to find the field
name from its verbose_name
argument, falling back to the field name.
Note
When Tagulous automatically generates verbose names, it intentionally
performs no checks on how long they will be. When Django attempts to create
permissions for the model, if the generated verbose name is longer than 39
characters, it may raise a ValidationError
. To resolve this, set
verbose_name_singular
to a string which is 38 characters or less.
Form Options
The following options are used by form fields:
The TagOptions Class
The TagOptions
class is a simple container for tag options. The options for
a model field are available from the tag_options
property of unbound
tagulous.models.SingleTagField or tagulous.models.TagField fields.
All options listed in Model Options are available directly on the
object, except for to
. It also provides two instance methods:
items(with_defaults=True)
Get a dict of all options
If with_defaults is true, any missing settings will be taken from the defaults in
constants.OPTION_DEFAULTS
.form_items(with_defaults=True)
Get a dict of just the options for a form field.
If with_defaults is true, any missing settings will be taken from the defaults in
constants.OPTION_DEFAULTS
.
Example:
initial_tags = MyModel.tags.tag_options.initial
if "force_lowercase" in MyModel.tags.tag_options.items():
...
TagOptions
instances can be added together to create a new merged set of
options; note though that this is a shallow merge, ie the value of
autocomplete_settings
on the left will be replaced by the value on the
right:
merged_options = TagOptions(
autocomplete_settings={'width': 'resolve'}
) + TagOptions(
autocomplete_settings={'allowClear': True}
)
# merged_options.autocomplete_settings == {'allowClear': True}
In the same way, setting autocomplete_settings
on the field will replace
any default value.