Customizing a block's appearance
There are a number of spots that a block's presentation template can be found in Concrete5, and if you know about them they'll make your life infinitely easier.
Is your block using a custom template?
To see if your block is using a custom block template, put the page you're working on in edit mode, roll over the block in question, and click. Then, select "Change Template" from the menu. A Concrete5 dialog will open. If your block is using a custom template it will be displayed here.
Custom templates are located within the "templates/" directory inside the particular block type's directory. So, say you're working with Autonav block and your block is using the "Header Menu" custom template. Your block's template is either here:
/concrete/blocks/autonav/templates/header_menu.php
or here:
/blocks/autonav/templates/header_menu.php
The second listing will be interpreted before the first. The name of the template is automatically determined based on the filename. In this case, "header_menu.php" becomes "Header Menu" automatically.
These custom templates are found by the system automatically, so if you need to create a new custom template, called "Secondary Nav List" for example, you would copy concrete/blocks/autonav/templates/headermenu.php to blocks/autonav/templates/secondarynav_list.php and make the changes there. Then when editing the site the custom template selector should pick up both the custom templates in concrete/blocks/autonav/templates and blocks/autonav/templates.
If your block doesn't use a custom template...
then it's even easier to find. If you open the custom template chooser and find no custom templates, or custom templates but your particular block is currently set to "(None Selected)" your block is pulling from either
concrete/blocks/your_block_name/view.php
or
blocks/your_block_name/view.php
or
blocks/your_block_name.php
Don't edit the templates within the concrete/ directory!
In the example above, the latter two items are templates in your root web directory. Whenever possible, if you need to change the template of block's that ship with Concrete, you should do so by copying their templates from concrete/ into your own root blocks/ directory and making changes there. That way, when you upgrade Concrete you can replace your entire concrete/ directory without worrying about merging changes you've made into the new directory.
Creating and implementing more complex custom block templates
When a designer/developer delves into creating more complex block templates that will require css or javascript additions, there is a new introduced method that was brought with 5.3.1+.
Generally speaking, any concrete5 sites not using at minimum version 5.3.1 do not have this functionality.
The currently most common method is to include these files in the actual theme by inserting the javascript and css files hard coded in the head section, or to write a custom controller that uses the handy $this->addHeaderItem() method.
What happens if we want to have one block with many custom views (say the image block) which can look entirely different based on a custom blocktype template without having to code anything at all in the pagetype? To do this you need to leverage the new optional blocktype template directory structure introduced as of 5.3.1 in concrete5.
To use this extremely helpful feature you must create your blocktype template using the following file structure:
It resides in the applicable folder in your website using this path terminology: siteroot/blocks/"blockname"/templates/"templatename"/ then the files added are view.php, view.js, and view.css directly into the "templatename" folder.
These files will be automatically loaded (and only once regardless of multiple instances of the block template on the page) to the head of the page whenever this custom block template is selected.. freeing us from any controller hacks or tying our block presentation to our pagetypes/theme.
An example:
siteroot/blocks/autonav/templates/drop_down/view.php
previously was and is still treated the same as
siteroot/blocks/autonav/templates/drop_down.php
but the first structure allows you to optionally specify a view.js and view.css that will be included in the head of the page which allows for jquery effects like a zoom, accordion, whatever you can dream up.
Please note that the name of the folder directly under the templates folder becomes the name of the template in the selector on the "select custom template" menu.
An initial stumbling block some may have is a template requiring more than one javascript file.
If you have several js files that you need to include, simply make a note of the order of the javascript files and combine them all into one file named view.js using any simple text editor. Do the same with multiple css files.
Creating a Custom Block Template Wrapper without Duplicating the Entire View File
While wrapping up a site for a client, I encountered a problem that I decided to solve in new, more sensible way. You see, the client's concrete5 theme – as many do – has a sidebar with some special properties and CSS classes that differ a bit from the main content area. With this in mind, blocks of content and functionality, when added to the sidebar, need to be wrapped in some extra DIVs, to add additional style and padding to the content.
Custom Template Views: All or Nothing
While the approach above is great and allows for endless flexibility, it's an all-or-nothing option: you have to copy all of the block's view template into your current directory, and work on the template that way. This is great when you want to make fundamental changes to the way the block appears, but when you just want to wrap the block in some content, and leave the block's actual view template unchanged, it's a bit cumbersome.
Furthermore, the two blocks I was working with were the form and the survey blocks. The view templates for these blocks are not lightweight. Plus, these blocks are complex. If the core view templates change in the future, I may miss out on some additional styles or features, having forked the entire template. It seemed like a bit much, since all I wanted to do was wrap the entire contents of the block in two DIVs.
A Solution
Fortunately, there's an easy solution to this problem.
- Create a custom template like you would at any other point.
- Within this custom template, add the new DIVs required by the special custom template.
- Within the DIV, instead of cutting and pasting the entirety of the block's view template, cut and paste this instead:
<?
$bvt = new BlockViewTemplate($b);
$bvt->setBlockCustomTemplate(false);
include($bvt->getTemplate());
?>
I'll walk you through what's going on here. First, we instantiate the BlockViewTemplate class, with our current block's object passed into the constructor. This object is the $b object, and it is always in the scope of a block's view template.
Next, we call setCustomTemplate method for the block's view template, and pass false as its argument. Why? If we didn't do this, we'd have an infinite loop on our hands. That's because the block object we're currently working with already has a custom template. That's the template that we're rendering right now! So what we're doing here is basically refreshing the current block, and grabbing the template for the block when a custom template is not activated.
Finally, once complete, we call getTemplate() to return the block's template before a custom one was set. For the form, this will be /path/to/concrete/blocks/form/view.php. We include this, confident that it will continue to work and remain up to date in the future, and knowing we didn't have to duplicate a large amount of view code just to do something simple.
Comments:
The code I added in is part of a Lightbox controller (Is there any way to access the built in lightbox controller in Concrete???? This would probably be a lot cleaner)
The JS file can be found at:
http://66.84.13.1/js/prototype.js
Any help would be most appreciated.
I tried copying view.php directly into my template file, but don't know how to set up the controller object. If this is a reasonable approach, can you give me any pointers?
I tried copying view.php directly into my template file, but don't know how to set up the controller object. If this is a reasonable approach, can you give me any pointers?
