1. The Template System

ConPresso keeps contents and design separate. Templates therefore govern the visual appearance of articles. As templates consist of HTML mostly you need to have at least some knowledge of HTML in order to be able to create and edit templates. However, you do not need to learn a complex template script language additionally.

You can add so called placeholders to the HTML code of an article template. These placeholders will load contents created by a user dynamically when the article is published. In addition to that, ConPresso placeholders determine which content elements are available for users creating or editing an article.

The next sections will introduce you to the definition of placeholders as well as to the different types of placeholders. For the actual creation of an article-template (see section Section 2, “Create Article Template”) and integration of placeholders into the formatting codes of an article-template ConPresso provides a comfortable the section called “Template-Editor”.

1.1. Definition of ConPresso Placeholders

A ConPresso placeholder basically consists of a "Type" and a "Name". Its definition follows this pattern: <!-- Typ: Name -->

In cpo; placeholders have the form of HTML comments. The advantage of this is that the output code generated will read faulty placeholder tags as comments so that they will not appear as visible faults in the frontend of the project.

All placeholders will generate valid XHTML by default for the frontend.

1.2. Types of Placeholders

ConPresso provides various types of placeholders enabling the in- and output of different kinds of content. These are, for example, placeholders for texts, images or files.

Basically ConPresso supports the following placeholders:

In addition to that, ConPresso provides placeholders for the "conditional output" of content. These placeholders enable the output or processing of some parts of the article-template on the condition that the related placeholder is either empty or full:

In the descriptions of some of the following types of placeholders you will come across the term "entity conversion". This term refers to the conversion of special characters to HTML entities (e.g. ">" becomes "&gt;", etc.).

[Note]Note

The list of placeholders named above can be enhanced by using modules, for example. If a module provides additional placeholders or additional options for existing placeholders, please refer to the module's documentation for further information.

1.3.  Placeholder Name

The name of a placeholder serves the purpose of identification. It will be shown as a “label” next to the respective entry field when you create or edit an artice. The name of a placeholder can be chosen freely.

1.4. Placeholder Options

You can specify certain options for placeholders. Just separate the options by entering a ";" behind the name.

You can add various options in a row. Each option is separated from the others by a ";":

There are two kinds of options:

  • the simple "switch" (that is "on" or "off"): "Option" or

  • the value input: "Option=Value"

Options mainly govern the way placeholders are processed on output. Settings that refer to entering the content of a placeholder can be specified as described in the section called “Edit Placeholder Settings”.

Which options are available depends on the type of placeholder. Therefore please refer to the description of placeholder types for more information on the options related to the respective type.

1.5. Image Placeholder (Placeholder of the Type "Image")

Placeholders of the type "Image" provide the facility of embedding images into a ConPresso article.

If an article-template contains placeholders of the type "Image", users creating or editing an article can select one image per placeholder to be displayed in the article. Please note that you have to upload and assign an image to a rubric first. For more information please read Section 1, “Upload Files”.

Example 11.1. Output (HTML Code) without Options

<img src="../_data/Dateiname" 
     alt="Alttext" 
     title="Title" 
     width="Width" 
     height="Height" />
    

Output Options

file

Outputs the file name of the image.

alttext

Outputs the alternate text of the image. Special characters are converted into entities.

width

Outputs the image's width in pixels.

height

Outputs the image's height in pixels.

description

Outputs the description of an image. Special characters are converted into entities.

Example 11.2. Using the Image Placeholder in a Template

without options: <!-- Image: an image; -->
file name:     <!-- Image: an image; file -->
alttext:       <!-- Image: an image; alttext -->
image width:    <!-- Image: an image; width -->
image height:      <!-- Image: an image; height -->
description:  <!-- Image: an image; description -->
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

1.6. File Placeholder (Placeholder of the Type "File")

Placeholders of the type "File" provide the facility of embedding files into a ConPresso article.

If an article-template contains placeholders of the type "File", users creating or editing an article can select one file per placeholder to be embedded in the article. Please note that you have to upload and assign a file to a rubric first. For more information please read Section 1, “Upload Files”.

Example 11.3. Output (HTML Code) without Options

<a href="../_data/Dateiname">Description [Filesize]</a>
    

The output of the file size will be "human readable" (e.g. 128Kb).

Output Options

file

Outputs the file's name.

description

Outputs the file's description.

hrsize

Outputs the file's size in a "human readable" format - e.g. 128Kb.

size

Outputs the file size in bytes.

Example 11.4. Using the File Placeholder in a Template

without options:                 <!-- File: a file --> 
file name:                     <!-- File: a file; file --> 
file size I (human readable): <!-- File: a file; hrsize --> 
file size II (bytes):         <!-- File: a file; size  -->
description:                  <!-- File: a file; description -->
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

1.7. Simple Text Placeholder (Placeholder of the Type "Text")

Placeholders of the type "Text" provide the facility of entering simple, sparsely formatted texts into a ConPresso article.

These placeholders create simple text fields, so-called text areas. Users creating or editing an article can enter text into this text field without using the ConPresso-WYSIWYG editor, which would allow all kinds of formatting. Use placeholders of the type "Text" if you do not want users to apply HTML formatting (e.g. bold, underlined or colours and tables) to their texts. Simple text placeholders make sure that default formatting and layout remain largely unchanged while placeholders of the type "HTML" allow for extensive changes.

Example 11.5.  Output (HTML Code) without Options

Text
    

HTML special characters will be converted to entities on output.

Output Options

strip_tags

Removes HTML tags before HTML special characters are converted to entities (entity conversion).

nl2br (new line to break)

After the conversion of HTML special characters line breaks will be converted to <br /> tags.

Example 11.6. Using the Simple Text Placeholder in a Template

without options:             <!-- Text: a text -->
HTML tags stripped:        <!-- Text: a text; strip_tags -->
line breaks as <br />: <!-- Text: a text; nl2br -->
combined:                <!-- Text: a text; striptags; nl2br -->
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

1.8. HTML Placeholder (Placeholder of the Type "HTML")

Placeholders of the type "HTML" provide the facility of entering HTML formatted texts into a ConPresso article by use of a suitable browser.

HTML placeholders allow users to use the ConPresso WYSIWYG editor when they are creating or editing articles. This editor works like a word processor so that users can edit texts comfortably. They can embed images, tables or links into their texts and choose any formatting they like (bold, underlined, colour etc.).

Switch to the HTML modus to edit the HTML code directly while you are creating or editing an article.

Example 11.7. Output (HTML Code) without Options

Text with <strong>HTML code</strong>
    

Output Options

strip_tags

Removes HTML tags from the text before output.

htmlspecialchars

Converts HTML special characters to entities before output.

Example 11.8. Using the HTML Placeholder in a Template

without options:      <!-- HTML: HTML -->
HTML tags stripped: <!-- HTML: HTML; strip_tags -->
HTML entities:      <!-- HTML: HTML; htmlspecialchars -->
combined:         <!-- HTML: HTML; strip_tags; htmlspecialchars -->
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

1.9. Link Placeholder (Placeholder of the Type "URL")

Placeholders of the type "URL" provide the facility of embedding links into a ConPresso article.

Example 11.9. Output (HTML Code) without Options

<a href="link target" >link text</a>
    

HTML special characters in the link text will be converted to entities.

Output Options

strip_tags

Removes HTML tags from the link text before HTML special characters are converted to entities.

starttag

Outputs only the start tag (<a href="URL (link target)" >).

url

Outputs the URL only (entity conversion).

text

Outputs the link text only (entity conversion).

target

Outputs the target only (entity conversion).

Example 11.10. Using the Link Placeholder in a Template

without options:  <!-- URL: a URL --> 
start tag:   <!-- URL: a URL; starttag -->other text</a> 
URL:            <!-- URL: a URL; url --> 
link text:    <!-- URL: a URL; text --> 
target: <!-- URL: a URL; target --> 
without HTML code: <!-- URL: a URL; strip_tags --> 

Special Cases (can be combined with examples above):

"go back" link:      <!-- URL: a "go back" URL; go back --> 
to article page: <!-- URL: a "more" URL; more --> 
to article page - combined with start tag: 
                  <!-- URL: a "more" URL; more; starttag -->other text</a>
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

1.10. Value Placeholders

ConPresso provides value placeholders for each article by default. These placeholders have the same structure as other placeholders. In contrast to other placeholders, however, their names cannot be chosen freely and you have to enter specific values (e.g. <!-- Value: Author -->).

Value placeholders only allow the output of information, for example metadata like title, author etc. This means that users creating or editing an article cannot change the content of these placeholders.

You can use the the section called “Template-Editor”, however, to embed value placeholders into the formatting code of article templates.

ConPresso supports the following value placeholders:

Value Placeholder "Title"

The value placeholder "title" outputs the title of an article.

Example 11.11. Output (HTML Code) without Options

Title
    

Output Options

strip_tags

Removes HTML tags from the title prior to entity conversion.

Example 11.12. Using the Value Placeholder "Title" in a Template

title:                  <!-- Value: title -->
title (without HTML tags): <!-- Value: title; strip_tags -->
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

Value Placeholder "Author"

The value placeholder "Author" outputs the author's details as registered in the system.

Example 11.13. Output (HTML Code) without Options

%lt;a href="mailto:author-eMail">author-name</a>
    

Output Options

name

Outputs the name of the author only.

email

Outputs the author's email address.

initials

Outputs the author's initials.

Example 11.14. Using the Value Placeholder "Author" in a Template

author:     <!-- Value: author --><br /> 
author-name: <!-- Value: author; name --><br /> 
author-email: <!-- Value: author; email --><br /> 
initials: <!-- Value: author; initials --><br />
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

Value Placeholder "Editor" (Last Edited By)

The value placeholder "Editor" outputs information on the user who last edited an article.

Example 11.15. Output (HTML Code) without Options

<a href="mailto:author-eMail">Last edited by</a>
    

Output Options

name

Outputs the user's name.

email

Outputs the email address.

initials

Outputs the initials.

Example 11.16. Using the Value Placeholder "Editor" in a Template

last edited by: <!-- Value: editor --><br /> 
name:                   <!-- Value: editor; name --><br /> 
email:                   <!-- Value: editor; email --><br /> 
initials:              <!-- Value: editor; initials --><br />
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

Value Placeholder "Publication Date"

The value placeholder "pub_date" outputs the publication date of an article as formatted in the rubric settings.

Example 11.17. Output (HTML Code) without Options

01.01.2006 11:30
    

The formats of the time and date are specified in the rubric settings.

Output Options

timestamp

Outputs the publication date in the UNIX timestamp format.

format

Use this option to change the format of the date. Possible formats are those specified in Appendix A, PHP Date Formatting.

Example 11.18. Using the Value Placeholder "Publication Date" in a Template

publication date:               <!-- Value: pub_date --><br /> 
publication date - timestamp:   <!-- Value: pub_date; timestamp --><br /> 
publication date - swatch-time: <!-- Value: pub_date; format=B --> <br /> 
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

Value Placeholder "Expiration Date"

The value placeholder "exp_date" outputs the expiration date of an article as as formatted in the rubric settings.

Example 11.19. Output (HTML Code) without Options

02.02.2007 14:15
    

The formats of the time and date are specified in the rubric settings.

Output Options

timestamp

Outputs the expiration date in the UNIX timestamp format.

format

Use this option to change the format of the date. Possible formats are those specified in Appendix A, PHP Date Formatting.

Example 11.20. Using the Value Placeholders "Expiration Date" in a Template

expiration date:               <!-- Value: exp_date --><br /> 
expiration date - timestamp:   <!-- Value: exp_date; timestamp --><br /> 
expiration date - swatch-time: <!-- Value: exp_date; format=B --> <br /> 
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

Value Placeholder "Article Number"

The value placeholder "articlenr" outputs the number of an article. This number is generated automatically upon creation of an article.

Example 11.21. Output (HTML Code) without Options

1
    

Example 11.22. Using the Value Placeholder "Article Number" in a Template

article number: <!-- Value: articlenr --><br />
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

Value Placeholder "Template"

The value placeholder "Template" outputs the number of the template used in an article. This number is generated automatically upon creation of the template.

Example 11.23. Output (HTML Code) without Options

1
    

Example 11.24. Using the Value Placeholder "Template" in a Template

template number: <!-- Value: template --><br />
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

Value Placeholder "Article Index"

The value placeholder "articleidx" outputs the sorting index number of an article.

Example 11.25. Output (HTML Code) without Options

1
    

Example 11.26. Using the Value Placeholder "Article Index" in a Template

article index: <!-- Value: articleidx --><br />
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

Value Placeholder "Rubric"

The value placeholder "rubric" provides the facility to display certain information on the rubric the article is placed in.

Example 11.27. Output (HTML Code) without Options

<a href="../rubricdirectory/index.php?rubric=rubricname">Rubric Name</a>
    

Output Options

id

Outputs the ID of the rubric.

directory

Outputs the name of the rubric directory.

name

Outputs the name of the rubric.

title

Outputs the title of the rubric.

strip_tags

Prior to the entity conversion, HTML tags will be removed from some elements.

urlencode

Prior to the entity conversion, some elements will be encoded for usage as parameters of a URL.

Example 11.28. Using the Value Placeholder "Rubric" in a Template

rubric an article is placed in: <!-- VALUE: rubric; -->
ID of that rubric: <!-- VALUE: rubric; id; -->
directory of that rubric: <!-- VALUE: rubric; directory; -->
name of that rubric: <!-- VALUE: rubric; name; -->
title of that rubric: <!-- VALUE: rubric; title-->
    

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.

1.11. Conditional Placeholders (ifSet/ifNotSet)

ConPresso allows the use of the following tags to generate output that depends on if a particular placeholder contains data or not.

  • <!-- ifSet: Name --> <!-- /ifSet -->

  • <!-- ifNotSet: Name --> <!-- /ifNotSet -->

"Name" stands for the name of the placeholder the ifSet or the ifNotSet placeholder refers to.

Example 11.29. Using Conditional Placeholders in a Template

<!-- ifSet: a text -->Text output above!<br /><!-- /ifSet -->
    
<!-- ifSet: articletext  --><!-- URL: "More" link; more --><!-- /ifSet -->
    

These placeholders are not tied to either rubric or article page and work independently. Thus it is possible (and expedient as well!), for example, to make the "More" link on a rubric page dependent on whether certain content (e.g. text) is displayed on the article page.

[Caution]Caution

Placeholders for conditional output may not be nested.

When you set up ConPresso the system installs the article-template "Placeholder Demo" by default. This template contains the entire range of ConPresso placeholders.