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
...
)
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 3 required positional arguments:
- Instance of the targeted model.
- User object.
- Request 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 request %}
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)
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 modelapp_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 is100(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
flagfolder 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 and create some intial data
(venv) $ python manage.py migrate
# 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¶
Features
- Confirm support for python
3.10.
v1.2.0 (2021-06-19)¶
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 (2021-05-01)¶
Bug fixes
- Handle Warning for
default_app_configin django >=3.2.
Features
- Move metadata from
setup.pytosetup.cfg. - this means the
__version__string is no longer available. To use the installed versions, you may useimportlib.metadata.version['django_flag_app'].
- this means the
- Move metadata from
v1.0.1 (2021-03-11)¶
Bug fixes
- Circular import caused by the use of
get_user_modelat modular level inflag.managers. - Version number according to PEP440