Working With Generated Code

You’ve got CMS Builder installed and your sections configured in the Database Editor. Now you’re ready to integrate the generated code from CMS Builder into your designed pages. This guide explains what each code component does and provides tips for working with it.

Loading Records

<?php
  /* STEP 1: LOAD RECORDS - Copy this PHP code block near the TOP of your page */

  // load viewer library
  $libraryPath = 'cmsb/lib/viewer_functions.php';
  $dirsToCheck = ['','../','../../','../../../','../../../../']; // add if needed: '/www/htdocs/'
  foreach ($dirsToCheck as $dir) { if (@include_once("$dir$libraryPath")) { break; }}
  if (!function_exists('getRecords')) { die("Couldn't load viewer library, check filepath in sourcecode."); }

  // load records from 'my_section'
  list($my_sectionRecords, $my_sectionMetaData) = getRecords(array(
    'tableName'   => 'my_section',
    'limit'       => '5',
  ));
?>

This code appears at the beginning of your page to specify which section records should be loaded from. It sets the options that control how records appear. The library loader tries a series of relative paths so viewers keep working when the website is moved between servers. For most applications this code requires no modifications unless you’re adding custom functionality. See Viewer Options for the full list of available options.

Repeating Records with foreach

This marks the beginning of the code that is repeated for each record on a List Page:

<?php foreach ($my_sectionRecords as $record): ?>

This line marks the end of the repeated record display code:

<?php endforeach; ?>

This usually doesn’t need to be modified. Think of it as a wrapper around content that repeats for each record on List and Detail Pages. The foreach construct is also used for displaying file uploads in STEP 2a blocks.

Displaying Fields with echo

<?php echo $record['num'] ?>

This is the code type you’ll work with most frequently. It pulls text content entered through CMS Builder onto your webpage. The example displays the current record’s number. Similarly, this displays the record’s title:

<?php echo htmlencode($record['title']) ?>

Generated code wraps text values in htmlencode(), which encodes HTML special characters so user-entered text can’t break your page markup. Text box fields also get nl2br() to turn line breaks into <br> tags, and WYSIWYG fields are echoed without encoding since they store HTML.

Wrap your own HTML tags (such as <div> tags) around these code pieces to control how the text is displayed.

Formatting Dates

<?php echo date("D, M jS, Y g:i:s a", strtotime($record['time'])) ?>

This displays dates and times on your pages. You can modify the date format by following the PHP date function documentation.

Multi-Value Lists with join

<?php echo join(', ', $record['cities:values']); ?>
<?php echo join(', ', $record['cities:labels']); ?>

This resembles the echo code but applies only to multi-value list fields. The :values and :labels pseudo-fields contain the selected values and their display labels, and CMS Builder displays each one separated by commas. If several cities were selected, they’d display like this:

Vancouver, New York, Sydney, Oslo

To separate them with dashes instead, modify the code:

<?php echo join(' - ', $record['cities:labels']); ?>

Now they’d display as:

Vancouver - New York - Sydney - Oslo

Single-value list fields get a :label pseudo-field alongside the stored value, and checkbox fields get a :text pseudo-field with the checked/unchecked label:

<?php echo $record['region:label'] ?>
<?php echo $record['featured:text'] ?>

The older getListLabels('my_section', 'cities', $record['cities']) function still works as an alternative if you have existing code that uses it.

Pseudo-field Reference

Besides the fields you created, getRecords() adds these computed values to each record:

Pseudo-field	Applies to	Description
fieldname:values	Multi-value list fields	Array of the selected values.
fieldname:labels	Multi-value list fields	Array of the display labels for the selected values.
fieldname:label	Single-value list fields	Display label for the stored value.
fieldname:text	Checkbox fields	The checked or unchecked text defined in the field editor.
fieldname:unixtime	Date fields	The date as a unix timestamp — handy with PHP’s date() function.
_link	Every record	URL to the record’s Detail Page, built from the Detail Page Url in the section’s Viewer Urls settings, the section’s filename fields, and the record number.
_filename	Every record	The sanitized text slug used in _link, built from the section’s filename fields.
_tableName	Every record	Name of the section table the record was loaded from.
createdBy.*	Every record	Fields from the account that created the record: createdBy.username, createdBy.email, createdBy._link, createdBy._filename, etc. The password field is excluded. Requires the loadCreatedBy option (on by default).

The : pseudo-fields can be turned off with the loadPseudoFields option. See Viewer Options.

Linking to a Detail Page

To link each record on a List Page to its Detail Page, wrap the title (or any other content) in an anchor using the _link pseudo-field:

<?php foreach ($newsRecords as $record): ?>
  <h2><a href="<?php echo $record['_link'] ?>"><?php echo htmlencode($record['title']) ?></a></h2>
<?php endforeach ?>

_link is built from the Detail Page Url on the section’s Viewers tab (CMS Setup > Database Editor > modify > Viewers), so set that first (the In-Depth Guide walks through it). To control the text slug that appears in the URL, set the section’s Filename Fields on the same tab (see Editing a Section).

Displaying Uploads

This handles file and image upload display. For each upload field the generator emits a “STEP 2a” block that loops over the uploads and shows every available tag (upload URL, download link, image and thumbnail tags, info fields, and more) so you can copy the tags you want to use and erase the ones you don’t need:

<?php foreach ($record['photos'] as $index => $upload): ?>
  Upload Url: <?php echo htmlencode($upload['urlPath']) ?><br>
  Download Link: <a href="<?php echo htmlencode($upload['urlPath']) ?>">Download <?php echo htmlencode($upload['filename']) ?></a><br>
  <img src="<?php echo htmlencode($upload['urlPath']) ?>" width="<?php echo $upload['width'] ?>" height="<?php echo $upload['height'] ?>" alt="">
  <img src="<?php echo htmlencode($upload['thumbUrlPath']) ?>" width="<?php echo $upload['thumbWidth'] ?>" height="<?php echo $upload['thumbHeight'] ?>" alt="">
<?php endforeach ?>

A common hand-written pattern picks one display per upload — the thumbnail if one exists, otherwise the full-size image, otherwise a file attachment link:

<?php foreach ($record['photos'] as $upload): ?>
  <?php if ($upload['hasThumbnail']): ?>
    <img src="<?php echo $upload['thumbUrlPath'] ?>" width="<?php echo $upload['thumbWidth'] ?>" height="<?php echo $upload['thumbHeight'] ?>" alt=""><br>
  <?php elseif ($upload['isImage']): ?>
    <img src="<?php echo $upload['urlPath'] ?>" width="<?php echo $upload['width'] ?>" height="<?php echo $upload['height'] ?>" alt=""><br>
  <?php else: ?>
    <a href="<?php echo $upload['urlPath'] ?>">Download <?php echo $upload['filename'] ?></a><br>
  <?php endif ?>
<?php endforeach ?>

Customize the code following each “if” stage to determine how images and file attachments are displayed. See Displaying Uploads for more detail.

You can also customize the “No records were found!” message:

<?php if (!$my_sectionRecords): ?>
  No records were found!<br/><br/>
<?php endif ?>