Site-wide adds a definition or a link for specialized terms.

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for BertrandBordage from gravatar.com BertrandBordage

Unverified details

These details have not been verified by PyPI
Project links
Meta
Classifiers

Project description

Site-wide adds a definition or a link for specialized terms.

Requirements

Mandatory

Optional

Installation

  1. [sudo] pip install django-terms

  2. Add 'terms', to your INSTALLED_APPS

  3. ./manage.py syncdb (./manage.py migrate terms if you use South)

  4. 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

Usage

  1. Add some terms in the admin

  2. Choose how django-terms should apply to your website:

The added terms should now be automatically linked to their definitions.

Middleware

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).

  1. Add 'terms.middleware.TermsMiddleware', to your MIDDLEWARE_CLASSES

  2. If the middleware applies to unwanted Django applications, HTML tags, classes, or IDs, set the corresponding Common settings

Template filter

A template filter is available to add links only on desired parts of your website.

  1. Choose one of your existing templates

  2. Add {% load terms %} to the beginning of the file (just after {% extends '[file]' %} if you have one)

  3. Use the filter replace_terms like every normal filter

  4. 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 in article.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']

Settings

Common settings

TERMS_ADDITIONAL_IGNORED_APPS

Default:

()

Definition:

A list or tuple of ignored Django applications (expressed as strings)

Used by:

Middleware

Extends:

TERMS_IGNORED_APPS

Syntax example:

['cms']

TERMS_ADDITIONAL_IGNORED_TAGS

Default:

()

Definition:

A list or tuple of ignored HTML tags (expressed as strings)

Used by:

Middleware, Template filter

Extends:

TERMS_IGNORED_TAGS

Syntax example:

['h1', 'h2', 'h3', 'footer']

TERMS_ADDITIONAL_IGNORED_CLASSES

Default:

()

Definition:

A list or tuple of ignored HTML classes (expressed as strings)

Used by:

Middleware, Template filter

Extends:

TERMS_IGNORED_CLASSES

Syntax example:

['footnote', 'text-caption']

TERMS_ADDITIONAL_IGNORED_IDS

Default:

()

Definition:

A list or tuple of ignored HTML IDs (expressed as strings)

Used by:

Middleware, Template filter

Extends:

TERMS_IGNORED_IDS

Syntax example:

['article-footer', 'side-content']

TERMS_REPLACE_FIRST_ONLY

Default:

True

Definition:

If set to True, adds a link only on the first occurrence of each term

Used by:

Middleware, Template filter

TERMS_DEFINITION_WIDGET

Default:

'auto'

Definition:

Explicitly tells django-terms which text widget to choose for the definition of a term. Accepted values are 'auto', 'basic', 'tinymce', and 'ckeditor'.

Advanced settings

These settings should not be used, unless you know perfectly what you are doing.

TERMS_IGNORED_APPS

Default:

see terms/settings.py

Definition:

A list or tuple of ignored Django applications (expressed as strings)

Used by:

Middleware

TERMS_IGNORED_TAGS

Default:

see terms/settings.py

Definition:

A list or tuple of ignored HTML tags (expressed as strings)

Used by:

Middleware, Template filter

TERMS_IGNORED_CLASSES

Default:

see terms/settings.py

Definition:

A list or tuple of ignored HTML classes (expressed as strings)

Used by:

Middleware, Template filter

TERMS_IGNORED_IDS

Default:

see terms/settings.py

Definition:

A list or tuple of ignored HTML IDs (expressed as strings)

Used by:

Middleware, Template filter

Troubleshooting

Side effects

Why?

When using django-terms, your HTML pages are totally or partially reconstructed:

  • totally reconstructed if you use the middleware (see Middleware)

  • partially reconstructed if you use the filter (see Template filter)

The content is parsed with HTMLParser, then rebuilt. See NeutralHTMLReconstructor and TermsHTMLReconstructor in tems/html.py to understand exactly how it is rebuilt.

List of known side effects

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" />

Exceptions

Resolver404

Raised by:

Middleware only.

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.

HTMLValidationWarning

Raised by:

Middleware and Template filter.

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 your HTML page is malformed; if you forget a start tag, an end tag, or the final / of a “start-end” tag.

Translations

Status

https://www.transifex.com/projects/p/django-terms/resource/core/chart/image_png

Write your translation

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)

Get & Compile

  1. Make sure you have transifex-client installed: [sudo] pip install transifex-client

  2. Pull all translations from Transifex: tx pull -a

  3. Compile them: cd terms && django-admin.py compilemessages

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for BertrandBordage from gravatar.com BertrandBordage

Unverified details

These details have not been verified by PyPI
Project links
Meta
Classifiers

Release history Release notifications | RSS feed

1.2.0

1.1.3

1.1.2

1.1.1

1.1.0

1.0.7

1.0.6

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

1.0.0

0.4.9.1

0.4.9

0.4.8

This version

0.4.7

0.4.6

0.4.5

0.4.1

0.4

0.3.2

0.3.1

0.3

0.2.1

0.2

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django-terms-0.4.7.tar.gz (15.2 kB view details)

Uploaded Source

File details

Details for the file django-terms-0.4.7.tar.gz.

File metadata

File hashes

Hashes for django-terms-0.4.7.tar.gz
Algorithm Hash digest
SHA256 781087d54368d25dd1c7604594b41af67cff15bd0e22f7198bd53c05274ffcb6
MD5 18f71435eb462f4f5b459d649653355d
BLAKE2b-256 8d2702dcfc0e2ac684450c5ce17a3229bcdf68444f0841e54de474241a709b43

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page