Liquid Site Template API

 Version 0.10
2006-04-07

 

The liquidsite object

The liquidsite object is the global entry point to the content of your domain. You can also access the request and session objects, and obtain information about users.

countDocuments

Returns the number of documents in the section and subsections specified by a path. The path is always relative to the domain root directory. Nested subsections are separated by /.

Syntax:

countDocuments(path) → number

Parameters:

Returns:

The number of documents in the section and subsections specified by path.

Example:

Assuming a content structure like this:

- mydomain
  - Section1
      doc1
      doc2
      doc3 
    - Section1.1
        doc1.1
        doc1.2

Then the line:

<p>The number of documents in Section1 is
${liquidsite.countDocuments("Section1")}.<p>

Will output:

The number of documents in Section1 is 5.

findDocument

Returns the document corresponding to a specified path. The path is always relative to the domain root directory. Nested subsections are separated by /.

Syntax:

findDocument(path) → document object

Parameters:

Returns:

The document specified by path.

Example:

This code finds a document and assigns it to a variable:

<#assign doc1 = liquidsite.findDocument("Section1/doc1")>

If the document was not found, doc1 will contain an empty document. This line checks whether doc1 is empty:

<#if doc1.name == "">

findDocuments

Returns a list of documents in the section and any subsections specified by a path. The path is always relative to the domain root directory. Nested subsections are separated by /. The documents returned are ordered by modification date in descending order.

Syntax:

findDocuments(path, offset, count) → sequence of document objects

Parameters:

Returns:

A list of at most count documents in the section and subsections specified by path, ordered by modified date in descending order, beginning at document number offset.

Example:

The next code loops through the four first documents in Section1.

<#list liquidsite.findDocuments("Section1", 0, 4) as doc>

findDocuments

Returns a list of documents in the section and any subsections specified by a path, ordered by a specified sort criterion. The path is always relative to the domain root directory. Nested subsections are separated by /.

The sort criterion can contain several criterion separated by commas. A criteria has the format:

[+|-]columName

An optional leading + or - indicates ascending or descending order, respectively. By default ascending order is chosen. And columnName can take these values:

Syntax:

findDocuments(path, sorting, offset, count) → sequence of document objects

Parameters:

Returns:

A list of at most count documents in the section and subsections specified by path, ordered by the specified sorting criterion, beginning at document number offset.

Example:

The next code loops through the four first documents in Section1 ordered by parent section id and name in ascending order.

<#list liquidsite.findDocuments("Section1", "+parent,+name", 0, 4) as doc>

findSection

Returns the section corresponding to a specified path. The path is always relative to the domain root directory. Nested subsections are separated by /.

Syntax:

findSection(path) → section object

Parameters:

Returns:

The section specified by path.

Example:

This code finds a section and assigns it to a variable:

<#assign sec1 = liquidsite.findSection("Section1")>

If the section was not found, sec1 will contain an empty section. This line checks whether sec1 is empty:

<#if sec1.name == "">

findUser

Returns the user corresponding to a specified name.

Syntax:

findUser(name) → user object

Parameters:

Returns:

The user specified by name.

Example:

This code finds a user and assigns it to a variable:

<#assign user = liquidsite.findUser("liquidsite")>

If the user was not found, user will contain an empty user. This line checks whether user is empty:

<#if user.name == "">

findUserByEmail

Returns a user corresponding to a specified email address.

Syntax:

findUserByEmail(email) → user object

Parameters:

Returns:

The user specified by email address or an empty user if not found. If several users have the same email address any one of them may be returned.

Example:

This code finds a user and assigns it to a variable:

<#assign user = liquidsite.findUserByEmail("info@liquidsite.org")>

If the user was not found, user will contain an empty user. This line checks whether user is empty:

<#if user.name == "">

date

Returns the Liquid Site build date.

Syntax:

date → string

Returns:

The Liquid Site build date.

Example:

This code outputs the build date:

<p>The Liquid Site build date is ${liquidsite.date}.<p>

Which will result in something like:

The Liquid Site build date is 2005-01-25.

doc

Returns the document matched by a translator. If no translator was used, or the translator didn't match any document, an empty document is returned.

Syntax:

doc → document object

Returns:

The document matched by a translator, or an empty document.

Example:

To obtain the document and assign it to a variable would be done with this code:

<#assign doc = liquidsite.doc>

To check whether the returned document is empty can be done like this:

<#if doc.name == "">

forum

Returns the forum matched by a translator. If no translator was used, or the translator didn't match any forum, an empty forum is returned.

Syntax:

forum → forum object

Returns:

The forum matched by a translator, or an empty forum.

Example:

To obtain the forum and assign it to a variable would be done with this code:

<#assign forum = liquidsite.forum>

To check whether the returned forum is empty can be done like this:

<#if forum.name == "">

plugin

Returns the plugin object.

Syntax:

plugin → plugin object

Returns:

The plugin object.

Example:

The following code calls the HTTP plugin get method:

${liquidsite.plugin.http.get("http://www.liquidsite.org/")}

request

Returns the HTTP request object.

Syntax:

request → request object

Returns:

The HTTP request object.

Example:

This code obtains the request object and assigns it to a variable:

<#assign request = liquidsite.request>

site

Returns the current site object.

Syntax:

site → site object

Returns:

The content site object.

Example:

This code obtains the current site object and assigns it to a variable:

<#assign site = liquidsite.site>

section

Returns the section matched by a translator. If no translator was used, or the translator didn't match any section, an empty section is returned.

Syntax:

section → section object

Returns:

The section matched by a translator, or an empty section.

Example:

To obtain the section and assign it to a variable would be done with this code:

<#assign section = liquidsite.section>

To check whether the returned section is empty can be done like this:

<#if section.name == "">

session

Returns the HTTP session object.

Syntax:

session → session object

Returns:

The HTTP session object.

Example:

This code obtains the session object and assigns it to a variable:

<#assign session = liquidsite.session>

topic

Returns the topic matched by a translator. If no translator was used, or the translator didn't match any topic, an empty topic is returned.

Syntax:

topic → topic object

Returns:

The topic matched by a translator, or an empty topic.

Example:

To obtain the topic and assign it to a variable would be done with this code:

<#assign topic = liquidsite.topic>

To check whether the returned topic is empty can be done like this:

<#if topic.name == "">

user

Returns the current user logged in. If no user is logged in, an empty user is returned.

Syntax:

user → user object

Returns:

The current user logged in, or an empty user.

Example:

To obtain the user and assign it to a variable would be done with this code:

<#assign user = liquidsite.user>

To check whether the returned user is empty can be done like this:

<#if user.name == "">

util

Returns the util object.

Syntax:

util → util object

Returns:

The util object.

Example:

This code obtains the util object and assigns it to a variable:

<#assign util = liquidsite.util>

version

Returns the Liquid Site version.

Syntax:

version → string

Returns:

The Liquid Site version.

Example:

This code outputs the version:

<p>The Liquid Site version is ${liquidsite.version}.<p>

Which will output something like:

The Liquid Site version is 0.8.2.

linkTo

Returns a relative link to an object in the same site. If the specified path starts with / it is assumed to be relative to the site root directory, otherwise it is assumed to be relative to the page directory. Note that the page directory is NOT always an empty string (consider dynamic pages linked to sections).

Syntax:

linkTo(path) → string

Parameters:

Returns:

A relative link to a specified object in the same site.

Example:

The next code specifies a reference to a stylesheet located at the site root directory:

<link rel="stylesheet" type="text/css"
      href="${liquidsite.linkTo('/style.css')}" />

mailTo

Sends an email to a specified receiver. The email will not be sent immediately, but rather queued in the outgoing mail queue.

Syntax:

mailTo(receiver, subject, text) → boolean

Parameters:

Returns:

A boolean value of true if the email was queued correctly, and false otherwise

Example:

The next code sends an email and checks whether it succeeded:

<#if liquidsite.mailTo("info@liquidsite.org", "About Liquid Site" "Liquid Site rocks!")/>

mailToGroup

Sends an email to all members in a group. The email will not be sent immediately, but rather queued in the outgoing mail queue.

Syntax:

mailToGroup(receiver, subject, text) → boolean

Parameters:

Returns:

A boolean value of true if the email was queued correctly, and false otherwise

Example:

The following code sends an email to a group:

<#assign res = liquidsite.mailToGroup("Newsletter", "News" "Blah blah")>

Copyright © 2004-2006 by Per Cederberg. All rights reserved. Distributed under the GNU GPL.