Reference

Please note: this page is a compact reference documenting the usage of PHeasel's placeholders, if you are new to PHeasel you might prefer to have a look at Getting Started With PHeasel first, which will take you throught the most important features step by step.

PHeasel's tags

Most web developers prefer an XML/HTML like tags as placeholders for dynamic elements of a website. PHeasel tags basically have the same syntax as a namespaced XML tag, however they are a lot more flexible, for your convenience and taste: quotes are optional and can be single or double, also the slash at the end of a self-closing tag can be left out. And if you want, you can use curly brackets instead angle brackets.
All tags in the example on the right-hand side have exactly the same meaning.

Example

        <ph:tag attribute="value">
        <ph:tag attribute='value'>
        <ph:tag attribute="value"/>
        <ph:tag attribute=value>
        {ph:tag attribute="value"}
        {ph:tag attribute='value'}
        {ph:tag attribute="value"/}
        {ph:tag
            attribute="value"
        }

Markup Configuration Parameters

Markup configuration parameters are included in a <ph:config> tag. You can put it anywhere in the markup file, but we recommend placing it on top or within the <head> section. The tag will not be included in the HTML output to your visitors. You can also do without line breaks and put it all in one line.

There are three kinds of markup files: pages, templates and snippets.

Example

    <!DOCTYPE HTML>
        <html>
        <head>
            <ph:config id="myMarkupFileId">
        </head>
        <body>
        </body>
        </html>

Page Markup Parameters

A page is a piece of markup that contains your actual page content. Your visitors will be able to access a page by URL.

<ph:config url=... [id=...] [name=...] [template=...]>

Option name	Description	Unique?	Optional?	Default value
`id`	You will need the ID to reference the page from other places, e.g. when creating links.	Yes	Yes	ID generated from directory path and filename, omitting language and type
`url`	Your visitors will be able to access the page under the given URL.	Yes	No	-
`name`	A short name describing your page, can be used e.g. for links or navigation elements.	No	Yes	-
`template`	ID of the template to be used for the page	No	Yes	`main` (if a template with ID main exists)

BTW: Optional Configuration Parameters

id: If you leave it out, PHeasel will assign one internally, derived from the relative path within the site directory. For example, the file site/myDirectory/mySubDirectory/page.myPageFile.en.php will have the ID myDirectory.mySubDirectory.myPageFile.
It is convenient and tempting not to manually assign page IDs, but always keep one thing in mind: if you do so, you give up one of the benefits of PHeasel: file system independency. So if you ever want to rename or move the page file, you will also have to modify all links pointing to it.

name: If you omit this, you will have to take care of labeling all links in your markup yourself, which might make it more difficult for you to create or use navigational elements like page navigation, bread crumb navigation or sitemap. You will read more about this later.

Template Markup Parameters

A template is a markup wrapper for the pages referencing it. It is usually used to re-use shared markup for page headers and footers, e.g. logo or navigation elements.

<ph:config [id=...]>

Within the template's markup, use the page placeholder <ph:page> to indicate where the actual page content is to be inserted.

Option name	Description	Unique?	Optional?	Default value
`id`	You will need the ID to reference the template from pages.	Yes	Yes	ID generated from directory path and filename, omitting language and type

Snippet Markup Parameters

Snippets are a convenient way to re-use pieces of markup within different pages, e.g. a teaser box in your sidebar, markup for advertisements or any custom component.

<ph:config [id=...]>

Option name	Description	Unique?	Optional?	Default value
`id`	You will need the ID to reference the snippet from pages, templates or other snippets.	Yes	Yes	ID generated from directory path and filename, omitting language and type

Placeholders

Placeholders look similar to markup configuration parameters (described above), and are also processed by PHeasel while it renders the page. However, placeholders are not simply read and removed from output, but rather replaced with a piece of dynamic information, e.g. a relative URL to another page.

URL and page name placeholders

A URL placeholder is replaced by a (relative) URL to another PHeasel page, for use with HTML links.
If the name parameter is configured in the page markup configuration, the <ph:pagename> can be used to output the name of the target page. It is always replaced with the name of the page that has been last adressed with a URL placeholder.

Example

            
            <a href="{ph:url pageid='mypage'}"><ph:pagename></a>

The link above would be rendered e.g. like

            <a href="my-page/">My Page</a> <!-- (en) or -->
            <a href="meine-seite/">Meine Seite</a> <!-- (de) -->

Resource placeholders

Similar to the URL placeholder, the resource placeholder is used to create a reference, just for static resources like external style sheets, javascript or images. Requests to static resources are waved through directly by PHeasel, so in theory you could as well just reference an image within the site/static/ directory like /static/logo.png. However, using the resource placeholder gives you more flexibity, especially if your PHeasel site is not located directly in the document root of your web server.

Example

            
            <img src="{ph:resource url='/static/img/logo.png'}">

The image above would be rendered e.g. like

                <img src="static/img/logo.png">

Anchor placeholders

Anchor placeholders are useful if you want to internationalise the part after the hash (#) symbol of a URL. When adding an <ph:anchor id=anyid> placeholder to your page, you can localise it by adding anchor.anyid=my-anchor-text to the page markup configuration section.

Example

            <h3 id="{ph:anchor id='myheadline'}">My Headline</a>

The link to the anchor above could be rendered e.g. like

            <a href="my-page/#my-headline">My Headline</a> <!-- (en) or -->
            <a href="meine-seite/#meine-ueberschrift">Meine Überschrift</a> <!-- (de) -->

if the page markup configuration includes e.g. one of

            anchor.myheadline=my-headline
            anchor.myheadline=meine-ueberschrift