Creating a template for use with MicroCyte is a fairly simple process if you follow the guidelines but when things go wrong it can be tricky to troubleshoot the issues. In this post we're going to look at common ways of solving these problems.
Rules of thumb
The simplest rule to remember when building templates is that they should be well formed XML. What I mean by this is that all tags should be closed, and characters should be escaped by their XML entity equivalents. When I say all tags should be closed, I mean that even 'img', 'input' and 'link' tags should have a closing ' />' at the end which means that they are self closing. XML entities cover characters which may vary between character sets, in this case characters like & become & and so on. If you get errors and the error line suggests a unclosed tag or an unknown entity then this is likely going to be your problem.
Because MicroCyte can support PHP includes in templates you might sometimes end up with a situation where you have opened a tag in the template and have closed it in an include or vice-versa. This will break the template for MicroCyte because it will contain unbalanced opening closing tags and wont parse as XML. To avoid this situation, try to avoid inserting includes at unnatural places in the markup.
Error logs
Generally error logs will tell you when there are problems and where there are likely to be in the template. When you get an error message you should look at your PHP error logs as a first port of call. In an all in one stack like MAMP or WAMP you'll generally find the error logs in an easily accessible central place. Hosting providers tend to vary on how and where they generate error logs but they should always be in a fairly obvious place, look for a logs directory or a .errors file in the root of the site.
Permissions
You may find that your templates fail to save even if you've thoroughly checked all the points talked about so far. In this case you could be facing a permissions issue. MicroCyte will always try to give you a specific error message if it can't save because of a permissions related issue but in rare cases it might not be able to.
If you find you have a permissions problem then you might need to do a little research to find out what permissions you should set in order to allow MicroCyte to write to and modify files and directories within the website. This will generally vary depending on the Apache/PHP setup being used. If in doubt you should explain to your hosting provider that you are running PHP scripts which need to modify files within your hosting account and ask what permissions those files should be set to, most hosting provides will be quite helpful.
Hassle free
So there you go, those are the main sticking points of developing templates for MicroCyte, not too much to keep an eye on! Keep these points covered and you should have no problems at all creating MicroCyte templates. For further information make sure you download and read the template development guide available on this site.
