Markup¶
How it works¶
Every time user save new post, message parsed by markup parser to it’s html representation. It will include only allowed by engine html tags, html tags should be html-encoded and rendered as simple text to prevent XSS attacks.
Pybbm includes two default engines. Actions needed to use these engines:
- bbcode engine: install required package with
pip install bbcode
command and set PYBB_MARKUP to'bbcode'
- markdown engine: install required package with
pip install markdown
command and set PYBB_MARKUP to'markdown'
Engine classes must inherit from pybb.markup.base.BaseParser which defines three required methods:
def format(self, text)
method receives post’s text as parameter and returns parsed message as html fragmentdef quote(self, text, username='')
method receives quoted post’s text and username and returns quoted string in terms of markup enginedef get_widget_cls(cls)
class method which return the class to use as the widget for the body field
How to change¶
If you want to write your custom engine you can write a new class which extends pybb.markup.base.BaseParser
To change behavior of one of the default parsers you can override pybb.markup.bbcode.BBCodeParser
or
pybb.markup.markdown.MarkdownParser
.
For example, for adding additional formatter to bbcode parser you can write your own class in myproject.markup_engines.py:
from pybb.markup.bbcode import BBCodeParser
class CustomBBCodeParser(BBCodeParser):
def __init__(self):
super(CustomBBCodeParser, self).__init__()
self._parser.add_simple_formatter('ul', '<ul>%(value)s</ul>', transform_newlines=False, strip=True)
self._parser.add_simple_formatter('li', '<li>%(value)s</li>', transform_newlines=False, strip=True)
include it in PYBB_MARKUP_ENGINES_PATHS setting dict and point pybbm to use it by PYBB_MARKUP setting:
PYBB_MARKUP_ENGINES_PATHS = {'custom_bbcode': 'myproject.markup_engines.CustomBBCodeParser'}
PYBB_MARKUP = 'custom_bbcode'
or you can override default bbcode engine in settings.py:
PYBB_MARKUP_ENGINES_PATHS = {'bbcode': 'myproject.markup_engines.CustomBBCodeParser'}
PYBB_MARKUP = 'bbcode' # don't required because 'bbcode' is default value
Using different media assets¶
When you define your custom markup parser you may want to control how it will be rendered.
For that purpose pybbm uses django’s concept of widgets
and their media assets.
Widget class used by markup engine controlled by get_widget_cls
class method of engine class.
By default it returns widget_class
attribute value. Pybbm default parsers use next widgets:
- pybb.base.BaseParser - django.forms.Textarea
- pybb.bbcode.BBCodeParser - pybb.bbcode.BBCodeWidget
- pybb.bbcode.MarkdownParser - pybb.markdown.MarkdownWidget
To get it working in your templates include {{ form.media }}
or {{ form.media.css }}
/ {{ form.media.js }}
in proper place in every template where you use post form.