Summary
-------

The tag cube allows to add labels to an entity as a simple yet
powerful way to classify your content. Tags can be used to refine a
search using facets.

It is a CubicWeb component. CubicWeb is a semantic web application
framework, see http://www.cubicweb.org

Install
-------

Auto-install from sources is preferred with *pip/Distribute*::

  pip install cubicweb-tag

If you have troubles, use *easy_install/setuptools* and eggs::

  easy_install cubicweb-tag

You can install the package manually from the uncompressed
`tarball <http://www.cubicweb.org/project/cubicweb-tag>`_::

  python setup.py install # auto-install dependencies

If you don't want the dependencies to be installed automatically, you
can force the setup to use the standard library *distutils*::

  NO_SETUPTOOLS=1 python setup.py install

More details at http://www.cubicweb.org/doc/en/admin/setup

Usage
-----

To allow tags on an entity type, you must allow the `tags` relation between `Tag`
and your entity type(s).

For instance to activate the tag functionality on Person, Company and Division
entity type, one should add to his schema:

.. sourcecode:: python

   from yams.buildobjs import RelationDefinition
   class tags(RelationDefinition):
       subject = 'Tag'
       object = ('Person', 'Company', 'Division')

You should then see the tags box appearing on the primary view for entities of
those type. The`TagsBox` display tags applied to the entity but also provides
an easily way to add / remove tags, if you've the permission to do so.

More views
----------
- The `SimilarEntitiesBox` shows some entities which share the most tags together

- The `TagsCloudView`, a classical, displaying a set of tags appearing more or
  less big according to the number of tagged entities. It's used by the
  `TagsCouldBox`, which is not visible by default (user can activate it using
  their preferences)  but that you can activate by default using the code snippet below:

  .. sourcecode:: python

    from cubicweb_tag.views import TagsCloudBox
    # make the tags cloud box visible by default
    TagsCloudBox.visible = True

- The primary view for tags provides a tags merging interface to site administrators,
  very useful to manage tags on a site where people tend to express the same thing with
  different words, or spelling.

Documentation
-------------

Look in the ``doc/`` subdirectory or read
http://www.cubicweb.org/doc/en/
