Developer Introduction: Part One
Terms & Concepts
In concrete5, "page" refers to the actual page you're navigating to when you visit a page on your website-- 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).
Pages as "Collections"
As you develop in concrete5, you may see the occasional reference to "collections". In concrete5’s earliest releases, we referred to "Collections" of blocks to express the flexibility of a concrete5 site's data. 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, certain parts of concrete5, today.
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 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');
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.
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');
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.
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.
Since each block is built to handle a different kind of content, each block installed in our site is a represented as its own Block Type. To see all the current blocks installed on your site, go to Dashboard > Stacks & Blocks > Block Types.
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.
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.
- Single pages are rendered using your theme's view.php file.
Page Attributes store data about a page. Standard page attributes are included in every page by default, and include Name, Public Date / Time, Owner and Description. Custom Page Attributes can be created and installed to handle custom data that you'd like to save against a page. Page Attributes are typed to reflect the kind of data they're saving-- like a string of text or a checked checkbox. We can then use these attribute values to do all kinds of useful stuff in concrete5, such as changing how a page is listed, or even managed.
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 mimics the working directory at the root of your concrete5 site.
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.
$html = Loader::helper('html');
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:
In this case, the core has returned valid a HTML tag for our core stylesheet and printed it out in our page's header-- very handy indeed. Helpers can be also be used to load navigation components, references to scripts, form elements and more.
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 files offer a way to access parts of concrete5 without loading the full environment. Placed in the root of your site, a tools script is called through index.php. For example: