Re: Reviving the Petal Cookbook
William McKee <[email protected]>
| Newsgroups | gmane.comp.lang.perl.modules.petal |
|---|---|
| Message-ID | <[email protected]> |
On Fri, Jan 21, 2005 at 12:34:15PM +0000, Bruno Postle wrote: > Ok, added to CVS, though I removed the dependency on Petal::Utils. Thanks. One more change which adds a new topic about creating valid documents (I've been dealing with this issue all week as you may have noticed :). Thanks, William -- Knowmad Services Inc. http://www.knowmad.com
Cookbook.pod.diff
(text/plain, 3.6 KB)
Index: Cookbook.pod =================================================================== RCS file: /var/spool/cvs/Petal/lib/Petal/Cookbook.pod,v retrieving revision 1.2 diff -u -r1.2 Cookbook.pod --- Cookbook.pod 21 Jan 2005 12:31:44 -0000 1.2 +++ Cookbook.pod 21 Jan 2005 17:45:19 -0000 @@ -20,7 +20,7 @@ When using Petal for web application development, your templates should not need to be accessible by the webserver. In fact, it could be a security risk if they are available since there may be code or comments which users -should not see prior to processing by Petal. Thus, you should strive to store +should not see prior to processing by Petal. Thus, it is recommended to store your templates in a non-web accessible directory. Personally I prefer to place the directory outside of the web root but you could also use permissions or .htaccess files to control access to the directory. This directory path should @@ -30,8 +30,55 @@ =head2 Template naming -Although not necessary, I like to name my templates with the .tmpl extension -to help myself and designers distinguish templates from static html. +Petal is indifferent about the name of the template files. Personally, I like +to name my templates with the .tmpl extension to help myself and designers +distinguish templates from static html. Some GUI editors, though, will not +open files without a htm/html extension (esp. under Windows). + + +=head2 Fixing invalid templates (Is this XML well-formed?) + +If you are getting a parse_error when trying to process your template, you +will need to clean up your XHTML template in order for Petal to process it. +Two tools will be of great assistance in taking the step towards better +standards compliance--HTML Tidy (L<http://tidy.sf.net>) and xmllint. In +addition, you can use the page validation services at W3C +(L<http://validator.w3.org/>). Alternatively, you could use the +L<Petal::Parser::HTB> module which will parse non well-formed HTML documents +using L<HTML::TreeBuilder>. + +HTML Tidy will rewrite your document into valid XHTML and, if requested, even +replace legacy formatting tags with their CSS counterparts. You can safely +ignore the warnings about proprietary attributes. Be sure to read the output +of what HTML Tidy is doing or else you may find it removing important tags +which it thinks are empty or invalid (e.g., inline elements outside of a +block). One of the important options that should be set is output_xhtml +(-asxhtml from the command-line). Here's an example of how to use it (see the +documentation for complete details): + + tidy --asxhtml original_file.html > new_file.html + +Once your document is well-formed, you can use xmllint to do day-to-day +checking that it stays well-formed without having to wade through the warnings +that HTML Tidy will generate about proprietary attributes. The following command will check that a document is well-formed: + + xmllint --noout <filename> + +To prevent errors about undefined namespace prefix, be sure to include these +in your template like so: + + <html xmlns="http://www.w3.org/1999/xhtml" + xmlns:petal="http://purl.org/petal/1.0/" + xmlns:metal="http://purl.org/petal/1.0/"> + +You may receive errors from xmllint about unknown entities such as nbsp. These +can be safely ignored. If you find a way to suppress these warnings, please +let us know. In the meantime, you can pass the output through grep to ignore +these bogus warnings:. + + xmllint --noout tmpl/contact_info.tmpl >& grep -v 'Entity' + +Now you have no excuse for not creating well-formed XHTML documents. =head2 Passing a hashreference to Petal::process