Review of the concrete5 Beginner's Guide - Second Edition


Packt asked me awhile ago to review the book concrete5 Beginner's Guide - Second Edition by Remo Laubacher. I finished reading last week, but haven't had a chance to write up my thoughts.

It feels like concrete5 is really at a tipping point. As places like Theme Forest and Code Canyon start moving in, exposure is really starting to explode. The number of people coming into the IRC channel and posting up using the #concrete5 hashtag on twitter is getting higher every day. It's a really great time to be learning the CMS, and getting in now is probably a good idea. Well, getting in now, if you didn't get in 4 years ago... ;)

One of the biggest hurdles to starting to develop for c5 is really the learning curve. Documentation is much better than it was, but there are a lot of moving parts, and the entire concept of how it works is a lot different from other Content Management Systems. So books like this one are really a help to jump start you past all the other developers that are trying to get up to speed with it.

Keep reading to see my notes/clarification about it, and find out how you could win one of three copies that we will be giving away at our next Minneapolis concrete5 User Group meeting on June 12th.


Installation and Basic Useage

The book starts out with installation. This seemed a bit limited, but I think that might have just been my own perception on things. It's been a long time since I used something like WAMP and Bitnami or anything like that. It seemed like enough for you to get set up and running, if you're a fairly new developer. A lot of people who are reading might already have this stuff set up, so it might have been nice to have more documentation than just using Bitnami. 

It does tell you to disable cache after installation. That's a big thing, really. One of the biggest things that I see when people come into the IRC channel looking for help is the cache causing problems when deploying between servers, or starting to develop. It also covers setting up pretty URLs using .htaccess and the dashboard page. One thing that I thought might be useful to note is that you actually want to leave this off if you are developing anything for the marketplace. It's easy to accidentaly hard code paths, so it works with them on, but not when index.php is in the URL.

As far as using the editing interface, it does a pretty good job of introducing you to the GUI. There were a couple points that weren't really explained to well, which are also the same kinds of things that aren't really documented on the site, either. Things like workflow are relatively new, and configuring is pretty, um, convoluted the first couple of times.

It does a pretty good job with permissions, too. I actually learned that there's a new page in the dasboard (/dashboard/blocks/permissions) where you can set the permissions for which blocks are available to users or groups. In previous versions, you would have to set these on page type defaults and inherit down, and do it on a per-area basis. It's a pretty common request that I get from designers. Once the site is set up and they are ready to hand off to the end customer, they want to make it less confusing by limiting the blocks. Now it just takes a couple of clicks. 

Managing Add-ons

This is really one of the best features of concrete5, the ability to easily install applications and themes without knowing any code, or even how to use FTP. Once you are connected to the marketplace, you can just buy or license a free item. 

It would have been nice if this section had a bit more info about how to customize this for developers. For instance, disabling so that your client doesn't just install anything willy-nilly, or download an update and break modifications you've done to customize it for their site. Or that when you uninstall, it moves things to the trash folder in the files directory. This can end up eating server space. The section on manually installing didn't tell you how to manually install a paid add on, either. That's a pretty big ommision, I think. 

The section on themes had a pretty big error/ommision, as well. It says that page types without an actual file in the theme use the default.php file. That's not totally true. It is true if there is no other file for it, or if you've simply created it from the dashboard. But if you have a page type from a package or in the outer directory that's inside of the page_types folder, that will use view.php. I have the feeling that could be pretty confusing for some people.

It's also a little weird - it shows you the outer theme directory and blocks directory. Seems like that's not really related to add-ons, since they're not in a package. It says that packages "make things easier to install" but really, I don't think things qualify as an add-on, really. Guess that's kind of splitting hairs. 


There were a few things I noticed here. One was that global areas are shown as taking an argument: $a->display($c) - the $c is supposed to be ommited for global areas, but kept for normal areas. Or how getStylesheet is used and helps with customization, but not that it actually can create performance hits. Most of the time I use $this->getThemePath() but that's because I don't like to allow customizations. That's probably because I'm doing very specific one-off themes. Allowing people to change font types, colors, etc, would be a recipe for making the site look very different than the designer's intention, and result in lots of calls about why things aren't working in specific areas.

Another big thing in concrete5 is the fact that edit mode adds 49px of top margin on the html tag. Often themes need to be adjusted for this. He uses $c->isEditMode(), but there's actually a new function $c->canViewToolbar() that covers a lot more situations. I'm not sure if that was available for the version the book targets. 

Block Templates

This is another section where I actually learned something, which kind of surprised me. He shows how to include another view for a block template into your own custom template. Seems pretty usefull if you just need a wrapper and don't need to do much else. I'm not sure, but it seems like you could also wrap in a div with a class or ID from the "Design" context menu option.

There's a customization of a gallery plugin to use attributes on the files to display title and text. This is actually how my Attributes Slider works, but it lets you edit things from the block edit form, rather than splitting between the file manager and the block edit form. Really, it's a great way to do things, attributes are one of the more powerful features in concrete5.

Creating Your Own Block

This actually had some more stuff I didn't know. The section on how db.xml is set up has some really great information. It also had info about an image function inside of the HTML helper that I didn't know about.

It didn't cover the "execute or die" header much, though. If you are developing for the marketplace, you have to have it. 

It covers block validation using javascript and defined strings. This is a good way to do things, and has been the default for most blocks. But you can actually add in a 'validate($args)' function that will give you the entire $_POST array. So you can do PHP validation, and return an error object. That will then be automatically displayed in a popup, with each error in a list. In my opinion, it's a much more elegant way to do things. But like so much of concrete5, it's not really documented anywhere, and not a lot of developers know about it.


There's a few things I didn't really like about this. I know maybe it's for slowly easing people into developing, but I thought that putting the package stuff earlier in the book would help keep things clearer. Removing blocks and themes and reinstalling (especially if it's on a site where you already have content) is a bit clunky and can cause some bugs.

If I were training in new developers, I would probably give an overview of overriding things, and how the system fits together, etc. Then start with package stuff. I find that a lot of what makes for confusing, hard to maintain code is actually doing a lot of work spread out across the top level directories. But it might be kind of hard to do that in a format like a book, where you have to start basic and build up.

I also learned something in this section, too. I didn't know that you could just use a function directly when hooking into an event, I thought you had to use models for that. Seems like it could be pretty useful.

One thing to keep in mind, which I think is actually for the versions that are newer than the book targets, is that on_start in a package doesn't fire if you are using full page caching.

Another thing that I've found very useful, but not really something you have to do, is to split out your package install into different fuctions. So $this->installBlocks(), $this->installSinglePages(), etc, called from within the install function. It helps keep things clean. 


I  think deploying / transferring files is really one of the things that I see a lot of people doing the hard way. The info is valid, and probably appropriate for newer devs. But, really, if you want to get faster at deploying, using things like rsync or git can help out a ton.  I often find that transfers of files with rsync can take minutes where FTP will take hours. Often git pushes are seconds. But again, it's the kind of stuff that is far out of scope for this book.

There were a lot of details about server configuration, caching, tuning, etc. I don't really know much about how to handle that stuff, so I can't really comment on it. But there was another thing I didn't know about here, Apache Bench.  That seems like it would be really handy for tweaking site speed.


Overall, I'd recommend this to anyone looking to become familiar with concrete5 development. It's a great overview. As I pointed out above, there are a few little things that could have used clarification, but overall it's quite solid. The information is current with the 5.6 branch, which is the latest and greatest. There have been a couple changes in the minor revisions, but overall it's great. It seems like there are a lot of changes coming in 5.7 - the developer snapshot is being released today, so I'm not sure how long it will be 100% valid. A lot of the overall structure stuff will be, but there will be tons of new features, and the editing interface is completely changing.

How You Can Win A Copy

When they asked me to review this book, I asked if we could do something like a contest to give away 3 e-book copies. They agreed, so I'm doing a contest! :)

It just so turns out that we have a pretty awesome meetup next Wed, and so we'd like a lot of people to show up. We'll be giving a lot of information that's similar to what's in this book, kind of a brief overview of how everything works for new developers. JordanLev, the mind behind the popular Designer Content add on will be with us, and demoing a new "Pro" version of Designer Content. I also would like to show my new Dashboard Page Managers add on, and how you can save a ton of time with it when creating new sites, and how it can create a very sophisticated blogging platform when combined with my newly approved Oembed add-on.

So, there's a ton of good information. 

The plan is (since people getting out to Minneapolis for it is kind of unlikely) to have our in-person meeting at Spyder Trap, then use U-Stream or Google Hangouts to allow people to attend remotely. Then anyone who is there in person or online will get their name dropped in a hat, and we'll pick the winners then.

We'd love to get as many people as possible to show up for it, so please share this post. I'll be posting up again in a day or two with full details on the online meeting. As I mentioned at the beginning of this post, concrete5 is really poised to explode. I'd love to make sure that people who begin with it get up to speed quickly, and learn best practices right away.

Things like the concrete5 Beginner's Guide and events like local user group meetings are a great way to make that happen.