Hacking Safari 5’s Reader
If you're anything like me, you do a lot of reading on the web. Which probably means you care about the quality of the typography you're staring at: the copy's color, the page's background, font choice, leading, etc. You may have even tried Arc90's Readability bookmarklet or Marco Arment's Instapaper. Readability is great for getting rid of page clutter and user comments, allowing you to focus on the article's content. Instapaper does the same thing as a byproduct. It focuses on aggregating articles you want to read later. I use both tools religiously; I can't recommend them enough.
One of the many fantastic features in Safari 5 is called Safari Reader—it's based on Readability. If you're reading this in Safari 5, go to View > Enter Reader or press cmd+shift+R (⌘+⇧+R) to try it out. Pretty spiffy, huh?
While Safari Reader is extremely handy, I'm not happy with the default typography:
So, I started looking for ways to adjust the type. Thankfully, the internet is full of like-minded individuals, and I found an article on how to modify the look of the Safari 5 Reader. They recommend creating a backup of the original Reader.html file, and so do I. One thing they don't mention is you'll need to restart Safari anytime you want to see your changes. I spent a few minutes hacking away at the CSS and arrived at something I'm happy with:
Here's the CSS if you're interested (“\” denotes a continuation on the same line):
<style>
* {
-webkit-font-smoothing: \
antialiased;
font-family: "Helvetica Neue", \
Helvetica, sans-serif !important;
color: #444;
}
a {
border-bottom: 1px dotted #65a2ef;
color: #0064e5 !important;
}
a:visited { border: 0; }
a:hover {
border-color: #cfe2fa;
color: #4c9bff !important;
}
p, li {
font-size: 14px;
line-height: 21px;
}
#article { width: 619px; }
#background { background-color: \
rgba(0, 0, 0, 0.9); }
#container { margin-left: -333px; }
#drop-shadow { width: 600px; }
.page {
background: #F6F6F6;
width: 458px;
}
</style>These styles are down and dirty. So, use them at your own risk. The easiest way to add them to Reader.html without disturbing the default styles is by appending the above code below the last </style> tag and above the first (and only) <script> tag within the document's <head>.
Managing CSS and JS In ExpressionEngine
ExpressionEngine, hereafter EE, has great built-in support for managing style sheets and JavaScript. Here's one simple way to manage your style sheets and JavaScript files with cache-busting and gzip compression using EE's templating system.
There's one prerequisite for managing styles and scripts using the following method: the LG .htaccess Generator. It's possible to use a different approach, but this method assumes you're using Mr. Graham's extension.
First, if you haven't already, enable gzip compression from within EE's control panel. Go to Admin > System Preferences > Output and Debugging Preferences and select “Yes” under “Enable GZIP Output?” Click “Update” to save your settings.
Next, create a new template group for your style sheets. I generally name mine “styles,” but name yours whatever you'd like. Don't duplicate a group. Click “Submit” to create the group. Within this new group, create a few templates with a type of “CSS Stylesheet.” I generally create a style sheet template for each logical group of styles: a style reset, some typographic styles, default styles, some hacks, etc. Put corresponding styles in each of these templates. I save all templates as files and use EE's built-in template revision system. You should see a checkbox with the label “Save Template as File” just above the “Update” and “Update and Finished” buttons on the template editing page. You'll need to allow templates to be saved as files if you don't. Go to Templates > Global Template Preferences > and select “Yes” under “Allow Templates to be Saved as Files?” While you're there, select “Yes” under “Save Template Revisions.” Click “Update” to save your settings. This is simply an added safety net since you're using some sort of version control for your site, right? Right.
Next, repeat the same steps for your JavaScript files. I typically name the group holding JavaScipt files “scripts.” Each of the templates should have the type “JavaScript.” I generally store classes and frameworks (jQuery, Prototype, etc.) in separate templates with each class getting its own template.
At this point you should have two template groups: one holding a few style sheets and an index and another holding a few JavaScript files and an index (“index” is automatically created when you create a template group).
Being kind to your server means you should serve only one style sheet and one JavaScript file per page load, ostensibly. And Server Side Includes—or SSIs—allow this method to be robust and kind to our servers. SSIs are called embeds in EE lingo.
So, we'll use each group's index file to serve a single file per type. Open your style sheet group's index file and add an embed for each of the templates in your group (minus the index, of course). Here's my style index as a reference:
{embed="styles/reset"}
{embed="styles/type"}
{embed="styles/layout"}
{embed="styles/default"}
{embed="styles/hacks"}Repeat the same process for your JavaScript group's index file. Remember, the order of the embeds is important.
We need to set the content type for these index files so the browser interprets them correctly. Go to Templates > Template Preferences Manager. In the first section, select your style template group name under “Template Groups” and “index” from the list of templates. In the second section, select “CSS Stylesheet” under “Type.” Click “Update” to save your settings. Repeat the same steps for your JavaScript group's index file, selecting “JavaScript” as its type. Don't forget to click “Update” to save your settings.
At this point, you should be able to visit http://yourdomain/styles/ and see a single style sheet containing the files you specified in your style sheet group's index. The same goes for your JavaScript group.
There's a final step to make this system nearly perfect: a cache-busting system. You're caching requests for media files on your server, right? Read Yahoo's Best Practices for Speeding Up Your Web Site if you're not sure what I'm talking about. So, you'll need a way to bust the cache when you make changes to your styles and scripts after you've enabled caching on your server. To do this, you need to create two global template variables: one for styles and one for scripts. Go to Templates > Global Variables and “Create a New Global Variable.” Name the variable something memorable. I generally name mine CSS_VERSION and JS_VERSION. The “Variable Content” should be something that's easy to increment. I use a three digit version number, 1.0.0. You can use whatever you'd like, but be sure to keep it simple. Also, do not input any whitespace (spaces, tabs, or line breaks). Click “Submit” to save each global variable. These global variables will need to be incremented anytime you make changes to their corresponding files. So, you'll need to change the version number(s) if you add or change a style or piece of JavaScript. The actual number is irrelevant. Incrementing makes sense (for our linear view of time) though.
Finally, we need to add a link and script tag to our document's head. They should look similar to this (“\” denotes a continuation on the same line):
<link rel="stylesheet" \
href="/styles/?v={CSS_VERSION}" \
type="text/css" media="screen" \
charset="utf-8">
<script src="/scripts/?v={JS_VERSION}" \
type="text/javascript" \
charset="utf-8"></script>Your mileage may vary.
You'll notice after each path is a GET variable v. This is the cache-busting variable. The v= isn't necessary. You could strip it down to just ?{CSS_VERSION}, and it would work fine. You're probably thinking, "Why not just put the version number inline? Why store it in a global variable?" You could definitely place it inline and everything would work as described. I find storing these version numbers in global variables to be cleaner.
One final note: This method isn't tied specifically to ExpressionEngine. It should work in any content management system. The nomenclature and syntax will be the only differences.
So, there you have it: a robust, cache-bust-able, single-serving-file method for managing style sheets and JavaScript files in ExpressionEngine. The only ingredient we're missing to make it perfect is compression/minification, but this system should be robust enough for the majority of sites.
Thoughts On Writing Team-Centric CSS
I've worked on a few different front-end development teams over the past few years, and I've seen a range of coding practices—the good, the bad, and the ugly. What follows is a compendium on CSS organization.
Follow Your Code Standards Guide
I want to be clear, before I dive into any specifics, that you should always follow the code standards or style guide for the team you're working with. The goal in code organization for a team of any size is clarity and consistency. Your code base should look as though one person wrote it. If you don't have a code standards guide, then I implore you to write one or adhere to someone else's.
Use Ample White Space
White space is a key component for clarity in any aspect of design, whether it's visual design, writing, coding, etc. White space is free, so you have no reason to be stingy. I recommend using a single line break between properties in a property list; two or more line breaks between declarations starting with the same element, id, or class; and four or more line breaks between declarations for different elements, ids, or classes. One exception is a declaration with one property-value pair; the declaration and property-value pair can inhabit the same line. There's a nice side effect when using this style for line breaks: understandable and easily-skimmed git blame (or whichever repository flavor you use), diff, etc.
Comment Liberally
Most developers I work with shy away from comments, but I find them indispensable. Annotating your code allows others on your team to understand why you've chosen a certain technique. Alternatively, you could just ask why your teammate chose a certain method. This approach is fine for small teams, but it's nearly impossible for large teams. Answering the same question multiple times is a waste of time.
A well-written annotation also helps you. Sometimes you need a reminder for why you wrote a declaration a particular way. I know comments have saved me from myself more than once. Good documentation saves time.
Comments also add clarity. As Donald Knuth said, “I still think people could be documenting what they write much better. And a comment is different than writing an essay. The way you write a program for another human being is completely different from the way you write it for a computer.” Your teammates are not computers. Write a commentary they can understand. Remember, the goal is clarity.
What About File Size?
I often hear this argument, "Well-documented code with ample white space sounds nice in the theoretical world, but it leads to larger file sizes in the real world. And serving large files is not good." I'll be the first to say serving large, fully-commented, abundantly white-spaced files is bad. This sounds like a contradiction to my advice on writing team-centric CSS, but it's not. The files your team uses and tests with should be different from the files you serve your end users. How is this possible? Minification and compression. A major component in any team's build process should be the step where comments and white space are stripped from the production files. I use YUI's Compressor and gzip to drastically reduce file sizes for lightweight production files.
This leads to another valid argument, "Multiple versions of the same file bloat the repository." I agree. They do. My only counter is that having well-documented, amply white-spaced code adds clarity and consistency in a team environment. The trade-off is well worth it.
Maybe you're a freelancer and have worked on a few different teams. Maybe you're a one-man shop. Maybe you're part of an in-house team. Whatever your role, I hope you found this advice helpful. I don't claim to have the ultimate answers for code organization, and I'd love to hear how you organize your code. and share your wisdom.