concrete5 Cookbook

Typically, you will write code that interacts with pages and page types in a block, a controller, or a model in your concrete5 application. For the purpose of these demonstrations, you can place the code anywhere where concrete5 lets you execute arbitrary PHP code.

A great place for this is to add a site_process.php or site_post.php file to your site's root /config directory. concrete5 will execute all of the code in that file once all of the core classes and libraries have been loaded (site_post gets executed before the current page has been loaded, site_process gets executed after the current page has been set). We will use classic PHP debugging techniques to verify that our code is working. Typically, we will dump the contents of a variable using PHP's var_dump or print_r functions followed by an exit command.

Because the debugging techniques used in this book can interrupt the regular functionality of a concrete5 website, it is recommended that you perform these exercises on a development copy of concrete5.

Be sure to comment out or remove the debugging code once you are finished, to resume the normal functionality of your concrete5 website.

The steps for getting the current Page objects are as follows:

Calling the static getCurrentPage function on the Page class will look in the concrete5 Request object to get the current page. If that is not set, concrete5 will use the global $c variable. Note the use of site_process.php to dump the current page variable. We used this file because it is read after concrete5 has set the current Page object. Using site_post.php would have resulted in a null object.

You may have already noticed that sometimes developers will use the global variable, $c, within their code to get the current Collection or Page object. This typically works fine, but best practices would be to use the getCurrentPage function to handle this for you.

We will need to know the numerical ID of the page that you are attempting to load. Often this will be stored in other objects, perhaps even a custom entity that you have stored in the database. For example, say you have a recipes table in the database, and each recipe has its own page in the concrete5 website. You store the page ID for each recipe, so you can load the relevant Page object whenever necessary.

First you will have to get the page ID for the Page object that you are trying to load. For this example, we will just hard-code the ID of the page that we are loading. The steps are as follows:

The page ID (also known as collection ID) is unique in the database, so calling the getByID function will load the correct page data and return a Page object that you can interact with.

We will be loading a page with the path of /about-us. If this page does not exist in your concrete5 site, please add it to the sitemap before attempting this exercise.

Using a static function called getByPath, we can easily get a Page object without knowing the ID. The steps are as follows:

concrete5 will query the database for the page that has the specified path assigned to it. You will want to use good judgment when loading pages by their paths, as that data can change easily through the concrete5 interface. Imagine that you are working on a site with 15 editors, and any one of them has the ability to edit the path of a page. concrete5 by default will save old page paths whenever a new one is changed, but it is not required. Hard coding page paths in your custom applications should be used only when appropriate. It is a much better idea to load pages by their ID whenever possible, as that ID does not change.

You can load any page on the site using this technique. To load a Careers page that exists below the About page that we just loaded, you would write the following:

$careersPage = Page::getByPath('/about-us/careers');

You should know that concrete5 will cache the page IDs related to each path, so if you are experiencing unexpected results while using this function, make sure to clear your site cache by visiting /dashboard/system/optimization/clear_cache/ on your concrete5 website.

We will continue performing these examples in the /config/site-post.php file, as that is a quick and easy place to run the arbitrary code. We will also continue making use of our custom my_debug function that was defined in the chapter introduction.

In this recipe, we will be loading a page type with the ID of 4. Please make sure that this page type exists in your instance of concrete5, otherwise change the ID to something appropriate to your environment.

Much like loading pages, you will need to call a static function on the CollectionType class. The steps are as follows:

The getByID function performs a simple database query to find the page type that belongs to that ID. A CollectionType object is returned when a successful lookup is made.

In this recipe, we will be loading a page type with the handle of left_sidebar. Please make sure that page type exists in your concrete5 installation, otherwise you can add a new page type with that handle, or adapt the recipe to work for your situation.

Here's how we would load the page type with a handle of left_sidebar. This is similar to loading a page by its path. The steps are as follows:

A simple database query is performed, which will return a CollectionType object if it is successful.

Just like the warning for loading pages by their paths, you will want to exercise the same good judgment when loading page types by their handles. Since these handles are just strings that can be edited through the concrete5 interface, you will need to make sure that you aren't writing code that could break if one of the site editors changes the handle of a page type.

We will be loading a page type with a handle of right_sidebar in this example. If that page type does not exist in your concrete5 system, feel free to adapt this recipe to suit your specific situation.

The steps for getting a page type's ID are as follows:

Once the page type object is loaded, developers can call a number of functions to retrieve data from it, including the numeric ID.

We will be loading a page type with the handle of right_sidebar, so if that page type does not exist in your instance of concrete5, please adapt this recipe to suit your needs.

The steps for getting a page type's name are as follows:

The getCollectionTypeName function simply returns the string value of the page type's name.

We will be loading a page type with an ID of 4, so please ensure that this exists in your concrete5 website. Feel free to change the ID in this recipe to something appropriate for your instance of concrete5.

The steps for getting a page type's handle are as follows:

The function getCollectionTypeHandle of the page type object returns the handle string of the page type.

We will be loading a page type with a handle of right_sidebar. Feel free to change this handle to something appropriate for your concrete5 instance if right_sidebar does not exist.

The steps for getting the icon for a page are as follows:

concrete5 returns a string containing the actual HTML image tag with the collection type's icon.

If you would like to get the numeric ID of the file containing the page type icon, you can simply call this function:

$iconId = $pageType->getCollectionTypeIcon();

The numeric ID is useful when working with the file manager in concrete5, which is discussed in detail in Chapter 3, Files and File Sets of this book.

If your instance of concrete5 does not have a page type with the handle of right_sidebar, feel free to adapt the recipe to suit your needs. We will continue using /config/site_post.php as our sandbox to run random code snippets, as well as our custom debugging function that we created in this chapter's introduction.

The steps for getting a list of pages belonging to a page type are as follows:

concrete5 simply uses the relational MySQL database to find all of the pages that are related to the page type. Be aware that concrete5 ignores permissions settings when this function is called, so this should really only be used for internal purposes.

First, you will need to create an associative array that contains the data of the page type that you are creating.

The array can contain the following fields:

We will create a page type using only the required fields: ctHandle and ctName. The steps are as follows:

concrete5 will take the data array that you pass in and use it to create a new CollectionType record in the database. concrete5 will also automatically generate a Master Collection page in the database. The Master Collection is a template page that concrete5 will use as base for all pages of that type. Any blocks, attributes, or other data assigned to the Master Collection will automatically be added to any new pages created with that page type.

If you are creating this page type in a custom package, you will need to pass in your package object to the add() function, so concrete5 knows that this page type belongs to your package. That way, when users uninstall your package, they will have the option of removing all of the page types that it created.

Assuming that you know the handle of your package, use the following code to create a page type with it:

$data = array(
  'ctHandle' => $handle,
  'ctName' => 'Page Type Name'
);
$pkg = Package::getByHandle('my_package');
$newPageType = CollectionType::add($data, $pkg);

First you will need to load an existing page type. You will need to pass in the same data array when updating page types as you would when creating them. The steps are as follows:

concrete5 will update the record in the database for the loaded page type. The Master Collection page is not updated when this function is called. You also cannot pass a packaged object to the update function, as that is only necessary when first creating a page type.

Since deleting page types is a destructive action that is irreversible, it's a good idea to create a dummy page type with the handle of delete_me for this exercise. We will also continue using site_post.php to execute arbitrary code.

The steps for deleting a page type are as follows:

The delete() function deletes the page type, the Master Collection, and all of the pages that use it. Use this function very cautiously, as once the data has been deleted, it cannot be recovered (unless you have a backup copy of the site's database).

We are continuing the practice of putting our code in /config/site_post.php for the purposes of demonstration and testing. In real-world use, your dynamic page creation would happen in controller files or in add-on packages.

We will be assigning the new page a page type with the handle of right_sidebar. If this doesn't exist in your own concrete5 installation, please adapt the recipe to suit your needs.

The steps for creating a page are as follows:

The add() function is a wrapper for the Collection class's add() function. Calling it will create a new Collection record in the database, and a new pending CollectionVersion record (which will be approved if the cvIsApproved variable is set to true or left blank). Then the new page will inherit the necessary permissions and get all of the blocks and other attributes from the Master Collection of the related page type.

You will need to provide two parameters to the add() function, a CollectionType object (which we worked with earlier in this chapter), and an associative array containing all of the data needed to create the page. The associative array can contain the following fields.

In this recipe, we will be modifying a page with the path of /about. We created that page in the previous recipe, but if it does not exist on your system, please adapt the code to your needs.

In this example, we will update the name of the About page. The steps are as follows:

The update function updates the necessary tables in the database with the newly specified information. concrete5 will also rescan all permissions for this page and all of the related page paths. When the function is complete, the on_page_update event is fired, which you can write custom code to listen to and perform custom actions when a page is updated. Listening to system events is covered in a later chapter.

Just like creating a page, you will need to pass an associative array to the update() function in order to update an existing page. You can use all of the fields specified in the previous recipe for adding a page, in addition to these other optional fields.

You will need to know at least the handle of the attribute key that you wish to assign to the page. A common attribute to set is the Meta Title attribute, which updates the text that appears in the HTML <title> tag.

We will set the Meta Title attribute to the About Us page in this example. The steps are as follows:

The setAttribute function is a member of the Collection class, which the Page class extends. It requires that you provide two parameters, an attribute key (which can either be a string representing the attribute key handle (which we provided here), or an actual AttributeKey object), and the value.

The setAttribute function is very handy for setting the data of any kind of page attribute. One can update a page's meta information (such as description, keywords, and title) and also give the page various options, such as, excluding it from the navigation (as seen previously) or from the sitemap.xml file that search engines look for.

You can update any attribute that has been installed in the concrete5 system. To see all available page attributes, or to create new ones, visit the Page Attributes area of your site's dashboard (located at /dashboard/pages/attributes/).

We are assuming the presence of a page with the path of /about in this recipe. If that page does not exist, you can create it, or adapt the code in this recipe to fit your circumstances.

The steps for getting a page attribute are as follows:

concrete5 uses the attribute handle string to find the appropriate record in the database and return its value. concrete5 stores attributes in the EAV format (entity, attribute, value), and this makes it difficult to read these values directly with SQL queries. The concrete5 API simplifies this for developers.

Please make sure the /about page exists in your instance of concrete5. Feel free to modify the code in this recipe if that page does not exist.

The steps for getting a page's ID are as follows:

The steps for getting a page's path are as follows:

The steps for getting a page's handle are as follows:

The steps for getting a page's name are as follows:

Many pages in concrete5 do not have descriptions. If you wish, you can edit a page to add a description as shown in the following screenshot:

The steps for getting a page's description are as follows:

The steps for getting a page's page type ID are as follows:

The steps for getting a page's page type handle are as follows:

The steps for getting a page's theme object are as follows:

The steps for getting the children below a page are as follows:

concrete5 will return an array of numeric IDs for each of the pages beneath the parent page. In this example, we loaded the home page, so the result should be a list of every page on the website. This function ignores permissions, and can be taxing on the database if there are a lot of pages to load. It is a better idea to use the PageList class to loop through pages, and that class is described later on in this chapter.

In this example, we are going to move a Careers page underneath the About Us page. Before we can move a page, we need to have the Page object of the new parent page that we are moving the current page to.

This exercise assumes that pages exist at both /about and /careers in your concrete5 site. You can create those pages through the concrete5 interface, or adapt the code in this recipe to work with pages that exist on your own site.

The steps for moving a page are as follows:

The move function is very easy to use. You only need to provide one parameter, which is a Page object of the new parent that you are moving the page under. There is an optional second parameter to indicate if you wish to retain the old page path in addition to the current one. That parameter defaults to false.

Once the page is moved, it will inherit the permissions of the new parent page (if the page does not have its own permissions set explicitly).

Once the page is moved, the event on_page_move is fired.

Deleting pages is a permanent destructive action. When experimenting with this code, it would be a good idea to create a dummy page with a path of /delete-me.

We will permanently delete the about us page and all of its child pages. The steps are as follows:

concrete5 will fire the on_page_delete event before any actual deleting occurs. After the event fires, the page (and all of its children) are deleted from the database. This operation is permanent, so it is important to make sure that you only delete pages when you are certain that they are no longer needed.

If you don't want to permanently delete a page, you can move it to the Trash. As of concrete5 version 5.5, pages can be "temporarily" deleted and moved under a special internal page called the Trash.

$page->moveToTrash();

In this example, we are going to find all of the pages under the /blog page. This is a common use of the page list model. The PageList class is not automatically loaded by concrete5, so we will need to use the Loader class to have it available to us.

If your site does not have a page located at /blog, it would be helpful to create that page, as well as a few child pages below it. Otherwise, feel free to adapt the code in this recipe to suit your needs.

In this recipe, we will get a list of 20 pages that exist under /blog in the sitemap. The steps are as follows:

The PageList class extends the core DatabaseItemList class, which has a number of useful functions itself. The get() function accepts two parameters, the number of records to retrieve, and the offset.

The page list class implements "magic methods," which allow allow us to filter the list by any page attribute. We simply need to create a function name based off of the camel cased version of the attribute handle, preceded by "filterBy". So to filter all pages that have the exclude_nav attribute, we would write the following function:

$list->filterByExcludeNav(true);

Alternatively, if you want to just get an array of the first 99 Page objects and ignore pagination, use the get() function.

$pages = $list->get(99);

Since version 5.5, concrete5 uses Twitter's open source Bootstrap CSS framework for many of their internal styles. You can get the pagination controls in nicely formatted HTML (with relevant Bootstrap CSS classes) by printing/echoing the results of the following function (preferably you'd use this function in a view or template file of a block or single page):

echo $list->displayPagingV2();

The DatabaseItemList class and PageList class have several functions that make working with a collection of pages easier. You can filter by keywords, by collection type, parent page, and by any attribute using magic methods. We will cover the DatabaseItemList class further in Chapter 5, Working with Databases and Models.

We will need to use the FormPageSelectorHelper class, which we will need to load using the Loader library.

This recipe will need to be written inside of an HTML form somewhere in your site. We have created a basic single page for this purpose, which can be downloaded with the code from the website for this book. To install the single page, copy the code for this recipe to your concrete5 site directory and visit /dashboard/pages/single. Add a new single page with a path of /example.

concrete5 includes a helper to generate the necessary JavaScript and HTML text needed to show the sitemap selector widget. We will use the Loader class to include and return the PageSelectorHelper class, which will then return the entire HTML that we need. The steps are as follows:

The selectPage function returns the HTML and JavaScript necessary to produce a page selector field. There is only one parameter required, and that is a string indicating the name of the field. concrete5 will add a hidden <input> element to the form, which will allow the selected page ID to be read from a POST request.

In this example, once the form is submitted, you could retrieve the selected page ID by looking in the $_POST super variable.

$pageId = $_POST['page_id'];

You can specify a page ID in the optional second parameter, which will populate the page selector with an existing page.

$page = Page::getByCollectionPath('/about-us');
echo $pageSelector->selectPage('page_id', $page->getCollectionID());

The pageSelector helper also has a function to display a sitemap in a modal window.

$args = array(
'display_mode' => 'full'
);
$pageSelector->sitemap($args);

Note that the sitemap() function loads an element, which is automatically printed to the screen, so there is no need to echo or print the result.