============
Introduction
============

Features
========

* Easy to install - simple requirements, **simple syntax**, lots of options
* Based on ForeignKey and ManyToManyField, so it's **easy to query**
* **Autocomplete** support built in, if you want it
* Supports multiple **independent fields** on a single model
* Supports **trees of nested tags**, for detailed categorisation
* Admin support for managing tags and tagged models

See :doc:`<comparison>` for a comparison with other tagging libraries.


.. _quickstart:

Quickstart
==========

Install with ``pip install django-tagulous``, add ``tagulous`` to Django's
``INSTALLED_APPS`` and :doc:`define the serializers <installation>`, then start adding
tag fields to your model::

    from django.db import models
    from tagulous.models import SingleTagField, TagField

    class Person(models.Model):
        name = models.CharField(max_length=255)
        title = SingleTagField(initial="Mr, Mrs, Miss, Ms")
        skills = TagField()

A ``SingleTagField`` is based on a ``ForeignKey``, and a ``TagField`` is based
on a ``ManyToManyField``.

They have relationships to a ``TagModel``, which is automatically created for you if you
don't specify one.

Assign strings to the fields to create new tags::

    myperson = Person.objects.create(name='Bob', title='Mr', skills='run, hop')
    # myperson.skills == 'run, hop'
    myperson.skills = ['jump', 'kung fu']
    myperson.save()
    # myperson.skills == 'jump, "kung fu"'
    runners = Person.objects.filter(skills='run')

Use them like a normal Django relationship in your queries::

    qs = MyRelatedModel.objects.filter(
        person__skills__name__in=['run', 'jump'],
    )

As well as this you also get:

* tag field support in public :doc:`forms <forms>` and the :doc:`admin <admin>`
  site, including autocompletion
* easy to build :ref:`tag clouds <tag_clouds>`
* ability to nest tags in :doc:`trees <models/tag_trees>` for more complex
  categorisation

Take a look at the :doc:`usage` to see what else you can do, or read on through
the :doc:`documentation <index>` to see exactly how everything works.


Glossary
========

This documentation uses a few terms to explain the ways tags are stored and
set:

Tagged model
    A model which has been tagged using :doc:`models/fields`.

Tag model
    A model where the tag definition is stored. It must be a subclass of
    :ref:`tagmodel`, but will be auto-generated by a tag field if it is not
    explicitly set.

Tag
    An instance of a tag model

Tag name
    The unique name of a tag, eg ``"run"``. This is the value stored on the
    ``name`` attribute of a tag model.

Tag string
    A tag string is a list of tag names stored in a single string, in tag
    format, eg ``"run, jump, hop"``. The format of this string is defined
    by the :doc:`parser`.