--- html_meta: "description": "" "property=og:description": "" "property=og:title": "" "keywords": "" --- (plone5-zpt-label)= # Page Templates ````{sidebar} Get the code! Code for the beginning of this chapter: ```shell git checkout views_1 ``` Code for the end of this chapter: ```shell git checkout zpt ``` {doc}`code` ```` In this part you will: - Learn to write page templates Topics covered: - TAL and TALES - METAL - Chameleon Page Templates are HTML files with some additional information, written in TAL, METAL and TALES. Page templates must be valid XML. The three languages are: - TAL: "Template Attribute Language" - Templating XML/HTML using special attributes - Using TAL we include expressions within HTML - TALES: "TAL Expression Syntax" - defines the syntax and semantics of these expressions - METAL: "Macro Expansion for TAL" - this enables us to combine, re-use and nest templates together TAL and METAL are written like HTML attributes (href, src, title). TALES are written like the values of HTML attributes. They are used to modify the output: ```html

I love blue

``` results in: ```html

I love red

``` Let's try it. Open the file {file}`training.pt` and add: ```html

red

``` (plone5-zpt-tal-label)= ## TAL and TALES Let's add some magic and modify the \

-tag: ```html

red

``` This will result in: ```html

blue

``` Without restarting Plone open . The same happens with attributes. Replace the \

-line with: ```html A sharepoint conference ``` results in: ```html An even better conference ``` We used three TAL-Attributes here. This is the complete list of TAL-attributes: `tal:define` : define variables. We defined the variable `a_fine_url` to the string `"https://www.ploneconf.org/"`. `tal:content` : replace the content of an element. We replaced the default content above with "An even better conference" `tal:attributes` : dynamically change element attributes. We set the HTML attribute `href` to the value of the variable `a_fine_url` `tal:condition` : tests whether the expression is true or false, and outputs or omits the element accordingly. `tal:repeat` : repeats an iterable element, in our case the list of talks. `tal:replace` : replace the content of an element, like `tal:content` does, but removes the element only leaving the content. `tal:omit-tag` : remove an element, leaving the content of the element. `tal:on-error` : handle errors. (plone5-python-expressions-label)= ### python expressions Till now we only used one TALES expression (the `string:` bit). Let's use a different TALES expression now. With `python:` we can use Python code. A example: ```html

A big title

``` With `context.title` you access information from the context object, that is the object on which the view is called. Modify the template {file}`training.pt` like this ```xml

${python: 'This is the {0} "{1}" at {2}'.format(context.portal_type, context.title, context.absolute_url())}

``` Now call the view on different urls and see what happens: - - - - - And another python-statement: ```html

A talk

``` With python expressions: - you can only write single statements - you could import things but you should not ### tal:condition `tal:condition` : tests whether the expression is true or false. - If it's true, then the tag is rendered. - If it's false then the tag **and all its children** are removed and no longer evaluated. - We can reverse the logic by perpending a `not:` to the expression. Let's add another TAL Attribute to our above example: ``` tal:condition="python:talks" ``` We could also test for the number of talks: ``` tal:condition="python:len(talks) >= 1" ``` or if a certain talk is in the list of talks: ``` tal:condition="python:'Deco is the future' in talks" ``` ### tal:repeat Let's try another attribute: ```html

A talk

``` `tal:repeat` : repeats an iterable element, in our case the list of talks. We change the markup a little to construct a list in which there is an `
  • ` for every talk: ```{code-block} html :linenos:
    • A talk
    • Sorry, no talks yet.
    ``` ### path expressions Regarding TALES so far we used `string:` or `python:` or only variables. The next and most common expression are path expressions. Optionally you can start a path expression with `path:` Every path expression starts with a variable name. It can either be an object like {py:obj}`context`, {py:obj}`view` or {py:obj}`template` or a variable defined by you like {py:data}`talk`. After the variable we add a slash `/` and the name of a sub-object, attribute or callable. The `/` is used to end the name of an object and the start of the property name. Properties themselves may be objects that in turn have properties. ```html

    ``` We can chain several of those to get to the information we want. ```html

    ``` This would return the value of the form dictionary of the HTTPRequest object. Useful for form handling. The `|` ("or") character is used to find an alternative value to a path if the first path evaluates to `nothing` or does not exist. ```html

    ``` This returns the id of the context if it has no title. ```html

    ``` This returns nothing if there is no 'average_rating' for a talk. What will not work is `tal:content="python:talk['average_rating'] or ''"`. Who knows what this would yield? ```{only} not presentation We'll get `KeyError: 'average_rating'`. It is very bad practice to use `|` too often since it will swallow errors like a typo in `tal:content="talk/averange_ratting | nothing"` and you might wonder why there are no ratings later on... You can't and should not use it to prevent errors like a try/except block. ``` There are several **built-in variables** that can be used in paths: The most frequently used one is `nothing` which is the equivalent to None ```html

    this comment will not be rendered

    ``` A dict of all the available variables at the current state is `econtext` ```{code-block} html :linenos:
    ${variable}
    ${python:econtext[variable]}
    ``` Useful for debugging :-) ````{note} In Plone 4 that used to be `CONTEXTS` ```{code-block} html :linenos:
    ``` ```` ### Pure TAL blocks We can use TAL attributes without HTML Tags. This is useful when we don't need to add any tags to the markup. Syntax: ```html some content ``` Examples: ```html ... The id of the template ... This text is only visible if the context is a News Item ``` ### handling complex data in templates Let's move on to a little more complex data. And to another TAL attribute: tal:replace : replace the content of an element and removes the element only leaving the content. Example: ```html

    ``` this results in: ```html

    <img src='https://plone.org/logo.png'>

    ``` `tal:replace` drops its own base tag in favor of the result of the TALES expression. Thus the original `` is replaced. But the result is escaped by default. To prevent escaping we use `structure` ```html

    ``` Now let's emulate a typical Plone structure by creating a dictionary. ```{code-block} html :linenos:
    Title Topics
    A talk
    ``` We emulate a list of talks and display information about them in a table. We'll get back to the list of talks later when we use the real talk objects that we created with dexterity. To complete the list here are the TAL attributes we have not yet used: `tal:omit-tag` : Omit the element tag, leaving only the inner content. `tal:on-error` : handle errors. When an element has multiple TAL attributes, they are executed in this order: 1. define 2. condition 3. repeat 4. content or replace 5. attributes 6. omit-tag ## Chameleon Since Plone 5 we have [Chameleon](https://chameleon.readthedocs.io/en/latest/). Using the integration layer [five.pt](https://pypi.org/project/five.pt) it is fully compatible with the normal TAL syntax but offers some additional features: You can use `${...}` as short-hand for text insertion in pure html effectively making `tal:content` and `tal:attributes` obsolete. Here are some examples: Plone 4 and Plone 5: ```{code-block} html :linenos: The Title of the current object ``` Plone 5 (and Plone 4 with `five.pt`) : ```{code-block} html :linenos: ${python:context.title} ``` You can also add pure python into the templates: ```{code-block} html :linenos:
    This object has the id "${python:someoptions['id']}"" and the title "${python:someoptions['title']}".
    ``` (plone5-zpt-metal-label)= ## Exercise 1 Modify the following template and one by one solve the following problems: \: ```{code-block} html :linenos:
    Title Topics
    A talk
    ``` 1. Display the subjects as comma-separated. ````{admonition} Solution :class: toggle ```{code-block} html :emphasize-lines: 21 :linenos:
    Title Topics
    A talk
    ``` ```` 2. Turn the title in a link to the URL of the talk if there is one. ````{admonition} Solution :class: toggle ```{code-block} html :emphasize-lines: 20 :linenos:
    Title Topics
    A talk
    ``` ```` 3. If there is no URL, turn it into a link to a google search for that talk's title: ````{admonition} Solution :class: toggle ```{code-block} html :emphasize-lines: 20, 21 :linenos:
    Title Topics
    A talk
    ``` ```` 4\. Add alternating the CSS classes 'odd' and 'even' to the \. ({samp}`repeat.{}.odd` is True if the ordinal index of the current iteration is an odd number). > Use some CSS to test your solution: > > ```css > > ``` ````{admonition} Solution :class: toggle ```{code-block} html :emphasize-lines: 19 :linenos:
    Title Topics
    A talk
    ``` ```` 5. Only use python expressions. ````{admonition} Solution :class: toggle ```{code-block} html :linenos:
    Title Topics
    A talk
    ``` ```` 6. Use the syntax of Plone 5 replacing `tal:attribute` and `tal:content` with inline `${}` statements. ````{admonition} Solution :class: toggle ```{code-block} html :emphasize-lines: 20, 24, 28 :linenos:
    Title Topics
    ${python:talk['title']} ${python:', '.join(talk['subjects'])}
    ``` ```` 7. Sort the talks alphabetically by title ````{admonition} Solution :class: toggle ```{code-block} html :emphasize-lines: 19, 21 :linenos:
    Title Topics
    ${python:talk['title']} ${python:', '.join(talk['subjects'])}
    ``` ```{warning} Do not use this trick in your projects! This level of python-logic belongs in a class, not in a template! ``` ```` ## METAL and macros Why is our output so ugly? How do we get our HTML to render in Plone the UI? We use METAL (Macro Extension to TAL) to define slots that we can fill and macros that we can reuse. Add this to the `` tag: ``` metal:use-macro="context/main_template/macros/master" ``` And then wrap the code we want to put in the content area of Plone in: ```xml ... ``` This will put our code in a section defined in the main_template called "content-core". Now replace the `main` in `fill-slot="main"` with `content-core` and see what changes. The template should now look like below when we exclude the last exercise. Here also added the css-class `listing` to the table. It is one of many css-classes used by Plone that you can reuse in your projects: ```{code-block} xml :linenos:
    Title Topics
    ${python:talk['title']} ${python:', '.join(talk['subjects'])}
    ``` ### macros in browser views Define a macro in a new file {file}`macros.pt` ```html

    I can be reused

    ``` Register it as a simple BrowserView in zcml: ```xml ``` Reuse the macro in the template {file}`training.pt`: ```html
    Instead of this the content of the macro will appear...
    ``` Which is the same as: ```html
    Instead of this the content of the macro will appear...
    ``` Restart your Plone instance from the command line, and then open to see this macro being used in our @@training browser view template. (plone5-tal-access-plone-label)= ## Accessing Plone from the template In the template you have access to: - the **context** object on which your view is called on - the **view** (and all python methods we'll put in the view later on) - the **request** With these three you can do almost anything! Create a new talk object "Dexterity for the win!" and add some information to all fields, especially the speaker and the email-address. Now access the view `training` on that new talk by opening in the browser. It will look the same as before. Now modify the template {file}`training.pt` to display the title of the context: ```html

    ${python: context.title}

    ``` ## Exercise 2 - Render a mail-link to the speaker. - Display the speaker instead of the raw email-address. - If there is no speaker-name display the address. - Modify attributes of html-tags by adding your statements into the attributes directly like `title="${python: context.type_of_talk.capitalize()}"`. ````{admonition} Solution :class: toggle ```html ${python: context.speaker if context.speaker else context.email} ``` ```{note} Alternatively you can also use `tal:attributes=" "` to modify attributes. ``` ```` ## Accessing other views In templates we can also access other browser views. Some of those exist to provide easy access to methods we often need: ``` tal:define="context_state context/@@plone_context_state; portal_state context/@@plone_portal_state; plone_tools context/@@plone_tools; plone_view context/@@plone;" ``` `@@plone_context_state` : The BrowserView {py:class}`plone.app.layout.globals.context.ContextState` holds useful methods having to do with the current context object such as {py:meth}`is_default_page` `@@plone_portal_state` : The BrowserView {py:class}`plone.app.layout.globals.portal.PortalState` holds methods for the portal like {py:meth}`portal_url` `@@plone_tools` : The BrowserView {py:class}`plone.app.layout.globals.tools.Tools` gives access to the most important tools like `plone_tools/catalog` These are very widely used and there are many more. (plone5-tal-missing-label)= ## What we missed There are some things we did not cover so far: `tal:condition="exists:expression"` : checks if an object or an attribute exists (seldom used) `tal:condition="nocall:context"` : to explicitly not call a callable. If we refer to content objects, without using the nocall: modifier these objects are unnecessarily rendered in memory as the expression is evaluated. `i18n:translate` and `i18n:domain` : the strings we put in templates can be translated automatically. There is a lot more about TAL, TALES and METAL that we have not covered. You'll only learn it if you keep reading, writing and customizing templates. ```{seealso} - - Using Zope Page Templates: - Zope Page Templates Reference: - ```