Changeset 2147 in main for trunk/docs


Ignore:
Timestamp:
03/11/13 17:21:43 (6 years ago)
Author:
pcosquer
Message:

docs: richtext: explain how to add a new syntax

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/docs/en/devel/richtext.rst

    r2145 r2147  
    1 .. versionadded:: 1.3 
    2  
    31========================================================== 
    42Rich text | Wiki syntax 
    53========================================================== 
     4 
     5.. versionadded:: 1.3 
    66 
    77 
     
    160160========================= 
    161161 
    162  
    163162.. warning:: 
    164163 
    165     Safe mode 
     164    Be careful, markup libraries may have features that allow raw HTML to be 
     165    included, and that allow arbitrary files to be included. These can lead to 
     166    XSS vulnerabilities and leaking of private information. It is your 
     167    responsibility to check the features of the library you are using and 
     168    configure it appropriately to avoid this. 
     169 
     170 
     171To add a new syntax, you only have to write one function that 
     172will convert the content. 
     173This function is registered by the :setting:`RICHTEXT_FILTER` setting 
     174which must be the complete python path to the function 
     175(``application.module.function_name``). 
     176OpenPLM will automatically import the module and call the function instead 
     177of the default implementation. 
     178 
     179 
     180The function must take two arguments: 
     181 
     182    * the content to convert 
     183    * the current object 
     184 
     185It must return a unicode string which should mark as safe if it 
     186is a safe html content. 
     187 
     188Example:: 
     189 
     190    # apps/my_filter/filters.py 
     191    from django.utils.safestring import mark_safe 
     192 
     193    def my_filter(content, obj): 
     194        # do something with content 
     195        html = f(content) 
     196        return mark_safe(html) 
     197 
     198:: 
     199 
     200    # settings.py 
     201    RICHTEXT_FILTER = 'openPLM.apps.my_filter.filters.my_filter' 
     202 
     203 
     204Then you can define two additional settings: 
     205 
     206   * :setting:`RICHTEXT_PLAIN_FILTER` which should be a 
     207     path to function. 
     208     This function is similar to the previous filter except it 
     209     must return a plain text without any HTML tags (content 
     210     is escaped by openPLM). 
     211     The default implementation cleans up the HTML code. 
     212 
     213   * :setting:`RICHTEXT_WIDGET_CLASS` which should be a 
     214     path to a widget class. 
     215 
     216 
     217For example, the markdown widget is defined like this:: 
     218 
     219    from django import forms 
     220 
     221    class MarkdownWidget(forms.Textarea): 
     222        class Media: 
     223            css = { 
     224                'all': ('css/jquery.markedit.css',) 
     225            } 
     226            js = ('js/showdown.js', 'js/jquery.markedit.js', ) 
     227 
     228        def __init__(self): 
     229            super(MarkdownWidget, self).__init__() 
     230            self.attrs["class"] = "markedit" 
     231 
     232As you can see, it defines extra css and js files. 
     233It also sets the class attribute of the textarea so that 
     234the javascript can easily treat the textarea 
     235(here, ``$(".markedit").markedit()``). 
     236 
     237 
Note: See TracChangeset for help on using the changeset viewer.