Documentation

How It Works

The Data Display add-on for Concrete5 is works with (and is dependent on) the Advanced Forms add-on.  Essentially, it lets you pull data that has been stored using advanced forms in order to display it on your site using a custom template.

Let's say for example you want to display an employee directory on your site.  Step one would be to create an Advanced Form to store all of the data about the employees - last, title, email address, phone number, bio, etc.  Once you have all of your data added, you then use Data Display to create a custom list template - a "section" of HTML into which each record (employee, in this case) will be populated using placeholders.

Say you wanted to be able to click on the employee to view more detailed info - you then setup a detail template, which is similar to the list template except that it only display a single record.

Templates

Data Display Templates are sections of HTML (and/or Javascript and CSS) that are used to display data from your forms.  Within the "content" sections of each template, you put placeholders.  Standard field placeholders appear as <field name="My Field Name" />. Detailed information about placeholders can be found in the "Placholders" section below.

There are two types of Data Display templates: List Templates and Detail Templates

List Templates

List Templates are used to display a listing of the form data that you have created using the Data Display package. List Templates are created from the back-end, but are displayed using the Data Display block.

A List Template consists of four HTML sections:

  1. Header - the header is a section of HTML code that is displayed only once at the top of the listing. No template placeholders can be added to the header.
  2. Content - the content is the section of HTML code that repeats for each item being listed. Placeholders are added to the content section that are replaced with the actual data when the template is displayed using the Data Display block.
  3. Alternate Content - works exactly like the previous content section, except that if alternate content is defined, the Data Display block will alternate between the content section and the alternate content section as is lists out the data. This is useful for displaying striped rows in a table or achieving similar effects.
  4. Footer - the footer is a section of HTML code that is displayed only once at the bottom of the listing. No template placeholders can be added to the footer.

IMPORTANT NOTE: Content and alternate content MUST be well-formed XML or the block will not be able to parse the template.

Detail Templates

Detail Templates are very similar to List Templates, except that Detail Templates display information for a single item from your data, as opposed to displaying multiple items like the List Template.  As a result, rather than having four HTML sections, the Detail Template only has a single section in which HTML and template placeholders may be added.

IMPORTANT NOTE: Detail Template content MUST be well-formed XML or the block will not be able to parse the template.

Template Placeholders

The following placeholders may be used in any content or alternate content sections of list or detail templates:

<field /> - Used to display a field from the form

Attributes:

  • name - The name of the field to be displayed.
  • maxlength - (optional) The maximum number of characters to display from the field's value.  Using the maxlength attribute will strip out any HTML from the field value.
  • format - (optional) Used to display a field value in different number formats.
    • format="number" runs the PHP number_format function on the field.
    • format="money" runs the PHP number_format function with two decimal places.
  • placeholder - (optional).  Used to place a field value elsewhere into a template where using the <field /> element would result in invalid XML.  See section "The Placeholder Attribute."
  • html - (optional) Used to specify that a fields content should be rendered as HTML (otherwise it will display the actual HTML characters).  Set to "true" in order to render as HTML.
  • property - (optional) Used on file fields to display a property of that file, rather than the path to the file.  Possible values are title, description, tags, type, filename, size, fullsize, and id.
  • separator - (optional) Used to specify a string that should go between each answer for a field that can have multiple answers (such as checkboxes and multi-select boxes).
  • striptags - (optional) Used to remove HTML tags from a field.  Set to "true" in order to strip HTML tags.
  • allowedtags - (optional) Used to allow certain tags when striptags is used.  Specify as a comma-separated list of tags without brackets, such as "a,p,br,div".

Examples:

  • <field name="Phone Number" />
  • <field name="Bio" maxlength="100" />
  • <field name="Price" format="money" />

<timestamp /> - Used to display the time/date that the record was submitted.

Attributes

  • format - the format in which the timestamp should be display.  This value is passed to the PHP date function.
  • placeholder - (optional).  Used to place a field value elsewhere into a template where using the <field /> element would result in invalid XML.  See section "The Placeholder Attribute."

Example

  • <timestamp format="F j, Y, g:i a" />

<recordid /> - Displays the unique ID associated with the record.

Attributes

  • placeholder - (Optional).  Used to place a field value elsewhere into a template where using the <field /> element would result in invalid XML.  See section "The Placeholder Attribute."

Example

  • <answerid placeholder="id" />

<owner /> - Display information about the owner of the record.

Attributes

  • attribute - (optional) Display a specific attribute of the record's owner.  Possible values are "email", "id", or a user attribute handle.  If no attribute is specified, the username will be returned.

Example

{{DETAILURL}} - Outputs the URL to the details for a particular record.  Can only be used on list templates.  Most useful when place within the href attribute of a link.

Example

  • <a href="{{DETAILURL}}">View Details</a>

{{LISTURL}} - Outputs the URL to return back to the list.  Can only be used on detail templates.  Most useful when placed within an href attribute on a link.

Example

  • <a href="{{LISTURL}}">Return to Listing</a>

<if></if>,<else></else> - Used to perform conditional operations within a template.  If returned true, the inner content of this tag will be outputted.  If returned false, content within the <else> tag will be outputted.  If no <else> is specified, the inner content will be ignored. <else> must be a direct descendant of <if>.

Attributes (only apply directly to <if>.  <else> has no attributes)

  • status - can be set to "approved" or "not approved"
  • name - the name of the field whose value will be checked
  • comparison - Optional. If not specified, the field will only be check to see if a value is specified (and return true if so).  Values that can be used include: "equal to", "not equal to", "greater than", "greater than or equal to", "less than", "less than or equal to", "contains", and "does not contain".
  • value - Optional. Required if "comparison" type is specified.  The value to check the field value against

Example

<if name="Phone" comparison="contains" value="601">
     Looks like <field name="First Name" /> is in the 601 area code.
     <else>
          <field name="First Name" /> is not in the 601 area code.
     </else>
</if>

<edit /> - Used to create a link to edit a record in context.  The link will only be shown to users that have access to edit records.  Set attribute display="inline" to display the edit form on the page rather than as a pop-up.

<delete /> - Used to create a link to delete a record in context.  The link will only be shown to users that have access to delete records.

<approve /> - Used to create a link to delete a record in context.  The link will only be shown to users that have access to approve records.

 

The Placeholder Attribute

Occasionally you will want to put a field value inside of an HTML attribute.  However, doing so would cause the template to contain invalid XML, and thus cause errors in parsing the template. In order to achieve this purpose, we created a special "placeholder" attribute that can be put inside of a field, timestamp, or answerid tag.  The format is as follows:

<field name="Photo" placeholder="my-photo" />

When using the "placeholder" attribute, the field will NOT be outputted when the template is parsed.</b> Instead, the field's value will be replaced in any instance of {{placeholder value}} that is found throughout the template.<br /><br />

So for example, we could later put the following into our template:

<img src="{{my-photo}}" />

Note that the placeholder must have two curly brackets on each side.

This is also useful when creating unique HTML id's using the "answerid" tag.  This could be achieved using:

<answerid placeholder="id" />
<div id="record-{{id}}"><field name="First Name" /></div>