docs/source/models.rst
ModelWithFlag Model
===================
``siteflags.models.ModelWithFlag`` is practically all that's needed for flagging.
Methods
-------
.. py:method:: get_flags_for_type([mdl_classes=None, [user=None[, status=None[, allow_empty=False]]]]):
Returns a dictionary with flag objects associated with the given model classes (types).
The dictionary is indexed by model classes.
Each dict entry contains a list of associated flag objects.
:param list mdl_classes: Classes objects (types) list to get flags for.
:param User user: Optional user filter
:param int status: Optional status filter
:param bool allow_empty: Include results for all given types, even those without associated flags.
.. py:method:: get_flags_for_objects(objects_list, [user=None[, status=None]]):
Returns a dictionary with flag objects associated with the given objects.
The dictionary is indexed by objects IDs.
Each dict entry contains a list of associated flag objects.
:param list, QuerySet objects_list: Homogeneous objects list to get flags for.
:param User user: Optional user filter
:param int status: Optional status filter
.. py:method:: get_flags([user=None[, status=None]]):
Returns flags for the object optionally filtered by user and/or status.
:param User user: Optional user filter
:param int status: Optional status filter
.. py:method:: set_flag(user[, note=None[, status=None]]):
Flags the object.
:param User user:
:param str note: User-defined note for this flag.
:param int status: Optional status integer (the meaning is defined by a developer).
.. py:method:: remove_flag([user=None[, status=None]]):
Removes flag(s) from the object.
:param User user: Optional user filter
:param int status: Optional status filter
.. py:method:: is_flagged([user=None[, status=None]]):
Returns boolean whether the objects is flagged by a user.
:param User user:
:param int status: Optional status filter
Customization
-------------
SiteFlags allows you to customize Flags model.
1. Define your own ``flag`` model inherited from ``FlagBase``.
2. Now when ``models.py`` in your application has the definition of a custom flags model, you need
to instruct Django to use it for your project instead of a built-in one:
.. code-block:: python
# Somewhere in your settings.py do the following.
# Here `myapp` is the name of your application, `MyFlag` is the names of your customized model.
SITEFLAGS_FLAG_MODEL = 'myapp.MyFlag'
3. Run ``manage.py makemigrations`` and ``manage.py migrate`` to install your customized models into DB.