Diazo Documentation Release 1.0B1

Diazo Documentation Release 1.0b1 Plone Foundation November 01, 2013 CONTENTS 1 Introduction 3 2 Quickstart 5 3 Installation 9 4 Basic syntax 11 4.1 Rule directives.............................................. 11 4.2 Order of rule execution.......................................... 16 4.3 Behaviour if theme or content is not matched.............................. 16 5 Advanced usage 17 5.1 Conditional rules............................................. 17 5.2 Modifying the theme on the fly..................................... 20 5.3 Modifying the content on the fly..................................... 20 5.4 Inline XSL directives........................................... 21 5.5 Doctypes................................................. 21 5.6 XInclude................................................. 21 5.7 Including external content........................................ 22 6 Compilation 25 6.1 Absolute prefix.............................................. 25 6.2 Custom parameters............................................ 26 6.3 Testing the compiled theme....................................... 26 6.4 Compiling the theme in Python code.................................. 26 7 Deployment 29 7.1 Plone................................................... 29 7.2 WSGI................................................... 29 7.3 Nginx................................................... 31 7.4 Varnish.................................................. 33 7.5 Apache.................................................. 33 8 Contributing to this documentation 35 9 Contributing to Diazo 37 10 Recipes 39 10.1 Drop empty tags............................................. 39 10.2 Insert wrapping element......................................... 40 i 10.3 Adding an attribute to elements..................................... 41 10.4 Modifying an attribute.......................................... 43 10.5 Modifying text.............................................. 43 10.6 Create an unordered list from a series of elements............................ 44 10.7 Contributing a recipe........................................... 46 ii Diazo Documentation, Release 1.0b1 di-az-o (also di-az-o-type) noun a copying or coloring process using a diazo compound decomposed by ultraviolet light Diazo allows you to apply a theme contained in a static HTML web page to a dynamic website created using any server-side technology. With Diazo, you can take an HTML wireframe created by a web designer and turn it into a theme for your favourite CMS, redesign the user interface of a legacy web application without even having access to the original source code, or build a unified user experience across multiple disparate systems, all in a matter of hours, not weeks. When using Diazo, you will work with syntax and concepts familiar from working with HTML and CSS. And by allowing you seamlessly integrate XSLT into your rule files, Diazo makes common cases simple and complex require- ments possible. Contents: CONTENTS 1 Diazo Documentation, Release 1.0b1 2 CONTENTS CHAPTER ONE INTRODUCTION Consider a scenario where you have a dynamic website, to which you want to apply a theme built by a web designer. The web designer is not familiar with the technology behind the dynamic website, and so has supplied a static HTML wireframe of the site. This consists of an HTML file with more-or-less semantic markup, one or more style sheets, and perhaps some other resources like images or JavaScript files. Using Diazo, you could apply this theme to your dynamic website as follows: 1. Identify the placeholders in the theme file that need to be replaced with dynamic elements. Ideally, these should be clearly identifiable, for example with a unique HTML id attribute. 2. Identify the corresponding markup in the dynamic website. Then write a “replace” or “copy” rule using Diazo’s rules syntax that replaces the theme’s static placeholder with the dynamic content. 3. Identify markup in the dynamic website that should be copied wholesale into the theme. CSS and JavaScript links in the <head /> are often treated this way. Write an Diazo “append” or “prepend” rule to copy these elements over. 4. Identify parts of the theme and/or dynamic website that are superfluous. Write an Diazo “drop” rule to remove these elements. The rules file is written using a simple XML syntax. Elements in the theme and “content” (the dynamic website) can be identified using CSS3 or XPath selectors. Once you have a theme HTML file and a rules XML file, you compile these using the Diazo compiler into a single XSLT file. You can then deploy this XSLT file with your application. An XSLT processor (such as mod_transform in Apache) will then transform the dynamic content from your website into the themed content your end users see. The transformation takes place on-the-fly for each request. Bear in mind that: • You never have to write, or even read, a line of XSLT (unless you want to). • The XSLT transformation that takes place for each request is very fast. • Static theme resources (like images, stylesheets or JavaScript files) can be served from a static webserver, which is normally much faster than serving them from a dynamic application. • You can leave the original theme HTML untouched, which makes it easier to re-use for other scenarios. For example, you can stitch two unrelated applications together by using a single theme file with separate rules files. This would result in two compiled XSLT files. You could use location match rules or similar techniques to choose which one to invoke for a given request. We will illustrate how to set up Diazo for deployment later in this guide. 3 Diazo Documentation, Release 1.0b1 4 Chapter 1. Introduction CHAPTER TWO QUICKSTART There are several ways to use Diazo: • If you want to theme Plone, you should use plone.app.theming • If you want to theme a Python WSGI application, you can use the WSGI middleware component described here and in more detail in Deployment. • If you want to theme just about anything, you can deploy a compiled theme to nginx or another web server To test Diazo, however, the easiest way is to set up a simple proxy. The idea is to run a local webserver that applies the Diazo theme to a response coming from an existing website, either locally or somewhere on the internet. To set up the proxy, we will use Buildout. 1. Create a directory for the buildout: $ mkdir diazo-test 2. Download the latest Buildout bootstrap.py and put it in this directory: $ cd diazo-test $ wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py 3. Create a buildout.cfg in this directory with the following contents. Please read the inline comments and adjust your copy as necessary: [buildout] # Adjust the version number as required. See # http://good-py.appspot.com/release/diazo for a full list extends = http://good-py.appspot.com/release/diazo/1.0b1 versions = versions # Uncomment the ‘lxml‘ line if you are on OS X or want to compile your # own lxml binary egg on Linux. This will not work on Windows. parts = # lxml diazo [diazo] recipe = zc.recipe.egg eggs = diazo [wsgi] PasteScript 5 Diazo Documentation, Release 1.0b1 [lxml] recipe = z3c.recipe.staticlxml egg = lxml 4. Bootstrap the buildout (this is only required once): $ python bootstrap.py Note: You should use a Python binary version 2.6 or above. Python 3 is currently untested and may not work. 5. Run the buildout (this is required each time you change buildout.cfg): $ bin/buildout You should now have the binaries bin/paster, bin/diazocompiler, bin/diazorun and maybe a few others. 6. Place the theme in a directory. The theme is a static HTML design, usually with placeholder content and images, stylesheets and JavaScript resources included via relative links. You would normally be able to test the theme by opening it from the filesystem. For the purposes of this quick-start guide, we’ll create a very simple theme: $ mkdir theme In the theme directory, we place a theme.html: <html> <head> <title>My own Diazo</title> <link rel="stylesheet" href="./theme.css" /> </head> <body> <h1 id="title">My own Diazo home page</h1> <div id="content">  Lorem ipsum ... </div> </body> </html> We also create theme.css: h1 { font-size: 18pt; font-weight: bold; } .headerlink { color: #DDDDDD; font-size: 80%; text-decoration: none; vertical-align: top; } .align-right { float: right; margin: 0 10px; border: dotted #ddd 1px; } 6 Chapter 2. Quickstart Diazo Documentation, Release 1.0b1 7. Create the rules file. The rules file contains the Diazo directives that merge the content (the thing we are applying the theme to) into the theme, replacing placeholders with real content. For this example, we’ll theme diazo.org, copying in the .content area and dropping the indices and tables. We create rules.xml at the top level (next to buildout.cfg): <rules xmlns="http://namespaces.plone.org/diazo" xmlns:css="http://namespaces.plone.org/diazo/css" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> <theme href="theme/theme.html" /> <drop css:content="#indices-and-tables" /> <replace css:theme-children="#content" css:content-children=".content" /> </rules> See Basic syntax for details about the rules syntax. Hint: Use tools like Firefox’s Firebug or Chrome’s Developer Tools to inspect the theme and content pages, looking for suitable ids and classes to build the rules from. 8. Create the configuration file for the proxy server. This uses the Paste Deploy toolset to set up a WSGI application. At the top level (next to buildout.cfg), we create proxy.ini: [server:main]

Diazo Documentation Release 1.0B1

Details

Download

Copyright

We respect the copyrights and intellectual property rights of all users. All uploaded documents are either original works of the uploader or authorized works of the rightful owners.

Support