Blog

This post is a recap of the video training embedded above and located at: http://youtu.be/3ETufV1OfpM

In this training, we are going to learn about the Diazo Syntax.

A Sample Rule

<replace css:theme-children=".mainNav"
   css:content-children="#portal-globalnav"/>

So here's a sample rule that you would see in a rules.xml: Here we are doing a replace of the .mainNav div from the theme and we are placing everything inside of it with everything inside of #portal-globalnav from the content, which would be the Plone site.

Selectors

Now to get more in depth, you can see the two selectors here. We have the theme selector and content selector. The theme is going to specify the element in the static theme that we are going to replace and content is going to specify what we are taking from the Plone site. By default, these use an X-path selector. Myself, I'm more familiar with CSS, so I use CSS selectors. To do that, you just have to add the css: prefix. In the example, you can see the css:theme and css:content. And to the end of each of these for this particular rule, I've used -children, and that's going to take everything inside of the selected element not including the element itself.

Other Attributes

<copy css:theme=".homeLink" css:content="#portal-logo"
 attributes="href" method="raw"/>

One attribute you can use in your rules is one simply called attributes. This determines which tag attributes to <copy>, <merge>, or <drop>. You can see the attribute specified is href, so I'm going to be taking the href attribute from #portal-logo in the Plone site and applying it to .homeLink in my theme. Then the next attribute is method. The value that you set for this is raw, and this forces the rule to run on the unmodified content. So if you have other rules that do things to #portal-logo, you might need to run method="raw" to make sure this rule is run first.

Also not mentioned in the video is the href attribute. It allows you to choose a location where the content is pulled from. It can be a relative path if from a specific location in the Plone site, and can even be an external URL (use with caution!). This attribute can come in handy when building a custom homepage template.

Conditions

<replace css:theme="article"
  css:content-children="#content"
  css:if-not-content="#content-core"/>

Conditions can be added to the rules to determine when the rules are run. We have if, if-path, and if-content. if is applied based on a preset variable (blog post on variables coming soon!).

You can specify if-path, and this is based on a location on the site. So if you want to make a set of rules that only applies to the news section, you would use if-path="/news".

if-content is a selector checking for elements in the Plone site. So the rule will only run if the specified element is within the content of the current page.

You can add not: into the selector for any of these, so you can do if-not:, if-not-path:, or if-not-content: to do the opposite.

Rule Rules

Now, rules for how these rules are run.

<replace css:theme="article"
  css:content-children="#content-core"/>

If a rule does not match the theme, then it is silently ignored. So in this example here, if I don't actually have anything in my theme called article, then this rule is completely ignored and passed by.

If a rule does not match the content, then the element is dropped from the theme. So in this example here, if there's not a #content-core in the content, then article will be completely dropped from the theme and will not display on the site.

It can also be helpful to know that rules can be nested, you can put several <rule> tags inside of each other with different conditions.

Inserting HTML

<replace css:content="#form-widgets-email">
  <input type="text" value=""
     placeholder="jdoe@domain.com"
     class="text-widget textline-field"
     name="form.widgets.email"
     id="form-widgets-email" />
</replace>

You can also insert HTML in the rules. You can see in this example here, I'm going to replace the #form-widgets-email field from within the Plone content. Basically, I'm just replacing it with a different input. Note that when making changes to the content from Plone, only <replace> can be used

Learn More about Diazo

You can learn more at Diazo.org and we also have more training available in our Plone How-To section.