BlogmyQuery – BMQ

PHP is widely available with inexpensive hosting plans, which makes it a popular choice for developers who write software for the Web. From big platforms, such as WordPress, down to small scripts, such as ones to display image galleries or to send forms to email, thousands of script and products are out there written in PHP that can be installed and used even if you don’t know much about PHP yourself.

I have been a PHP developer for 10 years, and my company has developed a content management system, written in PHP, that is intended to be very simple to install and get started with. So, I spend a lot of time working with designers who are installing a PHP script for the first time. If you are installing a script and something goes wrong, PHP can be incredibly infuriating. Until you know what they mean, PHP errors can be baffling. My favorite message is:

Parse error: syntax error, unexpected T_PAAMAYIM_NEKUDOTAYIM

Paamayim Nekudotayim means “double colonâ€� in Hebrew! But double colon is a lot easier to debug than T_PAAMAYIM_NEKUDOTAYIM.

This article is aimed at designers who are not PHP developers but need to install PHP scripts from time to time. Thus, the problems and error messages we will look at here are those you are most likely to encounter when installing scripts, rather than when writing PHP. The tips should help you work through other error messages and should at least help you give clear information to the script’s developer if you need to ask them for assistance.

“All I Get Is A Blank Page!�

Before we can diagnose PHP errors, we need to see some PHP errors. Ideally, you would first be installing the script locally, perhaps using MAMP on a Mac or XAMPP, both of which allow you to turn on error messages easily. You can get PHP to just spit the errors out directly on the screen or log them to a file for viewing.

If, however, you are installing a script directly in your hosting account, the host will likely have disabled the display of all PHP error messages. This is sensible for security, because an error message could give away important information about the server or database, but it isn’t so useful if you are trying to configure a script. If error displays have been turned off, then a fatal error before any output is made to the page would result in a blank page. An error that happens after some HTML has been outputted would result in the markup being “cut off� (stopping at the point where the error occurred). If you “View source� and see a completely blank page or half a page or are getting a “500 internal server error,� then a PHP error is probably the culprit.

Locate the Error Log

On a live server, you should have access to the PHP error log. This is different than the Web server error log, which shows things such as 404 errors when a page or image is not found. The PHP log gives information on errors and warnings in PHP itself. The host should have configured PHP to send errors to a log rather than write them to the screen.

If no error log can be found, then you might be able to configure PHP to maintain one in a location that you specify. To do this, create a directory on your website named errors. Make this directory writable. Then add the code below to the .htaccess file at the root of your website. If you do not have an .htaccess file, create one.

php_flag  log_errors on
php_flag display_errors off
php_value error_log  /your/path/public_html/errors/php_error.log

Then, protect the errors directory so that the file cannot be downloaded from the Web. You might be able to do this in the control panel or just by creating a new .htaccess file, this time in the errors directory.

Order allow,deny
Deny from all

If you now run the script that caused the error, the error message should get added to the php_error.log file. If it doesn’t work, try creating the file yourself first in the errors directory and making it writable.

If you have no luck creating an error log, then open a support ticket with your hosting provider, explaining what you are trying to achieve and inquiring how to do it.

Errors, Notices And Warnings

PHP classifies the messages that go to the error log as either errors, notices or warnings. These have different levels of severity. An error is something broken in your code. It needs fixing and will cause PHP to stop executing.

A warning is essentially PHP saying, “What you’re doing will likely cause a problem, but I’ll try to continue.�

A notice alerts you to something that needs attention in your script. It could be that the version of PHP on your server is newer than the one supported by the script. Things in PHP are deprecated in the same way that elements in the HTML specification get deprecated. When something is deprecated, it means that it will be removed in the future, so the notice lets you know this.

Errors in a purchased or open-source script are most likely an issue with your installation, assuming that your version of PHP meets the requirement. If a script is throwing out warnings that you cannot fix, then you should probably raise them with technical support. You can usually ignore notices, although you should check that the latest version of the script is installed. If a lot of notices are being thrown out, it could indicate a poor-quality script.

If the trick above for turning on error logging worked for you, you can set the level of error reporting in the .htaccess file, too:

php_flag  log_errors on
php_flag display_errors off
php_value error_log  /your/path/public_html/errors/php_error.log
php_value error_reporting 1

The above will add only errors to the error_log.

php_flag  log_errors on
php_flag display_errors off
php_value error_log  /your/path/public_html/errors/php_error.log
php_value error_reporting -1

Setting error_reporting to -1 will log all errors, warnings and notices. If you do this, then you’ll definitely want to set php_flag display_errors to off, so that notices do not get outputted to your website’s pages.

The First Error Is The Important One

If you are displaying errors to the page and hit a PHP error, you could run into a terrifying page full of errors. If you are reviewing errors in a log, refresh the page that is generating the error and then check the log. You might find a long set of errors for the same page; they should all have the same time code, helping you to identify them as a set. This usually happens when the first error is a warning; the script tries to continue running but hits more problems related to the initial warning. Fix the initial warning, and you might find that all of the other issues go away.

Database-Related Errors

Many of the errors people encounter when installing a script have to do with the connection to the database. Usually, when a script needs to make a database connection, you will be asked for four bits of information: the database’s user name and password, the server’s address (which is often, but not always, localhost) and the database’s name. If any of these are incorrect, you won’t be able to connect. Depending on the script, either you will see an ugly string of error messages or, if the developer has handled this gracefully, you will be told that the script was unable to connect to the database.

The database connection issues that I commonly see when providing technical support are as follows:

• The user has entered localhost instead of an IP address or URL for the database server.Localhost means that the database is on the same server as your website. Some hosts have different servers for MySQL and so will give you an address for the server that you need to use when configuring the script.
• An incorrect user name has been entered.One thing to watch is that cPanel prefixes user names that you create with the account’s name. If your account’s name is fred and you create a user named website, then the user name to enter when configuring a script would be fred_website.
• An incorrect database name has been entered.As with user names, cPanel prefixes the database’s name with the account’s name. Check that you are using the prefixed version in your configuration.

Database Permission Problems

Another possible cause of database-related trouble is when all of the connection details are correct, but the database user doesn’t have the permissions needed to do things that the script needs to do. For example, the script might need to create database tables and so would require the database user to have create permissions.

If you created the database user in cPanel, you would also need to select the database and join the user to it, giving the user enough permissions to run the script. For example, if you were installing WordPress, your database user would need to have All Privileges for the database it is attached to.

In cPanel, you can set these in the section named “Add user to database.� Select the user and database, and then on the next screen, click the “All Privileges� checkbox before submitting the form.

PHP Errors

The next set of errors are those generated by PHP because of some problem with the script that you’re installing or because of something that was introduced while you were installing or configuring it.

Fatal Error: Call to Undefined Function

Fatal error: Call to undefined function my_function() in /home/mysite/public_html/test.php on line 2

This means that a PHP function that the current page needs cannot be found. The function might be part of the script itself or built right into PHP. You might see this error when installing a third-party script for the following reasons:

• If you’re installing a new script, you might not have uploaded all of the files. In my experience, people who use Dreamweaver’s FTP client encounter this issue a lot.
• If you’re upgrading, you might not have replaced all of the required files. So, an old version that doesn’t contain the function is being used.
• You might not have added a required PHP include or specified a correct path in a configuration file.
• A script might be calling a PHP function that is not available on this server. For example, it might be calling imagecreatefromjpeg() when the GD image libraries haven’t been installed.

To solve the error, check carefully that all of the files have been uploaded or replaced and that you have followed the installation instructions. If you cannot resolve it, then contact the script’s developer, explaining what you have done and what you have checked and copying the error message.

If the issue is that something is missing in your PHP installation, then you might need to contact your hosting provider.

Fatal Error: Cannot Redeclare

Fatal error: Cannot redeclare my_function() (previously declared in /home/mysite/public_html/runtime.php:14) in /home/mysite/public_html/runtime.php on line 26

This usually means that you have included a file twice. Check everywhere you have edited and check included files to make sure you haven’t duplicated an include.

Fatal Error: Allowed Memory Size Exhausted

Fatal error: Allowed memory size of 67108864 bytes exhausted (tried to allocate 17472 bytes) in /home/mysite/public_html/lib/Image.class.php on line 198

You will typically see this error when trying to upload and process an image, although you might see it for any script that requires a lot of memory to run. The amount of memory that your scripts are allowed to use is set by the hosting provider. On cheap shared hosting plans, these limits are often set very low. If you need to use a script to process large images, contact your provider to see whether you can move to a plan with higher limits.

Permission Errors

Warning: move_uploaded_file(/home/mysite/public_html/upload/my_cat.jpg) [function.move-uploaded-file]: failed to open stream: Permission denied in /home/mysite/public_html/upload.php on line 49

This warning is an example of a permissions error. The script is trying to upload a file to a directory, but the directory doesn’t have enough permissions for the file to be moved to it. The permissions that PHP needs in order to write to a file or directory depend on how the server is configured and whether you are using a Unix or Windows host. The section on “Permission Scheme� in the WordPress Codex is relevant even if you are not using WordPress. However, if you get any kind of “Permission denied� error or warning and can’t fix it simply by changing the permissions for the folder, speak with your hosting provider rather than the developer of the script, because your provider will be able to tell you how to do this.

PHP Warning: Include

PHP Warning:  include(foo.php): failed to open stream: No such file or directory in /home/mysite/public_html/test.php on line 2

This warning tells you that an include file (included using PHP’s include syntax) was not found. It is a warning rather than an error, because PHP will continue trying to load the page if it cannot find an include.

In PHP, you can include files using include() or require(). If you use require(), then you are telling PHP that this script is vital to running the website, and so PHP will spit out an error if the file is not found, rather than try to continue.

If you get a warning or error message that a file could not be opened, then check that the file referred to in the error message is there and that your path to it is correct. For example, if you have the file /inc/navigation.php, and the page calling this file is in the directory /about, then you would need to include navigation.php with the following include:

<?php include(../inc/navigation.php); ?>

Omitting the ../ would result in a warning because PHP would not be able to find the file.

In Summary

PHP errors can seem very confusing if you are not a PHP developer, but if you read the error message carefully, you will usually find something that leads you to the root of the problem. Most of the errors I see in technical support have to do with incorrect database connections, missing files or permissions. These are all things that someone with no PHP knowledge can identify and fix themselves, just by learning how to access error messages and becoming familiar with what PHP is saying in them. Being able to debug these kinds of problems will save you a lot of frustration and will free you from having to wait for tech support to get back to you.

If you run into an error when installing a script, remember the following:

1. Learn how to access PHP errors on your server.
2. Look at the error log to see what the error actually is.
3. See if you can identify the source of the problem by looking at the initial error message or warning for the script.
4. If the error seems to involve permissions or an incorrect database configuration, open a ticket with your hosting provider.
5. If the script is the problem, then open a ticket with the developer, explaining what you have done and copying information from the error log. You will bring joy to their heart if you provide the actual error message rather than say you saw a blank page!

Further Reading

• “Advanced PHP Error Handling Via .htaccess,â€� Jeff Starr, Perishable Press
• “Configure Error Log,â€� WordPress CodexWordPress-specific information on configuring the error log.
• “3 Ways to Monitor PHP Errors,â€� Jeff Starr, Digging Into WordPressIncludes some other methods of logging errors.

Have you come across a particularly baffling error when installing a script? Have you come across a hosting provider that requires a different method to get error logs working? Add your suggestions in the comments section.

Image source on front page: Alex E. Proimos

(al)

© Rachel Andrew for Smashing Magazine, 2011.

Whether your product is an open-source script, a Web application or a downloadable product, you will need to provide some form of technical support. This article explores the subject based on my experience of supporting our company’s product, Perch, a small content management system (CMS) that we sell as a download for people to install in their own hosting space. Our support has been a key factor in the success of this product, not just because users love responsive support, but because we have used what we have learned from users to improve the product.

Don’t Underestimate The Importance Of Support

As Eran Galperin says in “You’re Pricing It Wrong: Software Pricing Demystified� on Smashing Magazine:

“A commercial product that comes with support will often win over customers who want that assurance that someone will be on the other end of the line should they need it.”

Support can be a key selling point, a reason for a person to choose your product over the competition. In our case with Perch, the competition is often free software, so including unlimited support with a license is a big part of why someone might choose us over a competitor. Even for products aimed at technologically literate users, knowing that someone is on hand to answer questions or fix bugs can influence the decision to buy or sign up.

Don’t Underestimate The Time This Will Take

Users will always need support. You could have a bulletproof product and the most excellent tutorials and documentation, and someone will find a way to break it or just not read the information staring them in the face. Later in this article, I’ll explain some ways to minimize support requests and the time spent in dealing with them. But you should expect to offer support and build it into the price of your product.

Your support systems should also help you track the amount of time being taken up by support, so that you can plan for future requirements. If you are a small company whose product developers are supporting the product at present, knowing the amount of time each license or user requires for support on average will enable you to project when you might need to hire additional support staff.

Methods Of Providing Technical Support

When launching your product, decide how you will support it. Depending on the product and the people using it, you might offer some or all of the following types of support:

• Phone,
• Email,
• Social media,
• Ticketing system,
• Real-time chat.

Phone

Supporting users by phone is time-consuming, but for some types of products, it can reassure potential buyers, particularly if they are not Internet-savvy or if the product handles sensitive information (for example, financial or health data). Users might trust the product more if they know they can speak to a real person. You can take phone support further by offering a remote-desktop feature to help customers right on their computer.

We chose not to offer phone support at Perch, because the support requests we get generally require us to look at a customer’s config file, diagnostic report or template code. So, an initial phone conversation would simply raise the cost of supporting customers, because we’d have to ask them to send this information by email or some other way.

If you do provide phone support, clearly state when it is available, including time-zone information. Also, keep track of the time you spend on this and the issues that customers raise so that you can combine it with the information that you collect via email or your online help desk.

Image source: Opensourceway.

Email

A lot of companies start with email support. Simply publish an email address, and answer queries as they come in. The advantages are that you don’t need any additional software, and everyone uses email. However, it gets tricky if you are not the only person supporting the product. If all of the support staff logs into the same mailbox, two people could very easily answer the same query, or a request could get ignored because everyone thinks someone else is dealing with it.

Email is also less than ideal for tracking requests over time and for working out the amount of time you spend dealing with them. You also need to be quite disciplined at filing away “closed� requests before your inbox descends into chaos.

If email is your predominant support mechanism, then consider setting up template responses to common requests, much as you would use canned responses in a help desk system (as I’ll describe below). Don’t forget to keep improving, adding to and correcting these responses as your website or product changes. Inadvertently giving out old advice is easy when these templates get out of date.

Social Media

Support via social media has become so important that many large companies are far more responsive on Twitter than via traditional means. Social media should be a part of your support system, but it shouldn’t be the only way that you help people. Being able to quickly respond to someone who is having a problem or has a question about your product is incredibly powerful. We have set up searches in our Twitter clients, so as soon as someone mentions Perch, we can respond. If a person mentions that they are trying out our demo, we simply say, “Let us know if you have any questions!� and we leave it at that. It is important that you not appear to hound potential customers; just give them a way to ask informally about anything on their mind.

If you have staff dedicated to support on Twitter, make sure they are empowered to help people. Many large companies have dedicated Twitter support personnel who only seem able to direct people to answers on the company website, which is often more frustrating than helpful! T-Mobile in the UK handles Twitter support very well via its @TMobileUKhelp account. Its support personnel is able to deal with most of the things that the phone-support operators handle, once the customer has verified their identity via direct message.

Small companies can do social media really well, often better than large companies. If a customer is using Twitter to vent their frustration, a couple of quick and helpful messages can turn them from “I’m so annoyed� to “Wow! Support for this product is amazing!� People are generally very understanding about problems as long as they can get help quickly.

A lot of support requests are hard to deal with on Twitter, though. For example, at Perch, many questions require us to see the user’s code or to ask them to try something. In these cases, you need to be able to direct them to another channel, whether a ticketing system or even an email address. Long discussions over Twitter tend not to be very helpful; so, unless I can answer the query in one or two messages, I point the user to our ticketing system or forum, where I can pick up the conversation and provide better information.

Ticketing System

I would suggest that anyone with a commercial product use some kind of ticketing system. This support system can often be combined with the methods listed above. For example, many systems can turn incoming emails into tickets, or can log phone sessions in a useful format, or have an interface where users can submit tickets directly.

Ticketing systems make the process of providing support easier when multiple staff members are involved, because you can see whether a request is being responded to and who is working on it. They also make it far easier to keep track of the support requests coming in and how much time they are taking up.

To use a real-world case study, when we launched Perch just over two years ago, we started using a hosted software-as-a-service system called Tender. Tender is a fairly lightweight system that allows users to submit tickets that are either public (visible and answerable by anyone, not just support staff) or private (visible only to support staff).

We were happy with Tender, except for a couple of issues. First, we didn’t want our ticketing system to function as a forum, so we set up a separate forum elsewhere. But this meant that people had to look in two places for answers: the forum and the ticketing system. Our documentation was also located elsewhere. Secondly, because anyone could view and respond to support queries, we often saw customers themselves replying to tickets submitted by other customers; often the advice was helpful, but sometimes it was incorrect or confusing, and customers couldn’t tell the difference between official responses and responses from well-meaning customers. There wasn’t a way to stop this from happening other than to make all tickets private.

It became obvious that Tender, while a good system, just didn’t suit the model we wanted to use for support. This, it turns out, is key when selecting a support system — far more important than the feature list. When looking for a support system, decide first how you want to support your customers, then assess each system against that model to see whether it fits.

Having decided that our initial choice of Tender wasn’t quite working out, we made a list of what we wanted in a support system:

1. A system with tickets and public forums all in one place (plus, the ability to publish documentation on the same system would be ideal);
2. Excellent support for multiple people responding to issues;
3. A system that can handle HTML and code examples being posted by customers and by us as responses;
4. Statistics to enable us to track tickets, response times and so on.

We started to research, and we asked on Twitter which support systems people liked. Zendesk quickly rose to the top of the list, and were it not for a long-standing issue with code formatting, we would probably have used Zendesk. I really liked the integration of social media in the product; however, while this was a nice to have, the problem with the code snippets was a deal-breaker.

We then looked at Assistly. It is another feature-rich system, but it felt a little too oriented around email and self-service for what we wanted. It felt a little impersonal in some ways, and our decision came down to it just not fitting our model and how we wanted Perch support to look and feel.

Finally we were pointed to HelpSpot. HelpSpot doesn’t have as many features “on paper� as the other two systems we looked at, but, crucially, it supports the combination of forums, tickets and documentation that we were looking for, thus enabling us to support customers the way we wanted. After trialling version 3 of the product, which was still in beta, we decided to move our tickets, forums and documentation to a self-hosted installation of HelpSpot.

All of the systems we looked at are good systems with excellent features. Ultimately, it came down to which best suited our model for providing support. Having figured that out before testing the systems in trial, we were able to choose more easily between them, and we are still happy with our choice a few months after having made the switch.

Real-Time Chat

Real-time chat-based support is a feature of some ticketing systems, and is also available as a standalone service (as with Olark). We do use this with Perch, although primarily for pre-sales queries rather than for actual support. Like Twitter, it can be a really good way to quickly answer a question, but for longer answers and code samples, dealing with people in the main support area is much easier.

Real-time support on websites can be helpful for companies that offer a service. With Olark, you can see exactly where someone is on your website as you are talking to them, so guiding someone through a potentially confusing process would be simple. It does, however, require that someone be available to provide this support should users come to rely on it. With a ticketing system, people expect some delay in getting a reply.

How To Reduce Support Requests And Time Spent Dealing With Them

You will never eliminate support requests completely, but you can do a lot to minimize them and to reduce the time you take in dealing with them.

Design Support Requests Out of Your Product

With Perch, we actively try to see support requests as an indication that something needs improvement or clarification in the product or related support material. By tracking requests and seeing where patterns emerge that show people running into problems in certain places, we are able to prevent the problem from occurring or provide better support material.

For example, before logging into your Perch admin account on your own website, you need to go to your account on the Perch website and specify the domain where Perch is installed. You can actually set two domains — the live and test ones — but before you can use Perch, you need to set at least one of these.

In the past, if you hadn’t set a domain in your account, then when logging in you got a message saying, “Sorry, your license key isn’t valid for this domain.�

People who didn’t fully read their email invoice might have missed the bit about setting up domains and so would have been confused when they saw this message, and thus submitted a support ticket. In an update to Perch, we changed this process so that if an administrator hadn’t yet entered any content, we could detect that they were a new user who just needed to configure their domains and so prompted them to do so (giving them the domain that they needed to register in their account). Support tickets were no longer submitted for this issue.

Designing support requests out of the product as much as possible obviously benefits us, because the less support we need to provide per license, the more profitable our product is. But it also gives our customers a better first experience with Perch. Being confused and needing support before even logging in isn’t a great first impression.

Build Debugging or Diagnostic Information Into the Product

Perch is a product that people download and install in their own hosting space. As you can imagine, we are now experts in the many bizarre ways that shared hosting providers configure PHP! We needed a way to get information from not very technical users about the environment in which they were running Perch. To do this, we created a diagnostics report that gives us a lot of information about the server that Perch is running on, which apps are installed, what their path to Perch is, and so on. The report, coupled with the user’s query, often gives us enough information to answer the support request right away.

Building in some diagnostic information that users can find and send to you could save a lot of back and forth, especially if your product or app is self-hosted and can be deployed in a variety of systems.

Add Features to the Product

If many of the people requesting support are asking about how to do something that your product doesn’t currently do, then it would be worth thinking about how you might accommodate this as a feature. While your ideas about what your product is and is not might be pretty fixed, you need to have some flexibility. In our case, Perch is “a really little CMS,� designed for small websites. When we launched, we thought that people wouldn’t need features such as undo, create drafts, edit drafts and previewing. It soon became apparent through support that our users very much wanted these features, and so we found a way to add them without bloating the software. Use your support requests to help guide development. Once it becomes obvious that someone is asking for something that Perch doesn’t do, we will often ask them, “How do you see this working?�

Provide a Range of Support Material

People learn how to use apps in a variety of ways. I like to read documentation and play around with code. For many people — especially visual learners — actually seeing things happen is much more helpful.

We were getting support requests from people who were obviously confused by our documentation. But we also heard people say how good our documentation was! What was going on? Blaming the first group for not understanding the documentation would be tempting — but once you decide to blame the user, you miss an opportunity to help people in different ways.

To help visual learners, we started a series of video tutorials. Currently, these videos just deal with the basics of using the product, but they have made a huge difference to the number of people we have to handhold through the website-building process. Frequently, we will point someone to the tutorial and then not hear from them again until we see the first post on their newly launched website. In the past, we might have seen a number of tickets from them during that process. The lesson here is to provide material in different formats and for different levels of users: bare documentation is important for technical users and for those who like to read quickly and get on with it; step-by-step examples and videos will help others.

Use a Support System That Lets You Create Template Answers

Often we need to ask people who request support for additional information, such as the diagnostics report mentioned above. HelpSpot lets us store these answers and punch them in as responses in one click, saving us time on the initial interaction. If you can reduce the time spent saying the same things, then you will have more time to dedicate to solving problems and working on the product.

Image source: Opensourceway.

How to Phase Out Support for Old Versions of a Product

If you sell desktop, phone or self-hosted Web software, rather than software as a service, you might need to consider what to do about supporting old versions of your product?

Traditional software companies tend to give users sufficient warning that support for an old product will end on a particular date. Security patches are often made available past that date if flaws are found in the old product, but no other fixes or changes are made. For example, Microsoft’s mainstream support for Windows XP Professional ended in 2009, although “Extended� support (which includes security patches) will continue until 2014.

The most important thing is to be fair to customers and give them plenty of notice of the end of a product version’s life. Your company needs to make decisions about the status of old versions far in advance of doing anything about it, and let customers know when support for an old version might end or be limited to critical security issues.

Some Final Thoughts

A question we are often asked at Perch is, “Is the support a nightmare?� It is all too easy for software developers to view support as a necessary evil, a part of the job to deal with as quickly as possible or even to outsource. If you approach support in this way, then you are missing out on a chance to make a real difference with people. You are also missing out on product improvements that you could have made by listening carefully to customer requests.

I firmly believe that software developers should provide their own support — perhaps not all of the support, if the product is popular or gets a lot of non-technical requests on the front line, but certainly some of it. It’s only by seeing the pain points firsthand and helping users through them that you can start figuring out how to solve them — and solving problems should be what we software developers do best.

Further Reading

• “Seven Steps to Remarkable Customer Service,â€� Joel on Software
• “On Scaling Customer Service in a Startup,â€� David Noel
• “How to Use Twitter for Customer Service,â€� Mashable

(al)

© Rachel Andrew for Smashing Magazine, 2011.

Designing and indeed front-end development for a website that will have content edited by non-technical users poses some problems over and above those you will encounter when developing a site where you have full control over the output mark-up. However, most clients these days want to be able to manage their own content, so most designers will find that some, if not all, of their designs end up as templates in some kind of CMS.

By considering the CMS as you design, you can maintain far more control over the final output. If your designs will be implemented and integrated into the CMS by a developer, then taking control at the design phase will help you to keep control over the design as opposed to leaving decisions to the developer or the content editors.

Know your enemy

Content Management Systems vary greatly in how much control they give the designer and the content editors. As a designer, you should first find out how much control over the templating system of your chosen CMS you have. Control may vary from simply being able to edit the existing templates to being able to shape the CMS completely around your designs. In some older CMS products you may find that you have little control over the mark-up that is inserted into the pages.

Where the content editors are concerned you should find out:

• Will the editors be able to insert any HTML tags into content areas, either by way of a WYSIWYG editor or directly?
• Is content simply large blocks of marked up content inserted by the editor or does the CMS use any kind of structured content?

Many people use WordPress as a CMS. In WordPress, users can add any mark-up to the Page content area

If users of the CMS will be able to insert their own HTML, then you need to consider how your design will hold up when that happens. The ideal situation for a designer is where the user has limited ability to enter their own mark-up and the CMS uses blocks of structured content to guide them into adding content in the right way that can then be marked up correctly by the templates. The more freedom a user has, the more defensively you need to design.

Keep it consistent

However flexible your CMS is, it is important to consider the consistency in your design templates. Training content editors is far easier if the elements that they have to work with are consistent across all pages of the site.

If working with any kind of structured content in your design (for example an article listing that displays a list of titles and excerpts from articles on the website), think of each section as a repeating block. With CSS3 we can more easily target every other item, or the last item, but this is not available for older browsers and it may not be possible to edit the back-end code of the CMS to add a class to every other item or the last item. Ensure that the design will hold up if each repeating block is the same — you can always add extra finesse for those browsers that do support CSS3.

When dealing with areas that are essentially large blocks of content where the user has control over the mark-up, don’t assume the user will remember to add lots of different classes to the mark-up to trigger the CSS effects you envisaged. Either keep things simple or use CSS3 selectors to target areas of the design.

Do not assume content length or height of blocks

On the web it is never a good idea to assume you know how tall something will be — as even where you have control of the content, text resizing can blow your assumed heights right out of the water and cause overlaps or text running off background images.

When designing for a CMS, you have the additional issue of more or less text being added to an area that you envisaged. If creating the initial designs in Photoshop or similar, consider how each box and the surrounding content will react to a greater or lesser amount of content. If providing PSD files to someone else to build, ensure that any background images on these boxes are provided with instructions on what happens if the box is taller. For example do we show more background or matt onto a flat color?

Grid type layouts of boxes can be a particular problem in this situation. A common design might have several boxes with header areas. They look lovely and neat in the PSD comp with regular lengths of lorem ipsum. However, once the content editors have added content, we find that some headings are on one line, some on two and the boxes are wildly differing heights leaving the neat grid looking rather messy. Considering this at the design phase may have dictated a different layout here.

The lists on the homepage of the Dubbed Creative website do not depend on height of content: some points have more text than others. This type of layout looks tidier than attempting to create equal height boxes with non-equal lengths of content.

If you are handing over to a front-end developer, thinking through these scenarios keeps the control on your side. Decide how you want it to look and explain to the developer how it should react to text resizing, additional content and so on and you don’t run the risk of leaving these decisions to people without an eye for design.

Avoid using image replacement for text

It is possible to generate images on the server side using PHP and other languages, however your CMS is unlikely to offer this capability as a standard feature. Therefore you should consider how any non-standard fonts will be included in your designs if that text needs to be managed by the CMS.

The situation with fonts is becoming far easier as there are now a number of services that allow you to use fonts that are not installed on your user’s computer but that would otherwise be difficult or impossible to license to include on your website. If you need a specific font you may be lucky and find that one of the below services have it available, or they may have something available which is close enough to get the visual effect you want.

Services such as Fontdeck and Typekit mean that using images for text is not neccessary to use a specific font.

• Fontdeck
• Typekit
• Fonts.com Web Fonts
• Font Squirrel
• Review of Popular Web Font Embedding Services (here, on Smashing Magazine)

Consider the CMS when designing navigation

The CMS that you are using is likely to dictate the navigation to some extent, so find out by checking the documentation or speaking with the developers what will be possible. It is useful to know what control content editors have over navigation. If they can add elements to the main navigation for example, it may be that you are best to avoid a neat row of tabs at the top of the site as additional tabs added by users may wrap.

An attractive row of tabs such as these on the Long Hollow Church Website may look untidy if editors have access to add new top level navigation elements.

Questions you should get answers to include:

• How many levels of navigation will be displayed? Is this configurable?
• Can content editors add to or change the main top-level navigation?
• Can you highlight the current page or section?
• Does the CMS offer breadcrumb style navigation?
• What mark-up will the CMS output for the navigation? Can we change it or add classes?

Design and create CSS rules for all possible HTML elements

In your design and dummy content you may only use two levels of heading and never add an ordered list or blockquote, However, if these elements can be added in the CMS, then at some point someone will use them. If you have used a CSS reset stylesheet you may not have styles defined for these elements at all — which will mean they look rather strange when used. Ensure that you have created CSS for all HTML elements in the content areas of your site.

I find it helpful to start my stylesheet with the default styling for all elements as this then acts as a fallback if I don’t add specific rules for styles later on in the document. I can always overwrite this CSS to make level 2 headings look different when they are in the main content area to when they are the heading of a sidebar box, but if I don’t add any specific CSS and then the user adds these elements, they do have some thought put into them.

Assume HTML elements can be stacked in any order

When creating your design, it is easy to assume that the content will look very much like your structured sample content. The h1 will be followed by a couple of paragraphs, never stacking headings and so on. The reality will be different once content editors get their hands on the design, so test the elements in different combinations.

Ask yourself questions such as:

• Does the design still hold together well with stacked headings? Is there appropriate spacing between them?
• What happens if a heading is used inside a list item?
• What happens if different list types are nested? Is the spacing correct at the bottom of each list?
• If the user can insert and align an image, what will then happen to the text around that image? Will there be a margin or will the text run right up against it? What happens if they put an image inside a list item?

Use CSS to enforce the style guide and semantics

This is something we tend to see once users become comfortable with their CMS: they begin to realize that, for example, an h1 heading gives them large bold text. You then start to find h1 headings in all kinds of strange places — wherever the user thinks something should be marked as very important. This can include half of the content of some pages. In the first instance we all need to try and educate our users and provide them with a style guide to help them understand the importance of semantics and correct usage of mark-up but the person you originally train will probably not be the person who manages the content forever and ultimately you will find users being creative with their mark-up.

A considered use of CSS can prevent this from happening. For example, we generally only want one h1 per page. If the main page heading is in a container, then you can use CSS selectors only to target that h1 with the main heading styling and reset the browser defaults on all other h1 headings to the same as the main body copy. This means the user has no benefit to using h1 in a non-semantic manner. The advanced selectors found in CSS3 can be very useful here.

CMS Editors may want to get creative when given a “WYSIWYG” editor such as CKEditor – use CSS to protect your design as much as possible.

Test with real content

Once your design has been developed into (X)HTML and CSS, test your assumptions in terms of how the content will behave. I find it helpful to do this before the templates are incorporated into the CMS. Points to test:

• Take each headline or small box in the design. Put in three times the amount of content you would expect it to have. How does it look? Does the box expand nicely or do you run off the background image or overlap another element?
• Grab a chunk of HTML from anywhere — just View Source on some site and grab a bunch of content complete with HTML tags. Paste it into your main content area in the template. How does it look?
• If using structured mark-up to display an event or similar — does the design hold up if certain items are removed or do you end up with obviously empty areas such as the word “Tel:” with no phone number after it if a phone number was not entered for a contact?

Help your content editors to maintain the design

If you hand over the CMS with little instruction for your users, then you can’t really expect them to read your mind and maintain the design as you would like. Even if your initial content editor is thoroughly trained on how to edit the site, as time passes by they may forget, or decide to get a little bit creative, or the initial editor may leave and someone else takes over with little training. At the end of the project, keep control over the design by helping your editor to do things the right way.

Remove functionality from the editor

The WYSIWYG editor in your CMS may by default give the user the ability to add all kinds of styling, even adding inline CSS. However, with many editors it is possible to trim down the toolbars to just offer a limited subset of icons and therefore functionality that is exposed to the user. If you can trim down the editor to only offer the ability to add basic HTML elements, you will have far fewer problems to deal with.

Add CSS to the WYSIWYG editor

If content editors have access to a WYSIWYG editor when editing content, add the CSS rules used on the site to the editor CSS. That way, editors can see how their changes to the content will actually look. In combination with using CSS to enforce the style guide, this can help users to maintain the consistency on the site.

Create a style guide that also includes semantics

Include a style guide for the site as part of your handover documentation. It is easy to just handover documentation on how the CMS functions and forget to also explain to content editors which elements they should be using when adding their content. This is particularly important if editors have a lot of control over the mark-up which they enter.

By considering how content will be edited on your site and the possible ways in which, over time, that content will grow and change, you can maintain far more control over a CMS website than you might think. If you have any additional tips or would like to discuss problems you have encountered when designing for Content Management Systems, leave a few lines in the comments below.

Further resources

Here are some additional resources that might help with your own CMS based projects:

• 24ways: Cleaner code with CSS3 Selectors
  Use CSS3 selectors instead of expecting your users to add classes to content.
• A List Apart: Strategic Content Management
  An in depth article about selecting and customizing a CMS.
• Design for CMS-Powered web sites
  An in-depth article explaining specific design techniques for use in CMS powered sites.
• cmsdesigns.org
  A showcase site for designs using Open Source CMS systems; a good place to see how flexible different systems are and how other designers are working with them.
• Getting Real: Use Real Words
  This tip is especially important when you are designing for CMS.

(vf) (ik)

© Rachel Andrew for Smashing Magazine, 2010. | Permalink | Post a comment | Add to del.icio.us | Digg this | Stumble on StumbleUpon! | Tweet it! | Submit to Reddit | Forum Smashing Magazine
Post tags: CMS, Content Management Systems

CSS3 continues to both excite and frustrate web designers and developers. We are excited about the possibilities that CSS3 brings, and the problems it will solve, but also frustrated by the lack of support in Internet Explorer 8. This article will demonstrate a technique that uses part of CSS3 that is also unsupported by Internet Explorer 8. However, it doesn’t matter as one of the most useful places for this module is somewhere that does have a lot of support — small devices such as the iPhone, and Android devices.

In this article I’ll explain how, with a few CSS rules, you can create an iPhone version of your site using CSS3, that will work now. We’ll have a look at a very simple example and I’ll also discuss the process of adding a small screen device stylesheet to my own site to show how easily we can add stylesheets for mobile devices to existing websites.

[Offtopic: by the way, did you already get your copy of the Smashing Book?]

Media Queries

If you have ever created a print stylesheet for a website then you will be familiar with the idea of creating a specific stylesheet to come into play under certain conditions – in the case of a print stylesheet when the page is printed. This functionality was enabled in CSS2 by media types. Media Types let you specify a type of media to target, so you could target print, handheld and so on. Unfortunately these media types never gained a lot of support by devices and, other than the print media type, you will rarely see them in use.

The Media Queries in CSS3 take this idea and extend it. Rather than looking for a type of device they look at the capability of the device, and you can use them to check for all kinds of things. For example:

• width and height (of the browser window)
• device width and height
• orientation – for example is a phone in landscape or portrait mode?
• resolution

If the user has a browser that supports media queries then we can write CSS specifically for certain situations. For example, detecting that the user has a small device like a smart phone of some description and giving them a specific layout. To see an example of this in practice, the UK web conference dConstruct has just launched their website for the 2010 conference and this uses media queries to great effect.

The dConstruct 2010 website in Safari on a desktop computer

The dConstruct 2010 website on an iPhone

You can see from the above example that the site hasn’t just been made smaller to fit, but that the content has actually been re-architected to be made more easy to access on the small screen of the device. In addition many people might think of this as being an iPhone layout – but it isn’t. It displays in the same way on Opera Mini on my Android based phone – so by using media queries and targeting the device capabilities the dConstruct site caters for all sorts of devices – even ones they might not have thought of!

Using Media Queries to create a stylesheet for phones

To get started we can take a look at a very simple example. The below layout is a very simple two column layout.

A very simple two column layout

To make it easier to read on a phone I have decided to linearize the entire design making it all one column, and also to make the header area much smaller so readers don’t need to scroll past the header before getting to any content.

The first way to use media queries is to have the alternate section of CSS right inside your single stylesheet. So to target small devices we can use the following syntax:

	@media only screen and (max-device-width: 480px) {

	}

We can then add our alternate CSS for small screen and width devices inside the curly braces. By using the cascade we can simply overwrite any styles rules we set for desktop browsers earlier in our CSS. As long as this section comes last in your CSS it will overwrite the previous rules. So, to linearize our layout and use a smaller header graphic I can add the following:

	@media only screen and (max-device-width: 480px) {
		div#wrapper {
			width: 400px;
		}

		div#header {
			background-image: url(media-queries-phone.jpg);
			height: 93px;
			position: relative;
		}

		div#header h1 {
			font-size: 140%;
		}

		#content {
			float: none;
			width: 100%;
		}

		#navigation {
			float:none;
			width: auto;
		}
	}

In the code above I am using an alternate background image and reducing the height of the header, then setting the content and navigation to float none and overwriting the width set earlier in the stylesheet. These rules only come into play on a small screen device.

My simple example as displayed on an iPhone

Linking a separate stylesheet using media queries

Adding the specific code for devices inline might be a good way to use media queries if you only need to make a few changes, however if your stylesheet contains a lot of overwriting or you want to completely separate the styles shown to desktop browsers and those used for small screen devices, then linking in a different stylesheet will enable you to keep the CSS separate.

To add a separate stylesheet after your main stylesheet and use the cascade to overwrite the rules, use the following.

<link rel="stylesheet" type="text/css" media="only screen and (max-device-width: 480px)" href="small-device.css" />

Testing media queries

If you are the owner of an iPhone, Android device or other device that has a browser which supports media queries you can test your CSS yourself. However you will need to upload the code somewhere in order to view it. What about testing devices you don’t own and testing locally?

An excellent site that can help you during the development process is ProtoFluid. This application gives you a form to enter your URL – which can be a local URL – and view the design as if in the browser on an iPhone, iPad or a range of other devices. The screenshot below is the dConstruct site we looked at earlier as seen through the iPhone view on ProtoFluid.

The dConstruct 2010 website in ProtoFluid

You can also enter in your own window size if you have a specific device you want to test for and know the dimensions of it’s screen.

To use ProtoFluid you need to slightly modify the media query shown earlier to include max-width as well as max-device-width. This means that the media query also comes into play if the user has a normal desktop browser but using a very tiny window.

	@media only screen and (max-width: 480px), only screen and (max-device-width: 480px) {

	}

After updating your code to the above, just refresh your page in the browser and then drag the window in and you should see the layout change as it hits 480 pixels. The media queries are now reacting when the viewport width hits the value you entered.

You are now all ready to test using ProtoFluid. The real beauty of ProtoFluid is that you can still use tools such as FireBug to tweak your design, something you won’t have once on the iPhone. Obviously you should still try and get a look at your layout in as many devices as possible, but ProtoFluid makes development and testing much simpler.

Note that if you don’t want your site to switch layout when someone drags their window narrow you can always remove the max-width part of the query before going live, so the effect only happens for people with a small device and not just a small browser window.

Retrofitting an existing site

I have kept the example above very simple in order to demonstrate the technique. However this technique could very easily be used to retrofit an existing site with a version for small screen devices. One of the big selling points of using CSS for layout was this ability to provide alternate versions of our design. As an experiment I decided to take my own business website and apply these techniques to the layout.

The desktop layout

The website for my business currently has a multi-column layout. The homepage is a little different but in general we have a fixed width 3 column layout. This design is a couple of years old so we didn’t consider media queries when building it.

My site in a desktop browser

Adding the new stylesheet

There will be a number of changes that I need to make to linearize this layout so I’m going to add a separate stylesheet using media queries to load this stylesheet after the current stylesheet and only if the max-width is less than 480 pixels.

	<link rel="stylesheet" type="text/css" media="only screen and (max-width: 480px), only screen and (max-device-width: 480px)" href="/assets/css/small-device.css" />

To create my new stylesheet I take the default stylesheet for the site and save it as small-device.css. So this starts life as a copy of my main stylesheet. What I am going to do is go through and overwrite certain rules and then delete anything I don’t need.

Shrinking the header

The first thing I want to do is make the logo fit nicely on screen for small devices. As the logo is a background image this is easy to do as I can load a different logo in this stylesheet. I also have a different background image with a shorter top area over which the logo sits.

	body {
		background-image: url(/img/small-bg.png);
	}

	#wrapper {
		width: auto;
		margin: auto;
		text-align: left;
		background-image: url(/img/small-logo.png);
		background-position: left 5px;
		background-repeat: no-repeat;
		min-height: 400px;
	}

Linearizing the layout

The next main job is to linearize the layout and make it all one column. The desktop layout is created using floats so all I need to do is find the rules that float the columns, set them to float: none and width:auto. This drops all the columns one under another.

	.article #aside {
		float: none;
		width: auto;
	}

Tidying up

Everything after this point is really just a case of looking at the layout in ProtoFluid and tweaking it to give sensible amounts of margin and padding to areas that now are stacked rather than in columns. Being able to use Firebug in ProtoFluid makes this job much easier as my workflow mainly involves playing around using Firebug until I am happy with the effect and then copying that CSS into the stylesheet.

Testing the site using ProtoFluid

Testing in an iPhone

Having created my stylesheet and uploading it I wanted to check how it worked in a real target device. In the iPhone I discovered that the site still loaded zoomed out rather than zooming in on my nice readable single column. A quick search on the Safari developer website gave me my answer – to add a meta tag to the head of the website setting the width of the viewport to the device width.

		<meta name="viewport" content="width=device-width" />

After adding the meta tag the site now displays zoomed in one the single column.

The site as it now displays on an iPhone

This was a very simple retrofit to show that it is possible to add a mobile version of your site simply. If I was building a site from scratch that I would be using media queries on, there are definitely certain choices I would make to make the process simpler. For example considering the linearized column orders, using background images where possible as these can be switched using CSS – or perhaps using fluid images.

Our desktop layout features a case studies carousel on the homepage, this wasn’t easy to interact with on a touch screen device and so I checked using JavaScript if the browser window was very narrow and didn’t launch the carousel. The way this was already written meant that the effect of stopping the carousel loading was that one case study would appear on the screen, which seems a reasonable solution for people on a small device. With a bit more time I could rewrite that carousel with an alternate version for users of mobile devices, perhaps with interactions more suitable to a touch screen.

More resources

This is a relatively new technique but already there are some excellent tutorials on the subject of media queries. If you know of others then please post them in the comments.

• A List Apart – Responsive Web Design
• Apple – Safari Web Content Guide
• Sitepoint CSS Reference – Media Queries
• Targeting the iPhone 4 Retina Display with CSS3 Media Queries
• Aral Balkan: How to make your web content look stunning on the iPhone 4’s new Retina Display
• Stuff and Nonsense: Proportional leading with CSS3 Media Queries
• Matthew James Taylor: iPad layout with landscape and portrait modes

Providing support for Media Queries in older browsers

This article covers the use of media queries in devices that have native support. If you are only interested in supporting iPhone and commonly used mobile browsers such as Opera Mini you have the luxury of not needing to worry about non-supporting browsers. If you want to start using media queries in desktop browsers then you might be interested to discover that there are a couple of techniques available which use JavaScript to add support to browsers such as Internet Explorer 8 (and lower versions) and Firefox prior to 3.5. Internet Explorer 9 will have support for CSS3 Media Queries.

• Media Queries section on When Can I Use, showing which browsers have support
• Media Queries jQuery plugin (only deals with max/min width)
• css3-mediaqueries-js – a library that aims to add media query support to non-supporting browsers

More inspiration

To see more interesting use of Media Queries have a look at Hicksdesign where Jon Hicks has used Media Queries to not only provide a better experience for mobile device users, but also for regular web browser users with smaller windows. Also, have a look at Simon Collison’s website and Ed Merritt’s portfolio for other examples of this technique.

Try it for yourself

Using Media Queries is one place you can really start to use CSS3 in your daily work. It is worth remembering that the browsers that support media queries also support lots of other CSS3 properties so your stylesheets that target these devices can also use other CSS3 to create a slick effect when viewed on an iPhone or other mobile device. If you have implemented media queries on your site, or try this technique after reading this article, let us know in the comments.

© Rachel Andrew for Smashing Magazine, 2010. | Permalink | Post a comment | Add to del.icio.us | Digg this | Stumble on StumbleUpon! | Tweet it! | Submit to Reddit | Forum Smashing Magazine
Post tags: CSS, css3, media queries, mobile