Anatomy of a Block
In Concrete5, a block is simply a collection of files in a directory, and some behind-the-scenes registrations that let Concrete5 know that the block is there and ready to be used.
- Core Concrete5 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.
Like other things in Concrete5, 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
Required. This file is the template displayed when a block is rendered on a page in Concrete5.
Optional. This file is the template displayed when adding this block through Concrete5. 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.
Optional. This file is the template displayed when editing the block through Concrete5.
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.
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.
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.
Optional. Contained within this directory are alternate views for instances of this block, which can be set as custom templates through Concrete5. 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.
Optional but Recommended. This is a combined add/edit interface for a block type that enables it to be used in Composer view.