Site-wide adds a definition or a link for specialized terms.
- Django (tested with 1.4)
- django-ckeditor (tested with 3.6.2.1) to type the definition in a beautiful GUI
- django-reversion (tested with 1.6.0) to recover changes and deletions
- django-CMS (tested with 2.3) because django-terms has an apphook and a menu
- django-haystack (tested with 2.0.0-beta) because django-terms has a search index
- django.contrib.sitemaps because django-terms has a sitemap
[sudo] pip install django-terms
- Add
'terms',
to yourINSTALLED_APPS
- Add terms to your urls:
- add
url(r'^terms/', include('terms.urls')),
to your urls.py - or, if you are using django-CMS, add a page and use the apphook and menu
- add
- Add some terms in the admin
- Choose how django-terms should apply to your website:
- Global use (to give django-terms a try or for development)
- Local use (for production)
The added terms should now be automatically linked to their definitions.
A middleware is available to automatically add links on all your website. It is not recommended to use it in production because it parses and rebuilds whole pages, which can be an overkill in most cases (even though django-terms has excellent performances).
It is also perfect for development: it never fails silently, unlike filters (see Exceptions for more details).
- Add
'terms.middleware.TermsMiddleware',
to yourMIDDLEWARE_CLASSES
- If the middleware applies to unwanted Django applications, HTML tags, classes, or IDs, set the corresponding Common settings
A template filter is available to add links only on desired parts of your website.
Note
If an error occurs, like every filter, it will fail silently. If this filter mysteriously has no effect, remove it, use the middleware, switch to DEBUG
mode and see Exceptions.
- Choose one of your existing templates
- Add
{% load terms %}
to the beginning of the file (just after{% extends '[file]' %}
if you have one) - Use the filter
replace_terms
like every normal filter - If the filter applies to unwanted HTML tags, classes, or IDs, set the corresponding Common settings
Example:
Suppose you have such a template:
{% extends 'base.html' %} {% block article_header %} {{ article.header }} {% endblock %} {% block article_content %} {{ article.section1 }} {{ article.section2 }} {% endblock %}
Here is how you can modify it:
{% extends 'base.html' %} {% load terms %} {% block article_header %} {{ article.header|replace_terms }} {% endblock %} {% block article_content %} {% filter replace_terms %} {{ article.section1 }} {{ article.section2 }} {% endfilter %} {% endblock %}
Now, suppose you have an HTML class
code-snippet
inarticle.section2
where you do not want to add links on terms. Go to Common settings, and you will find the solution:Add this line in `settings.py`:
TERMS_ADDITIONAL_IGNORED_CLASSES = ['code-snippet']
- Default
()
- Definition
A list or tuple of ignored Django applications (expressed as strings)
- Used in
- Extends
- Syntax example
['cms']
- Default
()
- Definition
A list or tuple of ignored HTML tags (expressed as strings)
- Used in
- Extends
- Syntax example
['h1', 'h2', 'h3', 'footer']
- Default
()
- Definition
A list or tuple of ignored HTML classes (expressed as strings)
- Used in
- Extends
- Syntax example
['footnote', 'text-caption']
- Default
()
- Definition
A list or tuple of ignored HTML IDs (expressed as strings)
- Used in
- Extends
- Syntax example
['article-footer', 'side-content']
- Default
True
- Definition
If set to True, add a link only on the first occurrence of each term
- Used in
These settings should not be used, unless you know perfectly what you are doing.
- Default
see terms/settings.py
- Definition
A list or tuple of ignored Django applications (expressed as strings)
- Used in
- Default
see terms/settings.py
- Definition
A list or tuple of ignored HTML tags (expressed as strings)
- Used in
- Default
see terms/settings.py
- Definition
A list or tuple of ignored HTML classes (expressed as strings)
- Used in
- Default
see terms/settings.py
- Definition
A list or tuple of ignored HTML IDs (expressed as strings)
- Used in
When using django-terms, your HTML pages are totally or partially reconstructed:
- totally reconstructed if you use the middleware (see Global Use)
- partially reconstructed if you use the filter (see Local Use)
The content is parsed with HTMLParser, then rebuilt. See NeutralHTMLReconstructor
and TermsHTMLReconstructor
in tems/html.py to understand exactly how it is rebuilt.
A few side effects are therefore happening during HTML reconstruction:
- Entity names and numbers (e.g.
é
,é
, …) are unescaped. This means they are replaced with their unicode characters (e.g.é
->é
) - Additional spaces inside HTML tags are stripped:
- Start tags
<a href = "url" >
-><a href="url">
- End tags
</ a >
-></a>
- “Start-end” tags
<input style = "text" />
-><input style="text" />
- Start tags
Warning
This implies one bad side effect: the unescaping breaks the special characters rendering in some complex form fields like django-ckeditor. django.contrib.admin is already ignored, so you should not encounter any problem. Otherwise, using filters instead of the middleware and/or ignore the correct apps/tags/classes/ids using Common settings will ensure a proper rendering.
These exceptions are only happening in Global use, since Django filters should always fail silently.
- Raised in
DEBUG
mode. Otherwise the page is ignored by django-terms.- Reason
This happens when django-terms is unable to resolve the current
request.path
to determine whether the application of the current page is in TERMS_IGNORED_APPS.- Encountered
In django-CMS 2.3, when adding a plugin in frontend editing.
- Raised in
DEBUG
mode. Otherwise we try to make terms replacements work anyway.- Reason
This happens when django-terms finds a problem in the architecture of the current HTML page.
- Encountered
If you forget the final
/
of a “start-end” tag.
Localization is done directly on our Transifex page. There is no access restriction, so feel free to spend two minutes translating django-terms to your language :o)
- Make sure you have transifex-client installed:
[sudo] pip install transifex-client
- Pull all translations from Transifex:
tx pull -a
- Compile them:
cd terms && django-admin.py compilemessages