Pages

In concrete5, "page" refers to the actual page you're navigating to when you visit a page on your webiste-- you've likely worked with pages from your sitemap or directly through concrete5's in-context editng. Each page has a unique URL, and all pages generally contain blocks (aka your content). But what more do we need to know about pages?

You may have noticed the occasional url rendering in such a fashion, perhaps after making an edit to your Home page:

http://www.your-c5-site.com/index.php?cID=1

Pages extend the collections class. If we check out the Collections table in our site database, we see that all are pages are listed. Even the Dashboard pages appear on this list. Notice that each Page gets a unique "cID" which stands for Collection ID. You can think of it as the primary key for accessing all the data contained on your page. The collection with ID number 1 is always going to be your top level "Home" page. Each other page has a cID as well-- 2, 3, 4 and so on. When you add a new page, concrete5 creates a new collection to store data about the page. Here's what a Collections table might look like:

Collections

To explain collections we need to delve back into some history. In concrete5’s earlier forms (concrete4, etc), pages weren’t referred to as "Pages"  but rather as "Collections" of blocks. As time has passed, we’ve sought to make concrete5’s structure more easily understandable, and this led to collections being referred to simply as what they’re commonly known as now-- Pages. As you develop in concrete5, you’ll still see references to a variable named $c in many places, and this refers to the curent collection. This is a naming convention that remains in place today. 

Page Types

At its most basic, a page type can be thought of as a "template" for your page.

As we click around a typical site, note that there are often different designs for displaying our content. Home has a right sidebar; About has a sidebar to the left. Blog Entry shows a sample post summary with thumbnail, tag block, etc. These variations are produced by applying different page types. Page types can be changed and selected from edit mode, by clicking the Design button.

To see the current available page types in your theme, go to Dashboard > Pages & Themes > Themes. Scroll to your currently activated theme (blue highlight) and click the Inspect button. Each page type file and its corresponding name is listed.

Areas

Areas are found in each of our Page Types, and their function is to serve as a place to put the editable content on a page. You can think of Areas simply as containers for blocks. Any content well in your site's design will most likely exist as an area your page type. Areas aren't rendered on a published page, but they'll show up when you enter Edit Mode, as a box with a grey dotted outline. Blocks contained by this area are stacked on top, each bordered by a dotted red outline. 

To edit an area, one mouses over the area and clicks. An overlay menu then appears with the various options available to you.

Here’s an example of some very typical code that you may encounter in a Page Type, and how it references $c. This particular snippet of PHP is be used to render an Area in a page: 

$a = new Area('Sidebar');
$a->display($c);

The first line creates a new area object named Sidebar, and the second line renders the contents of that area object. $c refers to the collection object for the current page, consisting of the all the current page’s blocks.

In the code snippet above, we’re rendering the area object named Sidebar from whatever the current page / collection is.

Creating a new area is as simple as adding this snippet to the page type again-- though we'll need to give it a name (aka handle) that is not already in use on the page. The next time our browswer loads the page, concrete5 adds our new Area to the Page's collection and we're up and running-- any page using our Page Type can now add content to the new Area.

Global Areas

Global Areas allow you to display the same blocks in multple places on your site. If you have a block that you want to render exactly the same on numerous pages, such as a header logo, navigation element or anything else that won't differ from one page to the next, a Global Area might just be the right tool for the job. Creating a Global Area is very similar to creating a regular Area, but specifying the GlobalArea object:

$a = new GlobalArea('Site Name');
$a->display();

How are Areas represented in the database?

Looking at the Areas table in a typical concrete5 site, we see that each area has a unique key, arID, and is also matched to the specific page where it gets rendered on your site, using the page’s collection key, or cID. The area handle (arHandle) is also included, adding the final measure of specificity needed to render its blocks in a certain area of a particular page in the site.

 

The first line creates a new area object named Sidebar, and the second line renders the contents of that area object. But what does that $c reference? $c refers to the collection object for the current page. The collection object consists of the current page’s blocks.

In the code snippet above, we’re rendering the area object named Sidebar from whatever the current page / collection is.

Blocks

In a nutshell, blocks are the content you place on your page. A block can be almost anything: a snippet of HTML, a form, a complex image gallery or chat tool. Blocks are also the most granular element of your site’s structure, and as you might already have noticed-- consist of your editable content. Any page content that can be manipulated in edit mode is created by placing a block in an area.

Block Types

To see all the current blocks installed on your site, go to Dashboard > Stacks & Blocks > Block Types. Core Block Types will list all the blocks concrete5 ships with, Custom blocks that are located in your site's blocks/ override directory will be listed under “Currently Installed”.

Clicking any block will display its description, number of instances currently in use on your site, and also provide the option to uninstall / remove the block. The Refresh button forces a reload of the database schema to update.  This last option is useful if you’ve developing a custom block and have recently changed the structure of the data you’re storing.

Note: If you're looking for block types installed by concrete5 packages downloaded from the Marketplace, go to Dashboard > Extend concrete5 and locate the package that installed the block you're looking for. Click "edit" to see a list of its block types.

Single Pages

Single pages are different from regular pages in concrete5. While a typical page is meant to be moved around from one location to another and flexibly fit any page type applied to it, the concept of a single page was created for one-off pages that will only feasibly ever exist in one location on your site. A good example of a single page is the Login page. It’s got custom logic to handle the login process, and we always want it to be available at yoursite.com/index.php/login.

You can see examples of the concrete5 core’s single pages at concrete/single_pages/. You may notice that this directory includes a folder named Dashboard, and if you’ve just surmised that the Dashboard consists of an assortment of single pages, you’re absolutely correct. We’ll be discussing this in greater detail, later on.

Despite being fundamentally different from a typical concrete5 page, single pages share some characteristics of "regular" concrete5 pages:

• Single pages respect permissions.
• Single pages can include editable areas.
• Single pages show up on the sitemap.

Page Attributes

Attributes are bits of data about a page.

Standard Properties

Standard page attributes are included in every page by default, and include Name, Public Date / Time, Owner and Description. These allow you to easily manage common page elements like page title, description, published date, etc. Owner reflects the user that created the page-- whether it's the admin user or another.

Custom Page Attributes

Custom attributes are optional settings that can be selected from a list of all available options. They're designed to solve various challenges a site owner might face when working with a particular site or page.

Packages

Packages are a way to bundle themes and add-ons downloaded from the concrete5 Marketplace. Packages are stored in the your site's packages/ folder, which keeps them separate from the concrete5 core. Inside a package directory, you'll notice that the folder structure mirrors the override structure you're familiar with from your site's root.

Models

Models define the various components of concrete5. Looking in the core models directory, we see files containing code that comprises a lot of the components we use every time we acces our site: areas, blocks, pages, jobs, etc. 

Helpers

Helpers are small libraries designed to simplify common tasks. One such example is the HTML helper. This helper provides an easy way to generate common HTML, CSS, and javascript tags without having to hard-code anything.  When a theme loads the header_required element, it in turn loads the HTML helper and then calls its CSS method, passing the name of the css file to load as its first argument:

$html = Loader::helper('html');
$this->addHeaderItem($html->css('ccm.base.css'), 'CORE');

The helper returns a fully-formed HTML link tag back to the view layer-- our rendered page-- with the path to our css file. This is shown in the first line below:

Later in header_required, we pass other files to to the HTML helper, this time using its javascript method. This time, it prints out HTML script tags with the correct pathsto the scripts we’ve asked for (in this case jQuery and ccm.app.js). The example above show how we’ve passed a total of four files through the helper, and it’s returned valid HTML references for each-- very handy indeed.

Libraries

concrete5 includes many code libraries to help make handling various tasks easier. All this happens behind-the-scenes in the concrete/libraries folder. Inside, you'll notice various concrete5-specific files as well as a folder containing libraries sourced from elsewhere, such as Zend, adodb, markdown, etc.

Tools

The core concrete/tools/ directory contains more components responsible for handling behind-the-scenes functions, like spellchecking, autocomplete, loading alerts and user interface elements like the Add Block menu.

You might have noticed that the tools directory has an override path in your site's root. Tools scripts are a good choice when building a component that requires access to the concrete5 environment but doesn't need to be user-facing. When you reference a custom tools file, remember that the correct path includes index.php-- so the file is run through the dispatcher.