Contributing: Custom Templates

Permalink 15 users found helpful
I just wanted to contribute towards Custom Templates:

http://www.concrete5.org/documentation/general-topics/custom-templa...


I know this probably has been discussed at length on the forums, but I didn't see it in the Help documentation, so I just wanted to write it here.


Concrete5 enables many approaches to customizing the exact look and feel of your blocks.

In addition to the settings provided by each block's edit dialog, you can control display by using CSS styles, the Design dialog or by using a custom template.

By far, the most common customization you use will likely be global CSS styles. By favoring tag-based styles, you can style many block types without having to assign CSS classes. Many block types also include unique class declarations, so you can fine tune styles for each block type individually.

When it becomes necessary to style a specific block instance even further, try clicking the block, selecting Design and configuring your unique styles or CSS class declarations there.

However, it is not always possible or practical to style your blocks using CSS alone. This is where custom templates come in.

Some block types, such as the Auto Nav block, include custom templates by default. Most block types, however, do not include any custom templates, but it is very easy to create your own.

Be aware that custom templates may need to be updated if the block has been improved or changed since the template has first been created. This is important to remember, but it should not dissuade you from using them when it's right.

For any block, duplicate it's path in the root directory of your concrete installation. For example, to create a template for the Auto Nav block, which is located at "/concrete/blocks/autonav", create a directory at "/blocks/autonav". You can exercise this same approach for add-ons from the Marketplace as well. To create a template for the Stickies add-on, which would be located at "/packages/stickies/blocks/stickies", create a directory at "/blocks/stickies".

Once you have created your duplicate directory, add an additional folder called "templates". For an Auto Nav template, the final path should be "/blocks/autonav/templates".

Next, duplicate "view.php" from the block you are creating a template for. Again, for an Auto Nav template, you would copy "/concrete/blocks/autonav/view.php" and paste it into "/blocks/autonav/templates/view.php"

Finally, you have two choices when it comes to making the name of your template unique. You may either rename your new copy of "view.php" to whatever you like (although lowercase and underscores are preferred), such as "my_custom_template.php", or you may create a new directory, placing the file in a location like "/blocks/autonav/templates/my_custom_template/view.php". Either will work fine -- it ultimately depends on which you prefer, and whether you will need any additional supporting files to create your custom template.

Once the proper directory structure has been created, and you have your copy of the original "view.php" file from the block, there are only two things left to do.

The first is to edit or modify your new file however you wish. Change the HTML structure, rearrange tags, comment out things you don't need ... the PHP file will need to work once your done, but if you're at this point you probably are generally familiar with PHP, Javascript and HTML. If this step is difficult, be sure you are using a colorized code editor which understands these languages, to make it easier to recognize code errors.

The second is to choose your new template. While editing a page in Concrete, click on the correct block, select "Custom Template" then select your template from the list.


Custom Templates are very easy to implement once you get the hang of it. Copy, paste, then edit as much as you like. This is a very powerful feature in Concrete5, but don't abuse it. Don't use a template when you could easily do the same with CSS -- it makes it easy to upgrade your add-ons or Concrete install to the latest version.

Hope this helps!

Tags:

basics, basic, block templates
elyon
View Replies:
synlag replied on at Permalink Reply
synlag
Thanks :)
dlloyd replied on at Permalink Reply
dlloyd
You've enlightened me. thanks!!
Shotster replied on at Permalink Reply
Shotster
Thanks for consolidating this info into one place, elyon!

> By favoring tag-based styles...

What are "tag-based" styles?

-Stevbe
elyon replied on at Permalink Reply
elyon
Ah, okay. Maybe there's a better term for it :)

A lot of CSS I see looks like this:


.my-very-specific-class { color: #FFF }



However, because of Concrete's block structure, it makes a lot more sense to try and create your styles like this:


#left-column h1 { color: #FFF }
#main-column h1 { color: #FF0000 }



By creating named DIVs in your theme, you can apply CSS based on which container your blocks are in. Once they are in that container, you can apply styles based on IMG, P, H1 and other tags, rather than trying to apply custom CSS classes to everything. This makes your code flexible, and applies your styles to all the block types at once. Occasionally you may run into blocks which use, say, a H1 when perhaps they should have used an H3, but you can always try and write in exceptions like this:


#left-column .ccm-some-kind-of-block h1 { }



Many blocks will declare a CSS style around themselves, so you can distinguish block-specific styles, however some won't, so in some cases you may consider adding one in the Design panel (then make it a saved design) or if really necessary, a custom template. However, it's better if you don't have to go this route, because many editors might not notice these values, and may forget to add them when putting in new content, or if they delete and recreate the element.


Does that make sense? One approach to CSS is very class-driven, with lots of class selectors, but I think Concrete works best when you do ID and tag selectors, with the occasional class selector when you really need to create exceptions
DragonReeper replied on at Permalink Reply
DragonReeper
The difference between id's(#) and classes(.) are that objects that are enclosed in tags inherit whereas objects within tagged object's don't inherit.

defining you're CSS with tag's are very useful if you want to customize the color scheme.
elyon replied on at Permalink Reply
elyon
Right. That's why I think the best approach, for Concrete's block structure and for theming, is to use a combination of ID and tag references.

If you do a style like this:


p { font-size: 20px }


It will not only affect your whole theme, but the Concrete5 editing interface as well. Instead, you could start a theme with an ID like "page", then name your difference content areas, like "main" and "right-sidebar". That keeps all your styles from breaking the editing interface, and also allows flexibility between different content areas.

For example, lets say my "Main" content area had a white background, but my "Sidebar" content area had a black background. You could define the styles like this:


#page p { font-size: 20px; }
#main p { color: #000000; }
#right-sidebar p { color: #FFFFFF; }


Any styles which affect my whole theme, like the font size, perhaps, can be applied to the whole theme, but then you can still build in specifics, if content should change when dragged between different block areas.
DragonReeper replied on at Permalink Reply
DragonReeper
Also ID's are very useful for javascript

One more thing, for super duper effective
CSS style-sheets you can do positioning in one style-sheet and colors and effects in others thereby having more than one css is possible,

one more one-more-thing:
Create you're styles to be falloff for example if you had more than one nav you could implement their styles as follows:

.nav{
background:red;/*This is the base background for <u>all<u> nav bars */
}
#nav_left{
left:0/*It tells the browser to add this to the spesific id*/
}
#nav_right{
right:0/*It tells the browser to add this to the spesific id*/
}

See what I'm getting to? Use CLASS for objects that are ment to be the template, then use id to modify the template for easier controll and scripting
Ricalsin replied on at Permalink Reply
Ricalsin
Lovely. elyon, I must compliment you on a very articulate presentation. Near perfect grammar too! (Now that's gettin' it on, baby.) It was so well crafted that it motivated DragonReaper to throw in more than his two cents worth.

As I've gotten older, I have discovered the power of "words" - written or spoken. I understand the short and quick version too, as we are all busy. But never discount the power of speaking and writing correctly. Look at Andrew and Franz, both highly articulate and it represents C5 well. Your post was the best I've seen other than theirs. Thank you. And I hope you find the time to do it again. (This post should be stuck up somewhere else for others to see. It's that good.)

Rick
Ricalsin replied on at Permalink Reply
Ricalsin
Lovely. elyon, I must compliment you on a very articulate presentation. Near perfect grammar too! (Now that's gettin' it on, baby.) It was so well crafted that it motivated DragonReaper to throw in more than his two cents worth.

As I've gotten older, I have discovered the power of "words" - written or spoken. I understand the short and quick version too, as we are all busy. But never discount the power of speaking and writing correctly. Look at Andrew and Franz, both highly articulate and it represents C5 well. Your post was the best I've seen other than theirs. Thank you. And I hope you find the time to do it again. (This post should be stuck up somewhere else for others to see. It's that good.)

Rick
osu replied on at Permalink Reply
osu
Might it be an idea to share some of our custom templates in some sort of repository?

I have a few that I could contribute, just need to make sure that they're organised based on C5 version and add-on (if appropriate) so that people who download are aware of Elyon's point that 'custom templates may need to be updated' when new versions of C5 are released or blocks are improved.

Not sure of the best way, maybe a series of How-to's are a better way?
Cyberdave replied on at Permalink Reply
Cyberdave
I have 4 different templates in a block. I have tried renaming the view.php file in each one, so they do not interfere with each other, but it doesn't work. If I change the file name in the custom template from view.php to newslist1.php for example, do I need to change the name anywhere else, or does the name of the template folder need to be the same?
elyon replied on at Permalink Reply
elyon
You can create custom templates either by placing a single PHP file inside the /templates directory with a unique name, or by placing it in its own directory, using view.php as the primary template file.


Here's an example file structure with four custom templates:


/blocks/media_library/templates/custom_template/view.php
/blocks/media_library/templates/custom_template_2/view.php
/blocks/media_library/templates/custom_template_3.php
/blocks/media_library/templates/custom_template_4.php


Even though two of these examples use directories, and two use a single PHP file, each one would appear in a similar way when you go to choose a custom template. This is how the list would look in the editing interface:


Custom Template
Custom Template 2
Custom Template 3
Custom Template 4


You can see that its pulling the name from either the single file, or from the directory name. Underscores are replaced with spaces, and the first letter of each segment is capitalized.

EDIT:

Oh, and I forget if this is mentioned elsewhere, but you should use the top-level /blocks directory when possible.

In the example above, I created a series of templates for the Media Library add-on. The *actual* path for the Media Library add-on when it is installed is /packages/media_library/blocks/media_library, but instead of placing files in the package, it's better to put it in a new directory within the top-level /blocks folder. That keeps your templates separate from the original add-on, which means that you can update, remove or install the add-on without worry of losing your templates. It's also cleaner, in my opinion :)