1. offline
  2. markdown-hg

Commits

Artem Yunusov  committed d71b9de

Writing extensions guide updated.

  • Participants
  • Parent commits 073d04d
  • Branches default

Comments (0)

Files changed (1)

File writing_extensions.txt

View file
  • Ignore whitespace
 any inline elements, and postprocessors which allow munging of the
 output of the parser before it is returned.
 
-As the parser builds an [ElementTree][] DOM object which is later rendered 
+As the parser builds an [ElementTree][] object which is later rendered 
 as Unicode text, there are also some helpers provided to make manipulation of 
-the DOM tree easier. Each part of the API is discussed in its respective 
+the tree easier. Each part of the API is discussed in its respective 
 section below. You may find reading the source of some [[existing extensions]] 
 helpful as well. For example, the [[footnote]] extension uses most of the 
 features documented here.
     * [Line Preprocessors][]
 * [InlinePatterns][]
 * [Postprocessors][]
-    * [DOM Postprocessors][]
+    * [ElementTree Postprocessors][]
     * [TextProstprocessors][]
-* [Working with the DOM][]
+* [Working with the ElementTree][]
 * [Integrating your code into Markdown][]
     * [extendMarkdown][]
     * [Config Settings][]
 core. This is were stored text gets added back in such as a list of footnotes, 
 a table of contents or raw html.
 
-There are two types of postprocessors: [DOM Postprocessors][] and 
+There are two types of postprocessors: [ElementTree Postprocessors][] and 
 [TextPostprocessors][].
 
-<h4 id="dompostprocessors">DOM Postprocessors</h4>
+<h4 id="etpostprocessors">ElementTree Postprocessors</h4>
 
-A DOM Postprocessor should inherit from `markdown.Postprocessor` and over-ride
+A ElementTree Postprocessor should inherit from `markdown.Postprocessor` and over-ride
 the `run` method which takes one argument `root` and should return either
 that root element or a modified root element.
 
         #do stufff
         return my_modified_root
 
-For specifics on manipulating the DOM, see [Working with the DOM][] below.
+For specifics on manipulating the ElementTree, see [Working with the ElementTree][] below.
 
 <h4 id="textpostprocessors">TextPostprocessors</h4>
 
 over-ride the `run` method which takes one argument `text` and returns a
 Unicode string.
 
-TextPostprocessors are run after the DOM has been serialized back into Unicode
+TextPostprocessors are run after the ElementTree has been serialized back into Unicode
 text.  For example, this may be an appropriate place to add a table of contents
 to a document:
 
     def run(self, text):
         return MYMARKERRE.sub(MyToc, text)
 
-<h3 id="working_with_dom">Working with the DOM</h3>
+<h3 id="working_with_et">Working with the ElementTree</h3>
 
 As mentioned, the Markdown parser converts a source document to an 
-[ElementTree][] DOM object before serializing that back to Unicode text. 
+[ElementTree][] ElementTree object before serializing that back to Unicode text. 
 Markdown has provided some helpers to ease that manipulation within the context 
-of the Markdown module...
+of the Markdown module.
+First of all, to get access to the ElementTree module object you should use: 
+
+    import markdown
+    etree = markdown.etree
+    
+It's try to import ElementTree from any known places, first as standard Python 
+cElementTree/ElementTree module, then as separately installed cElementTree/ElementTree.
+Another thing you need to know is that all text data, included in <inline> tag will be
+processed later with [InlinePatterns][].
+
+Example below show basic ElementTree functionality:
+
+    table = etree.Element("table") 
+    table.set("cellpadding", "2") # Set cellpadding to 2
+    tr = etree.SubElement(table, "tr") # Added child tr to table
+    td = etree.SubElement(tr, "td") # Added child td to tr
+    td.text = "Cell content" # Added text content to td element
+    table.tail = "Text after table" # Added text after table Element
+    print etree.tostring(table) # Serialized our table    
+
+Now let's write a simple ElementTree Postprocessor, that will add "class" attribute
+to all "a" elements:
+
+	class AttrPostprocessor(markdown.Postprocessor):
+	    
+	    def _findElement(self, element, name):
+	    """ 
+		find elements with @name and return list 
+		
+		Keyword arguments:
+		
+		* element: ElementTree Element
+		* name: tag name to search
+		
+		""" 
+		result = []
+		for child in element: 
+		    if child.tag == name:
+			result.append(child)
+		    result += self._findElement(child, name)
+		return result
+	    
+	    def run(self, root):
+
+		for element in self._findElement(root, "a"):
+		     element.set("class", "MyClass") # Set "class" atribute
+		     
+		retrun root
+
+For more information about working with ElementTree visit 
+ElementTree [official site](http://effbot.org/zone/element-index.htm).
 
 <h3 id="integrating_into_markdown">Integrating Your Code Into Markdown
 
 [Line Preprocessors]: #linepreprocessors
 [InlinePatterns]: #inlinepatterns
 [Postprocessors]: #postprocessors
-[DOM Postprocessors]: #dompostprocessors
+[ElementTree Postprocessors]: #etpostprocessors
 [TextProstprocessors]: #textpostprocessors
-[Working with the DOM]: #working_with_dom
+[Working with the ElementTree]: #working_with_et
 [Integrating your code into Markdown]: #integrating_into_markdown
 [extendMarkdown]: #extendmarkdown
 [Config Settings]: #configsettings