Tag: kranthi

How To Set Up A Print Style Sheet





 



 


In a time when everyone seems to have a tablet, which makes it possible to consume everything digitally, and the only real paper we use is bathroom tissue, it might seem odd to write about the long-forgotten habit of printing a Web page. Nevertheless, as odd as it might seem to visionaries and tablet manufacturers, we’re still far from the reality of a paperless world.

In fact, tons of paper float out of printers worldwide every day, because not everyone has a tablet yet and a computer isn’t always in reach. Moreover, many of us feel that written text is just better consumed offline. Because I love to cook, sometimes I print recipes at home, or emails and screenshots at work, even though I do so as rarely as possible out of consideration for the environment.

Print style sheets are useful and sometimes even necessary. Some readers might want to store your information locally as a well-formatted PDF to refer to the information later on, when they don’t have an Internet connection. However, print styles are often forgotten in the age of responsive Web design. The good news is that a print style sheet is actually very easy to craft: you can follow a couple of simple CSS techniques to create a good experience for readers and show them that you’ve gone the extra mile to deliver just a slightly better user experience. So, how do we start?

Getting Started

Let’s look at the process of setting up a print style sheet. The best method is to start from scratch and rely on the default style sheet of the browser, which takes care of the printed output pretty well by default. In this case, insert all declarations for printing at the end of your main style sheet, and enclose them with this distinct rule:

@media print {
   …
}

For this to work, we have to prepare two things:

  1. Include all screen styles in the separate @media screen {…} rule;
  2. Omit the media type for the condensed style sheet: <link rel="stylesheet" href="css/style.css"/>

In rare cases, using screen styles for printing is the way to approach the design of the print style sheet. Although making the two outputs similar in appearance would be easier this way, the solution is not optimal because screen and print are different kettles of fish. Many elements will need to be reset or styled differently so that they look normal on a sheet of paper. But the biggest constraints are the limited page width and the need for an uncluttered, clear output. Building print styles separately from screen styles is better. This is what we will do throughout this article.

Of course, you could separate the declarations for screen and print into two CSS files. Just set the media type for the screen output to media="screen" and the media type for printing to media="print", omitting it for the first one if you want to build on the screen style sheet.

To illustrate, I have set up a simple website of the fictional Smashing Winery.

screenshot
Our example website.

Everything needed for a proper screen display is in place. But as soon as the environment changes from virtual pixels to real paper, the only thing that matters is the actual content.

screenshot
The two pages of the unaltered print preview. The header is not yet optimal, and both the main navigation and footer are superfluous.

Therefore, as a first task, we will hide all the clutter: namely, the main navigation and footer.

header nav, footer {
display: none;
}

Depending on the type of website, you could also consider hiding images by default. If the images are big, this would be wise, to save your users some printing costs. But if the images mainly support the content, and removing them would compromise the meaning, just leave them in. Whatever you decide, limit the images to a certain width, so that they don’t bleed off the paper. I’ve found that 500 pixels is a good compromise.

img {
max-width: 500px;
}

Alternatively you could also rely on the tried and trusted max-width: 100%, which displays images at their maximum size but not bigger than the page width.

You might want to use a simple trick to get high-quality images when printing. Just provide a higher-resolution version of every image needed and resize it to the original size with CSS. Read more about this technique in the article “High-Resolution Image Printing� on A List Apart.

Of course, we should hide video and other interactive elements, because they are useless on paper. These include <video>, <audio>, <object> and <embed> elements. You might want to consider replacing each video element with an image in the print style sheet, too.

screenshot
With the main navigation, footer and images gone, the actual text is getting ever closer to center stage. But work remains to be done, especially with the header.

Adjusting To The Right Size

To define page margins, you can use @page rule to simply apply a margin all the way around the page. E.g.:

@page {
margin: 0.5cm;
}

will set the page margin on all sides to 0.5cm. You can also adjust the margins for every other page. The following code sets the left page (1, 3, 5, etc.) and right page (2, 4, 6, etc.) margins independently.

@page :left {
margin: 0.5cm;
}

@page :right {
margin: 0.8cm;
}

You can also use the :first page pseudo-class that describes the styling of the first page when printing a document:

@page :first {
  margin: 1cm 2cm;
}

Unfortunately, @page is not supported in Firefox, but supported in Chrome 2.0+, IE 8.0+, Opera 6.0+ and Safari 5.0+. @page :first is supported only in IE8+ and Opera 9.2+. (thanks for the tip, Designshack)

Now let’s tweak some general settings for the fonts. Most browsers set the default to Times New Roman, because serif fonts are considered to be easier on the eyes when read on paper. We can use Georgia at 12-point font size and a slightly higher line height for better legibility.

body {
font: 12pt Georgia, "Times New Roman", Times, serif;
line-height: 1.3;
}

However, to retain some control, we should explicitly set the font sizes below. The chart on ReedDesign gives us a feel for this; but with all of the screen sizes and resolutions out there, these are only rough estimates.

h1 {
font-size: 24pt;
}

h2 {
font-size: 14pt;
margin-top: 25px;
}

aside h2 {
font-size: 18pt;
}

Apart from special cases (like the <h2> heading, which would otherwise be too close to the preceding paragraph), we don’t need to touch the margins or appearance of any elements, because they are handled quite nicely by the default settings. If you don’t like that certain elements are indented, such as <blockquote>, <ul> and <figure>, you could always reset their margins:

blockquote, ul {
margin: 0;
}

Or you could override the default bullet style in unordered lists…

ul {list-style: none}

…and replace it with a custom one; for example, a double arrow (and a blank space to give it some room):

li {
content: "» ";
}

You could also make <blockquote> stand out a bit by enlarging it and italicizing the text.

The Header

Currently, the remaining things to be dealt with in the header are the <h1> title and the logo. The first is there just for accessibility purposes and is hidden for screen display using CSS. While we could use it as a sort of header in the print-out to indicate the source of the content, let’s try something more attractive. Wouldn’t it be nice to display the actual logo, instead of the boring text?

Unfortunately, the “Winery� part of the logo is white and therefore not ideal for printing on light-colored paper. That’s why two versions of the logo are in the source code, one for screen display, one for printing. The latter image has no alt text, otherwise screen readers would repeat reading out “Smashing Winery.�

<a href="/" title="Home" class="logo">
   <img src="img/logo.png" alt="Smashing Winery" class="screen"/>
   <img src="img/logo_print.png" alt="" class="print"/>
</a>

First, we need to hide the screen logo and the <h1> heading. Depending on the relevance of the images, we might have already decided to hide them along with other unneeded elements:

header h1, header nav, footer, img {
display: none;
}

In this case, we have to bring back the print logo. Of course, you could use the adjacent sibling selector for the job (header img + img) to save the class name and live with it not working in Internet Explorer 6.

header .print {
display: block;
}

Otherwise, you could just use header .screen (or header :first-child) to hide the main logo. And then the second logo would remain. Keep in mind that in print layouts, only images embedded via the <img> tag are displayed. Background images are not.

Voilà! Now we have a nice header for our print-out that clearly shows the source of everything. Alternatively, you could still remove the second logo from the source code and use the header’s <h1> heading that we switched off earlier (in other words, remove it from the display: none line). Perhaps you’ll need to hide the remaining logo as we did before. Additionally, the font size could be enlarged so that it is clearly recognized as the title of the website.

header h1 {
font-size: 30pt;
}

As a little extra, the header in the print-out could show the URL of the website. This is done by applying the :after pseudo-element to the <header> tag, which unfortunately won’t work in IE prior to version 8; but because this is just a little bonus, we can live with IE’s shortcoming.

header:after {
content: "www.smashing-winery.com";
}

To see what else these pseudo-elements can do, read the description on the Mozilla Developer Network, or consult Chris Coyer’s excellent article on CSS-Tricks.

Another thing about IE 6 to 8 is that HTML5 tags can’t be printed. Because we’re using these tags on the example website, we’ll have to apply Remy Sharp’s HTML5shiv in the header. The shiv allows you not only to style HTML5 tags but to print them as well. If you’re already using Modernizr, that’s perfect, because the shiv is included in it.

<script src="js/html5.js"></script>

Unfortunately, the behavior of the IEs is still a bit buggy even when this shiv is applied. HTML5 tags that were styled for the screen layout need to be reset, or else the styling will be adopted for the print-out.

Some developers add a short message as a supplement (or an alternative) to the displayed URL, reminding users where they were when they printed the page and to check back for fresh content. We can do this with the :before pseudo-element, so that it appears before the logo. Again, this won’t work in IE 6 or 7.

header:before {
display: block;
content: "Thank you for printing our content at www.smashing-winery.com. Please check back soon for new offers on delicious wine from our winery.";
margin-bottom: 10px;
border: 1px solid #bbb;
padding: 3px 5px;
font-style: italic;
}

To distinguish it from the actual content, we’ve given it a gray border, a bit of padding and italics. Lastly, I’ve made it a block element, so that the border goes all around it, and given the logo a margin.

To make it more discreet, we could move this message to the bottom of the page and append it to main container of the page, which has the .content class. If so, we would use the :after element and a top margin to keep it distinct from the sidebar’s content. As far as I’m concerned, the URL is indication enough, so I would rely on that and omit the message.

Finally, we need to remove the border of the logo to prevent it from showing in legacy browsers, and move the <header> away from the content:

img {
border: 0;
}

header {
margin-bottom: 40px;
}

screenshot
The header shown two different ways, one with a logo and simple URL, and the other with a message and the title in plain text.

The Missing Link

Obviously, on paper, links aren’t clickable and so are pretty useless. You could try to build a workaround, replacing links with QR codes on the fly, but the solution may not be feasible. To put the links to use, you could display the URL after each string of anchor text. But text littered with URLs can be distracting and can impair the reading experience; and sparing the reader excessive information where possible is advisable.

The best solution is the :after pseudo-element. It displays the URL after each anchor text, surrounded by brackets. And the font size is reduced to make it less intrusive.

p a:after {
content: " (" attr(href) ")";
font-size: 80%;
}

We’ve limited this technique to links within <p> elements as a precaution. To go a step further, we could choose to show only the URLs of external links. An attribute selector is perfect for this:

p a[href^="http://"]:after {
content: " (" attr(href) ")";
font-size: 90%;
}

The possibilities for links in printed documents seem to be almost endless, so let’s try some more. To distinguish all internal links, let’s precede them with the website’s domain (omitting all the other properties, to keep things concise and clear):

p a:after {
content: " (http://www.smashing-winery.com/" attr(href) ")";
}

Then, we can hide internal links (#), because there is not much to display:

p a[href^="#"]:after {
display: none;
}

Also, external links will be appended as is, like above. Let’s consider SSL-secured websites, too (i.e. ones that begin with https://):

p a[href^="http://"]:after, a[href^="https://"]:after {
content: " (" attr(href) ")";
}

But there is one thing to remember, especially with external links. Some are very long, such as the ones in the Safari Developer Library. Such links can easily break a layout, like at the screen output. Luckily, a special property takes care of this:

p a {
word-wrap: break-word;
}

This breaks long URLs when they reach a certain limit or, as in our case, when they exceed the page’s width. Just add this property to the first of the above declarations. Although this property is basically supported in a wide range of browsers — even IE 6 — it works only in Chrome when printing. While Firefox automatically breaks long URLs, Internet Explorer has no capability for this.

Finally, we set the link color to black to improve the experience for readers.

a {
color: #000;
}

screenshot
URLs, whether internal or external, now show up beside links with special treatment.

Aaron Gustafson went one step further and built the little script Footnote Links. According to the description:

This script builds a list of URIs from any tags within a specified container and appends the list as footnotes to the document in a specified location. Any referenced elements are given a dynamically-assigned number which corresponds to the link in the footnote list.

Aaron’s article on A List Apart “Improving Link Display for Print� gives more insight into the idea behind this script.

While we’re at it, letting readers know where quotes come from, such as those wrapped in <blockquote> and <q> tags, would be thoughtful. Just append the cite attribute (which will be the URL) after quotation marks, like so:

q:after {
content: " (Source: " attr(cite) ")";
}

Side By Side

We haven’t yet dealt with the sidebar content. Even though it appears after the main content by default, let’s give it some special treatment. To keep it distinct, we’ll give the sidebar a gray top border and a safe buffer of 30 pixels. The last property, display: block, ensures that the border shows up properly.

aside {
border-top: 1px solid #bbb;
margin-top: 30px;
display: block;
}

To separate it even more, we could set a special print property:

page-break-before: always;

This will move the contents of the sidebar to a new page when printed. If we do this, we can omit all of the other properties.

screenshot
The sidebar on screen (left) and printed out (right). I’ve grayed out everything else to make it more obvious here.

We could do the same for comments. Comments don’t appear in the example, but they’re still worth touching on. Because they sometimes run long, omitting them in the print-out might be reasonable (just set display: none for the whole container). If you do want to show the comments, at least set page-break-before. You can also use page-break-after: always if there is content to print on a new page. The page-break-before and page-break-after properties are supported in all major browsers.

We can also use widows and orphans properties. The terms derive from traditional printing, and they take numbers as values. The widows property sets the minimum number of lines in a paragraph to leave at the top of a page before moving them entirely to a new page. The orphans property sets the number of lines for the bottom of the page. The orphans and widows properties are supported in IE 8+ and Opera 9.2+, but unfortunately not in Firefox, Safari or Chrome.

Now that we have taken care of the sidebar, the print style sheet is ready! You can download it here. The file is fully documented and so can serve as a helpful reference or starting point.

screenshot
The completed print style sheet.

Just For Fun

You might be asking, “Why can’t we just put the sidebar next to the main content, like on the website itself?� Well, the screen and print outputs are a bit different. Unlike the former, print-outs aren’t very wide and thus don’t have much space to fill. But depending on the font size, the line length could exceed the maximum of 75 characters and so be more difficult to read.

In this case, we could, of course, limit the width of the main content (preferably not too much — we shouldn’t set the line length to fall below about 55 characters) and then absolutely position the sidebar just below it, just like in the screen display. But describing this method falls beyond the scope of this article, so please consult the screen style sheet of the example website (line numbers 112 and 141 and down).

In my humble opinion, avoid such experiments. While in principle, print layouts have endless possibilities, focusing on the content and removing everything else is better. The better way to ensure an optimal line length is just to shrink the page’s width or enlarge the font size.

Preview Made Easy

Print Preview by Tim Connell is a handy little jQuery plugin that replicates the built-in print-preview function, but with one difference. Instead of opening a separate page, it shows a sleek overlay, with “Close� and “Print� buttons at the top. It also has the convenient “P� shortcut. You might want to check out the demo page, too.

A Missed Opportunity

Imagine that you were able to visit any page, hit “Print� and get an optimized version of the page to enjoy on paper. Unfortunately, we don’t live in this perfect world. Some websites still rely on JavaScript to generate print versions, and many other designers simply don’t care. But this is a missed opportunity. A carefully composed print style sheet could be used not only for printing but to optimize legibility for screen reading.

As the website owner, you can determine the images to display (if any), the optimal font and size, and the presentation of other elements. You could make the content more appealing than the versions produced by Instapaper and Readability by giving the print version the extra attention it deserves.

The Future

While using CSS3 for screen layouts is pretty common nowadays, it hasn’t quite established itself in the print environment yet. The W3C has an extensive description of “Paged Media,� but unfortunately support is very limited at the moment, Opera and Chrome being the only browsers that enable a few of its related properties. With decent support, it would be possible to use the @page rule to set the dimensions of the page, switch to a landscape view, alter the margins, and do much more. Even media queries are were conceived to respond to different page sizes.

Websites Designed Well For Print

Let’s take a look at some examples of websites optimized for print.

A List Apart
The slick multi-column design is simplified into a single column, full width, which intuitively mirrors the website’s sensible hierarchy. Article titles and authors are no longer active links. And beautiful clean typography is kept intact, thanks to the compatible fonts and simple colors; no font change is necessary, although the font-size value increases slightly. Advertising and affiliate styles are hidden, and the result is a simple, clean printed page that easily conforms well to any printer or page set-up in the document. A List Apart is exemplary, save for one important point: the logo does not appear anywhere in the print-out.

A List Apart

A List Apart

Lost World’s Fairs
The smooth printed page helps to carry the visuals of the website for Lost World’s Fairs. The main title and its colorful background are swapped for a simplified version in the print-preview style. However, some images could be removed to save some expensive printer ink. (Updated).

Lost World's Fairs

Lost World's Fairs

The Morning News
One would expect most news websites to employ the print-preview function, yet that isn’t the case. The Morning News has prepared its content for print without much concern, happily excluding background images and color, while still getting its message across.

The Morning News

The Morning News

James Li
James Li has designed his personal website exceptionally well for this purpose, carefully preserving all spacing and key elements. The logo is a part of the printed product, whereas the navigation links are not: very clever, because navigation has no value on a printed page unless it is informative in and of itself. Non-Web fonts are converted to simple printable ones (see “Other Stuff…�). Brilliantly executed for print.

Infinitum

Infinitum

TechCrunch
TechCrunch’s recent redesign tweaked not only the visual design of the site, but also the small details that have to be considered when the site is viewed on mobile or printed out. The print layout is very clean and minimalistic, without unnecessary details, yet also without links to the actual page that was printed out. The TechCrunch logo is omitted as well.

TechCrunch

TechCrunch

R/GA
Although the logo isn’t present in the printed version of this website, attention is paid to the spacing of the content within. While the Web version has simple lines and a clean space, the printed page tightens up elements in order to best use the space. A strong grid and effective typography add to the effect. In this example, some images could be removed as well.

r/ga

r/ga

Studio Mister
An excellent job of the print-preview function. The page has been meticulously designed to a grid and requires little in order to prepare it for print; some attention to the background color of text and not much else. Unfortunately, though, the logo is a background image and thus excluded.

Studio Mister

Studio Mister

Bottlerocket Creative
Although this logo isn’t represented in the print-out either, the folks at Bottlerocket Creative have done very well to adapt their typographic style for offline viewing. Assuming the design was created mainly with images would be easy, but meticulous attention to type is evident upon closer inspection.

Bottle Rocket

Bottle Rocket

OmniTI
OmniTI has optimized its content for print not by shrinking the main column, but by increasing the size of the text and not crowding the images together. The playful look adheres to good spacing. The only drawback? Many of the line breaks have been eliminated, causing some words and sentences to run into each other.

Omni TI

Omni TI

In Conclusion

There’s a lot to consider when preparing your website to be printed out by readers. The process forces you to scrutinize every element of your content like never before, all because someone will want a hard copy of your work. Yet most of all, it’s important to recognize the difference between printing and actually reading. Perhaps these techniques hold merit in helping you visualize content for mobile devices. What better way to kill two birds with one stone than to work out your layout for the mobile while considering printing view at the same time to make sure that your content prints flawlessly for offline archival? The time you invest could double in value.

For more information on preparing content for print, including by modifying CSS, check out the following articles:

(al) (vf) (il)


© Christian Krammer for Smashing Magazine, 2011.


How To Improve Your WordPress Plugin’s Readme.txt





 



 


If you’re a plugin developer and you just love to write code, then writing a readme.txt file for a plugin in WordPress’ repository might be your idea of hell. When you’ve written all of that lovely code, why must you spend time writing about how to use it?

readmeheader

Unfortunately, some plugin developers view writing a readme.txt file as the least important part of their job. So, we end up with things like the following:

Why You Should Care About Your Readme.txt

A poorly written readme.txt does not necessarily indicate that the plugin is poorly written; the code could be mind-blowingly good. But it does give the impression of an overall lack of attention to detail and a lack of care for end users. You see, no one will notice if a readme file is particularly awesome, but they will notice if it’s bad.

You needn’t view the readme file as pain-in-the-butt homework that you’ve got to do after all the fun you’ve had with coding. A readme benefits you. Here’s how:

  • Gives you an opportunity to say why your plugin is so good,
  • Shows off your plugin’s features,
  • Makes it easy for users to install and use the plugin,
  • Anticipates support questions with a thorough FAQ,
  • Links to your website and other products,
  • Upsells your commercial services.

In this article, we’ll look at how to improve your WordPress readme file so that it benefits both your users and you.

But first, the mechanics.

Using (Quasi-)Markdown

Markdown is a text-to-HTML conversion tool, developed by John Gruber and Aaron Schwartz, that is used for readme files of plugins in the WordPress repository.

You write the readme in Markdown, and Markdown will convert it to HTML for the WordPress directory page, but it will still look good in WordPress’ back end and when you peek at it in your favorite text editor.

Take a look at the directory page for Simple Twitter Connect:

Simple Twitter Connect's listing in the plugin directory
Simple Twitter Connect’s listing in the WordPress plugin directory.

Here’s how it appears when I download and extract the readme:

Simple Twitter Connect's readme file
Simple Twitter Connect’s readme file in Notepad.

And here’s how it appears in WordPress’ back end:

Simple Twitter Connect's listing on the Edit plugin page in the WordPress dashboard
Simple Twitter Connect’s readme on the “Edit Plugin� page in the WordPress Dashboard.

It is readable no matter what medium it is viewed in. Imagine how difficult reading the readme in a text editor would be if it was marked up in HTML. Markdown makes your readme clear, readable and semantic.

WordPress.org uses what Mark Jacquith describes as quasi-markdown. It basically works like markdown, and much of the syntax is the same, but there are a few important differences, particularly in the headers.

To get you started with your WordPress readme, here’s a table containing the syntax that you’ll need.

Syntax Example Outputs as Use for
=== foo === === Plugin Name === <h2>Plugin Name</h2> Plugin name
== foo == ==Description== <h3>Description</h3> Tabbed section headings
= foo = =Inline heading= <h4>Inline heading</h4> Headings in the body of the readme
* foo * list item, *list item <ul>
<li>list item</li>
<li>list item</li>
</ul>
Unordered list
1. foo, 2. foo 1. list item, 2. list item <ol>
<li>list item</li>
<li>list item</li>
</ol>
Ordered list
foo bar You talking to me? <blockquote>You talking to me?</blockquote> block quotes
*foo* *emphasis* <em>emphasis</em> Italics
**foo** **bold** <strong>bold</strong> Bold
‘foo’ ‘wp-config.php’ wp-config.php Any code you want to display (including shortcodes)
[link] (http://foobar.com “foobar”) [WordPress](http://wordpress.org/ “Your favorite software”) <a href=”http://wordpress.org/” title=”Your favorite software”>WordPress</a> Links
<http://foobar.com> <http://wordpress.org> <a href=”http://wordpress.org”>
http://wordpress.org</a>
Links
[youtube http://foobarvideo.com] [youtube http://www.youtube.com/watch?v=CVmGBoPx6Ms] <div class=’video’><object width=’532′ height=’325′><param name=’movie’ value=’http://www.youtube.com/v/ CVmGBoPx6Ms?fs=1′></param> <param name=’allowFullScreen’ value=’true’></param><param name=’allowscriptaccess’ value=’never’></param><embed src=’http://www.youtube.com/v/ CVmGBoPx6Ms?fs=1′ type=’application/ x-shockwave-flash’ allowscriptaccess=’never’ allowfullscreen=’true’ width=’532′ height=’325′></embed></object></div> Video

Now that you know how to write in WordPress-flavored Markdown, let’s get started writing a readme.

Writing Your Readme.txt

Writing a readme is not hard, but putting a bit of thought into it beforehand does pay off.

  • What do you think end users will need in order to get optimal use from your plugin?
  • Do you need to include any special instructions or code snippets?
  • What problems do you anticipate users running into?
  • How can you make your plugin as attractive as possible?
  • In a saturated market, what makes your plugin stand out?

With a bit of thought, you can produce a useful readme that shows off the best aspects of your plugin.

When writing the readme, remember that if people are able to use your plugin properly, then they will be less likely to come knocking on your door asking for help.

Let’s look at each of the main readme sections to see what you can do to improve it. As a reference point, we’ll use the readme for Simple Twitter Connect, which is concise, useful and well-formed.

Plugin Header

The plugin’s header contains basic information about your plugin that the user will take in at a glance. This information will be displayed in the plugin’s directory as a quick reference for users.

the plugin header information in use in the plugin directory

Here’s what you’ll need to complete it:

  • Contributors
    Anyone who has contributed to the plugin. You should use a contributor’s user name from WordPress.org, linking it to their WordPress.org profiles, which list all of the contributor’s plugins. Unfortunately, many developers don’t mention their WordPress user name, which means they miss out on the opportunity to showcase the rest of their work.
    Contributor tag in the plugin directory linked to the contributor's page
    A contributor tag done right.
    plugin author listed in the directory that isn't a WP.org username
    A contributor tag done wrong.
  • Donate link
    This is your chance to get a little something back from the WordPress community. If you don’t have a donate link, you aren’t giving people the opportunity to thank you!
  • Tags
    As on a blog, tags are used to categorize content. In a directory of 15,000+ WordPress plugins, using tags effectively makes it easy for people to find your plugin. Keep the tags relevant, and think of what people who need your plugin might be searching for. Some developers tag their plugins with words that are only tangentially related.
    The WordPress.org listings for the twitter tag showing facebook plugins and an image gallery plugin
    This listing for the Twitter tag isn’t helpful because it’s bloated with irrelevant content. As WordPress community members and contributors, we have a responsibility to keep the directory of plugins as intuitive as possible.
  • Author URI
    Your home page.
  • Plugin URI
    The plugin’s home page. Note that the Author URI and Plugin URI aren’t included in the readme template provided by WordPress. Including them is definitely a good thing because they direct people to your respective home pages.
  • Requires at least
    This is the version of WordPress that your plugin requires. Some people don’t upgrade WordPress (some for valid reasons and some for dumb reasons). Tell them whether WordPress will work with their version.
  • Tested up to
    Another piece of important information. This tells people which version of WordPress your plugin has been tested up to.
  • Stable tag
    The stable tag tells WordPress which version of the plugin should appear in the directory. This should be in numeric format, which is much easier for WordPress to deal with. Aim for numbers like 1.5, 0.5 or whatever version you’re at. If your stable version is in the trunk in Subversion, then you can specify “trunk,� but that is the only time you should use words instead of numbers.

Here’s what the header information for Simple Twitter Connect looks like:

=== Simple Twitter Connect ===
Contributors: Otto42
Donate link: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=otto%40ottodestruct%2ecom
Tags: twitter, connect, simple, otto, otto42, javascript
Requires at least: 3.0
Tested up to: 3.2
Stable tag: 0.15

Tips for Writing Header Information

  • Use WordPress.org user names for contributors.
  • Use a number for the stable tag.
  • Include donation link to make some cash.
  • Keep tags relevant.
  • Test with the most recent WordPress version.

The Short Description

The short description is what appears on the WordPress.org page that lists plugins.

Simple Twitter Connect's short description on the WordPress dashboard plugin page

It also appears in the user’s list of installed plugins:

Simple Twitter Connect's short description on the WordPress dashboard plugin page

It’s your chance to craft a punchy 150-character description that will make people want to install your plugin.

Unfortunately, some people miss the mark:

buddystream on the listings page without adequate short decription

A plugin short description written in chinese

I’m not sure what this one is all about:

This short description drops down over four lines

None of these short descriptions tell you anything about what the plugin does. They’re totally useless in providing information to WordPress users.

Another problem is when developers do not add a short description at all. In that case, the 150 characters are excerpted from the long description. Check out the short description for Simple TrackbackSimple Trackback Validation with Topsy Blocker:

Plugin's short description cut off mid-sentence

The short description cuts off in the middle of a word. We know that the plugin performs a test on trackbacks, but why? What for? How?

Short Descriptions That Get It Right

  • VideoPress
    “Manage and embed videos hosted on VideoPress. Requires a WordPress.com blog with the VideoPress premium upgrade.�
  • Yet Another Related Posts Plugin
    “Display a list of related entries on your site and feeds based on a unique algorithm. Templating allows customization of the display.�
  • BuddyPress
    “Social networking in a box. Build a social network for your company, school, sports team or niche community.�
  • The Google+ Button
    “Adds the Google +1 button to your site so your visitors can vote to tell the world how great your site is!�

Tips for Writing a Short Description

  • Stick to under 150 characters.
  • Don’t rely on the text being pulled from the long description.
  • Tell people what the plugin will do for them.
  • Don’t worry about technical details. You can provide them in the long description.
  • Tell people whether the plugin has any requirements to work, such as a subscription.

Long Description

The long description is where you really go to town. You’ve hooked people with the short description; now it’s time to sell your plugin. Let’s check out the long description for Simple Twitter Connect:

== Description ==
Simple Twitter Connect is a series of plugins that let you add any sort of Twitter functionality you like to a WordPress blog. This lets you have an integrated site without a lot of coding, and still letting you customize it exactly the way you’d like.

First, you activate and set up the base plugin, which makes your site have basic Twitter functionality. Then, each of the add-on plugins will let you add small pieces of specific Twitter-related functionality, one by one.

Bonus: Unlike other Twitter plugins for WordPress, this one helps you create your own Twitter application and identity, so your tweets from here show up as being from Your Blog, not from some plugin system. You’ll never see "posted by Simple Twitter Connect" in your tweet stream, you’ll see "posted by Your Blog Name". Great way to drive traffic back to your own site and to see your own Twitter userbase.

Requires WordPress 3.0 and PHP 5.

**Current add-ons**
* Login using Twitter
* Comment using Twitter credentials
* Users can auto-tweet their comments
* Tweet button (official one from twitter)
* Tweetmeme button
* Auto-tweet new posts to an account
* Manual Tweetbox after Publish
* Full @anywhere support
* Auto-link all twitter names on the site (with optional hovercards)
* Dashboard Twitter Widget

**Coming soon**
* More direct retweet button (instead of using Tweetmeme)
* (Got more ideas? Tell me!)

If you have suggestions for a new add-on, feel free to email me at otto@ottodestruct.com.
Want regular updates? Become a fan of my sites on Facebook!

http://www.facebook.com/apps/application.php?id=116002660893

http://www.facebook.com/ottopress

Or follow my sites on Twitter!

http://twitter.com/ottodestruct

What makes this a good example of a long description?

  1. The opening description is clear and useful. It tells you what the plugin does and how it works.
  2. The key features stand out (you can tell that the plugin creates your own Twitter app).
  3. The plugin’s requirements are listed.
  4. Markdown is used to break up the text into sections and lists, making it easier to read.
  5. All current features are listed.
  6. Planned features are listed.
  7. The developer has included links to his Facebook page and Twitter account.

A good long description is useful and relevant. It tells the user what the plugin does and how it does it, and it provide anything else that the developer feels is important. You can also use it to send users to your home page or social-media profiles.

Here are some other plugins with great long descriptions:

Tips for Writing a Long Description

  • Use Markdown to bring some variety to the formatting. For example, add headings to break up sections, use lists, and put important points in bold.
  • Be clear about the plugin’s features.
  • Include any requirements, such as other plugins that your plugin relies on, or specific PHP versions.
  • Link to any extended documentation on your website.
  • Don’t be afraid to link to your website or social profiles.
  • If you’ve got one, a video is a great demonstration tool.

Installation

The installation section should include everything that a person needs to get the plugin up and running correctly. Often, you can keep this brief. Check out the instructions for Simple Twitter Connect:

1. Upload 'plugin-name.php' to the '/wp-content/plugins/' directory,
2. Activate the plugin through the 'Plugins' menu in WordPress.

For many plugins, this will suffice. But some plugins need detailed instructions. Check out the ones for these:

Users need mammoth instructions to set up both of these plugins. WP Super Cache requires you to look in your .htaccess file, and Domain Mapping needs you to move files to /wp-content/ and to edit wp-config.php.

Tips for Writing Instructions

  • Be brief, a few lines if possible.
  • Include everything the user needs to install the plugin.
  • Make sure each step logically follows the preceding one.
  • Include any code snippets that the user might need.
  • Be clear and concise. This is the place for instructions, not sales.

FAQ

The FAQ (frequently asked questions) section is your opportunity to troubleshoot problems before they even get posted to WordPress’ support forums. OK, so a few people will probably never bother looking at the FAQ to see whether their question is addressed there, which is annoying, but at least you will be able to direct them to the FAQ.

Some FAQs, however, are pretty lousy. In fact, some plugins, even popular ones, lack any FAQ at all. This is a problem: if too many plugin developers don’t include an FAQ, then some WordPress users will assume that plugins normally don’t have one and will run straight to the support forums. This wastes the time of people who have taken the trouble to include an FAQ.

Let’s check out the FAQ for Simple Twitter Connect:

== Frequently Asked Questions ==

= Whoa, what's with all these plugins? =
The principle behind this plugin is to enable small pieces of Twitter functionality, one at a time.

Thus, you have the base plugin, which does nothing except to enable your site for Twitter OAuth in general. It's required by all the other plugins.

Then you have individual plugins, one for each piece of functionality. One for enabling comments, one for adding Login, etc. These are all smaller and simpler, for the most part, because they don't have to add all the Twitter connections stuff that the base plugin adds.

= The comments plugin isn't working! =

You have to modify your theme to use the comments plugin.

In your comments.php file (or wherever your comments form is), you need to do the following.

1. Find the three inputs for the author, email, and url information. They need to have those ID's on the inputs (author, email, url). This is what the default theme and all standardized themes use, but some may be slightly different. You'll have to alter them to have these ID's in that case.

2. Just before the first input, add this code:
[div id="comment-user-details"]
[?php do_action('alt_comment_login'); ?]
(Replace the []'s with normal html greater/less than signs).

3. Just below the last input (not the comment text area, just the name/email/url inputs, add this:
[/div]

That will add the necessary pieces to allow the script to work.

Hopefully, a future version of WordPress will make this simpler.

= Twitter Avatars look wrong. =

Twitter avatars use slightly different code than other avatars. They should style the same, but not all themes will have this working properly, due to various theme designs and such.

However, it is almost always possible to correct this with some simple CSS adjustments. For this reason, they are given a special "twitter-avatar" class, for you to use to style them as you need. Just use .twitter-avatar in your CSS and add styling rules to correct those specific avatars.

= Why can't I email people who comment using Twitter? =

Twitter offers no way to get a valid email address for a user. So the comments plugin uses a fake address of the twitter's username @fake.twitter.com. The "fake" is the giveaway here.

= When users connect using Twitter on the Comments section, there's a delay before their info appears. =

Yes. In order to make the plugin more compatible with caching plugins like WP-Super-Cache, the data for a Twitter connect account is retrieved from the server using an AJAX request. This means that there will be a slight delay while the data is retrieved, but the page has already been loaded and displayed. Most of the time this will not be noticeable.

= Why does the settings screen warn me that I don't have a URL shortener plugin? =

Simple Twitter Connect does not implement a URL shortening service in favor of letting other plugins implement one for it. WordPress 3.0 includes a new shortlink method for plugins to implement this properly.

A shortener plugin should implement the "get_shortlink" filter for it to be detected. WordPress 3.0 will be required for this to work.

The WordPress.com stats plugin implements this, and it provides shortlinks to "wp.me" URLs. If you wish to use another shortener plugin, tell that plugin's author to implement this same standard, and the plugin will automatically be detected and used by Simple Twitter Connect.

That’s a pretty thorough FAQ! It’s useful because it anticipates any questions a user might have. It’s a pre-emptive strike: get in there with the answers before you see anxiety explosions in the support forums.

When writing support documentation such as an FAQ, aim at the lowest common denominator. A developer who is using your plugin likely won’t need an FAQ, and if they do, they’ll probably get the gist of it quickly and be able to implement it in an instant. There’s a rumor going around that WordPress is easy to use, which means that a lot of people who don’t know a whole lot about code will be fiddling around with it and break stuff. They are the people to whom you should be addressing your documentation, because they’ll be giving you the biggest headaches in the support forums.

Tips for Writing an FAQ

  • Anticipate issues and answer them in advance.
  • Deal with any known conflicts with old WordPress versions or other plugins.
  • If a problem recurs in the support forums, add it to your FAQ.
  • Use Markdown to highlight each question and follow it with an answer.
  • Include any code snippets or shortcodes that the user might need.
  • The FAQ is a tool to help you. Use it properly, and save some money on Aspirin.

Screenshots

Unfortunately, many developers think that screenshots are the realm of theme designers. Perhaps you assume that there’s nothing exciting or sexy to see in your plugin, so why bother providing screenshots? Check out the screenshots for Simple Twitter Connect. They show both the UI and the front end of the plugin, giving you an idea what it will be like before installing it.

Screenshots help users decide whether a plugin is right for them. As a developer, you might not think your UI is particularly interesting, but as an end user, I like to look at the settings before installing a plugin. It might not be a deal-breaker, but it does help me decide.

Here are some plugins with nice screenshots:

Tips for Putting Together Screenshots

  • Name screenshots as screenshot-1.png, screenshot-2.png, etc.
  • Include at least one screenshot of the UI, and one of what it does in the front end (if it does anything there).
  • Keep the size of the screenshot file small.

Other Notes

Including “Other Notes� is not essential. Many plugins don’t have them; Simple Twitter Connect doesn’t, for instance. But the section is useful if you have additional information that doesn’t necessarily fit in any other section.

Things You Can Include in “Other Notes�

Changelog

A changelog, as you would guess, is a log of all changes you’ve made to the plugin. It is an important part of the documentation and shouldn’t be ignored. A changelog may not make for the most exciting reading, but it is helpful. It tells a user what changes have been made to a plugin, and it makes clear why the user should update. It’s also useful for tracking the development of the plugin over time. A changelog gives a plugin context and history, and that can be important for people running big projects or important client websites.

Here’s a scenario: a user sees an alert in the admin area telling them that they need to update a plugin.

Update WP Touch notice
This user needs to update WP Touch!

The changelog shows the changes, so that the user can decide whether to update.

WP touch's changelog
The changelog helps us decide.

Maintaining some websites is a balancing act, and some administrators don’t want to upgrade unless absolutely necessary (say, for security updates or for new must-have features). Give them the information they need to be able to decide for themselves. If the update is minor, they might decide to save themselves the hassle and wait until something major arrives.

The changelog for Simple Twitter Connect is lengthy, not surprisingly. You’ll see all of the minor and major changes that have been made. Being able to see this plugin’s history and development is so useful.

Tips for Writing the Changelog

  • No change is insignificant. Make sure to add every single change.

Conclusion

Underestimating the importance of the readme file does a disservice to your code and to the WordPress community; so, seeing so many plugin developers do just that is sad. Don’t fight the readme: embrace it. It’s an important part of your documentation. A good readme is useful, helping users get set up to use the plugin as effectively as possible. And it’s useful to you, the developer. The readme demonstrates your plugin and anticipates problems, and it’ll save you time and headaches with support requests.

Here are some useful resources to get your plugin ready for the WordPress repository:

(al)


© Siobhan McKeown for Smashing Magazine, 2011.


How To Create Web Animations With Paper.js





 



 


The Web is just starting to use animation well. For years, animated GIFs and Flash ruled. Text moved and flashed, but it was never seamless. Animations had boxes around them like YouTube videos. HTML5 canvas changes everything about Web animation.

The canvas element makes it possible to integrate drawings and animations with the rest of your page. You can combine them with text and make animations interactive. This drawing mechanism is powerful, but very low-level.

Animations get more power and need less coding when you combine the canvas tag with higher-level libraries such as Paper.js. This article introduces HTML5 animation and walks you through creating an animation of dandelion seeds blowing in the wind.

Neat Is Easy, But Messy Is Hard

Computers love clean. They make spreadsheets, do statistics and plot multivariate curves; they always color inside the lines.

In the real world, even simple things are messy. Leaves falling from trees, water splashing — all the little interactions around us feel simple because we’re used to them; but little bursts of wind are actually messy and unpredictable.

For this article, we’ll animate dandelion seeds blowing in the breeze.

Dandelions are tricky because we all know what they look like: we’ve touched them and blown their seeds off. Commonplace objects produce instant recognition and feelings. I don’t have to tell you what dandelions are — you just know. Dandelions are a chaos of seeds piled on top of each other.

screenshot

(Image: Arnoldius)

Our dandelion animation will never reproduce the complexity of the real thing, and it will work better if we don’t try: make it too close to real and it will feel funny. Instead, we’ll create a stylized dandelion that makes the right impression without all of the details.

screenshot

Paper.js

Drawing simple shapes with the canvas tag, without any special drawing libraries, is easy. Create your canvas:

<canvas id="canvas" width="300" height="300"></canvas>

Then add a little JavaScript.

// Get our canvas
var canvas = $('#canvas')[0].getContext("2d");

// Draw a circle
canvas.beginPath();
canvas.arc(100, 100, 15, 0, Math.PI*2, true); 

// Close the path
canvas.closePath();

// Fill it in
canvas.fill();

screenshot

Cheat sheets for canvas show you the basics, but when you get into more serious drawing, you’ll want a higher-level library, such as Paper.js.

Paper.js is a JavaScript library for drawings and animations. It’s based largely on Scriptographer, a scripting language for Adobe Illustrator. You can write JavaScript with Paper.js, but most of the time you’ll be working with a JavaScript variant called PaperScript.

Paper.js calls itself “The Swiss Army Knife of Vector Graphics Scripting,� and the “vector� part is important.

There are two basic types of graphics, vectorized and rasterized. Rasterized graphics are like the pictures you take with your camera: big rectangles with maps denoting the color of each pixel. Enlarge them and you’ll get blurry dots.

Vector graphics are like connect-the-dots pictures: they’re sets of lines and shapes that give instructions on how to draw the image at any size. Using vector graphics, you can make an image of the letter Z really big and it will still look sharp. If you turned it into a rasterized graphic by taking a picture of it and then blowing it up, the letter would get all blurry.

Vector graphics libraries are perfect for animation because they make resizing, rotating and moving objects easy. They’re also much faster, because the program has instructions for drawing each object instead of needing to figure it out.

The Paper.js examples page shows some of the amazing things you can do with vectorized graphics.

The dandelion is a complete functioning example, and you can see it all running on the example page. You can also change the code by clicking the “Edit� button, see your changes live, and copy and paste the code to your own website. Over the course of the article, we’ll explain each part of the code in turn, but please note that in order to run the code yourself, you will need to head over to the example page and copy and paste it to your own environment.

Drawing Our Dandelion

The first step is to import our JavaScript and PaperScript files.

<script src="paper.js" type="text/javascript" charset="utf-8"></script>
<script type="text/paperscript" canvas="canvas" src="dandelion.pjs" id="script"></script>

The PaperScript code for running the animation is declared as text/paperscript. Now we’re ready to start drawing.

The first part of our dandelion is the stem. The stem is the green arc, with a circle on the top for the bulb. We’ll make both shapes with a path, a list of shapes, points and lines that the browser is instructed to display.

Paths are the basic building blocks of animation. They render lines, curves and polygons. You can also fill them in to make complex shapes. Our path looks like this:

var path = new Path();
path.strokeColor = '#567e37';
path.strokeWidth = 5;

var firstPoint = new Point(0, 550);
path.add(firstPoint);

var throughPoint = new Point(75, 400);
var toPoint = new Point(100, 250);
path.arcTo(throughPoint, toPoint);

Our path is an arc, so it needs three points: the start, the end and a midpoint to arc through. Three points are enough to define any arc we need. The arcTo function draws the line between them. The path item also supports styling information, such as stroke color and stroke width; #567e37 and 5 will make our arcing line green and thick. Paper.js supports the same color definitions as CSS.

We can add a few more items to make it all easier to see:

path.fullySelected = true;

var circle = new Path.Circle(throughPoint, 5);
circle.fillColor = '#CC0000';

Fully selecting the path will display some lines to show us the arc; the red circle shows us where the through point is.

screenshot

The stem ends with a circle to show the bulb of the flower and give us a place to attach all of the seeds. Circles are much easier in Paper.js than in direct canvas.

var bulb = new Path.Circle(toPoint, 10);
bulb.fillColor = '#567e37';

One line of code draws our circle, one more makes it green, and now we’re ready to add our seeds.

Drawing The Seeds

Each seed has a bulb, a little stem and a wispy part on top.

screenshot

(Image: Hmbascom)

Our seed starts with a small oval for the bulb and an arc for the stem. The oval is a rectangle with rounded corners:

var size = new Size(4, 10);
var rectangle = new Rectangle(p, size);
var bottom = new Path.Oval(rectangle);
bottom.fillColor = '#d0aa7b';

The seed stem is another arc, but this one is much thinner than the flower stem:

var stem = new Path();
stem.strokeColor = '#567e37';
stem.strokeWidth = 1;
stem.add(new Point(p.x + 2, p.y));

var throughPoint = new Point(p.x + 4, p.y - height / 2);
var toPoint = new Point(p.x + 3, p.y - height);
stem.arcTo(throughPoint, toPoint);

The wisps are more arcs with a circle at the end of each line. Each seed has a random number of wisps that start at the top of the stem arc and curve out in different directions. Randomness makes them look a little bit messy and thus more natural. Each seed gets a random number of wisps, between 4 and 10.

for (var i = 0; i < random(4, 10); i++) {
    path = new Path();
    path.strokeColor = '#fff3c9';
    path.strokeWidth = 1;

    var p1 = new Point(p.x, p.y);
    path.add(new Point(p1.x + 2, p1.y + 2));

    // Each flutter extends a random amount up in the air
    var y = random(1, 5);

    // We draw every other stem on the right or the left so they're
    // spaced out in the seed.
    if (i % 2 == 0) {
        throughPoint = new Point(p1.x + random(1, 3), p1.y - y);
        toPoint = new Point(p1.x + random(5, 35), p1.y - 20 - y);
    } else {
        throughPoint = new Point(p1.x - random(1, 3), p1.y - y);
        toPoint = new Point(p1.x - random(5, 35), p1.y - 20 - y);
    }

    path.arcTo(throughPoint, toPoint);

    // Now we put the circle at the tip of the flutter.
    circle = new Path.Circle(toPoint, 2);
    circle.fillColor = '#fff3c9';
}

Now that we’ve drawn the seed, we need to manage it; later, we’ll want to move and rotate it. The seed is made up of a lot of parts, and we don’t want to have to manage each one separately. Paper.js has a nice group object. Groups associate a set of objects together so that we can manipulate them all at once.

var group = new Group();
group.addChild(bottom);
group.addChild(stem);

this.group = group;

The last step is to package our seed into a reusable object called Seed. We add all of the code we’ve been writing to a new function with the name Seed and add a function to create the initial variables. This example calls that function create, but you can name it anything you want.

function Seed() {

    this.create = function (/*Point*/ p, /*boolean*/ shortStem) {
    …

The create function draws the seed at the specified Point, and the shortStem boolean tells us whether this is a short stem. We’ll look at short-stemmed seeds a little later.

These types of functions don’t work as constructors in JavaScript, but are supported in PaperScript.

var seed = new Seed()
seed.create(new Point(100, 100), false);

Our seeds will look like this when we draw them:

screenshot

The Seed object draws our random dandelion seeds. Now we can add them to our flower.

Adding A Little Chaos

The seeds will look better when we space them out around the circle of our dandelion bulb to feel like a halo of seeds. The bulb is a circle, and the circle is a path, so we can get each point on the path.

var bulb = new Path.Circle(toPoint, 10); bulb.fillColor = '#567e37';

var angle = 360 / bulb.length;
var seeds = [];

for (var i = 0; i < bulb.length; i++) {
    var seed = new Seed()
    seed.create(bulb.getPointAt(i));

    // Rotate each seed so that it points out from the bulb
    seed.rotate(i * angle);
    seeds.push(seed);
}

This will make a circle of seeds around the bulb but leave a space in the middle. We’ll add a few more seeds to fill in the center. We’re giving the center seeds short stems so that they show the white of the wisps more than the beige of the stems.

for (var i = 0; i < 18; i++) {
    var seed = new Seed()
    var point = new Point(toPoint.x + random(-3, 3),
                          toPoint.y + random(-3, 3));
    seed.create(new Point(toPoint), true);
    seed.rotate(random(0, 360));
    seeds.push(seed);
}

The seeds in the middle will bunch randomly and make our dandelion look nicely messy. Now we can make them blow off.

Animating The Seeds

Wind pushes seeds in complex patterns, and two seeds will never blow off the same way. We want to make them look real, so we’ll need a little more randomness.

Reproducing real wind is much too complicated, so we’ll make the seeds float off in a random-looking pattern. Each seed is assigned a random point on the right side of the screen as a final destination:

this.dest = new  Point(1800, random(-300, 1100));

The rotateMove function pushes each seed toward its destination point and rotates it. We can work with our Seed object as a group to rotate and move it with one function.

this.rotateMove = function(/*int*/ angle) {
    if (this.group.position.x < 850 && this.group.position.y < 650) {
        var vector = this.dest - this.group.position;
        this.group.position += vector / 150;

        this.angle += angle;
        this.group.rotate(angle);
    } else {
        this.isOffScreen = true
    }
}

This function will move the seed until it’s off the screen. Calling rotateMove for each frame of our animation will make the seed float across the screen.

Paper.js gives us an easy way to make animations with the onFrame function; when we implement onFrame, Paper.js will call it for every frame of our animation. With each frame, we iterate over each seed and move it across the screen.

function onFrame(event) {
    for (var i = 0; i < seedCount; i++) {
        if (!seeds[i].isOffscreen()) {
            seeds[i].rotateMove(random(2, 4));
        }
    }
}

The seeds slide and rotate a little closer to the destination point with each frame of the animation. Starting all of the seeds at the same point and ending them far apart makes them space out nicely as they move.

screenshot

We don’t want all of the seeds to fall off at once, so we’ll use a timer to make them drift away.

function start() {
    var id = setInterval(function() {
        seedCount++;
        if (seedCount === seeds.length) {
            clearInterval(id);
        }
    }, 1000);
}

The timer waits for one second before releasing the next seed, giving our dandelion a nice floaty feel.

Some green grass and blue sky as a background image for our canvas puts it all into context. Now we have a dandelion with seeds floating on the breeze.

screenshot

See the dandelion running here. You can edit and run the source code as part of the animation or download it from the dandelion GitHub page.

Paper.js In The Real World

Paper.js has some impressive examples and a nice coding model, but you should know a few gotchas before using it on your website.

It Doesn’t Work In Old Browsers

All Paper.js drawings use the canvas tag and require HTML5. This means that you need Internet Explorer 9+, Firefox 4+, Safari 5+ or Chrome. If your website must support older browsers, then you won’t be able to use canvas.

There’s no way around this requirement; if you need older browsers, you’re out of luck. As the Paper.js website says, “Let’s go forward!.�

Performance Can Be Slow

Paper.js can make a browser grind to a halt even if the browser supports HTML5. Pixar renders Buzz and Woody on giant server farms — all you get is your user’s cheap MacBook.

Not only are laptops slower than server clusters, but browsers make things worse by rendering the canvas tag with the CPU instead of the GPU. Games like Halo and Rage take advantage of the graphics processor on your video card to render rocket launchers and mutants. The CPU is less efficient with graphics, so the same computer that handles complex video games smoothly can make floating dandelion seeds look slow and jerky.

Make sure to test all of your animations with slower hardware, and watch the CPU usage. Use groups to minimize the calculations, and be very careful about what you do in each invocation of the onFrame function.

Mobile Devices Are Slower

Mobile performance is even worse. Most mobile devices support canvas, but they are mostly too slow to render canvas animations well. Even more powerful devices, like the iPad 2, can’t handle the dandelion seeds smoothly.

It Doesn’t Support Object-Level Events

Other drawing libraries, such as SVG (see below), support object-level mouse and keyboard events. Those events make it easy to respond when a path or a polygon is clicked, hovered over or touched.

The canvas tag doesn’t support object-level events. Paper.js has some basic functionality for hit testing, but it’s very low-level. You can listen for mouse and keyboard events on the whole canvas, but you’ll need to handle mapping those events to individual controls.

What About SVG?

The SVG (Scalable Vector Graphics) specification was defined over 10 years ago, but came to the forefront with support libraries such as Raphaël.js, which make it easy to generate SVG images with JavaScript. SVG is powerful, works well for smaller images, and is supported all the way back to Internet Explorer 7 with conversion to VML (Vector Markup Language). SVG is the best choice if you need to support older browsers.

The real issues with SVG are speed, future support and mobile devices. Every browser maker is actively working on making canvas faster. Safari 5 already offers hardware acceleration with the GPU for canvas, and the rest are working on it. SVG is also unsupported on Android devices.

There’s a growing community around canvas, the new technology that vendors are focusing on. They’re adding new features, fixing bugs and making it better every day.

Other Canvas Drawing Libraries

Paper.js isn’t the only option for canvas. Processing.js, from the creator of jQuery, ports the Processing programming language to JavaScript. It supports animations and has many examples.

The three.js engine supports canvas and the WebGL library, and it focuses more on 3-D drawings. Google Dart will also support canvas with built-in rendering objects.

Paper.js is a mature library with a very supportive community on the Paper.js Google Group and many impressive and well-documented examples. Check out some of the amazing things people are doing with it.

More Paper.js Examples

Our dandelion is just the beginning. Below are a few other impressive animations written in Paper.js.

Where’s your Paper.js amazingness?

(al)


© Zack Grossbart for Smashing Magazine, 2011.


Exporting From Photoshop





 



 


Congratulations. You’ve just completed a pixel-perfect mock-up of an app, and you’ve gotten the nod from everyone on the team. All that’s left to do is save the tens, hundreds or maybe even thousands of production assets required to bring it to life.

It’s probably the least interesting part of designing software, usually entailing hours of grinding. Saving images to multiple scales — as required by iOS and other platforms — adds complication to the process. But there are ways to streamline or automate the exporting process.

Copy Merged

Screenshot

Cutting up a design with the “Copy Mergedâ€� feature is fairly easy: ensure that the layers are shown or hidden as needed; draw a Marquee selection around the element; choose Edit → Copy Merged, and then File → New; hit Return; and then “Paste.â€� The result is a new document with your item isolated, trimmed to the absolute smallest size possible.
From here, all you need to do is save the image using “Save As� or “Save for Web & Devices.�

Rinse and repeat for every image needed for the app or website. The technique is simple and quick, but repetitive; and if you ever need to export the images again, you’ll have to start from scratch.

This seems to be the most common method and, for some designers, the only method, which is a shame, because better techniques exist.

You could create an action that triggers the “Copy Merged,â€� “New,â€� “Pasteâ€� process — a small time-saver, but ultimately not much of an improvement to the workflow.

Export Layers to Files

Screenshot

If you’re lucky, and your goal is to export a lot of similar images (typically with identical dimensions), you might be able to use Photoshop’s “Export Layers to Files� script.

By choosing File → Scripts → Export Layers to Files, each layer of the document will be saved as a separate file, with a file name that matches the layer’s name. This means you’ll probably have to prepare the document by flattening all of the elements that you’d like to export down to bitmap layers — a time-consuming process, but often quicker than using “Copy Merged.â€� It could also trim the size of the resulting file, if you choose to remove completely transparent areas.

I can’t say that I’m a fan of the script’s Flash-based UI or of the way it works, but “Export Layers to Files� is handy if your desired result fits its limited range of use cases.

Slices

Photoshop’s Slice tool lets you define rectangular areas to export as individual images, with some limitations: only one set of slices can exist per document, and slices cannot overlap (if they do, then smaller rectangle slices will be formed). During the ’90s, the Slice tool was a good way to create table-based Web layouts, filled with images. These days, designers far more often need finer control over how images are sliced, especially when creating efficient, dynamic designs, typically with images that have transparency. But, with a twist on the original concept, the Slice tool can be put to great use.

Sprite Sheets With Slices

Screenshot

Sprite sheets are commonly used in CSS and OpenGL games, where texture atlasing can have significant performance benefits. A similar method can be employed to build UI elements in Photoshop, even if the result is a set of images, rather than one large image.

By spreading out the elements that you need to export as a flat sprite sheet, you eliminate the need for slices to overlap. If there are too many elements to comfortably fit in one document, you can create multiple documents, eliminating the need for more than one set of slices per document.

The other benefit to working like this is that you’ll no longer need to build your main design documents with the same level of precision. Occasionally using a bitmap or forgetting to name a layer is fine, because you’ll have a chance to fix things when preparing the sprite sheet for exporting. But it does mean that the original mock-up document could get out of sync with the export documents if you make changes (for example, to adjust colors or layer effects).

Because we’re interested only in user-created slices, it might also be a good idea to click “Hide Auto Slices� (in the options toolbar when the Slice Select tool is enabled) and to turn off “Show Slice Numbers,� under “Guides, Grid & Slices� in Preferences. This way, you’ll remove unnecessary clutter from Photoshop’s slice UI.

Screenshot

After you’ve created a sprite sheet with the slices all set up correctly, you’ll be able to export all of the images at once, using “Save for Web & Devices.â€� Assuming you’ve done things correctly, you’ll be able to scale up by 200%, save all of your Retina images, and then batch rename them (adding @2x to the file names) — or scale them down, if you built everything at Retina size to begin with.

Layer-Based Slices

If your UI element is one layer and you’d like the exported image to be the smallest possible size, you might want to consider using a “Layer-Based Slice.� To create one for the currently selected layer, choose “New Layer-Based Slice� from the Layers menu. A Layer-Based Slices moves, grows and shrinks with the layer it’s associated with. It also takes into account layer effects: strokes and shadows increase the size of a Layer-Based Slice, so the effects are included. Less control, but more automated.

My Exporting Workflow

For years, I’ve used Copy Merged as my primary exporting method, and used Export Layers to Files when it made sense. That was a poor choice. Sprite sheets have so many advantages, especially in medium- to large-scale projects, that the set-up time is made up for very quickly. This is even truer when exporting Retina and non-Retina images: each set can be exported in a few clicks and is far less likely to have issues with file names or sizes due to its automated nature.

It also creates an environment in which modifying production assets is easy, allowing for faster iteration and more experimentation. It lowers the barrier to improving artwork during development and when revising the app or website.

And that’s a very good thing.

(al) (il)


© Marc Edwards for Smashing Magazine, 2011.


The Big Think: Breaking The Deliverables Habit





 



 


Right there in the center of my boilerplate for design proposals is a section that I glare at with more resentment each time I complete it. It’s called “Deliverables,� and it’s there because clients expect it: a list of things I’ll deliver for the amount of money that I specify further down in the document. Essentially, it distills a design project down to a goods-and-services agreement: you pay me a bunch of money and I’ll give you this collection of stuff. But that isn’t what I signed up for as a designer. Frankly, I don’t give a damn about deliverables. And neither should you.


(Image: Snoggle Media)

Case in point: for months now, I’ve worked consistently with a particular client for whom I do almost no work on actual design artifacts (wireframes, prototypes, etc.). Rather, I hold frequent calls with the main designer and developer to go over what they’ve done with the product (i.e. poke holes in it) and what they should do next (i.e. help prioritize). Some days, they hand me wireframes; sometimes, a set of comps; other days, live pages. Whatever the artifact, our purpose is always to assess what we have now versus where we need to get to. We never talk about the medium in which these design ideas will be implemented; we focus strictly on the end result, the vision of which we established long ago and continually refer to. And in working this way, we’ve been able to solve countless significant problems and dramatically improve the client’s website and products.

It’s not about deliverables. It’s about results.

Understanding why this works depends on understanding the real role of the designer and the deliverables they create.

A Designer’s Work

First, consider the role of a designer compared to what we actually spend most of our time doing.

What designers are hired to do — the reason why companies seek out designers in the first place — is what my friend Christina Wodtke calls “The Big Thinkâ€�: we’re hired to solve problems and develop strategies, determining what needs to be achieved and making design decisions that help to achieve it. But because companies have a compulsive need to quantify The Big Think, designers end up getting paid to create cold hard deliverables. Our very worth, in fact, is tied intrinsically to how well and how quickly we deliver the stuff. Heck, we’re often even judged by how good that stuff looks, even when much of it goes unseen by a single user.

Is this how it should be done? Absolutely not.

Hiring a designer to create wireframes is like hiring a carpenter to swing a hammer. We all know that the hammer-swinging is not what matters: it’s the table, the cabinet, the deck. Clients don’t hire us to wield hammers, but to create fine furniture. It’s not the process they need or the tools, but the end result.

In theory, companies understand this. In practice, not so much. They cling to the deliverables.

The Essence of Deliverables

So let’s look at what a design deliverable really is.

The purpose of a design artifact, whether a wireframe, prototype or sketch, is to illustrate our thinking. Pure and simple. It’s part of the thinking process. It’s also, according to some, a record to look back on later to aid when reconsidering decisions, tweaking the design and so on. But let’s be honest: people rarely look back at these documents once the design grows legs and starts walking on its own. More often than not, significant changes result in new wireframes, and minor tweaks are made on coded screens, not back in the deliverables that we were paid so much to create.


(Image: HikingArtist.com)

Most of the time, design artifacts are throwaway documents. A design can and will change in a thousand little ways after these documents are supposed to be “complete.� In terms of allocating time and budget, design artifacts can be downright wasteful. They can even get in the way; designers could get attached to ideas as they transition to functioning screens, precisely when they need to be most flexible. Every design is speculation until it’s built.

Like it or not — and some of you will surely disagree — we can survive with fewer deliverables. Of course, what this looks like depends on how you work.

Breaking the Deliverables Habit

The most important parts of any design project are the vision of the end result, the requirements for it, the design itself, and a way to measure its success.

Interestingly, only one of these parts involves complicated design artifacts. The vision is merely a statement that describes the purpose and desired outcome. Requirements are but a list. Success metrics? Another list. The only part that involves more than a simple, concise summary is the design itself. And nothing requires that process to involve layer upon layer of wireframes, prototypes and comps before going to code. (More on how to change this in a minute.)


(Image: lucamascaro)

Comps, of course, are a must when graphics are involved; in addition to necessarily being the source of the graphic files to be used in the actual design, they define the visual language, the specifics of layout, spacing, typography, etc. Creating wireframes, on the other hand, as quick as it is compared to creating coded screens, can take much longer than going from sketch to code. So, consider cutting the load down to what’s most essential and useful: the interaction model.

In other words, you don’t have to create wireframes and comps for every idea or every screen; just for the toughest screens, the ones that define the most crucial interaction paradigms. Use them to iron out the model, not every last detail.

It’s time for more design and less stuff. Consider the revised process below.

1. Strategy Document

Distill your research on users and the business down to a short vision statement on what the user’s experience should be like. Add to this a list of design criteria (specific guidelines or principles for the design), as well as success metrics (how you will know that the design is achieving your goals). You should be able to do all of this within just a couple of pages; and keeping it short will help to ensure that everyone reads it.

2. Activity Requirements

Write a list of tasks that users should be able to perform, and functions that the system should perform that will benefit users. Prioritize the ones that will appear on the screen.

3. Sketch

To apply the design criteria and meet (or exceed!) the requirements, sketch a dozen or so ideas — in Keynote, on paper or on a whiteboard — and then take pictures of the sketches. Sketch the toughest, most complicated and most representative screens first. These will frequently determine the interaction model for most of the design.

4. Comp and Code

If you’re not doing the visual design yourself, collaborate with the graphic designer to iron out the details of the most representative screens and any other screens that require graphics. At the same time, collaborate with the developers to identify issues and areas for improvement throughout the process.

Forget the lengthy strategy documentation. Forget the deck of wireframes. Just short summaries (long enough to get the point across, but short enough to be able to do quickly), sketches and comps, limited to the things that need to be brought to a boil in Photoshop. Skimping on the deliverables can save a lot of time.

Untying Deliverables From Project Fees

Of course, sufficing with this shorter list of artifacts and untying deliverables from your fees require a change to the design process. In short, we need to shift the emphasis from documentation to collaboration.

Set the expectation from the beginning that you will work with stakeholders collaboratively. They will help you think through the design at every step. You will not be a wireframe monkey. Rather, you’ll focus on The Big Think. And you’ll do it together. If the client is unwilling or unable to spend time and energy on the design as you develop it, find another client. A client who is too busy to get involved in the process is a client who doesn’t care about their customers.

Collaboration is essential to great design. No one person can think of everything or always have the best ideas for every aspect of a product. It takes a group to make this happen. This might require you to occasionally browbeat the client into being available for frequent discussions on new and developing ideas, but the result will be infinitely better. And with the added input, you can focus less on stacks of deliverables and more on converting rough ideas into comps, prototypes and/or functioning pages that give undeniable weight to those ideas.

In practical terms, this means working closely and constantly with the visual designers and developers (assuming you’re not doing this work yourself). And it means frequently reviewing what’s being done and discussing at a deep level and at every step how to make improvements. It means talking through every detail and making sure someone has the job of being the resident skeptic, questioning every idea and decision in the interest of pushing the design further.

Break The Habit

By focusing on The Big Think, the deliverables will matter less. And for a designer, focusing on beautiful products is a whole lot more rewarding than dwelling on the step by step of deliverables. On your next time out, consider breaking the deliverables habit. Go from idea to code in as few steps as possible. Hefty amounts of collaboration can cure the sickly feeling that you’re an overpaid wireframer, empowering you to build designs that you know are killer work.

(al)


© Robert Hoekman Jr for Smashing Magazine, 2011.


  •   
  • Copyright © 1996-2010 BlogmyQuery - BMQ. All rights reserved.
    iDream theme by Templates Next | Powered by WordPress