=====================
django-precise-bbcode
=====================
*Django-precise-bbcode* is a Django application providing a way to create textual contents based on BBCodes.
BBCode is a special implementation of HTML. BBCode itself is similar in style to HTML, tags are enclosed in square brackets [ and ] rather than < and > and it offers greater control over what and how something is displayed.
This application includes a BBCode compiler aimed to render any BBCode content to HTML and allows the use of BBCodes tags in models, forms and admin forms. The BBCode parser comes with built-in tags (the default ones ; ``b``, ``u``, etc) and allows the use of smilies, custom BBCode placeholders and custom BBCode tags. These can be added in two different ways:
* Custom tags can be defined in the Django administration panel and stored into the database ; doing this allows any non-technical admin to add BBCode tags by defining the HTML replacement string associated with each tag
* Tags can also be manually registered to be used by the parser by defining a tag class aimed to render a given bbcode tag and its content to the corresponding HTML markup
.. contents:: Table of Contents
:local:
Documentation
-------------
Online browsable documentation is available at https://django-precise-bbcode.readthedocs.org.
Requirements
------------
* Python 3.6+
* Django 3.2+
* PIL or Pillow (required for smiley tags)
Installation
------------
Just run:
::
pip install django-precise-bbcode
Once installed you can configure your project to use *django-precise-bbcode* with the following steps.
Add ``precise_bbcode`` to ``INSTALLED_APPS`` in your project's settings module:
.. code-block:: python
INSTALLED_APPS = (
# other apps
'precise_bbcode',
)
Then install the models:
.. code-block:: shell
python manage.py migrate
Usage
-----
Rendering bbcodes
*****************
*Django-precise-bbcode* comes with a BBCode parser that allows you to transform a textual content containing BBCode tags to the corresponding HTML markup. To do this, simply import the ``get_parser`` shortcut and use the ``render`` method of the BBCode parser::
>>> from precise_bbcode.bbcode import get_parser
>>> parser = get_parser()
>>> parser.render('[b]Hello [u]world![/u][/b]')
'<strong>Hello <u>world!</u></strong>'
*It's that easy!*
As you may need to render bbcodes inside one of your Django template, this parser can be used as a template filter or as a template tag after loading ``bbcode_tags``::
{% load bbcode_tags %}
{% bbcode entry.bbcode_content %}
{{ "[b]Write some bbcodes![/b]"|bbcode }}
The BBCode content included in the ``entry.bbcode_content`` field will be converted to HTML and displayed. The last statement will output ``<strong>Write some bbcodes!</strong>``.
Storing bbcodes
***************
While you can use the Django built-in ``models.TextField`` to add your BBCode contents to your models, a common need is to store both the BBCode content and the corresponding HTML markup in the database. To address this *django-precise-bbcode* provides a ``BBCodeTextField``.
.. code-block:: python
from django.db import models
from precise_bbcode.fields import BBCodeTextField
class Post(models.Model):
content = BBCodeTextField()
This field will store both the BBCode content and the correspondign HTML markup. The HTML content of such a field can then be displayed in any template by using its ``rendered`` attribute:
::
{{ post.content.rendered }}
And more...
***********
Head over to the `documentation <https://django-precise-bbcode.readthedocs.org>`_ for all the details on how to use the BBCode parser and how to define custom BBcode tags, placeholders and smilies.
Authors
-------
Morgan Aubert (`@ellmetha <https://github.com/ellmetha>`_) and contributors_
.. _contributors: https://github.com/ellmetha/django-precise-bbcode/contributors
License
-------
BSD. See ``LICENSE`` for more details.
Raw data
{
"_id": null,
"home_page": "https://github.com/ellmetha/django-precise-bbcode",
"name": "django-precise-bbcode",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "django,bbdode,html",
"author": "Morgan Aubert",
"author_email": "me@morganaubert.name",
"download_url": "https://files.pythonhosted.org/packages/c7/c3/f7dac7c2463060a1c0584c1e368615e88f08e4c27b5d17d8dc3901195933/django_precise_bbcode-1.2.16.tar.gz",
"platform": null,
"description": "=====================\ndjango-precise-bbcode\n=====================\n\n*Django-precise-bbcode* is a Django application providing a way to create textual contents based on BBCodes.\n\n BBCode is a special implementation of HTML. BBCode itself is similar in style to HTML, tags are enclosed in square brackets [ and ] rather than < and > and it offers greater control over what and how something is displayed.\n\nThis application includes a BBCode compiler aimed to render any BBCode content to HTML and allows the use of BBCodes tags in models, forms and admin forms. The BBCode parser comes with built-in tags (the default ones ; ``b``, ``u``, etc) and allows the use of smilies, custom BBCode placeholders and custom BBCode tags. These can be added in two different ways:\n\n* Custom tags can be defined in the Django administration panel and stored into the database ; doing this allows any non-technical admin to add BBCode tags by defining the HTML replacement string associated with each tag\n* Tags can also be manually registered to be used by the parser by defining a tag class aimed to render a given bbcode tag and its content to the corresponding HTML markup\n\n.. contents:: Table of Contents\n :local:\n\n\nDocumentation\n-------------\n\nOnline browsable documentation is available at https://django-precise-bbcode.readthedocs.org.\n\n\nRequirements\n------------\n\n* Python 3.6+\n* Django 3.2+\n* PIL or Pillow (required for smiley tags)\n\nInstallation\n------------\n\nJust run:\n\n::\n\n pip install django-precise-bbcode\n\nOnce installed you can configure your project to use *django-precise-bbcode* with the following steps.\n\nAdd ``precise_bbcode`` to ``INSTALLED_APPS`` in your project's settings module:\n\n.. code-block:: python\n\n INSTALLED_APPS = (\n # other apps\n 'precise_bbcode',\n )\n\nThen install the models:\n\n.. code-block:: shell\n\n python manage.py migrate\n\nUsage\n-----\n\nRendering bbcodes\n*****************\n\n*Django-precise-bbcode* comes with a BBCode parser that allows you to transform a textual content containing BBCode tags to the corresponding HTML markup. To do this, simply import the ``get_parser`` shortcut and use the ``render`` method of the BBCode parser::\n\n >>> from precise_bbcode.bbcode import get_parser\n >>> parser = get_parser()\n >>> parser.render('[b]Hello [u]world![/u][/b]')\n '<strong>Hello <u>world!</u></strong>'\n\n*It's that easy!*\n\nAs you may need to render bbcodes inside one of your Django template, this parser can be used as a template filter or as a template tag after loading ``bbcode_tags``::\n\n {% load bbcode_tags %}\n {% bbcode entry.bbcode_content %}\n {{ \"[b]Write some bbcodes![/b]\"|bbcode }}\n\nThe BBCode content included in the ``entry.bbcode_content`` field will be converted to HTML and displayed. The last statement will output ``<strong>Write some bbcodes!</strong>``.\n\nStoring bbcodes\n***************\n\nWhile you can use the Django built-in ``models.TextField`` to add your BBCode contents to your models, a common need is to store both the BBCode content and the corresponding HTML markup in the database. To address this *django-precise-bbcode* provides a ``BBCodeTextField``.\n\n.. code-block:: python\n\n from django.db import models\n from precise_bbcode.fields import BBCodeTextField\n\n class Post(models.Model):\n content = BBCodeTextField()\n\nThis field will store both the BBCode content and the correspondign HTML markup. The HTML content of such a field can then be displayed in any template by using its ``rendered`` attribute:\n\n::\n\n {{ post.content.rendered }}\n\nAnd more...\n***********\n\nHead over to the `documentation <https://django-precise-bbcode.readthedocs.org>`_ for all the details on how to use the BBCode parser and how to define custom BBcode tags, placeholders and smilies.\n\nAuthors\n-------\n\nMorgan Aubert (`@ellmetha <https://github.com/ellmetha>`_) and contributors_\n\n.. _contributors: https://github.com/ellmetha/django-precise-bbcode/contributors\n\nLicense\n-------\n\nBSD. See ``LICENSE`` for more details.\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A django BBCode integration..",
"version": "1.2.16",
"project_urls": {
"Homepage": "https://github.com/ellmetha/django-precise-bbcode",
"Repository": "https://github.com/ellmetha/django-precise-bbcode"
},
"split_keywords": [
"django",
"bbdode",
"html"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4169c207101d7eff5c0c4605371af042983cedd54dfef76d8920cbe1c9968c03",
"md5": "8e816cbba52a7e4d796c667ed9c2d01a",
"sha256": "6fc815c2a52202a6eb5a8bc562b770d760c6af1b719b833541b3b112e71229f2"
},
"downloads": -1,
"filename": "django_precise_bbcode-1.2.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8e816cbba52a7e4d796c667ed9c2d01a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 38643,
"upload_time": "2023-05-28T00:40:33",
"upload_time_iso_8601": "2023-05-28T00:40:33.345024Z",
"url": "https://files.pythonhosted.org/packages/41/69/c207101d7eff5c0c4605371af042983cedd54dfef76d8920cbe1c9968c03/django_precise_bbcode-1.2.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c7c3f7dac7c2463060a1c0584c1e368615e88f08e4c27b5d17d8dc3901195933",
"md5": "6ef0849f47474bb8f01f98faf3904671",
"sha256": "f3c9d38a3fe8d8495d0f742128aaa17a1922e71d7542597f1125b27736f7d67a"
},
"downloads": -1,
"filename": "django_precise_bbcode-1.2.16.tar.gz",
"has_sig": false,
"md5_digest": "6ef0849f47474bb8f01f98faf3904671",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 27270,
"upload_time": "2023-05-28T00:40:35",
"upload_time_iso_8601": "2023-05-28T00:40:35.640950Z",
"url": "https://files.pythonhosted.org/packages/c7/c3/f7dac7c2463060a1c0584c1e368615e88f08e4c27b5d17d8dc3901195933/django_precise_bbcode-1.2.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-28 00:40:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ellmetha",
"github_project": "django-precise-bbcode",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "django-precise-bbcode"
}
JSON
