Dev411 Blog: Category typo

Database Abstraction - code vs infrastructure

John Wang — Tue, 04 Sep 2007 23:38:00 -0500

I've worked on a number of database-driven projects and no matter how much people want database abstraction, it was always difficult to code and maintain. I was recently reminded of this when I read this Drupal article on dropping PostgreSQL support. Not only can it be difficult to maintain support for multiple databases, but it may be difficult to find developers.

One solution of modern programming is to move database abstraction from the code to the infrastructure using a ORM (Object-Relational Mapper) or Data Mapper. A ORM and Data Mapper abstracts the database for you so you no longer have to do tie db abstraction to each app. Not only does it let you code once for multiple databases it lets your users migrate their data from one database to another. This blog runs Typo which is based on Ruby on Rails and ActiveRecord. I've been contemplating migrating Typo from MySQL to PostgreSQL and I've been told that it would be as simple as exporting the data with YAML, updating the database.yml file and importing the data. I haven't gotten around to doing it yet but it is a powerful idea. ActiveRecord is a data mapper and isn't as flexible as a full blown ORM but it gets the job done for the most part. For a full-blown ORM, I think of Perl's DBIx::Class which provides a full OO interface to the RDBMS allowing you to code just once for multiple DBs without limiting you when you want to use some esoteric database-specific SQL. DBIx::Class is often used with the Catalyst Framework but is also used by itself.

There are PHP frameworks out there like Symfony and Cake but do any of them have stand-alone ORMs? If so, could Drupal move to something like that and solve their maintainership problems once and for all? Drupal is part of the Go PHP5 effort so there should be no issue using PHP 5 OO. Something to think about for the Drupal folks if a PHP ORM is available.

Typo - Upgrading to 4.1.1

John Wang — Sat, 16 Jun 2007 17:36:00 -0500

I finally got around to upgrading from Typo 4.0.0 r1188 to Typo 4.1.1 and it was pretty smooth. I had held off for a while because Typo was changing a lot under the covers with some much needed refactoring and I have a few hacks I didn't feel like modifying with every minor update.

I ran into some initial issues because I was installing from the tarball and not the gem. I had an older version of Rails and Typo 4.1.1 needs Rails 1.2.3. Running "rake migrate" doesn't check the Rails version and would just abort. Eventually I guessed the problem reading the --trace output and I was on my way. The other curiosity was that Gem's --install-dependencies didn't work for me. I still had to install/upgrade rake, activerecord and a number of other packages before installing rails using gem. I think it would be nice if --install-dependencies did install those or at least showed all the packages that were needed in one report instead of just showing one and aborting. Perhaps there was something wrong with my setup. With CPAN, you get to see all the required dependencies in the first report and it will install them all for you in one shot. However, compared to gem, CPAN might show too much information by default. Perhaps the majority of the information CPAN shows should be moved to a non-default verbose mode.

I have a few hacks running on this blog so the update consisted of the following:

Theme: This blog runs a modified version of Azure which used a table that no longer exists in 4.1.1. Because of this Typo wouldn't start. To get around this I did a manual SQL update of the settings column in the blogs table to reset the theme to Azure before migrating my mods over. The settings field is an aggregate field with serialized information delimited by carriage returns. I prefer using JSON to serialize complex data structures stored in a single db field which I think is much more maintainable.
Categories Sidebar: This had moved from ./components/plugins/sidebar/category to ./vendor/plugins/category_sidebar. Now that the sidebars are stand-alone Rails plugins, it makes more sense for me to turn my custom Category sidebar into its own thing instead of modifying the existing one.
Notable Links: I put together some social bookmarking links a while back for Typo 4.0.0 and it was reported to no longer function with 4.1.1. A little checking showed that article.location was no longer available and replaced by article.permalink_url. Both 4.1.1 and 4.0.0 versions of the Notable view are now available. The method call used to display the article body in ./views/articles/read.rhtml had also changed. This is used as a reference point to insert new code.
Table of Contents: The Table of Contents solution I had put together had also broken and is now fixed. It is interesting to see the progression of link creation from 2.6.0 to 4.0.0 to 4.1.1. The previous two used Rails' link_to helper but 4.1.1 creates the HTML manually.

The rest of the changes were pretty straight-forward to carry across, including the category icons and routes.rb mods I use.

Overall, the upgrade was smooth after I figured out I needed to upgrade Rails from the rake migrate failure. I like the refactoring of the plugins and look forward to making some.

Frédéric de Villamil, the current Typo maintainer, menioned that 5.0 is coming and will have the following features:

Plugin Manager: to download and install plugins from the official repository
Advanced Theme Manager: to download and install themes from the official themes repository
Real Multi-User Support
OpenID Support
and more....

I've been pleasantly surprised with the development activity happening around Typo and can't wait for version 5.0.

Displaying Dates and Times Using JavaScript

John Wang — Mon, 05 Feb 2007 18:28:00 -0600

Some considerations when displaying dates and times on a website include showing delta times, customized timezones and caching. Often it's nice to show a delta time like "10 minutes ago" or "5 days ago" to give readers a frame of reference instead of an absolute date. When the date is far enough in the past and an absolute date becomes desired, customizing the date to the user's timezone is useful. And if your site grows large enough that caching becomes useful, finding a way to display customized deltas and timezone information in a cacheable static page becomes an ideal solution.

JavaScript is an ideal solution for all three issues. With JavaScript you can place an absolute date in the web page and have the JS dynamically update it when the page is loaded. This can be used to calculate delta times and accommodate timezones as well. The result is that the page can embed the same date every time and thus becomes more cache-friendly.

The Typo blog engine (which runs this blog) comes with a useful MIT-licensed JavaScript in it's typo.js script. Just copy three of the JS date/time functions, wrap your dates with spans (using the appropriate class name and absolute date in the span title) and then call show_dates_as_local_time() when your page is finished loading. The two other functions you'll need are get_local_time_for_date(time) and distance_of_time_in_words(minutes). This is what I did for Planet Catalyst's Plagger theme a while back.

Although it's pretty easy to accommodate timezones, the Typo script doesn't do that. I've done this for some projects and might post some code in the future but it's not hard.

Customization and cacheability, two great advantages for using JavaScript to handle dates and times.

Notable social bookmarking/networking for Typo

John Wang — Sat, 02 Sep 2006 12:20:00 -0500

Benjamin Gorlick asked for WP-Notable-style social bookmarking/networking links on the #typo IRC channel so I put one together in the form of a single view (template file). WP-Notable, by Cal Evans, displays a row of icons with links to social bookmarking/networking sites under your blog article allowing for easy posting tovarious social bookmarking sites.

All the icons used here are from the WP-Notable plugin and look like the following:

Without further ado, here are the 4 steps (optional 5th step) to get this on your Typo blog:

Step 1: Copy the _article_notable_v4.1.1.rhtml or _article_notable_v4.0.0.rhtml partial include file to your Typo install's app/views/articles/ directory and rename it _article_notable.rhtml.

I've put the code for this all in a single template file to keep the modification in a single place since I have a growing number of mods. There is an array of information for each site. Right now it will create this array each time it is included which may be several times on the homepage. This could be put into the config file or a helper so it gets instantiated only once but I left it in the template since it means updating fewer files and the HTML pages are cached so I don't think it's a big deal. It's also possible to create a notable_link method to generate each link instead of having it created in the template.

Step 2: Install the icons by extracting the png files from typo_notable.tgz into your /images/notable directory. This directory is ferenced in the _article_notable.rhtml file so edit that file if you wish to change the icon locations. The tarball also includes the rhtml file just for completeness.

Step 3: Add the following to index.rhtml file under the "Read more..." article_link line. This file is either in app/views/articles/ or your theme directory.

<%= render :partial=>"article_notable",:locals=>{:article=>article} %>

Step 4: Edit the read.rhtml file and add the following line under the where the article body is rendered. In Typo 4.1.1, place this line under the <%= html(@article) %> line and in Typo 4.0.0, place this line under the <%= @article.full_html %> line. The read.rhtml file is either in app/views/articles/ or your theme directory.

<%= render :partial=>"article_notable",:locals=>{:article=>@article} %>

Step 5: If you want to style the notable icons, there are some CSS classes used typo_notable_line,typo_notable and typo_notable_icon. These are easy to spot in the _article_notable.rhtml file.

So far I've only tested del.icio.us and digg and the links work since that's where I have accounts. Please let me know if any of the links don't work (or work) for you. Enjoy!

Update: Thanks to Benjamin Gorlick for comments to these instructions.

Typo - License for TypoGarden Themes

John Wang — Sat, 26 Aug 2006 20:48:00 -0500

There has been some confusion about the license that covers the themes submitted to the 2005 TypoGarden Theme Contest. Many themes do not mention a specific license and the contest page simply says:

All themes submitted will be made available for download. Don’t submit it unless you want it to be used by tens of thousands of Typo users.

Geoffrey Grosenbach, of TypoGarden, mentioned on the #typo IRC channel that all the themes submitted are under the MIT License. This makes sense since Typo itself is under the MIT License.

Some contest theme authors have released their themes under different licenses, notably:

Lush by Marco van Hylckama Vlieg: This has a 2005 copyright notice and says the theme is "Licensed under the Creative Commons NC License (no commercial use)"
Lucid by Jamie Hill: There's no license file with the Lucid theme, however, Jamie mentions the theme should only be used for Typo in a blog comment: "You can use it as-is on any typo blog however I would not want to see it used for anything other than that i.e. corporate website." Jamie has been kind enough to allow me to use the Lucid theme on this site saying: "As for the licensing… strictly speaking it should only be used for blogs un-changed however I can’t see an issue with your usage as the projects you are using it for are open source (as long as the 'template by…' link stays on there)."

IMO, since there doesn't seem to be a license requirement on the theme page and I'm not sure whether the MIT License requirement was communicated to theme submitters via other channels, it seems safer to use the author specified license if it exists and the MIT License when none is specified. For future contests, specifying the submission license requirements with the rest of the rules seems best.

Categories vs. Tags

John Wang — Wed, 16 Aug 2006 01:18:00 -0500

Today, Google announced the next version of Blogger, Blogger Beta. As part of this upgrade, Blogger will finally get categorization. Like Gmail, Blogger will only give you 'labels' which other blog engines such as Typo and MovableType give you both categories and tags. When both categories and tags are available, there's often a question as how to use them, either together or one or the other. This can be seen in some blogs where there doesn't seem to be rhyme or reason to what is a category and what is a tag. For Typo, this is somewhat complicated by that fact that tags came along after categories, so some blogs used them for the same thing but never got rid of the old categories after switching to tags so there appears to be some overlap.

In my opinion, categories should be used for high level groupings. For example, The Register uses: Enterprise, Software, Internet, Telecoms, Mobile, Security, Management, Science and Odds & Sods. Google News uses : Top Stories, US, Business, Sci/Tech, Sports, Entertainment, Health and Most Popular. In the past, when people had different subjects they wished to talk about on Blogger, they often got different Blogger blogs to discuss each topic. When categories are available, they can e used to delineate such groupings. IMO, there should only be a limited number of categories and they should cover the general areas discussed by the blog. It would be nice if the categories appeard in a horizontal navbar under the header which will be a lot easer with the mulit-sidebar enhancement.

I feel that tags, on the other hand, should be used liberally to cover just about any subject that one may wish to discuss on two or more articles, kind of like short cuts to a search. This follows the typical usage pattern for Delicious where one can end up with many tags.

For this blog, I only have 'tags' (which are really renamed categories from when I was running 2.6.0) but I'm thinking about adding categories as well. Most of the articles now are related to software development so I don't think high level categories are needed. If I do add them however, they will be along the lines of: (a) Development (software programming), (b) Management (things like marketing, entrepreneurship, venturecapital) and (c) Legal (patents, contracts, etc.). That's just to give an idea of how I would use categories and tags together.

MediaWiki and Typo - Pros and Cons for Personal Use

John Wang — Fri, 11 Aug 2006 13:37:00 -0500

Now that this site runs both MediaWiki and Typo, I need to decide what to post where. Unfortunately I want to continue running both because they each have their advantages but ideally I could just run one, at least externally facing. These are some of the features I like of both MediaWiki and Typo which makes it hard to choose one over the other for all my posts. As a disclaimer, this is a personal wiki so I won't be discussing multiple users. The below lists the pros for each, If it's listed it means the other one doesn't have it ;)

MediaWiki

Heading-based Article Formatting: MediaWiki provides some functionality based on article headings. Headings are desginated by =, e.g. = My Heading =. This is similar to <h1>My Heading</h1> but MediaWiki goes a couple steps further:
- Automatic Outline Numbered TOC: A great feature of MediaWiki is the ability to take all the headings, assign anchors and create an outline numbered TOC. I find this invaluable for navigating long articles. For example, the TOC on my Installing Typo document lets me quickly nagivate to the section I want, whether it's to reference it or to edit it.
- Edit at Arbitrary Levels: MediaWiki's ability to open up just sections of an article for editing makes it a lot more convenient to update articles if you only want to work on a section. There's no need to scroll through lots of text you aren't interested in modifying. If you choose a heading level with its own sub-headings, they'll be included for editing. This makes editing large articles especially easy.
I'm actually kind of surprised that I haven't seen this feature on other wikis since I find it so useful.
URI Redirects: When you change the name of an article and the URI changes, MediaWiki will automatically add a redirect so sites using the old link will still get the article but be notified that the location has changed. This is very useful if you want to change a URI of an article that's already been indexed or bookmarked by others.
Category Pages: MediaWiki's category pages are useful for scanning articles because they list all the titles in multiple columns with alphabetical headers. Many blogs I've run across don't seem to have effective ways to scan articles by title. The TOC I added to my Typo install is very useful for me but some blogs have many times the articles this one does. I think a MediaWiki style category page would work better for scanning lots of articles quickly. The ability to have sub-categories is also nice.

Typo

Comments: One big feature of blogs that they let people comment on the articles. MediaWiki has a "discussion" section per-page but that's really just another wiki page, not a chronological list of comments identified by author. Some sites have links to forums and other software but it's nice to have the comments right on the page. Most blogs don't get too many comments per article but for blogs that do, say Tim O'Reilly's blog or the RoR blog, it'd be nice to have threaded, scored comments like on Digg or Slashdot. Howeve,r for my purposes, having comments is a lot better than no comments.
Dynamic Sidebars for Catgories and Tags: Typo sidebars for categories and tags are plugins that make database queries and retrieve the number of articles per group. This means that new categories/tags are automatically added to the list and it's pretty easy to sort the items by different criteria. To add custom items in the nav bar for MediaWiki, you have to create two MediaWiki entries per link and then reference them in LocalSettings.php config file, and you still don't get number of articles per group. Getting the number of articles and even listing all the groups in the nav bar probably doesn't make sense for Wikipedia but it could be nice on smaller wikis. Perhaps it can be done with a custom include. MediaWiki seems harder to browse and the Wikipedia portal pages seem a bit cumbersome to make. Something optimized for smaller sites would be useful

I don't mind hacking software but I'm not crazy about either adding heading-based articles to Typo or adding comments to MediaWiki. That being said, adding MediaWiki formatting to Typo seems to be better than adding comments to MediaWiki. The cleanest way would be to port the formatting code to Ruby and create a Wikimedia text filter. The other features should be easier to add.

Upgrading Typo 4.0.0 to Rails 1.1.5/1.1.6

John Wang — Thu, 10 Aug 2006 01:14:00 -0500

It was recently announced that Rails 1.1.0, 1.1.1, 1.1.2, and 1.1.4. have a very serious security hole. Although the RoR blog hasn't discussed exactly what the hole is, it has been rumored to involve uploading of .rb files to execute arbitrary code on the server (UPDATE: now confirmed). Typo only allows file uploads by administrators so certain applications may be somewhat safer. (UPDATE: Running arbitrary code was fixed in 1.1.5 however you could still crash it. 1.1.6 has been released to fix these lingering bugs. Just change 1.1.5 to 1.1.6 below).

Scott Laird is working on releasing Typo 4.0.1 (now released) which will include Rails 1.1.5 but until then, or if you don't want to upgrade Typo, you can simply upgrade the Rails used by Typo by installing the 1.1.5 vendor/rails directory over the existing one. Here are some steps:

$ cd /tmp
$ wget http://rubyforge.org/frs/download.php/12258/rails-1.1.5.tgz
$ tar -zxf rails-1.1.5.tgz
$ cd rails/vendor
$ tar -zcf rails-1.1.5-vendor-rails.tgz rails
$ mv rails-1.1.5-vendor-rails.tgz /path/to/typo/vendor
$ cd /path/to/typo/vendor
$ tar -zxf rails-1.1.5-vendor-rails.tgz

To verify that Rails has been updated you can view the version.rb file which should now give you the following:

$ cat rails/railties/lib/rails/version.rb
module Rails
  module VERSION #:nodoc:
    MAJOR = 1
    MINOR = 1
    TINY  = 5

    STRING = [MAJOR, MINOR, TINY].join('.')
  end
end

You'll probably want to back up the existing vendor/rails directory as this will extract the 1.1.5 files over it. If you simply swap vendor directories, you'll get a lot of missing requirements errors (e.g. redcloth, bluecloth, rubypants, uuidtools, etc.) because rails isn't the only thing installed under vendor for Typo.

Typo Upgrade: 2.6.0 to 4.0.0 r1188

John Wang — Wed, 02 Aug 2006 18:32:00 -0500

I finally got around to upgrading Typo here to the latest trunk. At first I was waiting to upgrade to 4.0.0 (officially r1161) but decided to move to SVN after hearing about some post-r1161 bugfixes and it seems like a fairly common practice to run off SVN, at least for Typo. I've hacked a few changes onto 2.6.0 and had to manually merge the mods to r1181. Merging one's own mods to the trunk was discussed today on the Typo mailing list under the heading "Version Controling Modifications" and most of the respondents have their own mods and use Chia-Liang Kao's SVK to keep their mods synced with the trunk. Scott Laird has a number of articles on using SVK with Typo's repo. Seems like running off of the trunk with SVK may be a best practice for Typo installations.

Hopefully I'll be on SVK for my next upgrade since I had to manually update the following files this time around:

app/controllers/articles_controller.rb
app/helpers/application_helper.rb
app/helpers/articles_helper.rb
app/views/articles/_article.rhtml
app/views/articles/_articles_toc.rhtml
app/views/articles/index.rhtml
app/views/articles/read.rhtml
components/plugins/sidebars/category/content.rhtml
components/plugins/sidebars/xml/content.rhtml
config/routes.rb
themes/azure/layouts/default.rhtml

I've moved all my Azure theme changes to a custom theme so the changes are easier to keep track of and don't interfere with the base Azure theme.

I've updated my Installing Typo article to cover SVN checkout, Feedburner customization and rake migrate. The Typo TOC How-to has also been updated for 4.0.0.

While code diving, I was happy to see lots of refactoring though the code is still pretty easy to follow and modify. Hopefully soon I'll be back to hacking more enhancements. I'm particularly interested in extending the sidebar functionality so groups of plugins can be positioned in multiple locations on the page, e.g. a 3-col layout.

Upgrade Gotchas

UPDATE: this section on Feed URIs seems to be inaccurate because I chose to use my old 2.6.0 routes.rb file. I didn't think the feed URIs would change. New approach: don't assume anything has stayed the same and move to svk.
Feed URIs: Typo 4.0.0 changes the feed URIs from 2.6.0 so if you have these URIs registered somewhere, e.g. Feedburner or LiveJournal, you'll need to upgrade your URIs. The new URI styles are:
- http://www.dev411.com/blog/xml/feed/feed.xml?type=feed&format=atom
- http://www.dev411.com/blog/xml/feed/feed.xml?type=feed&format=rss20
For comparison, the 2.6.0 style is:
- http://www.dev411.com/blog/xml/rss/feed.xml
Everytime this URI changes I need to file a support ticket at LiveJournal whereas on Feedburner I can change the URI myself. I've been wondering if I should just have LiveJournal use the Feedburner URI ;)
Categories sidebar no longer alphabetized: My categories list was no longer alphabetized so I edited the components/plugins/sidebars/category/content.rhtml page from:
```
<% for category in @categories -%>
```
to
```
<% for category in @categories.sort {|a,b| a.name <=> b.name} -%>
```
config no longer used in ArticlesController: If you used config, the code needs to be changed like this example:
```
config[:blog_name]
```
to
```
this_blog.blog_name
```

Mongrel and non-root URIs

John Wang — Sun, 23 Jul 2006 12:59:00 -0500

Two weeks ago, Scott Laird posted a Mongrel patch to the Typo list to make it work with non-root URIs. I'm particularly interested in this because Mongrel is getting more mindshare and my blog uses a non-root URI. The patch has been submitted to Zed Shaw for inclusion but, until it's in, here are some links since I don't think this is easy to find:

UPDATE: This is now included in Mongrel 0.3.13.4 pre-release.