In Concrete CMS, a block is simply a collection of files in a directory, and some behind-the-scenes registrations that let Concrete know that the block is there and ready to be used.
Location
- Core Concrete blocks are found in concrete/blocks/
- Blocks provided by marketplace items or custom packages can be found in packages/the_package_handle/blocks
- Custom block types (like in this tutorial) are found in application/blocks.
Handle
Like other things in Concrete, a block type has a handle. This is a lowercase-only, non-spaced string that describes the block type in the filesystem. Examples include "content", "youtube", "page_title", etc…
If we're creating a block type that we'd like to refer to as a "Hello World!" block, we'd give it the handle of "hello_world", and it would be found in application/blocks/hello_world/.
Contents of a Block's Directory
view.php
Required. This file is the template displayed when a block is rendered on a page in Concrete.
add.php
Optional. This file is the template displayed when adding this block through Concrete. Usually this is shown in a dialog window. If this file is ommitted, the block will be added to the area and saved the moment it is dragged into the page.
edit.php
Optional. This file is the template displayed when editing the block through Concrete.
controller.php
Required. This file contains a PHP class for this block type, which in turn contains vital information about the block type, including its name, description, dialog interface dimensions, and more. Additionally, different methods defined in the class can pass data through to the add, edit or view templates, and specify how the block saves its data.
db.xml
This file is required for any block that needs to save its data in the database-- which is most of them. This file contains an XML description of the database tables needed, in the AXMLS format. For more information, see Creating and Working with db.xml Files.
auto.js
Optional. If this file exists it is automatically included when the blocks is in add or edit mode. (Note: this file will only be included once per page load.) This can be useful for JavaScript that should run when interacting the block's edit interface.
icon.png
Optional but Highly Recommended. This graphic displayed in Concrete's interface whenever the block is listed. This icon should be square, and at least 50x50.
templates/
Optional. Contained within this directory are alternate views for instances of this block, which can be set as custom templates through Concrete. For example, the typical autonav block formats its entry as an unordered list, but the "Header Menu" template can be applied to the autonav block, which then restructures the menu with DIVs.
scrapbook.php
Optional. This is an alternate view layer to view.php which will be substituted whenever the contents of this block are listed in the scrapbook. This can be useful for blocks that contain complex JavaScript or multimedia content.
composer.php
Optional but Recommended. This is a combined add/edit interface for a block type that enables it to be used in Composer view.