CMS Categories

Understanding the CMS Category Module

User Interface
Category Manager
Model
- Category Metadata
- Tree Structure
Controllers
- Cat
- Page

Site Categories are the way we organize the site into a hierarchy of web pages. Each category may contain sub-categories, pages, or a combination of both. And the pages may be static or dynamic.

We create and maintain the categories in the Admin section of the site using the Category Manager.

User Interface

Here are the parts of a category page that are elucidated below:

A: an optional hero/tron image may be assigned to each category → note that since the category is a page, that page also has a thumb image which may or may not match the category image
B: configurable cards for the contents of the category (pages & sub-categories) of the default views to display the contents of a category
C: a sidebar panel that shows the category tree, with links to each published category listing

The Default View

A key concept is that categories are displayed in a view. By default that view is the default `page-summaries.php' which is also used to show search results, pages by author, and pages by tag. Of course you can lay out that page however you wish: It is a static page that typically shows the tron if specified (A), and the cards (B).

A couple of drawbacks of this default page are:

the cards for the sub-categories use the category icon as the image
a category that uses the default view cannot be disabled

Custom Views

Instead of the default view, any category may specify it's own dynamic page to display the category contents. This has several advantages:

You can effectively disable the category by not publishing it's page. This is very useful for categories that contain internal documents (e.g. procedures, to do lists, bug reports), not meant for public consumption.
You can add category specific information around the cards. For instance, in the construction category example, there are calculators and links to hardware stores in the sidebar, as well as general information below the cards about topics that don't warrant their own separate page.

Be sure to use the Custom Category Page Checklist in this page's sidebar!

The category tree widget (C) allows the user to view the overall site structure and navigate to any (published) category by clicking on the category. The branches may be expanded or collapsed.

It is available in any view since it is pre-built by the Category Manager. Use this code:

<div class="panel cattree" >
 <h3>Categories</h3>
 <ul class="tree">
  <?= file_get_contents('assets/files/cattree2.div') ?>
 </ul>
</div>

And be sure to use the Update Widget!!!! explained below.

Category Manager

The Category Manager is launched from Admin section of the site: expand the Content menu on the left side, then click Categories.

The left side of the page shows all of the current site categories as a tree (as shown), or as a list by selecting the appropriate tab on top. Next to these tabs are buttons that operate in the context of the selected category as described in the following sections.

You select a category by clicking on it in the tree. This will highlight the entire category, including its subcategories, and display the contents on the right side of the page, much like it will appear to the end user, but with more buttons primarily to manage the pages themselves.

But before you begin using the Category Manager, there are three very important buttons at the top of the page that you need to understand, especially the Update Widget, !

Once you have finished working with categories in the category manager,

it is crucial that you sink the sidebar widget with the database.

Remember that the sidebar widget is a pre-built piece of code that only gets updated when you click this button. The advantage is that pages load much more quickly without having to calculate the categories every access.

Backup & Restore Category Database

Before doing any major work in the Category Manager, it is highly recommended to click the backup button: This saves the entire Category database table on the server.

Then the restore button will put everything back to the way it was at the backup.

Use the backup button whenever the categories are stable.

Add/Edit Category

Click the add button, , to add a new child category at the end of the selected parent node, or the edit button, , to edit the selected parent category.

Both of these operations bring up the same modal dialog which starts off blank when adding.

Unlike the cut & paste operations below, the category database is updated immediately as soon as Save is clicked on the dialog.

Cut & Paste Branch

This scissors button, , cuts the entire highlighted branch to the clipboard. You can then select another category, and click the paste button, , to place the branch at the end of the newly selected node.

If you do not paste the branch, you have effectively deleted the entire branch.

However, this does not delete any custom pages linked to the deleted categories. It also does not delete any pages in the category.

None of these changes are sent to the server until you click the Save Tree Structure button, .

Page Operations

Recall that the right side of the page displays the current category's content, but with more power than the standard user view.

Publish Page

First of all, both published and unpublished pages appear: Unpublished pages have a grey background, a red bottom border, and a red blocked eye icon, . Click the icon to toggle the published/unpublished state of a page.

Remember that unpublishing the page assigned as the custom category page has the effect of unpublishing that category.

Change Category

Click this icon to move the page to a different category. The page will immediately disappear from the current category and be found in the new one.

Edit Page

Click the quill icon to switch to the page editor for the page.

View Page

Clicking the summary card outside of the above buttons brings you to the standard view of the page.

Model

Category Metadata

id: the system assigned id
id_page: the id of a custom page used to display this category. This value defaults to 0 which means that the category will use the default views to display it's content
title: the name of the category: e.g. My Very Cool Category
slug: the way the category appears in a url for instance, entering my-very-cool-category as the slug will result in the url: /category/my-very-cool-category
mid: stands for media id and it is a link to the tron/hero image displayed at the top of a category listing view. If it is 0, hero image is displayed
icon: the icomoon icon representation of this category. It is used in the sidebar category tree, and in the default category lists to show a category that does not have a custom page to define an image for the listing

Tree Structure

The ShaneBow CMS category module, stores the categories using the nested set model.

Controllers

`Cat`

controls the backend

`Page`

The Page controller controls the front end. There are some different ways to display the contents of a category.

Views

admin

route: /cat/manage

`cms-cat-manager.php.content`

!layout:admin
<title>Categories</title>
~~cms/cats/ui/admin/cat-manager.view

Custom Category Page Checklist

Create the category in the Category Manager
- take note of the category's slug in the add or 'edit' option
- take note of the category's parent category
Create a dynamic page using the standard CMS Pages Editor
- In the Metadata tab set the page's category to the category's parent category
- Also, in the Metadata tab set the page's slug to the category's slug prefixed with /category (i.e. /category/my-cust-category-slug)
  → this is required to force the page to be sent to the category processing method of the Page Controller which properly handles the hero/jumbotron image and sets up javascript variables telling the page what its children are.
- In the Content tab paste in <div id="child-pages"></div>
- In the Scripts tab paste in the javascript code below
- After saving the page, take note of the page id in the Page List

<script>
    new UBOW.PageSummaryFetcher('#child-pages', {
        per_page:12,
        extra: { by:'cat', id:UBOW.meta.kids },
        });
</script>

Go back to the Category Manager
- Select the category and click Edit Category
- set id_page to page id you noted above
- Click Save to apply the change

old Mblogs

The old blog_cats table was just a flat list of blog categories. This is superseded by the new cats table which stores all site categories in a tree structure that includes the blog categories as one branch.

To ease the migration to the new style, we can keep the blogs branch to a single level — Then fetching this branch can return a flat list similar to the old mblogs->get_cats(), below, which is pervasive in the Blog controller: .

    public function get_cats($fields='cats.id,name,icon,cats.slug') {
        return $this->db
            ->select($fields.',COUNT(blogs.cid) as numblogs')
            ->join('blogs', 'blogs.cid = cats.id','left outer')
            ->group_by('cats.id')
            ->get('blog_cats cats')
            ->result_array();
        }

Shane Bow

Technology Consultant

I enjoy making things that serve the greater good — Software (and gadgets) that promote social values, improved quality of life, and learning.

I especially thrive on building strong close knit teams of developers based on superior leadership skills and wide ranging technical know-how and experience.

Topics

Contents