Basic Block Development

Part Four

Turn Off Caching

Andrew makes an excellent point: you want to shut off all caching for your concrete5 site when you are trying to modify something, or create something new. You will especially want to turn off the overrides cache. Basically with the cache on, concrete5 will never even look to see if your files have changed.

Add an input field

In his example, Andrew adds another field to his block's db.xml. Here is some basic code to add another field. This will be a boolean.

    <field name="newCheckbox" type="I1">

and within your block's form_html_setup.php :

  <label class="checkbox">
     <input type="checkbox" name="newCheckbox" id="newCheckbox" value="1" <?=$newCheckbox ? "checked":""?>/>
        <?=t('New checkbox')?>

Will give you a checkbox in your add / edit form. This illustrates two things:

a. The database column in your block (the <field> here) will be called the same thing in code. b. That data is passed to your add / edit interface by the controller.

however, the block will not automatically pass $newcheckbox to the view.php. this would have to be done explicitly by doing $this->set('newcheckbox',$this->newcheckbox) in the controller's view() function.

Form Helper

Andrew also brings up the form helper. You can definitely use this helper, but if you wrap a checkbox with a <label>, clicking on the text next to the checkbox will also check the checkbos. Otherwise, the box has to moused over to work.

Override and Modify

Andrew then copies the next_previous block's view.php and view.css up to blocks/next_previous/ from concrete/blocks/next_previous/. Now his site will use these files instead of the defaults. Usually, to improve the look of a block you can add a template. Here is a how-to about that. But if you want one block to look the same everywhere, overriding is better, since you don't need to actually pick the custom template you created.

One more thing worth noting that Andrew discovers is that the next-previous block adds "arrows" to the words "next" and "previous" within the controller. He goes on to point out that this is not the way to do things.

The reason being that you should be able to change any kind of display code within your template and by setting this sort of thing in the controller, you limit the usefulness of a block.

In the video demo, it looks like Andrew modifies the block's controller in the core. Generally you would want to copy the block's controller up into your override folder in order to modify it.

Quick Review

Now Andrew wraps up by explaining what each file in a block type's folder does. Here it is:

add.php : always runs when this block is added. Usually, like edit.php, it will have a line like $this->inc('form.php'); and nothing else. Any supporting code you want add in here is fine, particularly if adding and editing a block is significantly different. Andrew also points out that using the inc() function is preferable to using require_once() or other php functions. The inc() function takes the guesswork out of knowing what folder you are actually in.

edit.php : The view that is seen on editing a block. Most often, this is exactly the same as add.php. Technically both are optional, but there is not much point in an uneditable block.

form_setup_html.php : This is usually what the file is named, and it is what is included by add and edit. It can be named anything: "form.php", "add_edit.php". All that matters is that it gets included in the add and edit views.

controller.php : This is where everything about the block is configured, and any supporting functions the block might need, like actions. Here are a few important functions:

  • view() : This gets run "just before" the page is sent to the browser. It's where you'll want to set variables to use in view.php.
  • on_page_view() : Runs before view() and it is where you will want to use the addHeaderItem function for anything that isn't in your block's css/ or js/ folders.
  • save() : Where to modify any data before it gets saved to the database.

db.xml : This file describes the database tables your block will need. The file is written in AXMLS format, you can read about the file format in the Data Dictionary Manual and how it applies to concrete5 in this how-to.

templates/ : This can have differently named php files that are modified versions of view.php but it can also contain folders with their own view.php and other supporting files.

auto.js : javascript that will be loaded only during add / edit.

view.js and view.css : javascript and css loaded on page view. These can be changed by including them in a template.

js/ and css/ : these folders can contain javascript and css that will be automatically loaded. .

Wrapping Up

Andrew mentions that checking out the developer docs and also our how-to section are good places to look for more tips on creating your own blocks, as well as other aspects of concrete5. Be sure to get active in the building with concrete5 forum. We have a helpful and knowledgable community.

Recent Discussions on this Topic

Custom Block View Tutorial

Attached is a white paper on creating custom block views. I am finding many C5 users do not understand this concept and even hesitate to modify purchased addons. I hope this is helpful. Please PM me if you have any additions or corrections and I …

Building a block with library image input?

I'm trying to build a block that has the ability to pull an image from the library (or, since I'm desperate, from anywhere, even a remote URL), but I can't figure it out, and I'm new to PHP... Does anyone have any pointers? I tried reading http://phple…

Check it out: custom block creator!

*** This package is now available on the marketplace: *** I've made a "custom block creator" which aims to solve the problem of allowing you (as the site designer) to specify exactly how som…

Adding smarter DISQUS to your concrete5

Guys, I've just finished figuring out a smarter way to implement Disqus, a third-party commenting system Sometime, you don't bother users to register on your site, but comment using Facebook, twitter or other social ID. Disqus is a fine comment s…

Issues with pasting a block from clipboard

When I paste my custom block from clipboard, it does copies the block but it does not seem functional. Do I need to use duplicate() function in my controller to get this to work properly? Can someone give me an example of using duplicate() function?