Changeblog - Blueprint

Spiders and robots

2009-03-26T14:34:36Z

A couple of new, related features for Blueprint sites.

Firstly, you can define rules that prevent search engine spiders and other robots from accessing various parts of your site. Why would you do this? Really just to improve the efficiency of your site, and the relevance of the site content that search engines are storing. For instance, you don't want search engine spiders adding stuff to their personal shopping basket.

Most big sites provide some degree of direction to search engines as to what should be indexed, using the robots.txt standard — here, for instance, is Google's robots.txt file.

Blueprint gives you an easy way to define the robots.txt rules for a site. In lib/rules.rb, use the robots_disallow method to deny specific robots access to specific resources. Here's some examples:

# No robot should access the individual images for the gallery.
robot_disallow '*' => '/gallery/image'

# ...except Google.
robot_disallow 'Google' => ''

# The Yahoo robot shouldn't be allowed to see the Foo or Bar top-level pages.
robot_disallow 'Yahoo' => ['/foo', '/bar', 'add_to_basket']

Custom blueprints can define their own robots rules, which apply to any site that employs them. The SHP blueprint already uses this to explicitly deny access to its various basket-related actions.

Concomitant with this change is Blueprint's very own spider. You can use this to test that all internal links on your site are working. It flags any HTTP status code above 399 (eg, 404, 411, 500, etc), and any ingredient errors. Here's an example:

$ rake site:spider domain=inventivelabs.com.au
SPIDERING [inventivelabs.com.au]
[200] http://inventivelabs.com.au/ -- 1.782209s
[200] http://inventivelabs.com.au/weblog/post/peeking-at-previews-in-blueprint -- 1.422189s
[200] http://inventivelabs.com.au/weblog/post/not-bad-for-a-one-year-old -- 0.967232s
[200] http://inventivelabs.com.au/weblog/post/5-minute-redesign-ebay -- 0.825736s
[200] http://inventivelabs.com.au/weblog/post/using-blueprint-as-a-drafting-tool -- 0.973908s
[200] http://inventivelabs.com.au/weblog/post/a-bloggie-for-ms-fits -- 0.825474s
[200] http://inventivelabs.com.au/weblog/post/harry-we-are-here-to-help -- 0.801349s
[200] http://inventivelabs.com.au/weblog/post/eight-days-at-the-labs -- 0.988544s
[200] http://inventivelabs.com.au/weblog/post/the-other-things -- 1.06554s
[200] http://inventivelabs.com.au/weblog/post/migrating-from-lighthouse-to-redmine -- 1.221826s
[200] http://inventivelabs.com.au/weblog -- 0.927285s
[200] http://inventivelabs.com.au/weblog/post/harry-we-are-here-to-help#comments -- 1.06135s
[200] http://inventivelabs.com.au/the-way-we-work -- 3.964896s
[200] http://inventivelabs.com.au/about-the-labs -- 2.099506s
[200] http://inventivelabs.com.au/blueprint -- 0.838506s
[200] http://inventivelabs.com.au/blueprint/screencast -- 0.655021s
[200] http://inventivelabs.com.au/portfolio -- 2.039005s
[200] http://inventivelabs.com.au/portfolio/project/resicon -- 0.860806s
[200] http://inventivelabs.com.au/portfolio/project/rmit-sro-database -- 0.747917s
[200] http://inventivelabs.com.au/portfolio/project/big-and-little-films -- 0.856033s
[200] http://inventivelabs.com.au/portfolio/project/australians-all -- 0.920293s
[200] http://inventivelabs.com.au/portfolio/project/cyclopharm -- 0.860129s
[200] http://inventivelabs.com.au/portfolio/project/shane-maloney -- 0.921109s
[200] http://inventivelabs.com.au/portfolio/project/register-of-urban-design-practices -- 0.923032s
[200] http://inventivelabs.com.au/portfolio/project/scribe-website-and-business-system -- 0.98052s
[200] http://inventivelabs.com.au/portfolio/project/iaia-reference-finder -- 0.921664s
[200] http://inventivelabs.com.au/portfolio/project/unico -- 0.922174s
[200] http://inventivelabs.com.au/portfolio/project/mcculloch-mcculloch-website -- 0.737803s
[200] http://inventivelabs.com.au/portfolio/project/readings -- 1.003813s
[200] http://inventivelabs.com.au/portfolio/project/plans-at-work-software-and-website -- 0.760026s
[200] http://inventivelabs.com.au/portfolio/project/back-to-back-theatre-website -- 1.073601s
[200] http://inventivelabs.com.au/portfolio/project/text-publishing-website -- 0.73745s
[200] http://inventivelabs.com.au/static/dark.css -- 1.054769s
[200] http://inventivelabs.com.au/static/style.css -- 0.993249s
[200] http://inventivelabs.com.au/static/images/apple-touch-icon.png -- 2.546059s
[200] http://inventivelabs.com.au/static/images/favicon.ico -- 0.519485s
[200] http://inventivelabs.com.au/static/files/assets/32bfd614/lighthouse_import.rake -- 1.212854s
[200] http://inventivelabs.com.au/weblog/post/the-writing-s-on-the-magnetic-wall -- 5.4549s
[200] http://inventivelabs.com.au/blueprint/ -- 1.267579s

You've got a few different ways to invoke the spider; to see them all, run:

$ rake -Tspider

It's pretty basic right now, but we'll be adding features to it over time.

Site helper methods

2009-03-13T17:35:21Z

A helper method is a method that is available to any of your templates, and outputs a string (normally of HTML).

You can now define helper methods for particular sites. Just edit lib/site_helper.rb and write your own methods. This change should reduce some of the current reliance on ingredients. Remember that ingredients are still good for HTML-heavy snippets, but helper methods are probably better for logic-intensive stuff.

See the comments of the default site_helper.rb for more info.

Rewriting URLs

2009-03-13T17:31:57Z

You can now define regular expressions for redirecting certain URLs to other URLs. This has been possible with the 'URL Rewrites' sidebar box in the Settings tab, but it was always a bit hit and miss, and only invoked when Blueprint would ordinarily return a 404 response.

Now URL rewriting (or 301 redirecting, more precisely) occurs when much earlier in route recognition, before page slugs are checked. So you can override page slugs to point particular URLs elsewhere. 'Elsewhere' can be some other URL on the same site, a subdomain, or anywhere on the web.

To set up a URL rewrite, add it to lib/rules.rb in your site directory:

rewrite /^\/artists\/\d+-(.*)$/ => '/artists/\1'

See the default rules.rb file for additional details.

How hidden pages work

2009-03-13T17:05:43Z

In the latest Blueprint trunk, the behaviour of hidden pages has been subtly but significantly changed.

How they used to work

It used to be that if a page was hidden, then all of its descendents were hidden too. There was no way to view the default action (typically index) on these pages. They did not show up in site navigation.

You could still view any other action on a hidden page by explicitly specifying an action in the URL. This was useful for search pages primarily, where the search page was hidden, but you could still view results, tag results and tag clouds.

In general however, hidden pages were designed for ingredients -- you could specify the page slug of a hidden page in the ingredient call and get to one of its actions by that means.

How they work now

Pages now have a 'visibility' setting, which is one of:

inherited
visible
hidden

The default is 'inherited'. When a page has a visibility of 'inherited', it takes the visibility of its parent page. Top-level pages with 'inherited' visibility are regarded as 'visible'. So the default behaviour is unchanged -- if you set a page to be hidden, by default all of its children will be hidden too.

But now you can explicitly set a child (or grandchild, etc) of a hidden page to be 'visible'. All of its actions (including its default action) are accessible via its URL.

Because of the way the render_in_hierarchy template helper works, these children of hidden pages will not show up in the navigation elements that use this helper. But you can iterate over and link to visible children of hidden pages. And if you start the render_in_hierarchy helper with those children, it'll work just fine too.

This should be a much more intuitive method of working with hidden pages, and makes things like footers and selective navigation much easier.

But note that you will no longer be able to access any actions of a hidden page, even by putting them in the URL, unless the page is defined to permit that action. At present, only the Search blueprint allows this, and only on the results, tag and tag_cloud actions. I'm pretty sure no-one's using this removed feature for any other purpose, but sing out if you are.

Ingredient API changes

2009-03-13T16:44:50Z

There have been a few changes under the hood for ingredients recently. All the changes are designed to be backwards-compatible, but there are some neat new aspects to them, and the old way of including them is now deprecated.

Because page ingredients (where you're referring to an action on a particular page) are more involved than site ingredients (where you just drop a template from the ingredients directory into your code), we've split them up into separate calls: page_ingredient and site_ingredient.

Using the old ingredient method continues to work (and will probably never stop working), but we recommend that you move to this new API -- if for now other reason than to make it clear in your head what you are doing with an ingredient.

A bonus: you can now pass local variables into page ingredients, which was not possible before.

There's much more detail on how ingredients now work in the documentation.

The Design tab

2009-01-16T15:40:16Z

Blueprint's Design tab in the Admin area has finally been overhauled. Now you can edit any file in the site directory, create new templates/layouts/stylesheets/javascripts and upload images. You can even delete unneeded files. It's really very simple, but powerful enough to build a site without leaving the browser.

Here's a screenshot:

Also new: you can now have multiple layouts for a single site. Just create your additional layouts in the site directory, named something like: raw.layout.html.erb. This will make the raw layout available for your pages in the Structure tab — to wit:

Naturally, if you only have the default layout, this dropdown is not visible on the Structure tab.

Blueprint has an installer

2009-01-07T13:24:15Z

As of last night, Blueprint has an installer. This means that once you've checked out the Blueprint code from our repository, you can run:

ruby script/install

This will fetch all required gems, then pop open the install wizard in your web browser. The screencast below demonstrates how to go from a fresh Blueprint checkout to a website in under two minutes:

Of course, you only have to do this once on your development machine, and then you can create as many sites as you like. It's really easy to reconfigure Blueprint at a later stage, too.

Login is required for staged sites

2008-12-18T16:25:03Z

In a recent commit, we made it mandatory for anyone accessing the public part of a site on the staging server to log in. Previously you only had to log in to access the admin area of a staged site.

This change is for you and your clients' benefit: it protects the public site from prying eyes — search engines, spammers, lucky guessers — while you prepare the design and content for launch.

However, this does mean that you'll need to create a user account for anyone who you want to view the site. If they shouldn't have access to the admin area, we advise that you create a special role — say 'Observer'? — that has no ticked capabilities, and assign it to these users. Simple.

The other implication of this change is that staged sites are no longer aggressively cached as they are in production, so they'll be marginally slower as a result. Don't worry, it'll all be zippy when you go live.

Windows support

2008-12-18T16:16:33Z

Microsoft Windows is now a supported Blueprint development platform. Instructions for installing and configuring Blueprint are in the Documentation section of this site: Your Computer (Windows).

On a tangential note, as of today you can add notes to most pages in the Documentation section — advice and tips for yourself and other users of this site. Please feel free to add to everyone's Blueprint documentation!

Expiring caches with the passage of time

2008-11-25T16:31:35Z

Until now, if you created a blog post in a Blueprint site and set it to publish in three days, it would not appear on the site automatically in three days. Instead, it would appear whenever any site data changed after that three days had elapsed (ie, when the site cache was purged).

With active sites, this has never really mattered — purges occur frequently enough that the cached pages stay fresh. With less frequently updated sites however, pages can get really stale.

I've just introduced an additional task to the Blueprint itinerary which purges the cache of any site that has one or more items being published that day. This resolves that problem.

There are a few other dates and times stored in the various blueprints that might affect the content of the site as they pass. The start_date and end_date of an Event, for instance, or the available_date of a Product.

You can flag these cache-sensitive dates in the blueprint_model declaration for the model — here's what it might look like for EvtEvent:

blueprint_model(
  :cache_sensitive => [:start_date, :end_date],
)

For any specified date, just after midnight on that date the site cache will be purged.

For any specified datetime, the site cache will be purged just after the midnight following that moment in time.

Per-page editing permissions

2008-11-21T11:44:53Z

Just introduced to Blueprint is the new per-page permissions feature. From the Structure tab, you can now assign an access role to each page.

Once assigned, only users belonging to that role — or to any role that allows editing pages from the Structure tab — may edit that page via the Content tab. This include creating posts, configuring the page, et cetera.

Users who don't have permission to edit a page will see it greyed out, with a lock icon replacing the normal page icon, in the Content tab.

You can svn up and rake db:migrate to start using this new feature.

Tools for optimising your templates

2008-11-11T10:06:38Z

I've just checked in a couple of new methods that might help you figure out the bottlenecks that are slowing down the rendering of your templates.

They are:

bench_marker — takes a "label" argument describing this point in the code. In the log, displays the time since the start of the request that this point was reached.
bench_measure — takes a "label" argument and block of code. Surrounds the block with bench_marker logging.

You can pass a few flags to bench_measure — :skip, which does not execute the block at all, and :echo, which returns the string result of the block rather than concatenating it to the template output (and is therefore only really useful in helpers).

bench_marker takes a hash of options, although only one option is currently checked — :prefix, which lets you change the text that precedes the timestamp in the logs.

Note: like most logging, benchmarking only displays in development logs.

Capistrano for remotely manipulating sites and blueprints

2008-08-07T11:27:18Z

There's a bunch of existing rake tasks for operating on blueprints and sites -- pushing and pulling data, syncing templates, installing blueprints and sites, erasing blueprints and sites, et cetera.

For the last few months, to perform these operations on remote servers (production or staging), you've had to log into the server as the deploy user, and run the rake task with the correct environment argument.

Now there are Capistrano tasks that allow you to do these things on remote servers from the comfort of your local command-line. Here's the current list of available tasks -- run cap -T for an official list.

cap site:data:pull       
cap site:data:push       
cap site:list            
cap site:retrieve        
cap site:templates:update

cap blueprint:install    
cap blueprint:migrate    
cap blueprint:uninstall  
cap blueprint:upgrade:all

Each cap task takes the same arguments as its rake equivalent. Assuming you have set up your config/hosts.yml file correctly, you can invoke them like this:

$ cap site:data:push domain=foo.org rails_env=staging

The rails_env determines which hosts the action is performed on. To save typing, you might want to set up the following bash aliases:

alias pcap='RAILS_ENV=production cap'
alias scap='RAILS_ENV=staging cap'

Then you can run the same command more succinctly:

$ scap site:data:push domain=foo.org

Rake tasks for creating new blueprint modules

2008-08-07T11:01:21Z

Until recently, you used the script/generate task to create new blueprint modules. Now that blueprints are stored in a separate repository, however, this approach has been deprecated in favour of a rake task that not only generates the requisite files and directories, but imports them into your blueprint repository, and checks them out for you.

You can learn about the rake tasks using the -D describe switch:

$ rake -D blueprint:create
rake blueprint:create
    Generate a new blueprint, checking it into a blueprint repository. 
        Arguments:
          CODE    - the blueprint code for the new blueprint
          ACTIONS - string list of actions (white-space separated) for which to
                    create templates and controller actions.

rake blueprint:create:inherit
    Generate a new blueprint inheriting from an existing blueprint, checking 
          it into the selected repository. Arguments:
            CODE    - the blueprint code for the child blueprint
            PARENT  - the blueprint code for the parent blueprint

So, for example, to create a 'Directory' blueprint:

rake blueprint:create CODE=dir ACTIONS="index list item alphabetical by_publication_date"

Or to extend the existing 'Gallery' blueprint to handle videos:

rake blueprint:create:inherit PARENT=gly CODE=vidgly

The hosts.yml file

2008-08-07T10:54:15Z

This is a fairly major change, and requires some explanation.

As Blueprint is now being used by developers other than Inventive Labs, anyone might potentially want to create custom blueprint modules. Previously these were all in the core Blueprint repository; this update has moved them into separate repositories. The 'Page' and 'Search' blueprint modules are the only ones that come with Blueprint core. The rest of the core modules have been moved to http://canister.inventivelabs.com.au/blueprints/core.

You can add your own repository for custom blueprints. The mechanism for this is the new config/hosts.yml file, which replaces Rails' built-in database.yml file. You'll need to create this file -- you can base it off the hosts.sample.yml file in the same directory. Define your site and blueprint repositories (you should probably retain the 'core' blueprints repository), and set up your databases as you previously did for databases.yml.

Once this is done, you need to follow a one-off upgrade path:

rm -rf app
svn up
rake blueprint:upgrade:all

One of the benefits of this change is that you no longer need to enter the 'Repository root' for a site when running rake site:retrieve.

Asset captions

2008-07-15T10:39:45Z

The 'Bluedown' text formatter has had an upgrade, providing marked-up caption text for images inserted into text fields.

As you know, you can insert an image into text with the following syntax:

[[example]]

Which results in markup like this:

<img alt="Example" src="http://blueprint.inventivelabs.com.au:80/static/files/assets/4068c115/example.jpg" title="Example" />

There are a bunch of options you can add to the asset tag, such as:

[[example|class=left,size=thumb]]

Which modify the resultant HTML in certain ways:

<img alt="Example" class="left" src="http://blueprint.inventivelabs.com.au:80/static/files/assets/4068c115/example_thumb.jpg" title="Example" />

Just added is the ability to do captions, by attaching parenthesised text to the end of the asset tag:

[[example]](This is a free markdown area, until the next closing parenthesis not 
preceded by a backslash. So this won't close the caption: \) but this *will*: )

Which gives markup like the following:

<div class="captioned">
  <img alt="Example" src="http://blueprint.inventivelabs.com.au:80/static/files/assets/4068c115/example.jpg" title="Example" />
  <blockquote><p>This is a free markdown area, until the next closing parenthesis not 
  preceded by a backslash. So this won't close the caption: ) but this <em>will</em>: </p></blockquote>
</div>

That is, the image tag is enclosed in a div tag with the class captioned, which also contains a blockquote containing the marked-up caption text. You can then style this however you like with CSS.