Software Development
Balagan Web Construction Blog

Managing versions of Ruby, Rails and Gems

02 Jun 2010 at 11:09

Macs now come with Ruby on Rails installed, which is nice, yet I wanted to try out Rails 3 without changing what Apple had given me. Luckily there are now tools to make this really easy - enter RVM and Bundler.

I got a Mac

02 Jun 2010 at 10:53

Ruby on Rails on Windows is possible but not particularly fun. Most of the supporting documentation is for OS X and/or Linux and things that work on OS X / Linux don't necessarily work on Windows.

Like others before me I gave up and got a Mac - a MacBook Pro with Snow Leopard (OS 10.6) to be precise. So I thought I'd write up some of the things I did to get set Ruby on Rails set up.

Ah, you say, but Ruby and Ruby on Rails come pre-installed on Snow Leopard so no set up required. Well, that is true but I still found some things to do. Read on.

Foreigner Ruby Gem / Plugin

02 Jun 2010 at 10:47

Rails supports relationships between entities in the models, including handling any foreign key constraints. That means that most Rails people don't seem to worry about including foreign key constraints in their database scheme. For the moment at least I can't put aside all those database lessons at university and feel I should address foreign key constraints in the database as well as the model.

It seems a chap called Matt Huggins agrees with me. He has just release a plugin / gem for this purpose: Matt Huggins: Foreigner. It is a gem for Rails 3 and a plugin for earlier versions of Rails.

Using it is trivial and it copes with the fact that SQLITE3 doesn't support foreign key constraints.

Scale and Performance

13 May 2010 at 11:37

I work at the BBC and scale and performance is a big deal. One day Mark Gledhill and I talk through what we do to achieve this scale and performance. It isn't rocket science; just good common sense. The general message is to avoid unnecessary repetition but there are lots of specific areas that are worth exploring.

More on my Tour of altered_beast

23 Mar 2010 at 16:42

I've been poking around in altered_beast a bit more and written up: 

Ruby on Rails

03 Mar 2010 at 22:00

I've started looking at Ruby on Rails again and this time I'm writing up my notes as I go. So far that means::

Datetime Design Pattern

18 Feb 2010 at 23:21

My attempt to Generate an Atom/RSS from hatom for a blog worked but not perfectly. The transformation service wasn't picking up the publish time. I had the time as a Value Class Pattern but I think need to include the machine readable time in the Datetime Design Pattern as well. So the "published" clause becomes something like this:

<span class="published"> 
  <span class="value-title" title="2010-02-08T19:38">08 Feb 2010</span>
  at <span class="value">19:38</span>
</span>

Notice the "T19:38" - this is the machine readable time element.

Unfortunately I started getting an XML error at the same time.  Back to the drawing board.

FavIcon: Displaying my web site logo

30 Jan 2010 at 12:03

OK, I want to display my own icon on the address bar and in the favourites list. Wikipedia: Favicon explains the background and Chami.com Tips: How to display your web site logo has a mechanism to generate a FavIcon.ico from an image, which for me is perfect. The simplest method is to put an icon file called favicon.ico in the root directory of the website.

The "proper" way of doing it is to add some tags to the <HEAD> section. I'll only bother doing this if the simple method doesn't seem to work. You need two tags as shown below.  The top one is for IE and the bottom one for everything else.

<HEAD>
  ...
  <link rel="SHORTCUT ICON" href="http://balagan.org.uk/images/logo.ico"> 
  <link rel="icon" type="image/vnd.microsoft.icon" href="http://balagan.org.uk/images/logo.ico"> 
  ...
</HEAD> 

Generating Atom/RSS from hatom for a blog

29 Jan 2010 at 22:13

The whole point of using the hAtom microformat for Blog Entries was so that I could easily produce an Atom/RSS feed.   There is no need to create or maintain a separate Atom or RSS XML files for syndication. Using hAtom and one of the several transformers on the web means I can get the syndication XML is automatically generated.

All I had to do is link to add the URL of my hAtom formatted blog (i.e. http://www.balagan.org.uk/software-development/blog/blog.htm) after the URL of one of the transformers (http://transformr.co.uk/hatom/). The result is something like this although I've had to split it over two lines to fit the page width.

<a href="http://transformr.co.uk/hatom/
  http://www.balagan.org.uk/software-development/blog/blog.htm">RSS Feed</a>

It is still not perfect as the time stamps are not showing up on the RSS Feed.

?? TODO ?? Get the timestamps

Published at last

02 Dec 2009 at 22:04

It has taken just under five months but I finally published today. There is still a lot to do but it was good enough to go live. It turns out there are over 890 pages on the site and I ended up having to hand finish each one. That means there are bound to be problems with at least some of them. If you spot any problems please let me know.

hAtom microformat for Blog Entries

08 Oct 2009

The hAtom microformat highlights semantic information in weblog posts and news articles. The idea is that feed readers will then be able to automatically read the source page rather than requiring a separate Atom, JSON, or RSS file. hAtom content is easily added to most blogs by simple modifications to the blog's template definitions. Essentially that means adding class definitions to key tags.

I found A Blog Not Limited: Getting Semantic with microformats part 5 hatom very handy when trying to figure out hAtom. It is very clear and has good examples.

I marked the content area of the page as a feed. In my case this is the "content" <div>. This step is optional - if it is missing the page is assumed - but I included it for completeness and also to exclude all the extraneous elements of the page such as the sidebar.

<div id="content" class="hfeed">      

Each entry in the blog has to comply with the hAtom microformat but this is pretty easy since the standard is very flexible.  I chose a format that seems simple and clean:

<div class="hentry entry" id="post-YYYY-MM-DD-HHMM">
  <h2 class="entry-title">title</h2>
  <span class="published"> 
    <span class="value-title" title="YYYY-MM-DD"DD MMM YYYY></span>
    at <span class="value">HH:MM</span>
  </span>
  <div class="entry-content">
    <p>Content</p>
  </div> 
</div      

Every hentry needs a bookmark/permalink although you don't have to give one explicitly.  Implicit bookmarks are formed from the URL of the page with the the id attribute of the hentry appended. And that explains why I've got in id for each hentry. It has to be unique and I've chosen to use the date in YYYY-MM-DD format as the basis of this id. If I get carried away and do more than one post on a particular day I can add an extra time element to the id to make it unique (HHMM). The hentry div for this post is: 

<div class="hentry entry" id="post-2009-10-09">

hAtom microformat talks about the datetime-design-pattern for publication and update dates but I've followed A Blog Not Limited: Getting Semantic with microformats part 8 value class pattern.  This uses a "value-title" <span> with the "title" element being machine readable and the value, i.e. content, being for the user to read.  I've opted not to have a time element nor an updated property.

<span class="published"> 
  <span class="value-title" title="2009-10-20">20 Oct 2009></span>
</span> 

Each hentry needs an author however if there is none the author of the page is assumed.  The author sub-property must also be marked up using the hCard microformat applied to an <address> element (A Blog Not Limited: Getting Semantic with microformats part 3 hcard). The <address> tag defines the contact information for the author or owner of a document (W3 Schools: address tag). In all browsers, the content of the address element renders in italic. Most browsers will also add a line break before and after the address element. Because I write all my posts I'll put this in the footer of the DWT so it appears in all pages. 

<address class="author"> 
  <a class="fn email" href="mailto:name@company.com">Full Name</a>
</address> 

The "fn" class name is short for full name. The full name must be two "words" separated by whitespace.

TODO: Sort out Author
TODO: Generating Atom/RSS from hatom for blog

Print CSS

04 Oct 2009

OK so I've spent a lot of time on my CSS for the screen but now I need to print something ... so what to do? Advice I'd read on the web suggested having a completely separate set off CSS files for printing. I started down this track but quickly realised the majority of the CSS was the same as for the screen. So I've ended up importing the screen CSS into the print file and then overriding anything that was inappropriate, such as the header and sidebar.

This line has to go into the DWT:

<link href="styles/print.css" media="print" rel="stylesheet" type="text/css" />

And this into the top of the print.css file (bear in mind that I have a sub-folder for all my "screen" CSS files).

@import url('screen/style.css');

A Regular Expression Killed my Site

07 Sep 2009

Regular expressions are great but are also very dangerous particularly if applying to multiple files in Expressio Web - you can't undo this operation. Today I was trying to strip out nasty microsoft formatting code from my tables. Unfortunately I forgot to adequately test the regular expression before applying it across the site. This mistake destroyed all my tables. The regular expression that killed my site was:

<tr{(.|\n)#> 

It should have been:

<tr{(.|\n)@> 

The difference is that the second one can cope with a simple <tr> tag whereas the first one groups that tag and everything through to the next >.  Since I was deleting the bit in between I lost whole rows of data. 

Luckily I had a recent backup and only lost a few hours of work.

CSS tables and is everything I know about CSS wrong?

04 Sep 2009

The article Everything you know about CSS is wrong and associated book (Andrew & Yank, 2008) are basically making a plug for CSS tables over techniques involving floats. The argument is pretty compelling except for one thing - IE 7 and less don't support CSS tables but IE6 and IE7 are still dominant in the market, particularly in corporates.  The authors do discuss ways to cater for IE but I didn't find the examples too convincing.  Basically if I was doing a commercial site I would use use floats and avoid CSS tables. 

But this site isn't commercial so I've decided to adopt CSS tables for certain aspects - notably image galleries.  IE8, Firefox, etc will render these as desired.  In IE6 and IE7 they will render as a long column of images - not ideal but I don't have time to offer a better solution to a market that will decline over time. I will retain floats as the basis of the layout for the entire site.

The example markup is for a two by two grid of images (see figures).  The key elements grid, gridrow, and gridcell corresponding to a <table>, <tr> and <td> respectively.  I've left out the markup for the images themselves.

<div class="grid">
  <div class="gridrow">
    <div class="gridcell figure">
      <p class="legend"></p>
    </div>
    <div class="gridcell figure">
      <p class="legend"></p>
    </div>
  </div>
  <div class="gridrow">
    <div class="gridcell figure">
      <p class="legend"></p>
    </div>
    <div class="gridcell figure">
      <p class="legend"></p>
    </div>
  </div>
</div>

The markup has to be supplemented by some CSS.  The elements grid, gridrow, gridcell, and optionally gridcaption all need to be displayed as their table equivalents. This is the CSS I use:

.grid { 
  display: table; 
  table-layout: fixed;
  width: 100%;
  border-spacing: 4px; 
} 
.gridrow { 
  display: table-row; 
} 
.gridcell { 
  display: table-cell; 
  width: auto; 
  border: 0; 
  vertical-align: center; 
  text-align: center; 
} 
.gridcell p { 
  text-align: left;
  margin-top: .2em;
}
.gridcaption {
  display: table-caption;
  caption-side: bottom;
  font-size: smaller;
  text-align: center; 
}

Andrew, R. and Yank, K. (2008). Everything you know about CSS is wrong!. Australia: Sitepoint

CSS and Named Anchors / Bookmarks

02 Sep 2009

When I converted my site I found that I had lots of named anchors / bookmarks which suddenly were being styled as links. An example of such a bookmark is:

<a name="discovery">Discovery</a>

which renders like this:

Discovery

Given it isn't a link, and is just a destination, I don't want it looking like a link. It turns out the answer is terribly simple. Just move text out of the anchor and there is nothing to style.

<a name="discovery"></a>Discovery

which renders as

Discovery  

Obvious really.

What style to use (reprise)

19 Aug 2009

Back on 19 Jul 2009 I decided to use style of Organisation 5 from Expression Webs standard templates. But really it is rather hideous. In trawling around sites on CSS I've found myself drawn to the simpler styles - black text on white, few borders. I've decided to use something based on A List Apart but tweaked to meet my own needs. They use faux columns so I've followed suit. 

CSS Tabs for Timelines and Scenarios

11 Aug 2009

There are a few places on my site where different pages are closely related, notably scenarios and their battle report, plus sequential timelines. A tabbing mechanism seems like a good way to facilitate the user journey between these pages.

I've opted for a simple "active" mechanism to achieve this.  Each of the pages has a "tab_area" <div>.  The current page is set at "active" in the "tab_area" so this can be styled differently. For example:

<div id="tab_area">
  <ul>
    <li><a class="active" href="timeline0711.htm">711-754</a></li>
    <li><a href="timeline0755.htm">755-1007</a></li>
    <li><a href="timeline1008.htm">1008-1085</a></li>
    <li><a href="timeline1086.htm">1086-1249</a></li>
    <li><a href="timeline1250.htm">1250-1492</a></li>
  </ul>
</div>

This needs some CSS to make it work:

#tab_area {
  z-index: 300;
  float: right;
}
#tab_area ul {
  list-style: none;
  margin: 0;
  height: 15px;
  white-space: nowrap;
}
#tab_area ul li {
  float: left;
  margin-right: 7px;
  text-align: center;
  list-style-type: none;
  display: inline;
  overflow: hidden;
}
#tab_area ul li a {
  display: block;
  height: 15px;
  background-color: #fff;
  color: #666;
  font-size: x-small;
  border-left: 1px solid #ccc;
  border-right: 1px solid #ccc;
  border-bottom: 1px solid #ccc;
  text-decoration: none;
}
#tab_area ul li a:hover {
  color: #fff;
  background-color: #7b8614;
}
#tab_area ul li a.active:hover {
  color: #fff;
  background-color: #7b8614;
}
#tab_area ul li a.active {
  background-color: #f2f2f7;
  z-index: 302;
}

This renders as:

Preparing for html5 with Semantic Class Names: Figure and Aside

05 Aug 2009 at 22:00

I've been struggling with what to call my classes related to images and to what a book would call a sidebar.  I want to wrap images in a <div> so I can associate a caption with the image.  A sidebar in a book is a box off to the side - strange that - discussing something indirectly related to the main thread of the narrative.  The trouble is that the web world has taken to calling the columns to the right and left of the main content "sidebars". 

Preparing for HTML5 with Semantic Class Names came to the rescue.  HTML5 is going to call these elements a "figure" and "aside" - good enough for me.

I'll wrap images in a figure class. Legend is the image's caption.  A figure can be centred (the default) or floated right or left.

<div class="figure"> 
  <img ...> 
  <p class="legend">...</p>
</div> 

Similarly an aside <div> can be styled and floated left or right as required.

<div class="aside right">
  ...
</div> 

I've decided to take a wait and see approach to other suggestions regarding HTML5.

How should I structure my CSS?

05 Aug 2009 at 20:00

OK I need some CSS, but what is the best way of organising it?  Based on Business Logs: My 5 CSS Tips I've come up with this scheme.  Essentially I've got different CSS files for different purposes:

  1. layout.css: Body and Box-like elements. Lump all container/layout blocks together (<div>s with an ID of “header”, “footer”, “maincontent”, etc.) at the top. IDs reserved for structural elements that appear only once on the page. Rules like #content, #sidebar, and #footer will go here.
  2. headings.css: H1 through H6
  3. paragraphs.css: includes rules for <p> tags but really it is anything that isn't in the other files, e.g. tables.
  4. navigation.css: links and menus.  In most cases you’ll want to specify them in the order :link :visited :hover :active. Take the initial letter for each state and you get “LVHA”, which can be expanded to “LoVe HAte”

Then I have a master file (style.css) to import them all in the correct order.

@import url('layout.css');
@import url('headings.css');
@import url('paragraphs.css');
@import url('navigation.css');

The Big move

01 Aug 2009

OK, I've been doing research for a few days and it is time for the big hack.  I took a copy of my FrontPage web site.  Ripped out the shared borders and theme. Then imported the site into Expression Web.

I then took advantage of the regular expression facility in Find and Replace to tidy up the HTML source code.

I also added some features.  For example I had been using two part headings like "Crossfire: Frequently Asked Questions".  With a little bit of regular expression and HTML magic this can be split over two lines with the first part as a section title and the second part as the main heading.  The two regular expressions were

Find What: <h1>{.#}\: {.#}</h1>
Replace With: <h1> <span id="sectiontitle"> <a href="#nogo">\1</a> </span> <br />\2</h1>  

CSS Menus

31 Jul 2009

Stu Nicholls has masses of examples of how to create CSS menus at CSSplay: List of Menus. None of them suited me perfectly but I've ended up with a very heavily hacked version of Skeleton 4. I won't list all the changes I've made but key changes were to simply the markup, i.e. take out unnecessary elements, and to support both top and side navigation menus.

Web Design Guidelines

30 Jul 2009 at 20:59

The Web Style Guide has some useful information design guidelines. Every web page needs:

  • An informative title (which also becomes the text of any bookmark to the page)
  • The creator’s identity (author or institution)
  •  A creation or revision date
  • A copyright statement, Creative Commons statement, or other statement of ownership to protect your intellectual property rights
  •  At least one link to a local home page or menu page, in a consistent location on all pages
  • The home page URL

Most web pages should also incorporate these additional elements:

  • An organization logo or name near the upper left corner, with a link back to your home page
  • Navigation links to other major sections of your site
  • At least one heading to identify and clarify the page content
  • Mailing address and contact information or a link to this information
  • Alternate (“alt”) text identifying any graphics on the page

Horizontal centring with with CSS

30 Jul 2009 at 20:20

Some things are really simple ... once you know how.  I learnt from Blue Robot: CSS Centering: Auto-width Margins that the way to get horizontal centering with CSS is to set right and left margin widths to "auto".

#content { margin:0px auto; }

So what is Content Tagging?

28 Jul 2009

Content tagging is a big deal at the moment. Not least because it helps with search engine optimisation (SEO). A tag is a keyword and/or subject that describes the current web page or a significant part of the page.

A Rel-Tag, i.e. rel="tag", is a MicroFormat you add to a hyperlink to indicate the destination is an author-designated tag (MicroFormats: Rel-Tag). For example in the following Rel-Tag the tag is everything after the last slash (/) in the URL, i.e. "spain". Of course the user also sees the word "spain" but that, in a sense, is coincidence.

<a href="http://www.balagan.org.uk/tag/spain" rel="tag">spain</a>

The tag can include a file extension (MicroFormats: [uf-discuss] [rel-tag] File extensions). So in the following Rel-Tag the tag is "spain.htm" not "spain". I'm not sure what the implications of this are. Certainly it is convenient to manage the tag files like normal HTML files but I'm not sure of any downside.

<a href="http://www.balagan.org.uk/tag/spain.htm" rel="tag">spain</a> 
The MicroFormats: Rel-Tag FAQ makes it clear you can include multiple words in a tag but that implementations of this capability vary between sites. Some systems directly support spaces, others strip spaces, and some replace spaces with an underscore. An example where spaces are stripped from the tag would be:
<a href="http://www.balagan.org.uk/tag/militaryhistory" rel="tag">military history</a>

The CSS selector for Rel-Tag is along the lines of:

a[rel~="tag"] { color: green }
I'm a long way from doing any of this so at the moment I'll just put this stuff on the TODO list.

TODO: Define a content tagging strategy
TODO: Tag the pages using the strategy

Ugly HTML? Consider HTML Tidy and HTML Trim

24 July 2009

FrontPage is pretty rough with the HTML and adds a lot of bloat. In FrontPage I rarely looked at the HTML but by moving to Expression Web I'll need to craft the HTML a lot more than. This means the mark up has to be well laid out. Furthermore FrontPage 2000 generates poorly formed markup, for example with missing end tags. I thought an automated tool would help clean it up. I looked at a couple of web based systems like Cool Form: HTML Formatter but given the scale of my problem I needed an application. I next bumped into Logic Hammer: HTML Formatter. You have to pay for it and I regret that I did. My two beefs being that it uses tabbed indentation and wraps end tags onto a new line in all cases including <a> and </a> tags. Not really a style I like. The guys at work use HTML Tidy so I thought I'd have a look. It is free and very good. The markup is clean and you get a lot of configuration options. I'm not really a command line kid of guy so I've opted to use int64: HTML Trim to provide a GUI front end to HTML Tidy.

TODO: Format all HTML

Broken HTML? Validate it

23 Jul 2009

Migrating from FrontPage to Expression Web suggests installing Firefox, the Html Validator extension to Firefox, and Total Validator Advanced Desktop Tool. Html Validator reports errors on the page being viewed in Firefox whereas Total Validator Advanced Desktop Tool is an application that can do whole sites.

TODO: Install Firefox, Html Validator, and Total Validator Advanced Desktop Tool. Done 23 Jul 2009.

Sitemap and Navigation with an Include file

20 Jul 2009

FrontPage Navigation/Link Bars and "Navigation View" have gone from Expression Web as they are proprietary / non-standard. Menus with graphic buttons are out of fashion because they are more complicated to maintain than text based menus. Expression Web and ilk use an include page that holds text links. You can us CSS to get some quite snazzy menu effects.

Have a look at PixelMill: Cannot use FrontPage link bars in Expression Web for how get rid of the Link/Navigation bars in Expression Web.

I did it in FrontPage and slightly differently. In FrontPage because I am trying to do the migration incrementally. I'm trying to do as much as possible in tweak the FrontPage version before taking the relatively risky step of moving to Expression Web. I also want to use the same include page for my site map, top navigation menu, and left navigation menu. And I've got over 8,000 files in my website so I was not going to build the menu by hand. This is what I did:

  1. In FrontPage create (CTRL-N) a new blank navigation page - this is the include file

  2. Save (CTRL-S) this as include_nav.htm

  3. In the same way create a new blank sitemap page called sitemap.htm

  4. Added a FrontPage table of contents to the sitemap page starting at the home page of your site. (Insert | Component | Table of Contents ... )

  5. Save (CTRL-S)

  6. Publish Web...

  7. In a browser surf to this page on the web site

  8. Select the entire tree of links and copy it to the clipboard (CTRL-C)

  9. Back in FrontPage paste (CTRL-V) the tree of links onto include_nav.htm

  10. Tweak the HTML of this page, e.g. remove references to the website itself which I did by doing a find and replace in the HTML

  11. Remove the table of contents from the sitemap page

  12. Put this code into the HTML code where the table of contents had been on the sitemap page. You can either copy (CTRL-C) from here and paste (CTRL-V) or use Insert | File ... and then browse to include_nav.htm and Click OK. Both methods achieve the same result.

<!--webbot bot="Include" U-Include="include_nav.htm" TAG="BODY" -->
  1. Save the page. The include page will be included onto the page with your new text navigation bar in place.

To add, change or remove links you have to edit and save the include page. The changes will flow through to any pages that reference your include page including the sitemap.

TODO: Create site wide navigation file = include_nav.htm. Done 20 Jul 2009.
TODO: Create sitemap using include_nav. Done 20 Jul 2009.
TODO: Replace Shared Borders using DWT
TODO: Use include_nav for left and top navigation

What style and layout to use?

19 Jul 2009

One of the objectives is to improve the visual appeal of the site. The trouble is I'm not a designer. Not even a little bit. So in the absence of a design talent I just picked one of the templates from Expression Web ... I can always change it latter. I browsed around looking for a free template on the web but didn't find one I liked. So I picked Organisation 5 from Expression Webs standard templates.

I did make one change to the template ... I expanded the page width from 750 to 960 pixels. My target market is likely to be 1024 x 768 screens and CameronMoll: Optimal width for 1024px resolution says the optimal page design for that size of screen is 960. There are a couple of reasons for this. Firstly this width allows for scroll bars. Secondly 960 is also divisible by a whole bunch of numbers so, for example, it is easy to get 1, 2, 3, 4, 5 or 6 evenly spaced columns out of this width. The only caveat is that Dibbern & Dibbern: About web page length, web page size say that 720 pixels is the widest that can be printed in portrait; wider than that means printing in landscape. I'll experiment and check this.

TODO: Pick a starting style and layout: Done 19 Jul 2009.
TODO: Check assertion that pages wider than 720 pixels have to print in landscape.

From FrontPage to Expression Web

15 Jul 2009

Despite the fact I've a degree in computer science and manage software development teams for work I'm pretty rubbish at crafting web sites myself. I created this particular site in 2001 using FrontPage 2000. Ever since then I've been stubbornly resisting an upgrade. This is partly financial but mostly because my interest is the raw content not the tool or the aesthetics. But this year (2009) it has become painfully obvious I need to do something. When FrontPage Extensions burped the other day this is what my ISP had to say

We would like to advise you also that you currently have over 8,000 files in your webspace. As FrontPage Extensions can experience an exponential degree of unreliability with sites over 1500-2000 files, we would advise that you consider moving to an alternate publishing solution for better long term stability for publishing your website.

There are many publishing / design programs available online and many will allow you to download a trial version to see if it suits you prior to purchasing.

I found this comment ironic because although I had purchased Expression Web version 1 a couple of years ago for a different project I had never transferred the balagan site from FrontPage because of the site's shear size. 8,000+ files as my ISP pointed out.

This blog is about my journey to upgrade the site to the 21st century. The specific objectives are:

  • Adhere to current web standards
    • Which gives me the option to change editor
  • Improve findability, specifically:
    • Improve Search Engine Optimisation (SEO)
    • At most 3 clicks to find anything
  • Improve visual design