6 min read

In this article by Sufyan bin Uzayr, author of the book concrete5 for Developers, you will be introduced to concrete5. Basically, we will be talking about the creation of concrete5 blocks.

(For more resources related to this topic, see here.)

Creating a new block

Creating a new block in concrete5 can be a daunting task for beginners, but once you get the hang of it, the process is pretty simple. For the sake of clarity, we will focus on the creation of a new block from scratch. If you already have some experience with block building in concrete5, you can skip the initial steps of this section. The steps to create a new block are as follows:

  1. First, create a new folder within your project’s blocks folder. Ideally, the name of the folder should bear relevance to the actual purpose of the block. Thus, a slideshow block can be slide. Assuming that we are building a contact form block, let’s name our block’s folder contact.
  2. Next, you need to add a controller class to your block. Again, if you have some level of expertise with concrete5 development, you will already be aware of the meaning and purpose of the controller class. Basically, a controller is used to control the flow of an application, say, it can accept requests from the user, process them, and then prepare the data to present it in the result, and so on.
  3. For now, we need to create a file named controller.php in our block’s folder. For the contact form block, this is how it is going to look (don’t forget the PHP tags): 
    class ContactBlockController extends BlockController {
    protected $btTable = 'btContact';
    /**
    * Used for internationalization (i18n).
    */
    public function getBlockTypeDescription() {
    return t('Display a contact form.');
    }
    public function getBlockTypeName() {
    return t('Contact');
    }
    public function view() {
    // If the block is rendered
    }
    public function add() {
    // If the block is added to a page
    }
    public function edit() {
    // If the block instance is edited
    }
    }

    The preceding code is pretty simple and seems to have become the industry norm when it comes to block creation in concrete5.

    Basically, our class extends BlockController, which is responsible for installing the block, saving the data, and rendering templates. The name of the class should be the Camel Case version of the block handle, followed by BlockController.

    We also need to specify the name of the database table in which the block’s data will be saved. More importantly, as you must have noticed, we have three separate functions: view(), add(), and edit(). The roles of these functions have been described earlier.

  4. Next, create three files within the block’s folder: view.php, add.php, and edit.php (yes, the same names as the functions in our code). The names are self-explanatory: add.php will be used when a new block is added to a given page, edit.php will be used when an existing block is edited, and view.php jumps into action when users view blocks live on the page.

Often, it becomes necessary to have more than one template file within a block. If so, you need to dynamically render templates in order to decide which one to use in a given situation. As discussed in the previous table, the BlockController class has a render($view) method that accepts a single parameter in the form of the template’s filename. To do this from controller.php, we can use the code as follows:

public function view() {
if ($this->isPost()) {
$this->render('block_pb_view');
}
}

In the preceding example, the file named block_pb_view.php will be rendered instead of view.php.

To reiterate, we should note that the render($view) method does not require the .php extension with its parameters.

Now, it is time to display the contact form. The file in question is view.php, where we can put virtually any HTML or PHP code that suits our needs. For example, in order to display our contact form, we can hardcode the HTML markup or make use of Form Helper to display the HTML markup. Thus, a hardcoded version of our contact form might look as follows:

<?php defined('C5_EXECUTE') or die("Access Denied.");
global $c; ?>
<form method="post" action="<?php echo $this->action('contact_submit');
?>">
<label for="txtContactTitle">SampleLabel</label>
<input type="text" name="txtContactTitle" />
<br /><br />
<label for="taContactMessage"></label>
<textarea name="taContactMessage"></textarea>
<br /><br />
<input type="submit" name="btnContactSubmit" />
</form>

Each time the block is displayed, the view() function from controller.php will be called. The action() method in the previous code generates URLs and verifies the submitted values each time a user inputs content in our contact form.

Much like any other contact form, we now need to handle contact requests. The procedure is pretty simple and almost the same as what we will use in any other development environment. We need to verify that the request in question is a POST request and accordingly, call the $post variable. If not, we need to discard the entire request. We can also use the mail helper to send an e-mail to the website owner or administrator.

Before our block can be fully functional, we need to add a database table because concrete5, much like most other CMSs in its league, tends to work with a database system.

In order to add a database table, create a file named db.xml within the concerned block’s folder. Thereafter, concrete5 will automatically parse this file and create a relevant table in the database for your block. For our previous contact form block, and for other basic block building purposes, this is how the db.xml file should look:

<?xml version="1.0"?>
<schema version="0.3">
<table name="btContact">
<field name="bID" type="I">
<key />
<unsigned />
</field>
</table>
</schema>

You can make relevant changes in the preceding schema definitions to suit your needs. For instance, this is how the default YouTube block’s db.xml file will look:

<?xml version="1.0"?>
<schema version="0.3">
<table name="btYouTube">
<field name="bID" type="I">
<key />
<unsigned />
</field>
<field name="title" type="C" size="255"></field>
<field name="videoURL" type="C" size="255"></field>
</table>
</schema>

The preceding steps enumerate the process of creating your first block in concrete5. However, while you are now aware of the steps involved in the creation of blocks and can easily work with concrete5 blocks for the most part, there are certain additional details that you should be aware of if you are to utilize the block’s functionality in concrete5 to its fullest abilities. The first and probably the most useful of such detail is validation of user inputs within blocks and forms.

Summary

In this article, we learned how to create our very first block in concrete5.

Resources for Article:

Further resources on this subject:

Packt

LEAVE A REPLY

Please enter your comment!
Please enter your name here