Changes between Version 16 and Version 17 of GenshiFaq
- Timestamp:
- Aug 24, 2006, 7:47:46 PM (18 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
GenshiFaq
v16 v17 5 5 [[PageOutline(2-3, Overview, inline)]] 6 6 7 == What is Markup? == 7 == General == 8 9 === What is Markup? === 8 10 9 11 We like to call it a ''“toolkit for stream-based generation of markup for the web”''. The largest feature provided by Markup is an XML-based template engine that is heavily inspired by [http://kid-templating.org/ Kid]. 10 12 11 == Why yet another template engine?==13 === Why yet another template engine? === 12 14 13 15 We'll let Ryan Tomayko, the author of Kid, answer this one: … … 20 22 See his article [http://naeblis.cx/rtomayko/2004/11/30/pythonic-xml-based-templating-language “In search of a Pythonic, XML-based Templating Language”] for the details. 21 23 22 == Why XML-based?==24 === Why XML-based? === 23 25 24 26 Most template engines for web applications are character-stream based: they know nothing about the format of the response body that is being generated. They simply substitute variable expressions, and provide some directives for looping, conditionals, etc. Thus they can be used to generate any kind of textual output, be it HTML, plain text emails, program code, or really anything else. … … 28 30 In addition, text-based templates don't even work all that well for many text formats. Imagine you want to generate a plain text email or an [http://www.ietf.org/rfc/rfc2445.txt iCalendar] file. How do you deal with important concerns such as line-wrapping and white-space in your templates? You may be better off using specialized formatters. 29 31 30 == So then why not just use Kid?==32 === So then why not just use Kid? === 31 33 32 34 We think that Kid represents a huge step forward for XML-based templating in Python. [http://kid-templating.org/language.html#match-templates-py-match Match templates] and the generator-based processing model are extremely powerful concepts. … … 36 38 We felt these problems would best be addressed by developing a new engine form scratch, as opposed to trying to “fix” Kid. 37 39 38 == What are the main differences between Kid and Markup?==40 === What are the main differences between Kid and Markup? === 39 41 40 42 Markup executes templates directly, there's no code generation phase. Expressions are evaluated in a more forgiving way using AST transformation. Template variables are stored on a stack, which means that some variable set in a loop deep in the template won't leak into the rest of the template. And even though Markup doesn't generate Python code for templates, it generally [wiki:MarkupPerformance performs] slightly better than Kid (even up to 2x in [source:/trunk/examples/basic/ some of our tests], but the exact differences depend on a lot of factors). … … 44 46 For more details about what's different see MarkupVsKid. 45 47 46 == What other stuff is in the toolkit?==48 === What other features does the toolkit provide? === 47 49 48 50 Beyond the template engine, Markup provides: … … 53 55 * An HTML “sanitizing” filter to strip potentially dangerous elements or attributes from user-submitted HTML markup. 54 56 55 == Why use includes instead of inheritance?==57 === Why use includes instead of inheritance? === 56 58 57 59 We think that includes are both simpler and more natural for templating. … … 63 65 ''See also MarkupRecipes/PyExtendsEquivalent and MarkupRecipes/PyLayoutEquivalent to find out how the Kid directives `py:extends` and `py:layout` map to includes in Markup.'' 64 66 65 == What do I need to use Markup? == 67 [[Image(http://static.edgewall.org/gfx/opensource-75x65.png, width=75, height=65, align=right)]] 68 === What license governs the use of Markup? === 69 70 Markup is released under the [wiki:License revised BSD license], which is a liberal open source license that has been [http://opensource.org/licenses/bsd-license.php approved] by the [http://opensource.org/ Open Source Initiative (OSI)]. 71 72 === What do I need to use Markup? === 66 73 67 74 Python 2.3 or later. Python 2.4 is recommended for better performance, plus error messages will include template line numbers and column offsets. [http://peak.telecommunity.com/DevCenter/setuptools Setuptools] is optional and only used for installation if it's available. 68 75 69 76 The template engine plugin (for http://www.turbogears.org/docs/plugins/template.html), which enables usage of Markup in frameworks such as [http://www.turbogears.com/ TurboGears], depends on Setuptools at runtime and installation time. Use of the plugin implementation is optional, though: Setuptools is ''not'' required for using Markup directly. 77 78 79 == Usage == 80 81 === How can I include literal XML in template output? === 82 83 Unless explicitly told otherwise, Markup escapes any data you substitute into template output so that it is safe for being parsed and displayed by web browsers and other tools. This saves you from the work of having to tediously escape every variable by hand, and greatly reduces the risk of introducing vectors for [http://ha.ckers.org/xss.html cross-site scripting (XSS)] attacks. 84 85 However, sometimes what you want is to include text in the template output that should ''not'' get escaped. For example, if you allow users to enter HTML verbatim (or provide a rich-text editor of sorts), you want that HTML to appear as actual markup in the output, not as escaped text. 86 87 Markup provides a number of ways to do that: 88 * The `Markup` class in the [ApiDocs/MarkupCore markup.core] module can be used to flag strings that should not be escaped. Strings wrapped in a `Markup` instance get copied to the output unchanged. 89 * The `XML` and `HTML` functions in the [ApiDocs/MarkupInput markup.input] module parse XML and HTML strings, respectively, and produce a [MarkupStream markup stream]. Note that this option can be rather expensive, as the text needs to be parsed just to be serialized again. Also, this method fails on bad markup that cannot be parsed by either [http://docs.python.org/lib/module-HTMLParser.html HTMLParser] or [http://docs.python.org/lib/module-xml.parsers.expat.html Expat]. 90 * If you are generating the snippets in question yourself, you may want to use the [ApiDocs/MarkupBuilder markup.builder] to [MarkupBuilder generate markup streams programmatically]. Just as the results of the `XML` and `HTML` functions discussed above, the stream produced using `markup.builder` will not be escaped in the template output. 91 92 ---- 93 See also: MarkupGuide, MarkupRecipes
