Template Reference

Contemple Version

Template Reference for Contemple 1.0.29

Last Update: 31. 08. 2021

Topics:

Root Templates
Sub Templates
Areas
Properties
File Handling
Expressions

Templates for Contemple contain Static Files and Template Files. They define the different parts of the website. Template files also define the settings wich are available in the editor interface. By default Contemple doesn't provide any User Interface. Everything has to be defined in the Template.

There are three different types of Templates

Root Template
also called Theme wich contains all template files, sub templates, page templates and also default content. An installed Theme is called Project.
Sub Templates
A Sub template is a single template for an Item from the Database. Sub templates can be installed into an a Root Template / Project.
Page Templates
Like template files, page templates are for new pages wich can be created in Contemple or with the default-content file.

Template Files may contain Template Areas and Template Properties.

Root Templates

A Root Template can be installed in Contemple. It contains several config, template, and static files.

Config options

The following table shows the config settings for a Root Template (config.xml)

Name

Description

defaultcontent

XML file with default content wich may be installed with the theme. To generate a content file, select Developer / Commands / Export Content from the Menu in Contemple.

defaultcontent = "content-export.xml"

files

comma separated list with all template files. Currently the files have to be in the folder of the root template

files = "contact.html,main.css"

folders

Website folders with static files

folders = "images,css"

help

XML file with help text and translations for the interface

help = "help.xml"

hiddenareas

List with Areas to hide in the interface

hiddenareas = "JS-Area,Files"

index

The index file of the website

index = "index.html"

name

Unique Name of the Root Template

name = "com.your-domain.template-name"

nocompress

List with template files to exclude from minify compression

nocompress = "events.php,main.js"

nolocareas

List with Areas to exclude from anker linking

nolocareas = "Menu,Imprint"

pagetemplates

List with template files wich can be selected to create a new Page in the interface. Page Templates can also use the keyword "page#" wich returns the name of the new page.

pagetemplates = "single.html,featured.html"

staticfiles

List with additional static files.

staticfiles = "favicon.ico,price-list.pdf"

type

Type have to be root.

type = "root"

version

Version of the Template.

version = "1.0.0"

Sub Templates

A Sub Template can be installed inside a Root template. Sub Templates are rendered for every Database item wich is not set to invisble. Database Items are created by an Editor in Contemple or with the default-content file. Every instance of a Sub template, or Database item, can also create its own Sub Page for the website using the articlepage and articlename config attributes.

Config options

Config settings for Sub Templates (config.xml)

Name

Description

articlepage

Render the item into a file (sub page). This feature can be used to create blog or product lists with a separate page for a detailed view. The articlepage attribute can be set to a page-template. The file path is relative to the subtemplate directory.

The database item is renderd into the root page and also into a new file using a separate page template. Database fields can be used inside the Page Template and the index file of the subtemplate.

Use the page# keyword to get the item name of a sub template item.

To access properties from the root template, use {#root:property-name} or {##root:area-name}

To create Areas inside the article page use inline area properties: {#my-area:Area("#itemname#","content")}

Areas and Properties for article sub pages have to be defined inside the index file of the sub template.

articlepage = "pg-tmpl.html"

articlename

Controls the name of the item file

articlename = "#YEAR#-#INPUTNAME#.html"

fields

List of database fields.

fields = "style,bgcolor,text1,text2"

files

comma separated list with template files inside the sub template folder

files = "contact.html,main.css"

folders

folders with static files

folders = "images,css"

help

XML file with help text and translations for the interface

help = "help.xml"

index

The index file of the Sub Template

index = "index.html"

listlabel

Label string in the interface. Database fields can be included inbetween two numeric chars (#)

listlabel = "(#style#) #name#"

listicon

Icon of the Sub Template in the interface. Use a default icon from ico:/ folder or with the template:/ path. The icon size should be 24x24 pixel.

listicon = "ico:/lion.png"

name

Unique Name of the Sub Template

name = "com.your-domain.subtemplate-name"

nolocation

If nolocation is true, the rendered items don't have anker links inserted in to the page.

nolocation = "true"

parselistlabel

Parse rich text in the interface label.

parselistlabel = "true"

staticfiles

List with additional static files in the Sub Template folder.

staticfiles = "bg.svg,highscore.json"

tables

Name of the database Table of the Sub Template.

table = "com_domain_subtemplatename"

type

Type of the Sub Template can be any String from an Area type.

type = "content"

version

Version of the Sub Template.

version = "1.0.0"

Areas

Areas define parts of the website for items from the database. The items allowed inside an Area can be restricted with the Area-Type. Template Areas begin with two numeric characters (##).

Definition:

##AREA-NAME(icon:String, description:String, offset:int, limit:int, link:String, orig-subtemplate1:String, new-sutemplate1:String, orig-subtemplate2:String, new-subtemplate2:String):area-types

Area Examples :

A simple website uses these areas in the root template:

{##HOME:content}
{##CONTENT:content}
{##CONTACT:content}
{##SIDEBAR1:content,sidebar}
{##SIDEBAR2:sidebar}
{##MENU:menu}
{##AUDIO-PLAYER:audio}

The sidebar requires special items so it has an additional type allowing also items of type sidebar

The sidebar2, menu and audio-player areas allows only special items.

To display items from another Area, the link argument can be used to link to other Areas and override the item templates.

{##FEATURED-HOME("ico:/falcon.png","Featured Home Page Content",0,1,"HOME","Text","Featured-Text-Template"):content}

Sections and priorities can be set to order areas and create folders in the User Interface. The number before the Name controls the priority of the folder or area:

{##100.FOOTER:content}
{##10.HEADER:content}
{##10.Foldernam2.100.FOOTER:content}
{##Products.Computers.500.Mices:products,sellout,sidebar}

Properties

Template Properties are like variables wich can be set in the Contemple app. The properties can be edited under Settings in the app. Template Properties begin with one Hasttag character (#).

Definition:

#PROPERTY-NAME(type_arguments)=default_value

Examples :

A Property can be defined everywere inside template files:

{#adress:String="4th avenue"}
{#GeneralOptions.Primary-Color:Color="#247"}
{#50.GeneralOptions.100.code:Number(0,99,1)=47}

Integers before a property name or folder can be used to control to order in the Contemple User Interface.

To get the value of a Property, the folder-path, order-id, arguments and default value can be discarded.
They are only required when the Property is defined:

{#adress}
{#Primary-Color}
{#code}

Alternative Definition:

It is also possible to define properties in a easier way between the #def: and #def; instructions.

Definig Properites inside a #def block allows to control the order of the Properties by the order the properties are defined.

#def:
adress:String = "4th avenue";
Primary-Color:Color = "#247";
code:Number(0,99,1)=47;
#def;

Using the Folder Type and the #scope instruction it is very ease to setup a hierarchical Menu in the Settings Editor:

#def:

MyPages:Folder;
MyPageItems:Folder;

#scope:MyPages;
all-pages:PageList = "a-page.html";
my-single-pages:PageList("template","page-single.html") = "singlepage.html";
my-blog-pages:PageList("template","page-blog.html") = "blogpage.html";

#scope:MyPageItems;
my-home-area-items:ItemList("Home") = "Item_1234";
my-menu-area-items:ItemList("Menu","url","<a href=",">#inputname#</a>","name") = "<a href=blog.html>Blog</a>";

#def;

Folders can be nested inside folders without affecting the theme code. In the theme, the folder does not have to be known to get the property, They are all accessible in the root hierarchy. Only if two properties have the same name, the full path have to be used in order to receive the correct Setting. In the example below, the deep-code property can be accessed in template files without any folders just by writing: {#deep-code} or {#GeneralSettings.GeneralFolder.deep-code}

#def:

GeneralSettings:Folder;

#scope:GeneralSettings;
adress:String = "4th avenue";
GeneralFolder:Folder;

#scope:GeneralFolder;
deep-code:ScreenInteger(0,99,1)="47px";

#def;

Reset the scope to root:

AFolder:Folder;

#scope:AFolder;
# following properties are stored inside Afolder until the next scope instruction;

#scope:global;
# following properties are stored inside the root hierarchy;

Note: it is also possible to write comments with the numeric character and the semicolon character.

Available Property Types:

Type

Arguments

Description

Area

name : String

type : String

Inline Area with add, edit, delete and sort functionality for subtemplate items. Currently the Area type can be used only inside Sub Templates.

Every inline Area requires a unique name. Inside a subtemplate, #itemname# returns the name of the item choosen by the user in order to create inline areas.

MyArea : Area( "my-#itemname#", "content" )

AreaList

none

Input with Area Popup List

MyAreaList : AreaList = "Home"

Audio

folder : String

filename : String

fileBrowserTitle : String

allowedExtensions : List

Sound File Input:

MyAudioFile : Audio('fileadmin/mp3', '#INPUTNAME#.#EXTENSION#', 'MP3 Files', '*.MP3;*.WAV;') = "fileadmin/mp3/default-file.mp3"

Background

folder : String

filename : String

Input for Css-Background values

MyBg1 : Background('img', 'bg-#inputname#.#extension#') = 'url(ing/bg1.png)'

MyBg2 : Background('img', 'bg-#inputname#.#extension#') = 'linear-gradient(45deg, #f907, #fff0)'

MyBg3 : Background('img', 'bg-#inputname#.#extension#') = 'url(ing/bg1.jpg) no-repeat, radial-gradient(circle, #f907, #fff0) #05f'

Boolean

yes : String

no : String

Boolean Input

MyBool : Boolean('true', 'false') = 'true'

Code

none

Text Input

MyHtmlField : Code = '<i>some text</i>'

Color

none

Color Input

MyBgColor1 : Color = '#123'

MyBgColor2 : Color = '#102030'

MyBgColor3 : Color = 'rgb(16,32,48)'

Date

format : String

Get the current Date. The format argument may contain the characters d, m, y for date, month, year and h, m, s for hours, minutes and seconds

MyDate : Date('d. m. y') = '22. 4. 2020'

MyDate : Date('d. m. y h:m:s (t)') = '22. 4. 2020 22:35:12 (Timezoneoffset)'

Handling Files with File Input Elements

Template Properties of type Audio, Image, File, Pdf or Video support the following keywords in the filename arguments

Extension

Returns the File Extension

Inputname

Name of the Page Item

Name

Name of the selected File without file extension

Sortid

Sorting value of the Page Item

Uid

Returns the SQL-UID of the Page Item

Vectorindex

Item Index in Vector Inputs only

Year, Month Day, Date Hours, Minutes, Seconds, Milliseconds, Time, Timezoneoffset

Returns current Date values

Page Item and Extension Fields

Returns database values of the Page Item (uid, name, visible, area, sortid, subtemplate, crdate and extension-fields)

Example: On selecting a file called 'test.txt':

MyFile1:File(dir,fix-test.#EXTENSION#)

-> dir/fix-test.txt

MyFile2:File(files,#YEAR#-#INPUTNAME#.#EXTENSION#)

-> files/2017-Item_1234.txt

MyFile3:File(files/dir1,#NAME#-#YEAR#-#MONTH#.#EXTENSION#)

-> files/dir1/test-2017-07.txt

Property Expressions

Some Property types allow to calculate expressions or get type specific values using the @ operator:

Set the height of a css style to the height of an image

.container { height: {#my-image@height}px; }

Set the width of a css style to the width of an image plus 20 pixel:

.container { width: {#my-image@calc width+20}; }

Get aspect ratio information:

.container { width: {#my-image@calc floor(width/height)}; }

Calculate expressions on Numbers:

{#my-num@number}

{#my-num@integer}

{#my-num@invert}

{#my-num@negativ}

{#my-num@unit}

{#my-num@add 20}

{#my-num@sub 1}

{#my-num@mul 2}

{#my-num@div 3.1415}

{#my-num@calc value*2}

{#my-num@calc value*pi/180}

Calculate expressions on Colors:

{#my-color@red}

{#my-color@green}

{#my-color@blue}

{#my-color@sat}

{#my-color@sat 0.5}

{#my-color@mul 0.5}

Reserved Static Properties

Get Current Date Values

{#get-date:year}

{#get-date:month}

{#get-date:date}

Get Random Values

Random values change every time the template is rendered. Or fixed to app-start if the first argument is a string

Returns a hexadecimal value with 3 or 4 digits. (1 iteration)

{#my-rnd:random(1)}

Returns a hexadecimal value with 5 to 8 digits. (2 iterations)(

{#my-rnd:random(2)}

Return a value betweem 0 and 1 round to 0.1

{#my-rnd:random(0,1,0.1)}

Return a fixed hexadecimal value, wich changes only after app start.

{#my-rnd:random("pre-text",2)}

Include files

Include a file from the web directory. The file have to be added to the Theme's files, staticfiles, staticfolders or pagetemplates config settings.

{#my-part:include('raw/my-file.html')}

Include a file from the template directory. The file have to be added to the Theme's files, staticfiles, staticfolders or pagetemplates config settings.

{#my-part:include('tmpl/my-file.html')}

Include a template file with Template Areas and Properties. The file have to be added to the Theme's files staticfiles, staticfolders or pagetemplates config settings.

{#my-part:include('tmpl/my-template.html',true)}

Template Properties in Subtemplates

Inside a Subtemplate, only the database fields set in the config.xml are accessible. Subtemplates currently support only one Area, the Area is added to the area tree in the app with the item name of the sub template instance. To use multiple Areas inside a subtemplate use inline-area properties

It is possible to render the item output into a external file with the articlepage, and articlename config settings for Subtemplates.

Static subtemplate properties

To get a property from the Root template:

{#root:My-Root-Property}

To get a database field value:

{#field:sortid}

{#field:subtemplate}

{#field:name}

Special Characters in Richtext Properties

Some characters are not allowed in Text or Richtext Propertie's default value, or default content.
Use the following replacements:

Newline #BR#

@ #AT#

# #HASHTAG#

" #QUOTE#

' #SQUOTE#

< #LT#

> #GT#

[ #SBRO#

] #SBRC#

The following replacements can also be used inside Richtext and Text fields:

#APP-NAME# Returns the app name set by install settings

#APP-VERSION# Returns the app version set by install settings

#TEMPLATE-NAME# The name of the current Root Template

#TAB# Returns three whitespace characters (nbsp)

#COPYRIGHT# Copyright character (copy)

#HR# Horizontal line (<hr>)