In my earlier post, The Basic Anatomy of a Custom Function, I described how to write a simple custom function that would add a small piece of content into a specific location (called a hook) on your web page. One point of confusion that occasionally comes up is where you actually put this code.

When you first install Thesis, you'll find two files on your server in the wp-content/themes/thesis_16/custom folder: custom.css and custom_functions.php.

Important: The custom folder originally gets installed as custom-sample. The installation instructions tell you to change the name of the folder to custom. If you haven't done that yet, now would be a good time. :)

These are the only two Thesis files you should be editing.

Note: The layout.css file captures the changes you make in the Thesis Options interface in WordPress. There's no need to edit it manually; however you do need to change the file permissions to 666 as per the installation instructions.

This two-file approach is one of the main benefits of Thesis compared to many other WordPress themes. The advantages include:

• You never have to try to remember where you put a piece of code you may have written months ago.
• You don't have to worry about royally screwing up your core theme files when you make a coding error (and you WILL make at least one... :)
• You won't overwrite all your fantastic customizations when upgrading to the next version of Thesis. You simply make a backup of your custom folder, install the new version, and add your customized files back into it.

custom.css
This file is where you put your CSS code—the code that lets you define how a certain element will look on the page. What you put in this file will take precedence over the built-in theme styles. For example, by default, all the columns are on a white background. A common customization is to add a background color to the sidebar area to better separate it visually from the main content area. So you would add code into the custom.css file that looks like the following:

That will add a gray background to the sidebar.

Note: I'll be providing CSS examples in many of my posts but won't be trying to teach CSS from scratch. An excellent resource for learning how it works (or just for reminding yourself of what the correct property names are) is W3 Schools. In addition to explaining the concepts, it offers great "Try It!" examples where you can make changes on the fly and see what the effect is on the page.

custom_functions.php
This is the file where you put the code for functions that you write, like the one in the article previously mentioned.

One problem I've seen occasionally on the DIYthemes forums is that people have put function code into their CSS file. This will prevent your style definitions from working properly, if at all. (On the flip side, CSS definitions can be integrated into a custom function, but not as standalone bits of code.)

Where does the code go within the files?

For beginners, I would suggest always adding new code to the bottom of the current file. I would normally add a blank line after the last text and then start writing (or pasting copied code) at that point. The advantages are that a) you can easily find where you put it and b) you're less likely to accidentally affect other style definitions/functions. When you get more comfortable with your coding, you may want to reorganize the files so the different sections flow in some sort of logical order, e.g. all the header-related code is near the top of the page. But this would purely be for your convenience—in general, it's not going to make a difference to how it works.

Note: There's one caveat to that last statement. The program will process the code in the order in appears in the file so, if there's some logical reason one piece of code needs to happen before another, then you'll need to make sure they're in the right order. A good example would be if you're putting two different pieces of content in the same hook and one has to appear before the other. The code for these would need to be reflect that.

How do you edit the files?

In the WordPress dashboard, under Thesis Options, there's a link for Custom File Editor. On that page is a dropdown box that lets you pick which file you want to edit. (If you're using the OpenHook plugin, there are links to these files in that section as well.)

While this seems like a nice, convenient way to edit these files, I would strongly recommend you don't use this interface. There are several reasons for this but the main one is that after spending hours the first day writing code for my blog, I made a small edit, clicked the Big Ass Save Button, and the file refreshed... completely empty. I had lost every bit of work I’d done, and there is no automatic backup. I don’t know how often this happens but it just takes once to make you start looking for a better solution. (I have seen other people reporting the same problem on the forums, so it's not just me...)

The other alternative is to make edits on your local hard drive using a simple text editor like Notepad, and then FTP the file back up to the server. You don't want to use word processing software like Microsoft Word because it will apply formatting that can cause problems in your code, like using curly quotes instead of straight ones. I use HTML-Kit, an inexpensive editor (there’s a free version as well) that has one feature that, by itself, makes the fee totally worth it—you can undo changes even after you've saved the file. This is really helpful because you have to save the file before you upload it so, if you don’t like the changes you made, you can just use the Undo function to go back to your earlier version. It has some other features that make it slightly easier to write code but you really don’t need them—Notepad works perfectly fine.

If you’re not comfortable with FTPing files and you still want to use the Custom File Editor, you should definitely make it a habit to copy and paste the full contents of the files into Notepad and save backup copies of the last known working versions in case you need to replace them at some point. (And you WILL need to replace them at some point...)

Troubleshooting

I've been coding HTML for years but, before I started using Thesis, I had limited experience with CSS and zero with PHP. It's actually been quite fun learning them and bending them to my will :) but it can also be quite frustrating when it doesn't so much bend as it does break. What's really annoying is how such a tiny little error, like using a comma instead of a semi-colon can completely crash your site, but know that this happens to everyone.

I've now created a Thesis Troubleshooting page where I've listed some of the most common issues I've run into (many of my own making) and how to fix them. If you have any you'd like to add to the list, please send them along. Of course, I'll be happy to credit you and add a link back to your own site.

In the meantime, if you have any specific questions about working with the custom files, you can also send me those, or post them in the comments area below, and I'll do my best to answer them as soon as possible.

Posted in Blogging, Formatting, How To, My Two Cents, Thesis, User Interface