New to Craft? 8 Important Lessons I Learned During My First Projects

Craft was intimidating as hell when I started my first project less than a year ago. But each time I ran into a perplexing Craft problem, I eventually found my way and gained a little knowledge. I just wrapped up a hefty deployment that involved a lot of fun Craft features. I came out much more confident with more knowledge under my belt.

Here’s what I learned — and some of the mistakes I made — along the way. Hopefully one of these tips can save you a little frustration.

1. Don't Be Afraid to Create Plugins

Depending on your project you may need expanded php functionality. That’s where Craft Plugins come in handy. Craft offers a host of plugins that add simple widgets to a page, use custom data types, build out repeatable tasks, or add new functionality to the control panel.

It is possible that you may need more specific and robust functionality. If you can’t find the just-right plugin, don’t be afraid to make your own. For this project, I needed a way to easily grab cookie information and make post requests, so I built a simple plugin to do so.

Craft plugins are somewhat opaque when trying to learn the basics, but the functionality they can provide is fantastic. The official plugin documentation isn't complete by a long shot, but I was able to learn most of the basics from reviewing what documentation is available, reading through this very simple but great MVC example, and studying source code of plugins at Straight Up Craft.

Learning plugin development in Craft requires a lot of Googling, Stack Overflow, and asking coworkers, "Have you ever tried to do X in Craft?" Sometimes though, you just need to read code. For example, building tasks in Craft is barely documented. I learned everything about it from this very tiny plugin: Power Nap.

2. Know and Understand Your Configs

Hopefully this will never happen to you. In attempting to add new blocks to a giant matrix field, I received a Craft error and a lot of block data was lost. I fixed this by increasing my post_max_size field in my php.ini file.

Keep an eye out when messing with big Matrix blocks. Take a database backup and make sure your post_max_size is large enough.

3. Order Entries By Changing Section Type from Channel to Structure

I struggled for a while to find a way to customize entry ordering for a channel. I first made a global variable to manually order the entries and built a much too complicated algorithm to reorder them properly. Great Craft exercises, but ultimately much more easily solved.

Although Craft warns that changing Section Type could result in data loss, all I needed to do was change the type from Channel to Structure. Then I could easily reorder the entries without any extra work. Note: Changing from Channel to Structure is probably the only Section Type change that won't result in drastic data loss.

4. Simplify and Streamline By Using Globals

I had infrequently used globals in other Craft projects, but during a refactor I noticed that all entries in a category had a Form ID field with identical values. Sounds like a great use case for globals!

I was able to remove the Form ID field from the section and use a global variable instead. The Twig syntax for using globals was really simple {{ globalCategory.fieldName }} so switching those over was pretty nice.

5. Fear and Respect Cache Busting

Clearing the cache in Craft is a double-edged sword.

On one hand: Recently a page on production suddenly went completely blank. There was no visible cause other than its entry was recently edited. Reverting to an older version of the entry resulted in the same blank page! When I pulled the database down to local, everything rendered fine. Turned out, all I needed to do was clear my compiled templates. Everything was back to normal within seconds.

On the other hand: Clearing the entire cache can slow traffic to a crawl while the server attempts to rebuild the compiled templates. The entire site may even become non-responsive while it rebuilds.

Caching is a tricky devil, and it’s tough to state any surefire rules regarding cache busting without knowing how templates are caching, the complexity and amount of templates to be rendered, and how the server is set up. Just learn from your mistakes and be very grateful to whoever is in charge of DevOps.

6. Reuse Fields Across Sections

Another frequent refactor I came across was creating too many unnecessary fields in Craft. One entry type had a text field named Form Key while another had a text field named Program Form Key.

Easy fix though: Replace custom, specific fields with common fields that can be reused across multiple sections. You can re-label fields with handy descriptions to save future headaches of wondering what fields do with this plugin. I was able to use the same Form Key field for both Entry Types and I just relabeled them accordingly. This way I could keep the amount of fields from unnecessarily blowing up.

8. Embrace the Learning Curve (It Gets Easier)

It takes a while to know where to go for simple Craft tasks. Adding new categories requires first adding a Category Group and then editing the list of categories.

If you want to add a field to a section you don't click on the section name, you need to click on Edit Entry Types. These will always be a few headaches at first; there’s no easy way to learn. You just need to get your hands dirty and repeatedly break your local setup. It might not be easy, but sometimes it's fun! At least until Craft 3 is released and I get to learn it all again.

Above all, my best advice is just to dig in. I learned the ropes the best way I know how: By getting a bit lost and making mistakes. Every mistake made is a learning experience for next time (and hopefully hasn’t cost you too much time).

I can now say Craft no longer intimidates me. That doesn’t mean I know it all. But next time I come across a perplexing part of working in the platform, I’ll know how to figure it out.