Basic Block Development
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"> </field>
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')?> </label>
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
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.
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
addHeaderItemfunction 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.
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.