Dustin Boston – Page 3

Getting Started With CSSDOC Commenting

February 19, 2009 By Dustin Boston

CSSDOC is a commenting convention much like Java Doc and PHP Doc. It provides a standard way for developers to tag parts of a stylesheet with important meta information. Eventually it may be used to provide an enhanced interface in your favorite IDE. Although it is still in the draft phase, CSSDOC is a great way to clean up your stylesheets.

Syntax

This is the basic block in which all comments will be placed. It has a very specific markup. The opening line has one forward slash followed by two asterisks. Each comment line thereafter should start with a single space an asterisk and one more space. Note: spaces do not show up in the examples unless you click the PLAIN TEXT link. Finally to end the block use a single space, one asterisk, and another forward slash.

[css]
/**
*
*/
[/css]

A tag is a single at sign (@) followed by some text with no space. Most tags can be followed by a single space and some descriptive text, as follows:

[css]
/**
* @tag This is a tag!
*/
[/css]

Additionally, each block may contain several lines that do not have tags. These lines are typically reserved for a title and long description:

[css]
/**
* Descriptive Title
*
* Your long description would go here, before any of the tags.
*/
[/css]

File comment

Most designers want to put a little title block at the top of their stylesheets. It will usually include information about the author and creation date. There are a lot of tags, I have included the most common ones in the example below.

[css]
/**
* Stylesheet title
*
* Your stylesheet description would go here.
*
* @project Name
* @version 1.0
* @author Name
* @copyright Year
* @license Type
*/
[/css]

Section and Subsection Comment

You can mark a section in your file with @section and @subsection tags. You can title these areas but I typically find myself dropping the title and just including the section name.

[css]
/**
* @section Section
*/
[/css]

One thing that CSSDOC lacks is a method for defining visual delineation between sections in a stylesheet. This should be left to the IDE. Unfortunately, I am not aware of any IDEs that support CSSDOC. I suggest this simple compromise for the time being.

[css]
/**
* ————————-
* @section Section
* ————————-
*/
[/css]

Visually it works pretty well. Someday CSS editors may incorporate the CSSDOC standard and render a visual indicator for section tags.

Bug/Workaround Comment

It’s a sad but true fact that we have to use hacks to fix browser display issues. Fortunately CSSDOC provides a great way to mark these sections of code.

[css]
/**
* Why the fix is here
*
* @workaround or @bugfix
* @affected browser
* @valid yes or no
*/
[/css]

The workaround/bugfix syntax is a little confusing to me. Here is the explanation from the draft:

Bugfix: Should remove CSS-Rendering Problems without having bothersome effects.

Workaround: Some browsers need a reduced rendering because they are full of errors. A Workaround works around those Issues.

They list the Guillotine bug as a workaround and the disappearing list-background bug as a bugfix. I don’t get it. Instead, I would prefer to combine both tags into one, such as @hack or @fix.

You can also document the affected browser and whether or not the hack is valid. For a complete list of browser codes check the appendix in the draft.

I have wondered what to do about a simple hack, like a display:inline to prevent the double float margin bug. You don’t want to put it in a huge block of its own and you don’t want to put a CSSDOC block inside of a declaration. So what do you do? I don’t know. Maybe this will be addressed in the technical spec.

Other Useful Tags

@colordef: For notating colors. Follow it with a #color and a description of what it is used for.
@see: If you need to reference a website you can drop a link after this tag. It’s nice to give attribution.
@todo: I use this one all the time. Whenever you need to remember what you have to do next you can use this tag.

Conclusion

CSSDOC is a great way to standardize your stylesheet comments. It provides a nice framework for adding rich meta information to your CSS that might otherwise be lost. Someday we may even see it implemented in an IDE. If you are interested in finding out more, download the Public Draft.

How to Use WordPress for Bookmarking

February 6, 2009 By Dustin Boston

After Ma.gnolia went down I was so disappointed that I decided to take matters into my own hands. I thought, why not use WordPress to store my bookmarks. It has all the neat features of most popular bookmarking sites, and even some more (XFN, for example).

Of course, I could just post a link whenever I saw one but it panged me to think that I would be putting to waste that wonderful link schema that the folks at WordPress have put so much thought into. And then Smashing Magazine reminded me about shortcodes. I had used them before in plugins but I never thought about just adding one off short codes to my functions.php file.

It turns out that this was the perfect solution to my problem. With one tiny little shortcode I was able to utilize the bookmarks system in WordPress and publish my links as normal. Here is how I did it.

1. The shortcode code

First you want to start by adding the following code somewhere in your functions.php file.

[php]
/**
* Get a bookmark and display it
*
* usage: [magnolia id=”bookmarkid”]
*
* @return string
*/
function magnolia_rip($atts) {
extract(shortcode_atts(array(
‘ids’ => ‘1’,
), $atts));

$idarr = explode(‘,’,$ids);
$bookmarks = ”;

foreach ($idarr as $id) {
$bookmark = get_bookmark($id,ARRAY_A);
extract($bookmark);

$bookmarks .= <<

$link_notes

$link_name

LINK;
}

return $bookmarks;
}
add_shortcode(‘magnolia’, ‘magnolia_rip’);
[/php]

I’ll skip the details on how shortcodes work, the Smashing Magazine post does a great job of summing that up. However, I do want to explain the bookmark stuff.

We start by passing in the id or comma separated list of ids through the shortcode. They get put into an array where they are iterated. For each id we call the get_bookmark method, which is currently undocumented. It returns an object or array with all the values from the links table in your WordPress installation. The ARRAY_A parameter tells the method to return an associative array.

Here are all the fields in the links table:

link_id
link_url
link_name
link_image
link_target
link_category
link_description
link_visible
link_owner
link_rating
link_updated
link_rel
link_notes
link_rss

I have used the extract() method to convert each key (field) in the returned array to a variable. That’s probably not the best idea for performance reasons, but for demonstrational purposes it’s nice and clean. Next, I create a div with some paragraphs and a link. This is the part where you can customize to your hearts content. I just went with something basic.

2. Add a link

Now all you need to do is head over to your links page in the WP admin and add a link. I put mine in a category called bookmarks just to keep things organized. You can go crazy here if you want. Once you’ve saved the link make sure to get the ID for it.

The ID isn’t anywhere obvious, unfortunately, which makes this technique feel a little hacky. Regardless, if you go back to the links page and hover over the title of your link you will see something like this in your status bar at the end of the URL:

[html]
link_id=165
[/html]

Just take note of the id, you’ll need it for the next step.

3. Write your post

Finally, lets post the link to the blog using the shortcode we created earlier. Start a new post and add the following:

[html]
[magnolia ids=”165″]
[/html]

That’s it! Now save your post and basque in the glory of your ingenuity!

Caveats

~~There is one caveat that I can think of. The RSS feed will not publish the generated text. So you’ll only have titles for those posts unless you add more text to the body of your post.~~

This is a great way to use an often under-utilized feature of WordPress. It is also fun to host and publish your own bookmarks for people to see. Let me know how it works for you!

Update: After more careful testing I realized that the full text does, in fact, show up in RSS. So there you have it, if you want to post your bookmarks to your site nothing is standing in your way!

Avoid Using Generic CSS Classes

February 1, 2009 By Dustin Boston

The W3C has worked hard to remove presentational elements from HTML. Unfortunately, old habits don’t die easily. This has resulted in some standard generic CSS classes that are contradictory to the intention of HTML and CSS. If you are using classes like .left, .right, and .clear you are guilty as charged.

[Read more…]

ICanLocalize Provides Human Translation for WordPress Blogs

December 16, 2008 By Dustin Boston

ICanLocalize has recently released a set of WordPress plugins designed to make the difficult process of translating a website into another language much easier.

The biggest feature of their system is obviously the translation mechanism. Here is how it works (from their website):

Our system produces a translated blog with contents that are based on the original language blog. Whenever there are new contents or when contents update on the original language blog, they are sent to translators. The translations are then published in the translated blog.

The entire process is fully automated. Bloggers don’t need to spend any time administrating the translation. From the translators’ point of view, the process is seamless. They are notified whenever there is new work and translate inside ICanLocalize’s system. Translations are being sent automatically and published.

And the results are great. If you have ever tried to translate a website using an online tool I am sure you have realized how inadequate it can be. Don’t get me wrong, Google Translate and Babelfish have their uses, but nothing can compare to a professional human translator, writing in his or her native language.

More than just translation

ICanLocalize offers more than just translation. They have created several other WordPress plugins that compliment the translation service but are beneficial without it. For example, the CMS Navigation plugin provides “out-of-the-box support for full CMS navigation in your WordPress site including drop down menus, breadcrumbs trail and sidebar navigation.”

The Absolute Links plugin “prevents dead links between any post or page by guaranteeing that all links always point to the current addresses (permlinks).” I could have used that one on a project that I recently completed which required non-technical people to deploy a WordPress blog in test and transfer it to a production site with a different URL.

Each individual plugin is great but the whole package of plugins, used together, allow you to do things that are difficult to do otherwise. They are all GPL and in the WordPress plugin repository. Check it out and let us know what you think!

Even More Drupal Client Guides to Make Your Life Easier

December 11, 2008 By Dustin Boston

Here’s the scenario: your client is starting to get comforatable with logging in to their Drupal site and adding content. They can edit a post just fine. You start to see that hunger in their eyes for more. What do you do?

If you answered “Hand ’em a couple more client guides!” you would be correct.
These two client guides take it up a tiny notch by showing your client how to manage user accounts and check out their statistics.

For these to work you will need to make sure that the client account has the proper permissions (we know you’re not letting them loose as an admin). You will also need to enable the Statistics module.

Guide 3 Downloads

Guide 4 Downloads

« Previous Page