relatedRecords special fieldname

7 posts by 4 authors in: Forums > CMS Builder
Last Post: November 9, 2017   (RSS)

By Deborah - October 13, 2017

I've just discovered the relatedRecords special fieldname and am using it with a product table set up with a category table managed via the relatedRecords field - very useful!

My questions are:

1) Are there other uses for this field inside the editor?

2) Does this field have any usage on the generated web pages?

3) Are there other special fieldnames not listed in the online documentation? I don't want to miss any opportunities.


By Dave - October 13, 2017

Hi Deborah, 

In reverse order: 

3) Are there other special fieldnames not listed in the online documentation? I don't want to miss any opportunities.

There are a few more undocumented ones, but they're mostly for internal use and may change.  (eg: the accounts "accessList" field has a special fieldtype of "accessList").  

The best way to familiarize yourself with all the options is to go through all the field types and options in the field editor.  And let us know any questions!

2) Does this field have any usage on the generated web pages?

No, it's just for seeing related records in the database from within the CMS.

1) Are there other uses for this field inside the editor?

Yes, we use it a lot any time we want to show related records, examples: 

  • Within a single section, you could show other records with the same field value.  eg: for a store record, other stores in this city
  • With related data, you can link to the parent and/or child records
  • You can set it up to add child records and return to the parent record.  eg: company record could have a list of related "employees" with an add button that prepopulated the "company num" when you click to add a new employee

It's basically just a way to get a list of records.  So anytime you want to show data from another section it can be helpful.

Let me know any other questions!

Dave Edis - Senior Developer

By Toledoh - November 2, 2017

Hi All.

Zick: There is a way to do that - something about if the related field is fieldName, then you use fieldNameNum and it automatically works... but I always get confused with that so maybe someone else can jump in :)

Deborah: I also use relatedRecords to give my admin users the ability to build out their own page structure...

I use a category section to build the page navigation, and for each page I have fields for the masthead, main content, SEO aspects etc.

I then have a relatedRecords that allows users to "Add / Edit / Delete" panels (from another table).

Each "Panel" has the ability to choose things like background colour, layout (text only, image and text or text and image, carousel, etc) and from that (using is displays the appropriate fields for that panel.  

In addition, I have pre-built modules that I add a "includes" here.  so a panel may include an Image Gallery, or News, or Blog etc.

I've also got a custom plugin that extends the related fields system a bit so I can re-order those panels within the parent record.  But it's built in with a number of of things so it's not something I can share.  I'm sure the interactivetools could offer custom development if it's something you would need.

Hope that helps.

Tim (

By Deborah - November 6, 2017

Hi, All.

Tim, I'm intrigued by your setup for allowing users to build out their own page structure. I can't get my head around what you described entirely, but will give it some thought. Thanks for your insight on this topic and if you have any examples you'd like to share, please do.

~ Deborah

By Zicky - November 6, 2017

2) Does this field have any usage on the generated web pages?

How about this?

I created a "relatedRecords" under accounts, and connected it to a section editor called "User Pages" using Related Records selecting the "user_pages" as the related table, List Actions checked (View, Modify, Erase, Create), with the MySQL Where set to "accountsNum='<?php echo mysql_escape(@$RECORD['num']) ?>'" and More "Search" Link set to "accountsNum_match=<?php echo htmlencode(@$RECORD['num']) ?>" SEE ATTACHED SNAP SHOTS FOR REFERENCE.

I then used a ForeignField to connect the "User Pages" to the user who created the page(s). In the section editor I created a textfield called "accountsNum". This captures the user's account number and stores it in the page the user is creating.

Next create your User page for the front-end of the site, and drop in code for the lists of pages, and filter the list of pages using a matching User Num to the matching ForiegnField number.

See what's in bold in the code below:

<?php header('Content-type: text/html; charset=utf-8'); ?>
  /* STEP 1: LOAD RECORDS - Copy this PHP code block near the TOP of your page */
  // load viewer library
  $libraryPath = 'cms/lib/viewer_functions.php';
  $dirsToCheck = array('/home/directory/','','../','../../','../../../');
  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 record from 'accounts'
  list($accountsRecords, $accountsMetaData) = getRecords(array(
    'tableName'   => 'accounts',
    //'where'       => '', // load first record
    'where'       => whereRecordNumberInUrl(0),
    'loadUploads' => true,
    'allowSearch' => false,
    'limit'       => '1',
  $accountsRecord = @$accountsRecords[0]; // get first record
  if (!$accountsRecord) { dieWith404("Record not found!"); } // show error message if no record found

  // load records from 'user_pages'
  list($user_pagesRecords, $user_pagesMetaData) = getRecords(array(
    'tableName'   => 'user_pages',
    'loadUploads' => true,
    'allowSearch' => false,


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
<html xmlns="">
  <meta http-equiv="Content-Type" content="text/html;charset=UTF-8" />
  <style type="text/css">
    body          { font-family: arial; }
    .instructions { border: 3px solid #000; background-color: #EEE; padding: 10px; text-align: left; margin: 25px}

    <div class="instructions">
      <b>Sample Detail Viewer - Instructions:</b>
        <?php /*><li style="color: red; font-weight: bold">Rename this file to have a .php extension!</li><x */ ?>
        <li><b>Remove any fields you don't want displayed.</b></li>
        <li>Rearrange remaining fields to suit your needs.</li>
        <li>Copy and paste code into previously designed page (or add design to this page).</li>
  <!-- /INSTRUCTIONS -->

  <!-- STEP2: Display Record (Paste this where you want your record to appear) -->
    <h1>User Accounts - Detail Page Viewer</h1>
      <h2>Full Name: <?php echo htmlencode($accountsRecord['fullname']) ?></h2><br/>
  <!-- /STEP2: Display Record -->
    <h1>User Pages - List Page Viewer</h1>
    <?php foreach ($user_pagesRecords as $record): ?>
    <?php if ($accountsRecord['num'] == $record['accountsNum']): ?>
      <h2>Title: <?php echo htmlencode($record['title']) ?></h2><br/>
      <b>View: <a href="<?php echo $record['_link'] ?>"><?php echo htmlencode($record['title']) ?></a></b><br/>
    <?php endif ?>
    <?php endforeach ?>

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

  <a href="<?php echo $accountsMetaData['_listPage'] ?>">&lt;&lt; Back to list page</a>
  <a href="mailto:?subject=<?php echo urlencode(thisPageUrl()) ?>">Email this Page</a>

<?php echo poweredByHTML(); ?>

I attached a bunch of testing files and two scheme ini.php files I created for messing around with this.

BE AWARE! The "__accounts.ini.php" is the same as the normal CMSB accounts.ini.php schema file, so I renamed it so as not to overwrite your accounts.ini.php file.

Hope this helps, Zicky

By Deborah - November 9, 2017

Hi, Zicky.

Thank you for the examples and nicely detailed explanation! I have a much better understanding now of how relatedRecords can connect with section editors and can foresee many possibilities for its use.

Thanks again! ~ Deborah