Welcome to Django Flag App’s documentation!

django-flag-app

A pluggable django application that adds the ability for users to flag(report or moderate) your models.

For complete documentation you may visit Read the Doc. or see the docs directory.

Installation

Install using pip

$ pip install django-flag-app

If you want, you may install it from the source, grab the source code and run setup.py.

$ git clone git://github.com/abhiabhi94/django-flag-app.git
$ cd django-flag-app
$ python setup.py install

Usage

Add app

To enable django_flag_app in your project you need to add it to INSTALLED_APPS in your projects settings.py file:

INSTALLED_APPS = (
    ...
    'flag',
    ...
)

Add URL

In your root urls.py:

urlpatterns = patterns(
        path('admin/', admin.site.urls),
        path('flag/', include('flag.urls')),
        ...
        path('api/', include('flag.api.urls')),  # only required for API Framework
        ...
    )

Migrate

Run the migrations to add the new models to your database:

python manage.py migrate flag

Connect the flag model with the target model

In models.py add the field flags as a GenericRelation field to the required model.

E.g. for a Post model, you may add the field as shown below:

from django.contrib.contenttypes.fields import GenericRelation

from flag.models import Flag


class Post(models.Model):
    user = models.ForeignKey(User)
    title = models.CharField(max_length=200)
    body = models.TextField()
    # the field name should be flags
    flags = GenericRelation(Flag)

Important

the name of the field should be flags.

Use template tag

If you want to use web API, this step is not required. See further instructions at Web API.

render_flag_form tag requires 2 required positional arguments:

1. Instance of the targeted model.
2. User object.

To render the flag form for a the instance post, place this inside your detail view, perhaps in some template of the sort postdetail.html.

{% render_flag_form post user %}

Contributing

Please see the instructions at Contributing.rst.

Web API

django-flag-app uses django-rest-framework to expose a Web API that provides developers with access to the same functionality offered through the web user interface.

The available actions with permitted user are as follows:

• Flag content. (authenticated users)
• Unflag content. (user who has previously flagged that content)

Setup

To integrate the flag API into your app, just follow the instructions as mentioned Usage.

API Actions

All actions can only be performed by authenticated users. Authorization must be provided as a TOKEN or USERNAME:PASSWORD. POST is the allowed method for all requests.

All available actions are explained below:

Flag content

This action can be performed by providing the URL with data queries related to the content type.

The request requires the following parameters:

• model_name: is the model name of the content type that have flags associated with it.
• model_id: is the id of an object of that model
• app_name: is the name of the app that contains the model.
• reason: number corresponding to the reason(e.g. 1, 2, 3).
• info: ‘’ (This is only required if the reason is 100 (Something else))

For example, to flag a content of second object (id=1) of a model (content type) called post inside the app(django app) post. You may do the following:

$ curl -X POST -u USERNAME:PASSWORD -H "Content-Type: application/json" -d "{'app_name': 'post','model_name': 'post', 'model_id': 1,'reason': 1,'info': ''}" http://localhost:8000/api/flag/

Un-Flag Content

To un-flag a FLAGGED content, set reason value to 0 or remove it from the request.

$ curl -X POST -u USERNAME:PASSWORD -H "Content-Type: application/json" -d "{'app_name': 'post','model_name': 'post', 'model_id': 1}" http://localhost:8000/api/flag/

Settings

django-flag-app has a few configuration options that allow you to customize it.

FLAG_ALLOWED

The number of flags allowed before a content is set as flagged. Defaults to 10.

FLAG_REASONS

The reasons for which a content can be flagged. Users will have a choose one of these before they flag a content. This a list of tuples. Defaults to:

from django.utils.translation import gettext_lazy as _

[
    (1, _('Spam | Exists only to promote a service')),
    (2, _('Abusive | Intended at promoting hatred')),
]

Remember that (100, _('Something else') will always be appended to this list.

Style Customization

The flag app has been built in a way that you can customise its look and feel completely. Most of the styles can be customised through HTML classes.

In case, you feel there is some customisation that can be added, feel free to open an issue.

The template structure of the flag app looks something like this:

├── templates
└── flag
    ├── flag_form.html
    └── flag_icon.html

Overriding templates

To customise a template,

• Create flag folder inside templates directory.
• Inside it, create a new template file, giving it the same name as that of the default template that needs to be overridden.

For example, to override the HTML classes of submit button

create templates/flag/flag_form.html (assuming all your templates are placed under the directory templates)

{% extends "flag/flag_form.html" %}

{% block cls_flag_modal_submit %}
my-class
{% endblock cls_flag_modal_submit %}

Blocks

Please refer to this table when using blocks to customise HTML classes

Block	Use	HTML element
{% block cls_flag %}	complete flag element	div
{%  block cls_flag_icon_img %}	flag icon image element	div
{% block cls_flag_modal %}	modal that appears when flagging	div
{% block cls_flag_modal_content %}	modal content	div
{% block cls_flag_modal_close %}	the cross icon(close button) inside the modal	span
{% block cls_flag_modal_form_div %}	the div element containing the modal form	div
{% block cls_flag_modal_form %}	modal form element	form
{% block cls_flag_modal_title %}	the text containing modal title	div
{% block cls_flag_modal_reasons %}	the element that displays reasons for flagging	tr
{% block cls_flag_modal_reason %}	individual reasons	input
{% block cls_flag_modal_info %}	text box which appears when Somthing else is selected	textarea
{% block cls_flag_modal_submit %}	submit button inside the modal	input

Flag Icon

To change the flag icon, just override the template flag_icon.html as explained above. Make sure that you add the property class="flag-icon {% if has_flagged %}user-has-flagged{% else %}user-has-not-flagged{% endif %}" to your HTML element. These classes are used by javascript files.

For other customisation, please refer to the Blocks above

Contributing to Django Flag App

There are many ways to contribute to the project. You may improve the documentation, address a bug, add some feature to the code or do something else. All sort of contributions are welcome.

Development

To start development on this project, fork this repository and follow the following instructions.

# clone the forked repository
$ git clone YOUR_FORKED_REPO_URL

# create a virtual environment
$ python3 -m venv venv
# activate the virtual environment(unix users)
$ . venv/bin/activate
# activate the virtual environment(window users)
$ venv\Scripts\activate
# install dependencies
(venv) $ pip install -e . Django -r testapp/requirements.txt
# migrate the migrations to the database
(venv) $ python manage.py migrate
# create data
(venv) $ python manage.py create_initial_data
# start the development server
(venv) $ python manage.py runserver

Testing

To run tests against a particular python and django version installed inside your virtual environment, you may use:

(venv) $ pytest

To run tests against all supported python and django versions, you may run:

# install dependency
(venv) $ pip install tox
# run tests
(venv) $ tox

Changelog

v1.2.0

Full Changelog

Features

• Add link to the related content object in the admin.
• Dropped support for django 2.1 (this version is not LTS. See supported django versions for more information on this).

v1.1.1

Full Changelog

Bug fixes

• Handle Warning for default_app_config in django >=3.2.

Features

• Move metadata from setup.py to setup.cfg.

  • this means the __version__ string is no longer available. To use the installed versions, you may use importlib.metadata.version['django_flag_app'].

v1.1.0 (2021-04-18)

Full Changelog

Features

• Add support for python3.9 and django3.2

v1.0.1 (2021-03-11)

Full Changelog

Bug fixes

• Circular import caused by the use of get_user_model at modular level in flag.managers.
• Version number according to PEP440

v1.0.0 (2020-11-17)

Full Changelog

Bug fixes

• Fix API response

Features

• Add app settings

v0.1.1 (2020-10-22)

Full Changelog

Bug fixes

• Fix icon title when flagging/unflagging
• Fix template for unauthenticated users

v0.1.0 (2020-09-28)

Full Changelog

• Release first version

Indices and tables

• Index
• Module Index
• Search Page