Sub-categories Tutorial

134 posts by 17 authors in: Forums > CMS Builder
Last Post: August 7, 2012   (RSS)

By Chris - January 22, 2010 - edited: January 26, 2010

Let's say you want to organize a bunch of articles into categories and sub-categories. In the end, you want a list of all your categories displayed on your site, and when users click on these categories, they'll see a list of all the articles belonging to that category. Of course, everything will also need to dynamically update as you change your categories and articles from within CMS Builder.

Firstly, we'll need two sections.
In Admin > Section Editor, create a Multi Record section called "Articles".
Create another section, selecting "Category Menu" as the menu type under <Advanced Menus>; call this menu Categories.

Next, we'll add a "category" field to the Articles section to associate articles with categories.
Click "modify" next to your Articles section, then click Add Field.
Type a Field Label of "Category" and select a Field Type of "list".
Under Field Options, change List Options from "Use options listed below" to "Get options from database (advanced)".
Under that, three new fields will appear. Set Section Tablename to "categories", "Use this field for option values" to "num", and "Use this field for option labels" to "name".
Your field should now be configured like this:

Field Label: Category
Field Name: category
Field Type: list

Field Options

Display As: pulldown
List Options: Get options from database (advanced)

Section Tablename: categories
Use this field for option values: num
Use this field for option labels: name

Now Save your field, and let's add it to the ListPage Fields before leaving the Section Editor.
Change the ListPage Fields to: "dragSortOrder, category, title", then click Save Details.

On the left side of the screen, you should see your new sections: Articles and Categories. Let's add some content now so we'll know we have everything working as we write our viewers.
Click Categories, then Create.
Ignore the Content field for now, just set the Name field to "Dogs", then save it.
Create a second category called "Cats". Now create a third category called "Chihuahuas", but set its Parent Category to "Dogs".
When you save, you'll be able to see that you've created a subcategory.

Now let's add some articles.
Click Articles, then Create.
Enter "Dog Article 1" as the Title and "Dogs" as the Category.
Create two more articles -- one for each of your categories.

It's time to get our fingers dirty.
Click Admin > Code Generator.
Select Section "Articles" and Viewer Type "List page", then click Show Code.
Copy and paste the resulting code into a text editor (notepad will suffice) and save it as articlesList.php.
Let's make a few changes: (new code in red, removed code struck-out)

<?php header('Content-type: text/html; charset=utf-8'); ?>

require_once "/my/path/to/viewer_functions.php";

list($categoriesRecords, $selectedCategory) = getCategories(array(
'tableName' => 'categories',

list($articlesRecords, $articlesMetaData) = getRecords(array(
'tableName' => 'articles',

<!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 List Viewer - Instructions:</b>
<?php ?>
<li><b>Remove any fields you don't want displayed.</b> (Most list pages only have title and link fields.)</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>

<li><a href="?">(All Articles)</a></li>
<?php foreach ($categoriesRecords as $categoryRecord): ?>
<?php echo $categoryRecord['_listItemStart'] ?>

<?php if ($categoryRecord['_isSelected']): ?><b><?php endif ?>
<a href="?category=<?php echo $categoryRecord['num'] ?>"><?php echo $categoryRecord['name'] ?></a>
<?php if ($categoryRecord['_isSelected']): ?></b><?php endif ?>

<?php echo $categoryRecord['_listItemEnd'] ?>
<?php endforeach ?>

<!-- STEP2: Display Records (Paste this where you want your records to be listed) -->
<h1>Articles - List Page Viewer</h1>
<?php foreach ($articlesRecords as $record): ?>
Record Number: <?php echo $record['num'] ?><br/>
Title: <?php echo $record['title'] ?><br/>
Content: <?php echo $record['content'] ?><br/>
Category: <?php echo $record['category'] ?><br/>
_link : <a href="<?php echo $record['_link'] ?>"><?php echo $record['_link'] ?></a><br/>


<a href="<?php echo $record['_link'] ?>"><?php echo $record['title'] ?></a><br/>

<?php endforeach ?>

<?php if (!$articlesRecords): ?>
No records were found!<br/><br/>
<?php endif ?>
<!-- /STEP2: Display Records -->


Now you should be able to click between the different categories and see the correct articles show up. The magic is in getRecords() -- it automatically filters results based on the query string. I hope this helps you get started with categories! Please let me know if you have any questions!
All the best,

Re: [chris] Sub-categories Tutorial

By gkornbluth - January 23, 2010


Thanks for this much needed tutorial

Very clear and concise.


Jerry Kornbluth
The first CMS Builder reference book is now available on-line!

Take advantage of a free 3 month trial subscription, only for CMSB users, at:

Re: [chris] Sub-categories Tutorial

By flamerz - January 25, 2010 - edited: January 26, 2010

this works great.

could be possible to have some identation inside the article pulldown (inside cms builder)?

for example, if we have fruits:apples and fruits:oranges.. the pulldown could show:

instead of


Note: i updated my entry form with the <?php echo $ESCAPED_FILTER_VALUE ?> trick.

nice way to populate a list from another.

Re: [flamerz] Sub-categories Tutorial

By Chris - January 26, 2010 - edited: January 27, 2010

Hi flamerz,

Not quite, but you can achieve something similar by choosing:

Use this field for option labels: breadcrumb

This will give you a pulldown with these options:

fruits : apples
fruits : oranges

I hope this helps! Please let me know if you have any questions.
All the best,

Re: [chris] Sub-categories Tutorial

By paulmac - January 27, 2010

Hi Chris

I can get this working to a point, but you may be able to give me some pointers or assistance with the following:

I want to set the menus up as following:

(when a user selects this link, they get taken to a new page with an overview of all their products and a list/menu of all the Product Categories:

This new page will display the following menu:


When the user selects PRODUCT2 from these options, they will be taken to a new page with an overview of PRODUCT2 and a menu like below:


When the user selects product2_1 from these options, they will be taken to a new page with an overview of product_2 and a menu the same as the previous one.

Hope this all makes sense, I would appreciate any help with it.


Re: [paulmac] Sub-categories Tutorial

By Chris - January 27, 2010 - edited: January 27, 2010

Hi paulmac,

Does this help? Try adding this line (in red):

list($categoriesRecords, $selectedCategory) = getCategories(array(
'tableName' => 'categories',
'categoryFormat' => 'onelevel',

I hope this helps! Please let me know if you have any questions.
All the best,

Re: [paulmac] Sub-categories Tutorial

By Chris - January 28, 2010 - edited: January 28, 2010

Hi paulmac,

For simplicity, the tutorial is only concerned with a single viewer. If you need to specialize the behaviour of your pages depending on whether or not a category is selected, (e.g. removing the "(All Articles)" link,) you can either use separate viewers or check $selectedCategory (note that if there is no selected category, the variable will be an empty array, see below for an example.)

Displaying an overview of your category can be accomplished with the Category section's "content" wysiwyg field:

<?php if (!empty($selectedCategory)): ?>
Selected Category: <?php echo $selectedCategory['name'] ?><br />
<?php echo $selectedCategory['content'] ?><br />
<?php else ?>
No Category Selected.<br />
<?php endif ?>

I hope this helps! Please let me know if you have any questions.
All the best,

Re: [chris] Sub-categories Tutorial

By DanMaitland - March 30, 2010

Are you able to bring in any images that are related to the article as well or just text? If you can bring in imagesthen what is the difference between Categories, subcategories and the relatedrecordslookup plugin?

Re: [Dan Maitland] Sub-categories Tutorial

By Chris - March 30, 2010

Hi Dan,

Categories and Sub-categories are the same thing, really. They can have uploaded images, yes, and getCategories will load them.

The relatedrecordslookup plugin is something completely different.
All the best,