Read more about my piano recording series here.

Related posts:

1. Beethoven – Sonata Op. 27, No. 2 (Moonlight), 2nd movement
2. Beethoven – Sonata Op. 27, No. 2 (Moonlight), 1st movement
3. Chopin – Prelude Op. 28, No. 4 in E minor

Read more about my piano recording series here.

Related posts:

1. Chopin – Nocturne Op. 9, No. 2 in Eb Major
2. Chopin – Mazurka in Ab Major, Op. 24, No. 3
3. Chopin – Nocturne Op. 72, No. 1 in E minor

• Homepage (grab the bookmarklet from there)
• Source code on github

It is said that, for optimum readability, text line length should be around 12 words per line. This allows the eye to easily track from the end of one line to the beginning of the next.

Using Thankful Eyes is better than simply maintaining a minimum font size with your browser settings because doing that increases the size of many elements which usually do not require magnification, such as sidebar text, menu items, small labels, and so on. Thankful Eyes aims to adjust only body text. It’s also better than using browser zoom, because browser zoom also magnifies and distorts images.

Leave feedback here, or come visit me in IRC on the FreeNode network.

No related posts.

Read more about my piano recording series here.

Related posts:

1. Chopin – Nocturne Op. 72, No. 1 in E minor
2. Chopin – Mazurka in Ab Major, Op. 24, No. 3
3. Chopin – Polonaise Op. 40, No. 1 in A Major

Read more about my piano recording series here.

Related posts:

1. Chopin – Nocturne Op. 72, No. 1 in E minor
2. Chopin – Nocturne Op. 9, No. 2 in Eb Major
3. Chopin – Mazurka in Ab Major, Op. 24, No. 3

Read more about my piano recording series here.

Related posts:

1. Chopin – Nocturne Op. 9, No. 2 in Eb Major
2. Chopin – Polonaise Op. 40, No. 1 in A Major
3. Chopin – Nocturne Op. 72, No. 1 in E minor

Read more about my piano recording series here.

Related posts:

1. Chopin – Nocturne Op. 9, No. 2 in Eb Major
2. Chopin – Prelude Op. 28, No. 4 in E minor
3. Chopin – Polonaise Op. 40, No. 1 in A Major

Read more about my piano recording series here.

Related posts:

1. Beethoven – Sonata Op. 27, No. 2 (Moonlight), 1st movement
2. Chopin – Nocturne Op. 9, No. 2 in Eb Major
3. Debussy – Clair de Lune

Read more about my piano recording series here.

Related posts:

1. Beethoven – Sonata Op. 27, No. 2 (Moonlight), 2nd movement
2. Chopin – Nocturne Op. 9, No. 2 in Eb Major
3. Debussy – Clair de Lune

Keying and the input line

The keying system of Diakonos has been refactored. What this means to the end user is the input line now supports the full range of keys. For example, keys like the Home and End keys actually produce multiple characters of input each, and so would not function properly in older versions. They are now are properly supported. As part of this new implementation, the notion of keying modes has been introduced. For now, there are only two hard-coded modes: “edit” and “input”. There is now an mkey configuration directive, used to bind a function to a key chord or sequence under a specific mode. The old directive, key is equivalent to mkey edit, and so acts as a shorthand.

Another nice enhancement to input is the fact that the input line can now scroll left and right, to allow proper editing of long inputs (inputs wider than the screen or terminal).

zsh and bash completion

This version includes in the tarballs files that can be used to provide tab completion for Diakonos under bash and zsh. Of course, all shells already provide tab completion for files and directories, but with the provided files, you can also have completion of session names for use with diakonos -s <session>.

Selection and Find

A new select_wrapping_block function has been added, with a default keychord of Alt-space. This function will select all lines at the current level of indentation (or deeper). That is, you can select the current code block with it. You can press Alt-space additional times to quickly and easily select increasingly shallower parent blocks.

The find functionality of Diakonos has been enhanced: if you perform a search with text selected, the search is restricted to the selected text. Put these two new features together, and you have a way to restrict searches to code blocks — something I find quite cool and useful. Haven’t you ever wanted to know “where else do I reference this variable within this method?” or asked similar questions? Well now you can find out things like this very easily.

Cursor stack

The cursor stack was broken in the last release, but it has been repaired and also enhanced. The cursor stack is now cross-buffer, instead of buffer-specific. This lets you return to logical work areas no matter which buffers they are in. (For those of you that don’t know, the cursor stack is essentially the equivalent of your web browser’s Back and Forward functionality, except within your editor.)

git integration

Diakonos git integration got a big boost recently, by way of a really cool git tool called tig. Of course, tig is neither required for Diakonos operation, nor bundled with Diakonos. However, if you install it, and also install the Diakonos git extension, then you get one-key access (F9) to a slick curses interface to git. If you are a git user, I certainly recommend you take tig for a whirl. With dk-git and tig, we Diakonos users get something comparable to emacs’ magit.

Changelog

The full set of changes is listed in greater detail in the changelog:

• Refactored keying system.
• Introduced keying modes.
• Ruby version now enforced, both at installation and run time.
• Input line can now scroll if input is longer than screen width.
• Added support for session completion in zsh and bash.
• Added select_line.
• Added select_wrapping_block (default key: Alt-space).
• Searching is now restricted to the selected text, if any.
• Added view.non_search_area.format.
• Fixed cursor stack.
• Cursor stack is now global (cross-buffer).
• Simplified switch_to_next_buffer and switch_to_prev_buffer; no more history.
• Added chdir function.
• Various refactorings.
• Various bug fixes.

As usual, report any bugs here, or come visit me in IRC!

No related posts.

This release brings a handful of minor feature enhancements and fixes, but the most important addition is the new extension system.

Diakonos Extensions

Diakonos has been scriptable for many versions now, but with this release I have baked in an official system and structure for extensions. Diakonos dances to the same tune as Ruby, insofar as it exposes pretty much the entire core to any enterprising developer who wants to add new features. Later on, I’ll describe some of the ways a programmer might extend Diakonos, but first, let’s take a look at the Hello World extension that comes with the Diakonos tarball.

The Anatomy of an Extension

Every extension must have an info.yaml file. This YAML file contains lots of information about the extension. Here are the contents of the info.yaml file of the Hello World extension:

name: Hello World
description: An example of a Diakonos extension
author:
    name: Pistos
    email: somebody@example.com
    uri: http://blog.purepistos.net
version: 1.0.0
uris:
    homepage: http://github.com/Pistos/diakonos/tree/master/extensions/dk-hello-world
    repository: git://github.com/Pistos/diakonos.git
licence: MIT
requirements:
    diakonos:
        minimum: 0.8.11
        tested:
            - 0.8.11
    gems:
        # - gemname:
            # minimum: 1.0.0
            # tested:
                # - 1.0.0
                # - 1.1.0
notes: >
    This extension adds a hello_world function to Diakonos.
 
    Pressing Shift-F11 will activate the function.

I think the file contents and format are self-explanatory. The only thing to keep in mind is that the requirements key is required. All other items are optional. The fields are all fully described in Diakonos’ built-in help.

Besides the info.yaml file, an extension can have one or more .conf and .rb files. The .conf files are of the same format as normal Diakonos configuration files. The Ruby (.rb) files are where all the code of the extension is placed.

Here is the code of the Hello World extension:

module Diakonos
  module Functions
    def hello_world
      @current_buffer.paste "Hello, world!"
    end
  end
end

In it, a new function, hello_world, is defined. Obviously, it pastes “Hello, world!” into the current buffer (at the current cursor position).

The Hello World conf file has just this line:

key f23   hello_world

So, once the Hello World extension is loaded, you can press Shift-F11, and you’ll receive the well-known greeting.

Managing Extensions

Extensions are simply self-contained directories of files, and so can be packaged into tarballs, made into git repositories, or whatever strikes your fancy.

To install an extension, just copy or unpack (or even symlink) its directory under ~/.diakonos/extensions/. For example, ~/.diakonos/extensions/dk-hello-world/.

To activate an extension, use the load_extension directive in your Diakonos configuration. For example:

load_extension dk-hello-world

You can see what extensions are loaded and active with the new About page, accessible with default hotkey F11. Any extensions that failed to load will also be listed.

What Extensions Can Do

An extension might do any number of things, like:

• provide a new language definition
• set up an alternative key mapping
• provide an alternative shared or default colour scheme
• share a user’s personal configuration settings
• add new functions to Diakonos, and map them to keys
• provide new status line variables
• install code to run on Diakonos hooks

The range of possibilities is very broad. I have begun filling out source code documentation for Diakonos. I hope to add more and more documentation with each release. The current docs can be accessed at http://purepistos.net/diakonos/rdoc/. As of this writing, it’s quite incomplete, but at least the classes and methods are enumerated. Since this documentation is sparse, don’t be afraid to dive right into the source code. Although I am continually refactoring, and some [very] old code is still hanging around, I think most of the codebase is readable and understandable. Also, of course, you can always come and ask questions in our IRC channel if you need help with writing extensions, or using Diakonos in general.

Example Extensions

A few extensions have already been made to help exemplify the new extension system. Check out their source to learn more about extending Diakonos.

• Hello World – A minimal example extension
• git – A git extension
• Selector – An extension for CSS/XPath selecting on the current HTML/XML buffer
• Comment Toggle – Smart (un)commenting for Diakonos

Release Changelog

Here is the detailed changelog for this release:

• Added join_lines_upward (Alt-Shift-J).
• Added one-key selection in buffer list.
• Added support for single line indentation.
• Added extension system.
• Added surround_selection and related functions.
• Added “about” page.
• Various bug fixes and refactorings.

Report any bugs here, or come visit me in IRC!

No related posts.

With this release, I’d like to welcome Dominik Honnef (dominikh) to the Diakonos development team. He has already made several contributions, including some fixes which were cherry-picked from the master development branch and included in this version. His other contributions to date will be seen in the next version (0.8.11), and I think we can expect more from him in future versions.

Starting with this version, Ruby 1.8 support is officially dropped. Diakonos will now only run on Ruby 1.9. There’s no need to rush the upgrade on your systems; it is quite possible to have both 1.8 and 1.9 installed on the same system. Search the web for how to do this.

go_to_char (Alt-N) and go_to_char_previous (Alt-P) have been added. These let you move the cursor directly to a specific nearby character.

The shell command has been adjusted a little, so that the results buffer is no longer cluttered with the command that was run.

The way you activate Klipper synchronization has been centralized and simplified. You now simply set “clipboard.external klipper”, instead of setting each clipboard-related key mapping. Along with this change, xclip support was added. This will let non-KDE users synchronize their X clipboard with Diakonos.

Sessions have been improved a bit: Cursor position is now saved, and Diakonos also remembers which was the current buffer when restoring a session.

Basic pair highlighting and jumping was added. Matching brackets are now highlighted, and you can press Alt-{ to jump to a match.

Dynamic prefix expansion was added. With this feature, you can complete long words — good for those of us who don’t like to type a lot. Type the beginning of a long variable name, or such, then press Alt-E. Diakonos will complete the word using a word found in the open buffers (the most frequently used one). Press Alt-E more times to cycle through all the matches. Here is a screencast which shows this feature in action:

Here is the full changelog for this version:

• Ruby version 1.9+ now required. (Ruby 1.8 support dropped)
• Added go_to_char (Alt-N).
• Added go_to_char_previous (Alt-P).
• shell command now shows executed command on interaction line.
• shell command is now interruptible.
• Klipper synchronization now a single setting (clipboard.external klipper).
• Added xclip support.
• Cursor and viewport positions now saved in and restored from sessions.
• Current buffer number now saved in sessions.
• Fixed context line.
• Textual indication of no shell results now given.
• Added basic pair (bracket) highlighting.
• Added go_to_pair_match (Alt-Shift-[).
• Fixed chmodding in installer.
• Undo and redo now actually compare file contents to set “modified” flag.
• Added support for a special ‘all’ language, whose formats apply no matter the current language.
• Added dynamic prefix expansion (Alt-E).

Report any bugs here, or come visit me in IRC!

No related posts.

This release is primarily an internal refactor release. The only changes visible to the user are bug fixes. These include improvements to the installer, and vastly improved handling of X windows pasting. No more brutally slow terminal pasting!

The changes are listed in greater detail in the changelog:

• Put interaction timer only on first stale session prompt, not any after that.
• Changed all function names from camelCase to snake_case.
• Added –help-dir switch to installer.
• Fixed some issues with installer.
• Changed delete_to_and_from to always assume given character is the left side character when matching pairs.
• Fixed a line number display bug.
• X windows pasting handled much better now.
• Numerous internal refactorings and reorganizations.
• Accepted patches from Decklin Foster.

Report any bugs here, or come visit me in IRC!

No related posts.

Read more about my piano recording series here.

Related posts:

1. Beethoven – Sonata Op. 27, No. 2 (Moonlight), 1st movement
2. Beethoven – Sonata Op. 27, No. 2 (Moonlight), 2nd movement
3. Chopin – Prelude Op. 28, No. 4 in E minor

Is Etanni a performance improvement over ERB? I’m just converting a site over to Ramaze and I’m wondering if it’d be worthwhile to convert my ERB tags to Etanni tags?

manveru promptly replied:

ERB is a lot larger, and does a lot more, but usually you don’t use that functionality. Etanni consists of a single regular expression substitution and should be faster than just about any other templating engine around, the whole core source of Etanni is around 4 lines.

So yes, i suggest you use Etanni instead of ERB

He also quickly wrote up some benchmarking code to substantiate his claims, and then enlisted me to solidify matters. I used his code as a base, and ran the same engine test code through better-benchmark. I put the benchmarking code up as a gist. The full results are embedded as a comment at the end of the gist. Here is a summary:

Based on the results of this little test we might conclude: If rendering speed is a concern, but you also want to just stick with your framework’s default engine to minimize gem dependencies, go with Ramaze.

No related posts.

Read more about my piano recording series here.

Related posts:

1. Chopin – Nocturne Op. 72, No. 1 in E minor
2. Chopin – Polonaise Op. 40, No. 1 in A Major
3. Chopin – Prelude Op. 28, No. 4 in E minor

If you just want a basic short message service with almost no frills, then sure, Twitter fits the bill. But if you’re going to be using your communications service a lot, I think you might be pleasantly surprised, like I am, by all the great things FriendFeed is and does. The following points may not provide enough justification for you to join FriendFeed (or completely switch over), but it is for me.

Of course, there are other features of FriendFeed beyond the ones I list here, but they are not the main selling points for me personally. You can read FriendFeed’s own sales pitch on the FriendFeed home page.

8. Quickly find friends already on FriendFeed

While signing up, you are given the opportunity to find your friends who might already have FriendFeed accounts. After one click (and giving my nick), it imported everyone I knew on Twitter who were already on FriendFeed. Granted, Twitter has a similar on-join feature, but Twitter only imports from popular email services, whereas FriendFeed also imports from Twitter and Facebook.

7. Comments are second class citizens

I care about what I post to the Internet. I believe in the quality of my postings. I think that I owe it to my readership (and potential readership) to make everything I post on the net worth reading — something that would, if even just a little bit, enrich the life of the reader. This holds especially true for this blog of mine, but also applies to my microblogging, even if only to a lesser extent.

Sometimes we want to reply to or acknowledge a tweet, or maybe just chuckle with the tweeter when they make a joke or witty remark. On Twitter, what am I to do? If I reply tweet with nothing but “@Jaykul lol”, I’d have degraded the quality of my tweetstream. If I’m not willing to do that, then I have effectively been suppressed by the limitations of Twitter.

On FriendFeed, everyone has a main feed to which they can post messages, just like on Twitter or Facebook. But over there, I can comment on Jaykul’s tweet with my one-word laugh message, and my main feed is not polluted.

6. Like or Share, not retweet

On FriendFeed, I can indicate I like something with a single click. Then, everyone who cares to know (dependent on their account settings) can see what I marked. The advantage there is that I don’t need to expend message text on attribution (“RT @nickname …”). FriendFeed records and displays that metadata for me. This character savings becomes more pronounced with further degrees of retweeting; you lose dozens of precious tweet characters when trying to preserve multiple attributions (“RT @nickname1 @nickname2 @nickname3…”). Not so with FriendFeed.

Full-fledged sharing is also possible, to any of several other social sites, including Twitter, Facebook, Digg, Reddit and Delicious.

5. Shortened URLs are expanded

Those of you wary of (or downright averted to) URL shortening will be pleased to hear that FriendFeed expands URLs for you in your FriendFeed homepage. If you don’t know what the problems with URL shorteners are, I’ll let you exercise your google fu and find out.

4. Echo to Twitter

FriendFeed allows you to echo your messages over to Twitter, so you still have a heartbeat over there while you wait for people to get FriendFeed accounts. This of course removes the need to post the same message manually in both places.

3. Aggregate other services, including Twitter

FriendFeed has this great feature called “imaginary friends”. Yeah, get the giggles out of your system from that name, then let’s move on. By creating an imaginary FriendFeed friend, you can in effect follow (subscribe) to their accounts on other services — 57 other services, to be exact, including Twitter, Flickr, Facebook, and many others. This way, you can effectively import your Twitter friends who haven’t joined FriendFeed yet. Once added as an imaginary friend, all their Twitter updates (or Flickr photos, or Facebook updates) appear in your FriendFeed home page.

Let’s recap the last two points again: You can post to Twitter from FriendFeed instead of at Twitter, and you can receive your Twitter friends’ updates on FriendFeed instead of at Twitter. In other words, it’s really starting to look like you don’t need Twitter much any more. I only check it once in a while for direct messages, or for updates from people I haven’t turned into imaginary friends yet.

You can also follow any RSS feed with FriendFeed, which makes it a sort of primitive or summary-only RSS reader or aggregator. I’m not an avid RSS collector (uses up too much time, a resource of which I have precious little to spare), so this suits me just fine. For example, it’s allowed me to follow my personal github.com feed on FriendFeed instead of in a separate github browser tab. Nice and tidy and unified.

2. No 140 character limit

For the most part, I do not communicate in short squirts.

I’ve lost count how many times I’ve tried to tweet something, then had to trim it down because of the 140 character limit, and also because I was trying not to break a message across two tweets. One time I used “shorthand” like “2″ for “to” or “u” for “you”, and was almost ashamed of myself for doing so. Those of you that know me know that writing like that is so not me.

So, not having to restrict myself to the limits of an archaic technology was a huge selling point. I don’t use my phone for text messaging, and I definitely don’t use it for updating Twitter, Facebook or FriendFeed. So that 140 character limit feels annoying at best.

1. Very high usability; nice design

FriendFeed’s website is extremely well-designed. There are many signs of the user interface being well thought out, and it’s clear that usability was given importance during development. You should check it out for yourself, so you can experience what I’m talking about first-hand, but I can list a few items here.

The FriendFeed site strikes a great balance between AJAX versus full page loads. You get a spinner (AJAX) or popup (JS/CSS) where appropriate; a full page refresh where appropriate. This lends to a snappy and fluid user experience.

Hover over an account or group, and you get a handy JS/CSS popup that gives info and links for doing things or learning about that account or group. This in effect reduces click depth, which gives the feel that the information you want is that much more accessible and readily available.

Text boxes start out small, but automatically expand in size as needed, when the text you type gets lengthy. This lets the interface remain tidy and concise, but grow dynamically if there is a functional need.

When viewing a feed (such as the one on your personal FriendFeed home page), it updates in realtime with AJAX/JS effects. Contrast that behaviour with the pages on Twitter.

FriendFeed is very customizable. You can tweak notification settings, Twitter publishing preferences, and numerous other little things. As with all software, options help to give a very satisfying experience, because the same software can be tailored to satisfy many different tastes and preferences.

Multiple messages are compressed into “see more” links, which further helps keep the interface tidy. You can also Hide things with one click. With another click, you can hide similar items, too. For example, you might choose to hide a particular flickr photo of one friend — or go the distance and ignore their entire flickr photo stream.

When viewing someone or a group you might subscribe to, it tells you that the person posts “about 5 posts per day”. This lets you quickly gauge how much activity the person or group would add to your feed.

Conclusion

In summary, I think these reasons combine to make switching from Twitter to FriendFeed very compelling. FriendFeed offers everything Twitter does for me, and it does it much better, while also providing several enhanced features that Twitter does not provide.

If you’re a Twitter user, you at least owe it to yourself to make a FriendFeed account and test drive it. Compare and make a decision for yourself.

• http://friendfeed.com
• http://friendfeed.com/Pistos

No related posts.

Innate

For those of you that have not been following, manveru (Ramaze lead dev) had been brewing a new web framework core called Innate since the middle of last year. As of today, Innate is pretty much done, and only sees minor updates. Innate has its own repository on github, where you can find a detailed README. Innate is built on top of Rack, the “web framework framework”, and acts as the core for Ramaze as of this Ramaze release.

Upgrade carefully

Because of this big change, Ramaze applications built with Ramaze 2009.03 or prior need non-trivial effort to port to 2009.05. As such, proceed with caution when upgrading your gem, especially on production servers. You can install multiple Ramaze gem versions side by side, and then select a specific version in your applications as follows:

require 'rubygems'
gem 'ramaze', '2009.03'
require 'ramaze'

Install or update Ramaze with

gem install ramaze

The Ramaze team would like to apologize to those who unwittingly upgraded their Ramaze gems to 2009.04, which was essentially a beta release of the new Innate-cored Ramaze. We understand and acknowledge that it may have caused some confusion for some, since legacy apps have a high chance of not working without modification, and also since nearly all online information written about Ramaze to date covers pre-Innate Ramaze. We hope to rectify the situation with this release and announcement, and thank you for your understanding.

Documentation

As is the tradition in the Ramaze community, new code doesn’t come without a healthy dose of documentation. manveru has taken a lot of time to document the way things work in Ramaze 2009.05. Along with this release, he presents the fully updated, official online Ramaze book. It is quite detailed, and should help newcomers and old timers alike get to know the new Ramaze. Although not complete at this time, it is receiving regular updates and additions. The source of the book is open source.

manveru has also updated his Ramaze todo list tutorial to work with 2009.05.

Don’t forget that the source code repositories of Ramaze and Innate also have abundant documentation in them. Questions about Ramaze are sometimes answered by simply grepping the source code and reading the documentation, examples and tests. Consult both Ramaze and Innate source.

It’s a good idea to bear in mind that anything written about Ramaze up to March 2009 may not accurately reflect Ramaze as it stands in April 2009 and onwards.

Major changes

Below are some of the changes introduced by the advance from 2009.03 to 2009.05. Do not consider it exhaustive; you’d be better served checking other sources like the Ramaze book, and also hanging out in IRC so you can ask questions and receive live support. The mailing list is also a good way to get specific questions answered.

Content representations

Controllers can now provide one of multiple representations when responding to requests, based on conditions of your choosing. For example, this new feature lets you serve a normal response to /foo, but a JSON response to /foo.json. You can even use different templating engines for different wishes. See the content representations section of the Ramaze book and the source code of Innate::Node for more details.

Modes

Ramaze applications can now run in different modes, such as :dev and :live. You can make up custom modes since a mode is simply a nested array of Rack middleware.

Layouts

Layouts now reside in their own directory, layout/, distinct from the view/ directory. (As usual in the Ramaze world, these specific directories are only defaults.) Layout specification can also now take a code block to control when a layout is applied. See the layout section of the Ramaze book for more details.

Helpers

The old link helper’s methods (A, R and Rs) have been deprecated and replaced by Innate’s link helper’s methods: a, r and rs. They are mostly interchangeable, but the r methods can now also be called “off of” controllers:

OtherController.r( :foo, :bar, :a => :b )
#=> URI('/other/foo/bar?a=b')

The old partial helper has now been replaced by the render helper of Innate. The source code for the render helper is well-documented. Refer to it for usage syntax and examples.

Apps

Ramaze Apps have been introduced (notice the spelling with a capital A). A Ramaze App can be thought of as a namespace for controllers and options. You can thus take related controllers, and then package, distribute and reuse them with relative ease. An App is itself mapped to a path of your site, and can also use directories specific to it. Some example code:

module Forumaze
  class MainController < Ramaze::Controller
    map '/', :forumaze
  end
 
  class AdminController < Ramaze::Controller
    map '/admin', :forumaze
  end
end
 
app = Ramaze::App[ :forumaze ]
 
# path on site (relative URL)
app.location = '/forum'  
 
# filesystem paths relative to current dir
app.options.publics = 'forumaze/public'  
app.options.views = 'forumaze/view'
app.options.layouts = 'forumaze/layout'

With the above code, hits to http://yourdomain.com/forum would be served by Forumaze::MainController, and hits to http://yourdomain.com/forum/admin would be served by Forumaze::AdminController. Views would be taken from the directories forumaze/view/ and forumaze/view/admin. The same idea applies for static files and layouts of this App.

You can have multiple Controllers per App, and multiple Apps per Ramaze application.

ramaze binary

The ramaze binary has been updated. See ramaze --help and the ramaze command section in the Ramaze book.

Ezamar -> Etanni

The old default templating engine, Ezamar, has been replaced by the Innate equivalent, Etanni (or the more powerful Nagoro, if you choose). Ezamar templates should be forward-compatible with Etanni, but Ezamar Elements have been removed. To keep using Elements, use either Nagoro, which has Elements too, or the new render helper, which can accomplish the same thing in a different way.

Miscellany

The old start.ru Rackup file has been replaced with config.ru. This is particularly important for those of you deploying with mod_rack (Passenger).

Ramaze::Global has been removed and replaced with Ramaze.options which is intended to be a much better means of configuring Ramaze. Ramaze.options is also extensible, so you can use it for custom configuration of your applications.

Contributors

Direct contributions to the code repository for this release came from the following people (listed alphabetically, nickname in parentheses):

Innate

• Sam Carr
• Michael Fellinger (manveru)
• Ryan Grove (rgrove)
• Andreas Karlsson (jeltz)
• (Pistos)
• Tadahiko Uehara (kiko)
• TJ Vanderpoel (bougyman)

Ramaze

• Clive Crous (clive)
• Michael Fellinger (manveru)
• Ryan Grove (rgrove)
• Aman Gupta (tmm1)
• Andreas Karlsson (jeltz)
• Victor Luft
• (Pistos)
• Tadahiko Uehara (kiko)
• TJ Vanderpoel (bougyman)

Of course, all the folks who use and test drive Ramaze every day also deserve thanks, not just for using it, but also for providing valuable feedback on previous releases ramping up to this one.

As usual, we’d love to hear from long-time users and newbies alike. Stop by and say hello in our IRC channel (#ramaze on Freenode), or ask questions on our mailing list. We know converting old Ramaze apps may be challenging for some, but we’re here to help make the transition as smooth as possible for you.

Enjoy this release, and keep on Ramazing!

No related posts.

Read more about my piano recording series here.

Related posts:

1. Chopin – Prelude Op. 28, No. 4 in E minor
2. Chopin – Nocturne Op. 72, No. 1 in E minor
3. Chopin – Nocturne Op. 9, No. 2 in Eb Major

Read more about my piano recording series here.

Related posts:

1. Chopin – Prelude Op. 28, No. 4 in E minor
2. Chopin – Nocturne Op. 9, No. 2 in Eb Major
3. Chopin – Mazurka in Ab Major, Op. 24, No. 3

No more gem

Beginning with this release, I am doing something radical: I am not releasing Diakonos as a Ruby gem. While that may seem strange to some, I think the move is not only justified, but better for Diakonos.

I don’t believe Diakonos has a tremendously large user base at the moment. According to DistroWatch and LinuxRank, Ubuntu is easily the most popular Linux distribution. If Diakonos is to gain any popularity, it behooves me to ensure that it installs onto and plays well with Ubuntu.

I noticed that the Debian package for Diakonos had fallen behind my upstream releases (it was stuck at 0.8.4). I exchanged e-mails with Ralph Amissah, the maintainer of the Debian package (and, by extension, indirect maintaner of the Ubuntu package too), and was thereby informed that the inception of the new help system (introduced in 0.8.6) impeded the downstream updates. In particular, Diakonos’ downloading of configuration and help files for first time users was behaviour that ran contrary to Debian policy.

I think Debian and Ubuntu users who are not advanced Linux users would be more inclined to install packages via the apt system, as opposed to via RubyGems.

Furthermore, I have concluded that the RubyGems system is tailored much more towards libraries, and not applications. It’s great for putting files where Ruby’s require and load statements can find them. But it’s not so well suited to moving global configuration files into /etc, or system-wide documentation into /usr/share/doc. I mumbled about this over two years ago. At first, I worked around the problem by having Diakonos installed via RubyGems, and then downloading configuration files (and, later, help files) from the Internet when the user first runs Diakonos. But, as I’ve mentioned, this prevented smooth inclusion into the Debian package repositories.

RubyGems is focused on letting Ruby developers disseminate their libraries to other Ruby developers; Diakonos is an end-user application. That it is written in Ruby is secondary and peripheral; it is not my intention to present a cute novelty to the amusement and delight of a fraction of the developers of a subculture programming language. My goal is to create the most user-friendly console editor for Linux (“a Linux editor for the masses”).

In light of these facts, I elected to abandon the RubyGems system in favour of a custom installer (install.rb in the package). This installer would allow a distro package maintainer to install Diakonos to specific locations of his or her choosing in the filesystem. I envision that package maintainers for all distros should have little difficulty using it to create or update their packages. Of course, it is easy to use for the end user himself, as well. It can be used to install Diakonos completely in userspace (i.e. somewhere under a user’s home directory, without the need for root/sudo privileges).

The new package (simply a tarball) contains everything needed to run Diakonos, including default configuration files and a full set of help files. Diakonos no longer accesses the Internet for these like it used to in previous versions.

Configuration is loaded from the system-wide location (specified during installation), but user-specific overrides are (as before) loaded from ~/.diakonos/diakonos.conf.

Configuration inheritance

Configuration settings can now be inherited (cascaded). Simply use an equals sign (=) to set one setting to the value of another.

one.setting = another.setting

For an example, have a look at the Ruby language definition in the default config file. See how the shared settings are defined earlier in the file.

This inheritance will work for any setting, not just formatting. The important thing to remember is that Diakonos will parse configuration files top to bottom, and visit each included file in the order the include directives are encountered, with a depth-first strategy. So you should define ancestor settings before descendant settings.

Block selection

You can now switch between block (columnar) selection and normal (flow) selection. Default keychains: <Alt-Shift-M, B> for block, <Alt-Shift-M, N> for normal. Mnemonic: M for Mark, B for Block, N for Normal.

Line numbering

Default keychord <Alt-Shift-L> can be used to toggle line numbering on and off. Line numbers appear in a left-side margin. Enable line numbering permanently by setting view.line_numbers to true in your config. Set view.line_numbers.width to the number of columns to use for the line numbering margin. view.line_numbers.number_format is the setting to use to define a sprintf format for the line numbers. Set the colour and brightness with view.line_numbers.format.

Code block navigation

A cool thing I’ve added in this release is code block navigation. Using Ctrl-PageDown, you can jump to the next code block of the same indentation level as the current line. Ctrl-PageUp goes back in the opposite direction (up or previous block). You might use this to easily browse: the methods of a class; or the different when clauses of a Ruby case expression; or the components of an if-elsif-else tree; or the rules of a CSS stylesheet; and so on. Diakonos will automatically limit the extent of the navigation, so if you start your browsing within an if-elsif tree, your cursor won’t jump outside that tree if you press Ctrl-PageDown too many times.

Alt-PageDown brings the cursor one block level deeper; Alt-PageUp brings you out one level.

Column markers

You can now define column markers using the view.column_markers.* settings. I’ve provided an example in the default config:

view.column_markers.margin.column 80
view.column_markers.margin.format 9

Uncommenting or adding these lines would set up a column marker named “margin”. The name “margin” is arbitrary; use whatever names you want for your markers. The “margin” marker would highlight the 80th column using the format code 9 (white on red in the default 16-colour configuration).

You might use such a column marker as a visual cue to help you not exceed a certain line length. You can set up as many column markers as you like.

Remove word from input line

Pressing Ctrl-W on the input line will now delete the last word on the line. I mainly included this to lop off file path components when opening new files or grepping directories.

Ruby 1.9 and 1.8 support

Ruby 1.9 support is even better now. There are no known issues with Diakonos running under Ruby 1.9.1. If you encounter anything, please let me know.

As I move forward with development, I am preferring 1.9 styles and constructions where there is a choice. As such, some functions of Diakonos may no longer function under Ruby 1.8. I encourage you to install Ruby 1.9 if you have not already, and to keep both versions concurrently installed on your systems. The Ruby community benefits when people move forward to adopt and use this latest stable release of Ruby.

A corollary of running under 1.9 is the ability to open and edit files with encodings other than ASCII. The little test files I opened were handled by Diakonos without difficulty. I could insert and delete UTF-8 characters and save the file. Any real world usage (testing) of Diakonos with non-ASCII files is appreciated!

Also, don’t forget that things run faster under Ruby 1.9, and Diakonos is no exception!

Et cetera

Several bugs were fixed (see the git commit log for details). If you subscribed to the particular LinisTrac tickets in question, you would have already been notified.

The rest of the changes are described in this version’s full changelog:

• New installation and uninstallation method: tarball + install.rb.
• Added configuration setting inheritance.
• Added block selection mode (Alt-Shift-M B; Alt-Shift-M N).
• Added line numbering settings.
• Added spawn function.
• Added go_block_previous, go_block_next (Ctrl-PageUp, Ctrl-PageDown).
• Added go_block_outer, go_block_inner (Alt-PageUp, Alt-PageDown).
• “Remove word” functionality (Ctrl-W) added to readline.
• Added find.show_context_after setting.
• Added view.column_markers.
• Added lang.____.indent.not_indented setting.
• Introduced $d shell variable: current buffer’s directory.
• $f and $d now expand to absolute paths.
• delete_to and delete_to_and_from can now operate over multiple lines.
• delete_to_and_from can now delete between matching brackets.
• Added git diff (F9).
• Ruby 1.9 support smoothed out. Ruby 1.8 support being deprecated.
• Support for non-ASCII encodings tentatively confirmed.
• Several bugs fixed.
• Help files updated.

As usual, report any bugs here, or come visit me in IRC. If you like Diakonos, please consider making a small donation.

Enjoy version 0.8.8!

No related posts.

Read more about my piano recording series here.

Related posts:

1. Chopin – Nocturne Op. 72, No. 1 in E minor
2. Chopin – Polonaise Op. 40, No. 1 in A Major
3. Chopin – Prelude Op. 28, No. 4 in E minor

strip_trailing_whitespace_on_save

A strip_trailing_whitespace_on_save setting was added, defaulting to true. I’ve joined the camp of those who believe that trailing whitespace doesn’t belong in source control repositories (due to diff false positives).

Sessions

I’ve added sessions to Diakonos, and use them all the time now. Name your session by starting diakonos with a -s option:

diakonos -s my-website

The default configuration will show the session name in the bottom right. If you close Diakonos and reopen it with the same session name, it will reopen all the same files as were open when you closed it.

If you open Diakonos without a session name, it will still maintain an anonymous session until you quit. If Diakonos or your computer should crash during your session, you can start up Diakonos and it will prompt you to restore any sessions that were not closed gracefully.

Grep as you type

The previous release of Diakonos saw the inclusion of “find as you type”. This version provides grep as you type. Behold the coolness via this mini screencast:

delete_to

Being forced to use vi on occasion at work, I’ve become acquainted with at least one neat thing: You can press “dt” in vi to “delete till”. So I brought this functionality over to Diakonos. Type Ctrl-D-T, " to change this:

 some_method( "here is a string", 3 )

to this:

 some_method( "here is a ", 3 )

Type Ctrl-D-I, " to change this:

 some_method( "here is a string", 3 )

to this:

 some_method( "", 3 )

custom.conf

The default diakonos.conf configuration file now has an include custom.conf directive. This lets you keep your custom Diakonos configurations in ~/.diakonos/custom.conf while allowing you to regularly upgrade diakonos.conf with each new Diakonos version.

Ruby 1.9 compatibility

Version 0.8.7 marks the first version of Diakonos that can run under Ruby 1.9. Diakonos 0.8.7 will also run under Ruby 1.8.6. Please be advised that I am tentatively planning on dropping Ruby 1.8.x support beginning with the next Diakonos version.

Changelog

Here is this version’s full changelog:

• MRU buffer history added.
• strip_trailing_whitespace_on_save setting added.
• Sessions (named and unnamed) added.
• grep as you type added.
• delete_to added.
• delete_to_and_from added.
• find.return_on_abort setting added.
• Makefile config added.
• Markdown config added.
• Sass config added.
• Now including custom.conf from default diakonos.conf.
• Help files updated.
• Some Ruby 1.9 compatibility introduced.
• Lots of code refactoring done.
• Numerous little adjustments and fixes made.

Report any bugs here, or come visit me in IRC! Enjoy this release.

No related posts.

• Redirection within https fixed.
• flash.delete now fully deletes from flash.
• Subclass controllers now properly inherit the template engine of the parent controller class.
• Ruby 1.9 compatibility improved.

manveru has always been conscientious about Ruby 1.9 compatibility in Ramaze (indeed, in all his projects), so Ramaze had already been considered 1.9-compatible for some time. With the recent release of Ruby 1.9.1, though, a fresh problem crawled out of the woodwork. This release addresses the issue; see the mailing list thread for details.

As some of you can probably appreciate, 1.9 compatibility is a non-trivial assignment. If you encounter any sort of problems using Ruby 1.9.1+, please don’t hesitate to let us know.

Contributions to this release came from the following people (listed alphabetically):

• Andreas Karlsson (jeltz)
• Michael Fellinger (manveru)
• (Pistos)
• Riku Raisaenen (rikur)
• Sean Lai

Install or update Ramaze with

gem install ramaze

As usual, we’d love to hear from long-time users and newbies alike. Stop by and say hello in our IRC channel (#ramaze on Freenode), or ask questions on our mailing list.

And don’t forget that the next generation of Ramaze, with an “Innate” core, is on the horizon, with several features and improvements. In the mean time, enjoy this release!

No related posts.

From the Selfmarks site:

Selfmarks is anti-social bookmarking for the technically endowed. Trouble-free bookmarking for geeks. Bookmarking without the centralization handcuffs; you take all the credit (and blame).

I used Diigo to manage all my bookmarks for the past couple years, and for the most part the service has been decent. I would still recommend them as a good site for social bookmarking. But now and again, I would find their servers responding very slowly, and I just got fed up with that, because I never really used the “social” part of social bookmarking. All I really wanted was a place on the Internet I could put my bookmarks.

So, after one more episode of dissatisfactory service, I finally cracked and started writing up my own bookmarking site.

Selfmarks is written in Ruby, using the Ramaze web framework. I access a PostgreSQL database using M4DBI for ORM. Thanks go to Alexut for the Selfmarks logo.

Selfmarks is OpenID-enabled, so go ahead and use your OpenID to instantly create an account and play with the site. You can import your bookmarks in delicious format.

The project is open source; grab it from github, or

git clone git://github.com/Pistos/selfmarks.git

Installing Selfmarks for oneself should only be a mild challenge for a seasoned programmer. There has already been one other successful installation by an experienced Rails and Ruby dev.

Let me know what you think! Leave a comment on this blog post, or chat with me on FreeNode.

No related posts.

To get the most out of this article, you should be comfortable with Ramaze, HTML and Javascript. If you need to get up to speed on Ramaze, learn more at the Ramaze website.

What’s Comet?

From the Wikipedia article on Comet in web programming):

In web development, Comet is a neologism to describe a web application model in which a long-held HTTP request allows a web server to push data to a browser, without the browser explicitly requesting it. Comet is an umbrella term for multiple techniques for achieving this interaction. All methods have in common that they rely on browser-native technologies such as JavaScript

Why Comet?

In traditional web applications, the process flow is:

1. time passes until the web browser (the client) wants data
2. client requests data from server
3. server gives data to client
4. repeat from step 1

As web developers got more clever, they wondered how they might get the server to give data to the client when the server wanted to give it, not when the client wanted to get it. So they came up with a flow like this:

1. client asks for data from server, if any (client polls server)
2. if server doesn’t have data ready, server tells client no data is available
3. client waits a “short while”; repeats from step 1
4. if server has data, server gives data to client
5. repeat from step 1

However, when developing an application with this design, you had to make a tradeoff:

• Polling frequently puts unnecessary load on the server
• Polling infrequently causes the client interface to lag behind the actual data source

Comet tries to address both problems, so no tradeoff has to be made. With Comet, you can poll infrequently but still get the data to the client very soon after the server is ready to give it.

Two kinds of Comet

There are roughly two kinds of Comet:

Streaming

In streaming Comet, a connection between client and server is made, and data is pushed from server to client whenever it is available. The connection always remains open, even after each bit of data is transferred. The example in this article does not implement this type of Comet.

Long polling

Long polling works like the “bad” polling design, except the server does not respond to the client until the data is ready. As already mentioned, this results in fewer network connections while still maintaining low latency.

A Comet example in Ramaze

I’ll exemplify Comet in Ramaze by building a web application that tails a file on the server and displays the lines on the web page as soon as they are available. The full source code can be found on github. You are advised to clone or download from there so you can follow along. I will not go over every line of code in this article.

I also make use of another data producer which manveru provided. The application demonstrates that the very same process and implementation can be applied with different producers.

Client

The web page code is very simple. It has this body:

<body>
  <h4>Tailer:</h4>
  <textarea id="tailer" rows="16" cols="80"></textarea>
</body>

We’ll use a <textarea> to hold the file lines, and give it an id, tailer.

In the Javascript, we have a function called get_more_lines. The client:

1. calls this function which
2. waits for data
3. receives the data
4. appends the data into the <textarea>
5. calls the function again (repeats from step 1)

Server

The interface page (located at the path /tail) is just static HTML, so it needs no controller code. But let’s examine the controller code to see how the server side gives data to clients.

As you saw in the client code, the tailer data is retrieved from the path /next_tailer_lines. In the controller, next_tailer_lines calls a more generic next_lines method, which has this code in it:

60.times do
  lines = producer.new_lines( session.session_id )
  if lines.any?
    Ramaze::Log.debug "New data!"
    return lines
  end
 
  Ramaze::Log.debug "Waiting for data..."
  sleep 1
end

When there is a request for next_lines, the server checks the server-side producer for more data. If there is no new data, rather than returning any response to the client, the server continues to poll the producer.

The key thing to note here is that the server is doing the polling server-side. The client is merely waiting for the server to respond to the single request — no polling is going on between client and server while data is unavailable. Because the polling is server-side, it is much cheaper, so we can be much more liberal with the polling frequency.

If and when the data becomes available from the producer, the server gives that data to the client right away.

On a basic level, that’s all you need for Comet!

1. Server-side producer(s)
2. URI for the client to retrieve data from
3. Client-side “request and consume” loop
4. On request, server polls data source (producer), responding only when ready

Try out this example yourself! Grab the code with

git clone git://github.com/Pistos/ramaze-comet-example.git

(or download it with the “download” button on github).

Install the file-tail gem, and then open up a ramaze-comet-example.log file in the same directory as start.rb. Fill it with some sample text. Then run

ruby start.rb

and browse to http://localhost:7001/tail. You should see the last 10 lines of your ramaze-comet-example.log file. Now, with the web page open, add some more lines to the file (don’t forget to save if you’re using an editor to add lines), and then look at your browser; the new lines should appear (after a tiny delay). And of course, since this uses AJAX, there is no need to refresh the page to see new data.

You can also experiment by changing the filepath in the source code to point to a real log file of your own.

Details

Server-side timeout

You may wonder why we loop only 60 times instead of infinitely polling for data. While infinite polling is possible, it is not practical to employ because the server would continue to poll even after the client disconnects (such as when the browser tab is closed, or the page is refreshed). It’s better to time out the polling and return empty data. If the client is gone, the empty data is sent harmlessly into the ether, communications cease, and the server will stop polling. If the client is still around, it will reinitiate a fresh network connection, and polling will continue. But that’s why this technique is called “long polling” and not “infinitely long polling”. In contrast with the naive polling implementation, the client-side polls are less frequent and their durations are much longer.

In this example, we loop 60 times, waiting one second per iteration. You can obviously tweak these numbers for your own needs in your application; sleep less or more; loop fewer or more times for a shorter or longer server-side timeout. The tradeoff with longer server-side timeouts is that your application is doing a little extra work for nothing for clients that have disconnected.

Browser connection limit

You should also be aware that most browsers limit the number of connections to a server (typically only 2). If you keep one connection open for Comet, that only leaves one other one available, so normal operations like parallel fetching of images, CSS files, etc. will be slowed down. That also limits you to only one Comet connection.

A common workaround for this issue is to create subdomains on a domain (usually pointing to the same server as the domain), so the browser is tricked into thinking it is making connections to different servers; each domain or subdomain is given a full set of connections to work with. You could, for example, have a subdomain comet.mydomain.com for Comet connections, and use mydomain.com for normal HTTP requests.

The Javascript in detail

For those who are interested, I’ll explain the Javascript in greater detail. Let’s look at the get_more_lines function:

$.get(
    data_uri,
    function( data ) {
        if( data != '' ) {
            $( receiver_id ).append( data + "\n" );
            var receiver = $( receiver_id ).get( 0 );
            receiver.scrollTop = receiver.scrollHeight;
        }
        setTimeout( get_more_lines( receiver_id, data_uri ), 0 );
    }
);

The first line is the call to jQuery’s get function. This issues an HTTP GET request. The first argument is the URI to call. The second argument is a callback function used to process the server response.

Inside the callback function, we have a conditional to check whether (a) we actually got data, or (b) the server timed out waiting for the producer to produce new data. If we have data, then we append the data to the jQuery element (or document element, if you prefer) which we reference by the given id string. Then we use scrollTop and scrollHeight to auto-scroll the <textarea> to the bottom as new lines are fetched.

The last line of the callback function calls get_more_lines again. The reason we use setTimeout is because if we called get_more_lines directly, that would be recursion, which runs the risk of consuming memory as each step of recursion grows the call stack.

Alternative producer

Browse to http://localhost:7001/chat to see the same Comet code work with a different data producer. New “chat” lines are added to a channel at random intervals, and the browser is updated with the new lines as they come.

No related posts.

• The project generator (ramaze --create) should now work under Windows
• Most extensions to Ruby core classes have been moved into the Ramaze namespace
• String#/ and Symbol#/ have been deprecated (use File.join instead)
• Fixed bug which mapped ‘/’ to Controller
• Changes and improvements to file watching (automatic source reload); will use inotify if available on system
• Fixed routing bug which caused occasional, rare routing failures under concurrent load
• Fixes, improvements and/or more documentation for the paginate, httpdigest, user, redirect, gravatar, mock_http, markaby helpers
• Bench(mark) helper added
• Several other minor updates to the core, core warnings and error messages, core docs, and core specs.
• Some updates to contrib code

Contributions to this release came from many people (listed alphabetically):

• Aki Reijonen
• Aman Gupta (tmm1)
• Andreas Karlsson
• Andrew Farmer (Xichekolas)
• Antti Tuomi (hrnt)
• Clive Crous
• Colin Shea
• Gavin Kistner
• Michael Fellinger (manveru)
• (Pistos)
• Riku Raisaenen (rikur)
• Vincent Roy

Install or update Ramaze with

gem install ramaze

It may also be worth mentioning that the Camping dependency that was inadvertently introduced with Rack 0.9.0 is no longer present in Rack 0.9.1, so the latest Rack gem (as of this writing) should be compatible with all recent Ramaze releases.

In addition to announcing this release, I should also mention that a team is currently working on the main website and wiki. This includes major visual redesign, as well as plenty of content updates. I’m hesitant to directly link to the website at this time, as I feel it isn’t ready for general amazement, but stay tuned!

As usual, we’d love to hear from long-time users and newbies alike. Stop by and say hello in our IRC channel (#ramaze on Freenode), or ask questions on our mailing list.

No related posts.

Having gone through this tutorial, you should now know about:

1. installing Ramaze
2. setting up a database schema
3. creating a base Ruby file for an application
4. models and using them to interface with the database
5. views
6. interpolating data into views
7. controllers
8. the relationship between requests, controller methods and views
9. how to implement basic CRUD operations
10. handling HTTP POSTed data
11. using layouts for consistent page appearance
12. where Ramaze gets static files from
13. basic built-in Ramaze methods and helpers, like the link, flash and redirect helpers
14. handling errors and displaying error messages

Armed with this information, you should be well-equipped to build a small web application of your own right now.

Learning More

This tutorial has covered a fair bit, but there are actually considerably more features and functions of Ramaze that I didn’t discuss. Some of these are:

• partials or elements
• session variables
• aspects
• testing
• routing
• deployment
• form helpers and scaffolding generators
• cooperation with Javascript, AJAX
• … and more!

I hope to cover some of these things in future blog posts. You can subscribe to my blog via RSS or by email.

Here are some resources you can reference to learn more about Ramaze:

• ramaze.net, the official website
• The RubyConf 2008 Ramaze presentation by Luc Castera
• The original todolist tutorial by manveru
• The Ramaze codebase – no really, you can learn a lot from it, and the code is easy to read, and very well commented
• The examples/ dir of the Ramaze codebase
• ramaze-book, a partially complete e-book written by manveru
• The codebase of sociar, an open source social networking platform. Sociar is pretty much the de facto, comprehensive Ramaze example, written by manveru himself.
• The #ramaze IRC channel and mailing list

Get Started!

# gem install ramaze

require 'ramaze'
class MainController < Ramaze::Controller
  def index
    "Hello, world!"
  end
end
Ramaze.start

What are you waiting for? Write your first single-file web application right now! Then stop by our IRC channel and say hello. We’d love to hear from you.

No related posts.

Up to this point, we’ve been assuming users will always behave nicely and in predictable ways. As we all know, this is not a safe assumption in practice, so now we’ll add some validation and error handling to our application. I’ll introduce the changes I made somewhat in reverse order, beginning with error message display.

The Flash Helper

Ramaze::Helper::Flash is useful for displaying one-time messages to users. In your controller, you treat flash as a Hash in which you store Strings (usually). These strings can then be interpolated in views, but not just in handling the current request, but also the next one. To understand this tool and technique better, let’s examine how I make use of it in our todo list application. I’ve added a fail method to the controller:

def fail( message )
  flash[ :error ] = message
end

It simply takes an argument and assigns it to the :error key of the flash Hash. I call the fail method whenever I want to send an error message to the user. To actually display the message, we use the method flashbox in our layout:

<body>
  <h1>#{@title}</h1>
  #{flashbox}
  #{@content}
</body>

Checking the operand

Our check off and delete actions have been assuming that there always exists a task that has an id matching the id parameter given. Now we’re going to check whether this is true, and handle the situation gracefully if the condition false.

Since we’re going to perform this check in more than one spot, we stay DRY by making a single method to do the check, a method we will call from multiple places.

def ensure_task_exists( id )
  task = Task[ id ]
  if task.nil?
    fail "No task with id #{id}."
    redirect_referrer
  end
  task
end

If there is no task in the database with the given id, then we call our fail method to setup an error message, and then redirect the user back to wherever she came from with redirect_referrer. If instead the task exists, we simply return the task to the method caller.

So next, we change the action methods to make use of this utility method. Here’s a diff of the relevant part of the controller:

   def check_off( id )
-    Task[ id ].check_off
+    task = ensure_task_exists( id )
+    task.check_off
     redirect Rs( :/ )
   end
 
   def delete( id )
-    Task[ id ].delete
+    task = ensure_task_exists( id )
+    task.delete
     redirect Rs( :/ )
   end

Observe how the error handling and redirection are nicely parcelled away elsewhere, keeping the action code clean and succinct.

Seeing errors in action

Now, run the code:

  git checkout 11-error-handling
  ruby start.rb

and visit /delete/99999 to see this error handling code work. The important thing to notice here is that even though the error message is set in one action (delete), it is available for usage in the next requested action (index). However, it will not be available to future requests (unless it is set again). That’s why it’s called the “flash” hash: because data only remains for a short while.

Constraining the input

We would like to ensure that task descriptions are not empty. While other developers may choose to constrain data at the model or view (Javascript) level, I’m of the persuasion that one should constrain data as much as possible at the database level, to maximize one’s confidence that the data in the database is as pristine as possible. So I will setup the constraint in the schema:

ALTER TABLE tasks
  ADD CONSTRAINT minimum_description_length
  CHECK ( char_length( description ) > 1 );

After adding this constraint, if you try to enter a description which is less than 2 characters long, it will fail — but not very gracefully. So we add some grace by rewriting our create method:

def create
  description = h( request[ 'description' ] ).strip
  begin
    Task.create( :description => description )
  rescue DBI::ProgrammingError => e
    if e.message =~ /minimum_description_length/
      fail 'Please enter an adequate description for the new task.'
      redirect Rs( :new )
    else
      raise e
    end
  end
  redirect Rs( :/ )
end

As you can see, we are wrapping the Task.create call with a begin/rescue pair so we can handle the exception thrown by the database. The if block inside the rescue clause is used to handle a specific exception, namely a violation of the minimum_description_length constraint which we named and defined earlier. If an exception of this kind is thrown, then we setup an error message with fail and redirect back to the task addition page. If it’s some other kind of exception, we don’t want to swallow it up; instead we re-raise it. If no exception is raised, then the user is redirected to the task list.

Try this out to see for yourself that it works. (Don’t forget to add the constraint first if you haven’t done so already.)

Custom error handler

Up to this point, we’ve worked with errors which we anticipate and handle. In reality, we can never foresee every possible error. If you check out the previous tutorial part’s code and run it (git checkout 10-cosmetics; ruby start.rb), then try to visit a non-existent page, such as http://localhost:9001/foobar, you will see an error message and stack trace, something like this:

No Action found for `/foobar' on MainController
  /usr/lib/ruby/site_ruby/1.8/ramaze/lib/ramaze/controller/resolve.rb:274:in `raise_no_action'
  /usr/lib/ruby/site_ruby/1.8/ramaze/lib/ramaze/controller/resolve.rb:98:in `default'
  /usr/lib/ruby/site_ruby/1.8/ramaze/lib/ramaze/controller/resolve.rb:25:in `send'
...

Ramaze lets you override this error page with one of your own; simply put something in place to handle an error action. As we’ve learned, that means either a controller method, or a view, or both. Here’s the controller method we add:

def error
  @title = 'Application Error'
  @e = Ramaze::Dispatcher::Error.current
end

Whenever an exception occurs in a Ramaze application, the error action is hit. If no handler is set up by the application programmer, Ramaze will use a default error method.

Ramaze::Dispatcher::Error.current evaluates to the Ruby Exception which has been raised and is causing the error condition. We make it available to our view so we can display information about the exception. Here is our error.xhtml view to go with the error method:

<h2>#{@e.message}</h2>
<ul>
  <?r @e.backtrace.each do |frame| ?>
    <li>#{frame}</li>
  <?r end ?>
</ul>

It should be relatively clear what the above combination of method and view does, but in case it isn’t for you, git checkout 11-error-handling; ruby start.rb and visit http://localhost:9001/foobar again.

Review

Let’s review what we’ve learned over the final parts of this tutorial:

• Layouts are used to keep view code dry and maintain a consistent look across multiple views.
• A layout is just another view, one which interpolates #{@content}.
• @content contains the rendering of a view (or, in other words, a layout “wraps” other views).
• The layout method is used in a controller definition to tell Ramaze which view to use as the layout view for a controller. It accepts a Hash argument, with the key-value pair being the site path of the layout view, and an array of controller methods (actions) to apply the layout to. e.g.
  layout '/page' => [ :index, :new ]
• Layouts can make use of controller instance variables (e.g. @title) just like normal views.
• Static files (CSS, Javascript, images, etc.) are placed in a public/ subdirectory in your application’s file tree.
• flash is a session-wide Hash.
• Data stored in the flash Hash persists only for two requests, making it useful for temporarily storing messages for the user across redirects.
• flashbox is used in views, and evaluates to an HTML <div> for each key-value pair in the flash Hash.
• redirect_referrer is used to redirect a browser back to the referring page.

In the Conclusion, I will wrap up the tutorial and talk about further avenues of exploration and learning.

No related posts.

In this part, I change several things in the view layer so that the site looks a bit better. The exact details of the HTML changes are not pertinent to learning Ramaze, so I won’t go over them. You can view them yourself by doing the usual branch diff.

In this part of the tutorial, I introduce a CSS file. The reference in layout.xhtml is typical for web development in general:

<link href="/layout.css" rel="stylesheet"
  type="text/css" />

But where exactly should one put one’s CSS files? Ramaze, by default, serves static files from a subdirectory called public/. This is where I’ve put layout.css. You would put other static resources under public as well; things such as Javascript files, images, video files, and so on. The paths you write in your HTML should correspond to the path relative to the public/ directory. For example, a reference like

<img src="/images/banner.png" />

would make Ramaze serve a public/images/banner.png file.

Next, in Part 11: Validation and Error Handling, we’ll see how to gracefully deal with unusual user behaviour.

No related posts.

If you look at our two views, you might notice that there is some common code in both. Being good coders, we know that such unnecessary duplication is bad for maintenance and debugging, and also hinders our flexibility for future changes we might want to make.

Fortunately, Ramaze has some facilities that let you consolidate shared view code. One of these facilities is the ability to use layouts.

A layout template

In the 9-layout git branch, I add a layout.xhtml view file:

<html>
  <head>
    <title>#{@title}</title>
  </head>
  <body>
    <h1>#{@title}</h1>
    #{@content}
  </body>
</html>

I’ve copied roughly the top and bottom parts of both existing views. The differences are that I’m interpolating the title, and that the middle portion of each view is not present. Instead, there is another interpolation: #{@content}. I’ll hold off explaining this…

Adjusting the controller

We now have a layout view, but to make use of it, we need to make some changes to our controller. Looking at the source code diff, you can see that in MainController I’m using a Ramaze::Controller class method, layout:

layout '/layout' => [ :index, :new ]

The layout method takes a Hash argument. The hash key is the path to the layout. This path is specified from the root of the site (a common newbie mistake is to specify the filesystem path). The hash value is an array of symbols corresponding to the paths that we want laid out by the layout. If we omitted the array, the layout would apply to all paths, but most applications would not want this behaviour. For example, remember that our application has controller methods that handle creation and deletion of tasks. In general, it’s better to be explicit about what pages you want laid out.

I further adjust the controller by specifying each page’s @title, to be picked up by the layout.

Modifying the views

Since we are trying to move duplicate code into a single, shared location, we should remove that code from their original places in the views. To see exactly what I’ve removed, view git diff 8-delete-task 9-layout.

Now the only thing left in the views are the inner portions that distinguish them from one another. For example, here’s what’s left of view/new.xhtml:

<a href="/">Back to task list</a>
<form method="POST" action="create">
  Description: <input type="text" name="description" /><br />
  <input type="submit" />
</form>

See the layout in action

So, check out the 9-layout branch, and take a look at the result of the changes.

git checkout 9-layout
ruby start

http://localhost:9001

Use View Source in your browser to see for yourself that a full webpage is rendered, even though neither the layout alone, nor the view alone has a complete page of HTML. Observe also that the @title we set in different controller methods passes along to the layout as well.

We’ll pretty up the face of our application a bit in Part 10: Cosmetics.

No related posts.

We’ll round out the functionality of our app by adding a way to delete tasks from the list. As is commonplace when building a feature into an app, we think about implementation in terms of changes to the three parts of MVC. In this case, we don’t need to make any changes to the model, because M4DBI provides us with deletion functionality for free.

Modifying the view

In the list view, we add a link for users to click on to delete tasks:

(#{ A( 'delete', :href => Rs( :delete, task.id_ ) ) })

Nothing new here. I’m using A and Rs to build a link to a ‘/delete’ path, passing a task id as a parameter.

Modifying the controller

And of course, we need something to receive ‘/delete’ requests, so we add this to our controller:

def delete( id )
  Task[ id ].delete
  redirect Rs( :/ )
end

This should look straightforward, too. The delete method of MainController will be executed on requests for ‘/delete’, and it will take the id number passed as a parameter.

So we grab the task from the database using our Task model, then call the delete method on the task instance. When we’re done, we redirect back to the list, so there is no need for a delete.xhtml view.

Wasn’t that easy? Check out what we just did:

git checkout 8-delete-task
ruby start.rb

and surf to http://localhost:9001.

Review

Let’s review what we’ve learned while fleshing out the functionality of our application.

• Ramaze can respond to requests when only a controller method or only a view is present (it doesn’t require both).
• Controller methods should match controller paths. e.g. def create matches ‘/create’.
• The request object acts like a Hash to provide access to POSTed parameters, keyed by field name.
• h() is used to sanitize (escape) potentially malicious strings.
• redirect is used to redirect to another site path.
• A() is used to generate HTML <a> tags.
• R() and Rs() are used to build site path strings relative to a controller’s mapped root. We can use these paths with h, A, redirect and anything else that needs a path string.
• Controller methods can take arguments; these arguments correspond to a slash-separated list of parameters in a request.
  e.g. def check_off( id ) corresponds to a request like ‘/check_off/32′.
• M4DBI model classes are extensible.

In Part 9: Layout, I will introduce a DRY way to have a consistent look across multiple web pages.

No related posts.

So now we are able to record things that need to be done; but we have no way of marking them completed!

Modifying the view

Examining the source code delta (git checkout 7-check-off-task; git diff 6-add-task), you’ll see that I added this to our index.xhtml view:

<?r if not task.done ?>
  [#{ A(
    '&nbsp;&nbsp;',
    :href => Rs( :check_off, task.id_ )
  ) }]
<?r end ?>

It looks a bit convoluted, but let me explain each little bit.

I used <?r ?> to use a condition. If the task is not done yet, then we’d like to display a checkbox for users to check off the task. If the task is done, then we don’t want to show a checkbox. Note the matching end at the bottom; this makes the stuff in between if and end render only when the condition is true, as you would expect from normal Ruby code.

I’m using square brackets to “draw” a checkbox ( “[ ]” ). Following the opening bracket, we have #{, which opens up string interpolation, as per normal Ruby. Inside the interpolation, I am making a call to a built-in Ramaze method, A(). Like R and Rs, A is part of Ramaze’s LinkHelper. You use it to build links (HTML <a> tags). The first argument I pass to A is the clickable text to be displayed (the content of the <a> tag). The second argument is an attribute hash, in this case consisting simply of the href attribute for the <a> tag.

I use Rs to build the href, passing Rs the path and then an argument. If you run the code of step 7 (ruby start.rb), and browse to the site and view source, you’ll see the <a> tags that were built, including the parameters on the hrefs. Each link points to a ‘/check_off’ path, passing the task’s id number as a parameter. (I use id_ instead of id because id is reserved in Ruby 1.8. M4DBI knows that you mean id when you use id_.)

Modifying the controller

Next, we add a method to the controller to handle the browser requests that will come when users click on checkboxes.

def check_off( id )
  Task[ id ].check_off
  redirect Rs( :/ )
end

As you might expect, I match the name of the method with the path in the links. Also, the method accepts a parameter, just like the links have a parameter on them (e.g. ‘/check_off/5′ ). Nice and intuitive.

In the method, using our model, we pull out of the database the task with the corresponding id number: Task[ id ]. Then we execute the check_off method on that task.

And when we’re done, we redirect back to the todo list.

Modifying the model

Those of you paying attention may have asked: “check_off method? What check_off method?” Your suspicion is warranted: there is no check_off method — yet. To complete our work in this phase of the tutorial, we extend our model as follows:

def check_off
  self.done = true
end

Although M4DBI automatically gives us read and write access to table rows via column names, sometimes we want to have more than just that basic level of functionality. You can extend a model class by adding more methods. In this case, we’ve added a method to mark a task done. Although making a method out of a simple one-liner is not strictly necessary in this case (we could have put Task[ id ].done = true directly in the controller method), this is slightly better design (discussion and debate of this are left as exercises for the readers ).

Try it!

And that’s all we need to do to add the ability to check off tasks! Try it yourself:

git checkout 7-check-off-task
ruby start.rb

then browse http://localhost:9001.

We’ll round out the functionality of our app in Part 8: Deleting Tasks.

No related posts.

So now we have a fully functional Ramaze application, with all components of MVC, each elegantly and intuitively working together with one another. However, our app’s actual functionality is very limited at the moment, so let’s build on that. We’ll add the ability to add more tasks to our todo list.

A link

First, we introduce a way to add a task to our interface. Just a simple link in the index view:

<a href="/new">Add Task</a>

If you run the server (ruby start.rb) and visit that address in your browser at this point (those of you following along with git should git checkout 5-controller and visit http://localhost:9001/new), you will encounter an error page, with a message like:

No Action found for `/new’ on MainController

That’s because, although we have an index method in MainController and an index.html view to handle requests for ‘/’, we don’t have anything to handle requests for ‘/new’. The clever among you might suppose we have to add a new method to MainController. You could do that; but actually, Ramaze will respond to requests when only a view (or only a method) is present, which is exactly what we add.

An entry form

As you can see, view/new.xhtml consists entirely of static HTML; no variable references or Ruby code like we saw in view/index.xhtml. We won’t add anything to our controller at this point.

If you surf to your tutorial site after adding the new view (git checkout 6-add-task), you’ll see Ramaze render the HTML.

The new view contains a form which accepts the description for a new task, and then POSTs to ‘create’. We don’t have any code to handle a request for ‘/create’, so let’s add that next.

A submission handler

You can see (git diff 5-controller) that I added a new method to the controller:

def create
  Task.create(
    :description => h( request[ 'description' ] )
  )
  redirect Rs( :/ )
end

In this method, we first create a new task in our database via our Task model. request[ 'description' ] evaluates to what the user typed into the description field in the entry form.

h() is another helper method of Ramaze (part of Ramaze::Helper::CGI). It safely escapes HTML and code that could be dangerous when strings are placed into templates. It’s good practice to use h to sanitize all user input which could be displayed in a template, since malicious users might try to inject HTML or Ruby code into your views. Here, we are sanitizing at source, at the point of entry into the database (as opposed to at the point of display, in the view, or the controller method related to data display).

After adding to the database, we redirect the browser back to the task list which resides at the root (/) of the site. R is a built-in Ramaze method which generates proper paths for use in links. Rs is a specialized version of R which builds paths based on the current controller. Think “R for reference” as in “href”. We also could have used redirect '/' but using R or Rs helps us stay flexible. When developing an application, you may choose to map a controller to a different path.

So, after typing in a description and pressing the submit button, a new task is added to the database, and the user is returned to the task list.

Part 7: Checking off Tasks adds more functionality to our app.

No related posts.

The Controller part of the MVC pattern is the meat of your application. As much as possible, the logic, thinking, rules, and procesess of your application should be placed in controllers. A controller acts as a hub, or a central place of command. Controllers interact with models to read the state of the system, prepare variables with data that the views display, accept interactions from the user, and use models to modify the system state stored in the database. To do things by the book, you should try to keep to a minimum the Ruby code used in your views, and instead place it in controllers.

Ramaze has no expectation about where your controller code should go. A common convention is to place controller source code under a src/ subdirectory in your project. Note that this corresponds with the acquire statement in start.rb. Here is src/main.rb:

class MainController < Ramaze::Controller
  def index
    @tasks = Task.all
  end
end

We have just this one controller in our application. To define a controller, make a subclass of the Ramaze::Controller class. We call our controller class MainController. The name MainController is somewhat of a convention in Ramaze. Later, we’ll see what bearing this has on Ramaze applications.

In the controller, there is an index method. In it, we see the initialization of a @tasks variable, the very same @tasks variable we reference in our view. This exemplifies that instance variables in controller methods are used to make data available to views.

The right-hand side of the assignment is Task.all. What this tiny piece of code is doing is using the Task model to retrieve all the tasks from the database. If you were to inspect the @tasks variable, you would see that the DBI::Model.all method returns an Array of model objects; in this case, tasks.

MVC in action

If you’re new to the MVC pattern, the last three parts of the tutorial may seem like a lot to digest. It would aid understanding a lot, though, to see these three components work together to deliver a web page. So let’s see the fruit of the effort we’ve spent up to this point. If you’ve got the tutorial source code cloned, switch to the branch for part 5:

git checkout 5-controller

Now let’s start up our Ramaze application. Do this by running start.rb:

ruby start.rb

After a moment of initialization, you should see output similar to this:

[2008-11-12 22:50:09] INFO   Starting up Ramaze (Version 2008.10)
[2008-11-12 22:50:09] WARN   Public root: 'public' doesn't exist
[2008-11-12 22:50:09] DEBUG  mapped Controllers: {"/"=>MainController}
[2008-11-12 22:50:09] INFO   Ramaze is ready to run on: 0.0.0.0:9001 using Ramaze::Adapter::Mongrel

Now browse to http://localhost:9001. You should see a simple page consisting of a title and a list of tasks. There are several things we can observe:

1. The HTML source code of this page came from our view, view/index.xhtml. (Use Ctrl-U in most browsers to view the HTML source of the page.)
2. The static parts of the template are served as-is by Ramaze to the browser.
3. The dynamic parts are processed by Ramaze, and the results of the processing are placed in the template.
4. Browsing the root of a Ramaze website causes Ramaze to execute the index method of MainController, and render the index view. In MVC terms, we say that “the path ‘/’ is mapped to MainController”.

This mapping is actually just a default; it is possible to map the root path to a different controller, or to map MainController to a different path.

If you look at the log output of Ramaze, you’ll see a line like this:

[2008-11-13 23:35:52] INFO   Dynamic request from 127.0.0.1: /

Ramaze is telling you that a visitor’s browser requested the path ‘/’ from the webserver; that is, the root path, just as we have been discussing.

You can press Ctrl-C to stop the server if you want to. But Ramaze actually doesn’t need to be stopped and restarted (generally). Any changes you make to the source code of your application are automatically reloaded and reflected in new browser hits to the site.

Review

Let’s review what we’ve learned about Ramaze and MVC:

• Models are our nice, object-oriented read/write interface to the database.
• There is generally a one-to-one correspondence between models and database tables.
• Create an M4DBI model by subclassing DBI::Model.
• Views are the user-facing code; HTML, CSS.
• Views are templates: they are mostly constant, with some interpolation of data.
• Use #{ ... } in Ramaze templates to interpolate variables and other expressions.
• Use <?r ?> to employ flow control and conditional expressions.
• Controllers are the crux of your application’s processing.
• Create a controller by subclassing Ramaze::Controller.
• Using the class name MainController automatically maps the controller to the root site path (‘/’).
• Instance variables in controller methods are used to make data available to views.

We’ll begin building up the functionality of our application in Part 6: Adding Tasks.

No related posts.

The View part of the MVC pattern is the part of your application you look at. It is essentially comprised of the static stuff: HTML and CSS. But the pretty picture is not completely inert: some parts are always the same, but other bits vary. In other words, views are templates. You setup the overall picture, and instruct Ramaze where to put the parts of the picture that change.

By default, Ramaze looks for template files in a view/ subdirectory in your project. Here is a template I made for our application, view/index.xhtml:

<html>
  <head>
    <title>Todo List</title>
  </head>
  <body>
    <h1>Todo List</h1>
    <ul>
      <?r @tasks.each do |task| ?>
        <li>(#{task.status}) #{task.description}</li>
      <?r end ?>
    </ul>
  </body>
</html>

For the most part, this is just plain HTML. There are a couple of features that are non-HTML, though.

The first is the <?r ... ?> syntax. This is the syntax used by Ramaze’s default templating engine (Ezamar) to inject Ruby flow control and conditional expressions, and any other basic Ruby code you might need to control the dynamic portions of your views. Ramaze supports many other templating engines, so if you have a preferred templating engine, feel free to go ahead and use it in your own apps. In this template, we are using <?r ?> to iterate over an array of tasks which has been preprepared for us. We’ll cover the details of this preparation in the next part of the tutorial.

The second feature we encounter is the #{ ... } syntax. This is just plain Ruby string interpolation, and functions just as you would expect: It interpolates the string values of Ruby expressions into your template.

So, as you can see, our template is instructing Ramaze to build an HTML list out of the tasks, with each list item consisting of a task’s status and description.

The third and final component of MVC is explored in Part 5: Controller.

No related posts.

Now we setup our models. The models are the Ruby classes that allow us to access the data in the database with Ruby objects instead of awkward things like arrays, hashes or long strings. Whatever numbers, strings, dates and things are in the database, we can read from model objects. When we change some data of a model object, a corresponding change occurs in the database. Models act as our read and write interface to the database.

We only have one table, so we only have one model. This one-to-one relationship is typical. If your app has several tables, you’d generally have a model for each one, except perhaps association tables.

So here’s our model code:

class Task < DBI::Model( :tasks )
  def status
    done ? 'done' : 'not done'
  end
end

Pretty simple. Making a model class with M4DBI is as easy as subclassing DBI::Model and passing the name of the table you want to model. Even having an empty class definition would have provided us with a lot of access and manipulation power, but as you can see, I’ve also added a helpful method, status, which we can use to turn the plain boolean done column into a clear, informative string. We’ll see models in action later in the tutorial.

I’ve put this code in a file called task.rb, and situated the file under a src/model/ directory (in accordance with the acquire call in start.rb). Again, this is personal preference. You can setup your application’s directory structure however you wish.

Now let’s learn about the next component of MVC in Part 4: View.

No related posts.

The typical base Ramaze application consists of a Ruby script with the command Ramaze.start. Traditionally this file is called start.rb, but you could name it anything you like. Let’s examine the start.rb I’ve built (you can view the whole file on github or in your local repo clone).

require 'rubygems'
require 'ramaze'
require 'm4dbi'

Require some libraries. If your system is cool, you can omit “require 'rubygems'“.

$db = DBI.connect( 'DBI:Pg:todolist', 'todolist', '' )

Connect to the database. Pg is the DBI driver to use (for PostgreSQL), todolist is both the name of the database and the database user. The final argument is the database password. We don’t ever actually use the database handle ($db) in this tutorial, but if you should ever want to show off your SQL fu in one of your own apps, that’s what you would use. For our purposes, we only need to connect so that our ORM can access the database to do its thing.

acquire 'src/model/*'
acquire 'src/*'

Ramaze provides a nifty little command called acquire. This works like Ruby’s normal require command, except you can use wildcards and globs (* and **), like the Dir class supports.

Ramaze.start :port => 9001, :adapter => :mongrel

And finally, press the flipcovered red button to launch. Ramaze.start can take several configuration options. Here, we specify the TCP port to listen on, and which web server adapter to use.

Review

Let’s review what we’ve learned up to this point.

• With Ramaze you write very little code.
• You understand and know all the code of your app, because you wrote it.
• acquire is like require, but allows wildcards.
• Ramaze.start is the Ruby code that fires up your Ramaze application.

MVC – Model, View, Controller

In web development, there is a way of structuring your code, splitting it into three parts that are separate, yet which still work together. This architectural pattern is called “MVC”. MVC stands for Model, View, Controller. When working with Ramaze, you structure your application according to the MVC pattern.

The next three steps of the tutorial will cover each part of MVC. We’ll begin with the Model in Part 3: Model.

No related posts.

First, we will design the schema for our database. We will be making a todo list web application, so we’re going to need a table for tasks that need to be done.

-- schema.sql
CREATE TABLE tasks (
    id          SERIAL          PRIMARY KEY,
    description VARCHAR( 1024 ) NOT NULL,
    done        BOOLEAN         NOT NULL DEFAULT FALSE
);

To keep things simple, we won’t make any other tables (like a users table or a tasklist table). But let’s add some sample data:

-- data.sql
INSERT INTO tasks ( description )
  VALUES ( 'Learn Ramaze basics.' );
INSERT INTO tasks ( description )
  VALUES ( 'Say hello in Ramaze IRC channel.' );
INSERT INTO tasks ( description )
  VALUES ( 'Write a blog post about Ramaze.' );

I’ve placed these two files in an sql/ subdirectory under the project root. That’s a personal practice, but because this is Ramaze, you are free to do as you please — there are no forced opinions, no conventions you must conform to.

Anyway, that’s about all we need to do with the database! If you are an experienced database user and know how to create the tutorial database, make the schema and insert the test data, then feel free to skip the rest of this part and go on to Part 2: Base Application. If you need help with any of those steps, continue reading.

Setting up the database

PostgreSQL comes with some convenience tools which you can use to set up the tutorial database. First, we create a database user specifically for the tutorial. At your shell prompt, type:

createuser -U postgres -S -D -R todolist

This makes a user named “todolist”. (Run createuser --help if you want to know what the options do.) Then we’ll make the database:

createdb -U postgres -O todolist todolist

Once that’s done, we make the schema in the database:

cat sql/schema.sql | \
psql -U todolist todolist

And populate the table with the sample data:

cat sql/data.sql | \
psql -U todolist todolist

And that’s it! Go now to Part 2: Base Application.

No related posts.

To install Ramaze, simply install the gem like you would any other gem:

gem install ramaze

Because this is a demonstration of real-world usage, we’ll use a proper HTTP server and adapter. Grab Mongrel and its dependencies:

gem install mongrel

You will not need a full blown web server such as Apache, nginx or lighttpd for this tutorial. A production deployment most likely will use one of these. If, after finishing this tutorial, you want more details on using Ramaze with a web server, see the Deployment section of the Ramaze wiki.

I will not cover PostgreSQL installation here. OSX and most Linux distros will have packages for it, so you can use your distro’s package manager to install it. For Windows, you have a choice of two installers. If you want to get down and dirty, there are full installation instructions on the PostgreSQL website.

M4DBI installation is done via gems as well:

gem install m4dbi
gem install dbd-pg

Installing m4dbi will pull the dbi gem as well, as a dependency. dbd-pg is the DBD we need to use with DBI for PostgreSQL. It will pull the pg gem as a dependency.

This tutorial was made, run and tested using the following software versions:

• Ruby 1.8.7
• Ramaze 2008.10
• DBI 0.4.0
• M4DBI 0.6.0
• dbd-pg 0.3.5
• pg (gem) 0.7.9.2008.10.05
• PostgreSQL 8.3.1
• mongrel 1.1.5

Note that pg-0.7.9.2008.10.13 is known to be incompatible with DBI 0.4.0, so make sure you’re not using that version. If necessary, specify an exact version, like:

gem uninstall pg
gem install --version 0.7.9.2008.10.05 pg

Next, we initialize things in PostgreSQL in Part 1: Database Schema.

No related posts.

• Introduction
• Part 0: Installation and Preparation
• Part 1: Database Schema
• Part 2: Base Application
• Part 3: Model
• Part 4: View
• Part 5: Controller
• Part 6: Adding Tasks
• Part 7: Checking off Tasks
• Part 8: Deleting Tasks
• Part 9: Layout
• Part 10: Cosmetics
• Part 11: Validation and Error Handling
• Conclusion

What’s Ramaze?

Ramaze is a fabulous framework that lets you create web applications in Ruby with a minimum of code.

Why Ramaze?

With king of the hill Rails chugging along, and up-and-comer Merb picking up steam, why bother with Ramaze? (If you don’t care about the rationale, you can skip right to the beginning of the tutorial.)

The number one* thing that makes Ramaze stand out from the crowd is that you write very little code and you write it all yourself. No generators.

“No generators!? How will I survive? What kind of mad scheme is this?” Relax. It’s all good. Why? It’s all a matter of philosophy.

The Ramaze philosophy

Before Rails, people wrote lots and lots of code when making a web app, and they did it over and over as they did web app after web app. With each new app, they would spend time “ramping up” with just the base application before they got into the real meat of the matter, the core functionality which varied from client to client, application to application. Rails and Merb and their ilk try to make your life easier by generating this “lots and lots of code” for you, so you don’t have to spend time repeating the motions of getting the skeleton of your application coded.

Ramaze takes a different approach. It asks: How about we dump the “lots and lots of code” part altogether? This way, you get the benefit of nearly nil ramp up time, without the gaping jaw effect that hits you after you run a code generator script and sit staring at the big filetree that just sprouted out of the ground (think Jack and the Beanstalk).

So yeah, it’s a matter of philosophy. Sure, the Rails way works for some people. And that’s cool. But if you’re the kind of person who went to your local neighbourhood Rails tutorial, got to the generator part, and went “Okay, what the heck is all this stuff… I thought we were making a Hello World app?” — well by jove, you’ve come to the right place at the right time. Come! Come, and I will show you a wonderful world where it needn’t be so. A world where your code is tiny, yet powerful, and you understand it all, because it was generated — not by a script that someone else wrote — but by your own God-given clever little noodle.

Web development by example: A Ramaze tutorial

Update: This tutorial applies to Ramaze 2009.03 and prior. It probably won’t work under Ramaze 2009.04+.

Thus begins our adventure into Ramaze, the web framework. I will lead you through the making of a non-trivial Ramaze application, using the same parts and features you would use in your own killer, take-the-world-by-storm web app. You will come to know all the basics, and perhaps even some advanced things, too. Along with Ramaze, I will make use of a real-world database and ORM. My personal choices for these are PostgreSQL and M4DBI, but the same techniques and principles easily apply to other options like MySQL, SQLite, Sequel and DataMapper. I may cover usage of these in the future.

This tutorial is based on the earlier work of manveru, namely his todolist tutorial. It is similar to that one in some ways, but differs in other ways. That tutorial is still a good reference, though, so you may wish to go over it when you’re done with this one.

You should have some familiarity with the basics of Ruby and HTML to learn and use Ramaze, but you need not have any prior experience with web frameworks in general. In fact, you are at an advantage if you do not, since you won’t have any preconceptions, habits or conventions that might negatively bias your first impressions and experiences.

Source Code

The full source code for this repository is available at github.com. Each step of the tutorial is a separate branch which builds upon the previous step. To get the code, you should use git, the great version control system.

git clone git://github.com/Pistos/ramaze-todolist-tutorial.git

If you really don’t want to get or use git, github has download links you can use. You can also browse the code online at github by hovering over the “all branches” tab in the menu bar and selecting a branch. I recommend you use git itself, though, because you will be able to easily switch between branches as we progress through the tutorial:

git checkout 1-database

and you’ll also be able to see what was added and what changed in the codebase from step to step:

git diff 5-controller 6-add-task

Live Support

The Ramaze community is most active in IRC. Our home channel is #ramaze on irc.freenode.net. If you have any questions before, while or after going through this tutorial, feel free to drop by. I myself (Pistos) am there from time to time, but there are usually others around available to answer questions. There’s also the Ramaze mailing list.

So let’s begin with Part 0: Installation and Preparation.

* “Our chief weapon is surprise…surprise and fear…fear and surprise!”

No related posts.

Users can now define their own custom status variables to display whatever they want on the Diakonos status line. As an example, I’ve placed a git branch script in a new scripts directory of the source code repository. It demonstrates how to use hooks and status variables to show the git branch the current file belongs to, if the file is in a git repository.

Diakonos now accepts a -m (–open-matching) argument which will open all files in the current directory subtree which match the given regular expression — a sort of “grep and open“.

A few formatting features were added. First, the long-awaited comment and uncomment functions. As you’ve come to expect with Diakonos, comment characters are language specific and completely customizable. I also added a function to hard wrap text at a margin. As well, the snazzy new columnize function was added. Watch how to use it in this mini screencast:

Finally, I am very pleased to present in this latest Diakonos version the brand new built-in help system. Up till now, the “help” provided by the F1 key has been … well it’s been borderline useless. (For those of you that don’t know, all it did was list all the mappings of keys to functions, in a not so user friendly way.) But with 0.8.6, you are brought into an interactive, searchable help system which has a growing number of documents that cover many aspects of Diakonos from usage to configuration to default keys to tips and tricks. I’d tell you more — but I want you to try it! I’ve designed it to further my goal of Diakonos being the most user friendly console text editor available for Linux. If Diakonos falls short of this, I want to know.

The rest of the changes are described in this version’s full changelog:

• Find-as-you-type added.
• Help system added.
• print_mapped_function added.
• User-definable status line variables added.
• :after_open and :after_buffer_switch hooks added.
• Sample script for git branch status variable added.
• comment_out and uncomment functions added.
• comment_string and comment_close_string settings added.
• Added -m (–open-matching) command line argument.
• wrap_paragraph function and wrap_margin setting added for hard wrapping text.
• columnize function and column_delimiter setting added.
• Numerous small fixes, adjustments and refactorings.

Report any bugs here, or come visit me in IRC!

No related posts.

/wanted-dir-1
/wanted-dir-1/wanted-subdir-1
/wanted-dir-1/wanted-subdir-2
/wanted-dir-1/unwanted-subdir-1
/wanted-dir-1/wanted-subdir-3
/wanted-dir-1/unwanted-subdir-2
.....

Your syntax should be as follows:

tar cjvf tarball.tar.bz2 --exclude unwanted-subdir-1 \
[--exclude unwanted-subdir-2...] wanted-dir-1 \
[wanted-dir-2...]

The critical part that I was not cluing into was that the ‘f’ option/command of tar expected the tarball filename (tarball.tar.bz2 in the above example) to immediately follow it. For example, this will NOT work:

tar cjvf --exclude unwanted-dir tarball.tar.bz2 \
wanted-dir

and it will, in fact, create a file literally named “–exclude” in the current directory.

Hope this helps some frustrated souls.

No related posts.

If your terminal supports 256 colours, Diakonos syntax highlighting can now employ 256 colours (instead of the usual 16). See diakonos-256-colour.conf which comes with the 0.8.5 package.

I have also added the ability to synchronize the Diakonos clipboard with the KDE clipboard (via DCOP and Klipper). If you are using KDE and have DCOP installed, activate this feature by using these lines which are commented out in the default configuration file.

Some of you may also have noticed that I’ve recently overhauled the Diakonos homepage. Have a look if you haven’t already!

The other changes are detailed in the actual changelog:

• Added 256 colour support.
• Added support for opening files with “filepath:linenumber” syntax.
• Added ability to put %_ in a code closer as the place to position the cursor.
• Code closers can now contain newlines.
• Now closer text is parsed-indented by default.
• Added integration with Klipper (KDE clipboard).
• Added support for regexp match placeholders (\1, \2, etc.) in findAndReplace.
• Added eol_behaviour setting.
• Various minor bug fixes.
• Changed to MIT licence.

Report any bugs here.

No related posts.

Create a simple Ramaze app

Even if you have an existing Ramaze app that you will use instead of this little demo app, you should read this section because I talk about important pitfalls that can cause things to break. You can apply the same ideas to your app.

As per the Passenger User’s Guide, I created a tmp/ directory under the root of the Ramaze app. Passenger needs this directory (see the User Guide if you want to know why). I also made a public/ directory, which is a standard part of Ramaze apps in general.

Afterwards, I crafted a basic one-file Ramaze app in start.rb (the standard filename for the executable in Ramaze apps), and a config.ru file, which is needed by Rack. (Rack is the interface layer between Ramaze and Apache.)

start.rb

require 'ramaze'
class MainController < Ramaze::Controller
  def index
    'hi'
  end
end

A critical thing to note about this Ramaze app is that there is no Ramaze.start command. If you put it, the whole jalopy will fall apart — so don’t put that in your app. If you have a legacy app that you want to start running under Passenger, comment out or remove the existing Ramaze.start line.

config.ru

require 'start'
Ramaze.trait[:essentials].delete Ramaze::Adapter
Ramaze.start!
run Ramaze::Adapter::Base

This is the standard “rackup” file that comes with Ramaze. I didn’t make any changes to it, but I should point out that the rackup file that was shown on the Passenger site was out of date.

Overview

So, to recap, my basic little app had these four things:

  public/
  tmp/
  config.ru
  start.rb

Install Passenger

If you are intending to run a Ramaze app under a web host that already offers Passenger to its users, you can obviously skip this section.

As per the Install page of the Passenger website, I simply ran

  gem install passenger

and

  passenger-install-apache2-module

I did this as root, but it looks possible to do so as a non-root user. The Passenger installation script was straight forward, and required no interaction on my part other than to confirm my desire to proceed with the installation. It is sufficiently verbose enough for you to see it compile and install things under your /usr/lib/ruby tree. When it’s done, it clearly displays some lines for you to put into your Apache configuration file. In my case:

 LoadModule passenger_module /usr/lib/ruby/..../mod_passenger.so
 PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-2.0.3
 PassengerRuby /usr/bin/ruby18

I obediently pasted that into the main Apache config. It then shows a sample virtual host configuration that you can use as a skeleton:

 <VirtualHost *:80>
    ServerName www.yourhost.com
    DocumentRoot /somewhere/public
 </VirtualHost>

I copied that into my virtual host config file, and adjusted the hostname and changed the document root to the full, absolute path of the public/ directory of my Ramaze app.

Restart Apache

I restarted Apache to get all my configuration changes active.

Run the app

At this point, my Ramaze app was ready to run under Passenger, so I browsed to http://myhostname and saw “hi” displayed, as expected. To see a little detail (or to troubleshoot problems), examine your Apache logs. You should see all output from Ramaze piped there.

I hope this helps people who are trying to run Ramaze under Passenger! If you need further assistance please visit our support channel, #ramaze on the FreeNode IRC network, or try the discussion group.

No related posts.

I was doing some Javascript debugging today, and observed what I think is a design flaw in Firefox (and perhaps in GUI applications in general). The Firefox alert box is modal. From Wikipedia:

a modal window is a child window which requires the user to interact with it before they can return to operating the parent application, thus preventing the workflow on the application main window

Now, the modality of the alert popup is nothing to be too alarmed about, but its inaptness became magnified because I happened to put an alert statement in a loop of sorts, causing 40+ alert boxes to show up. Not all at once; one after another, requiring acknowledgement of each and every one. The killer part: You can’t do anything with Firefox while an alert box is displayed (short of SIGnalling the process). Technically speaking, you have a brief window of a few milliseconds between alert boxes in which you can sneak in a little bit of interaction (a keypress or mouse click).

Overall, the experience was inconvenient at best, irritating at worst.

It brings to mind the general issue with GUI applications where you might be typing or otherwise interacting with an application, and a dialogue box will pop up, interrupting your typing or clicking, and capturing (or discarding) your keystrokes or clicks. This brings up the usability question:

Does any popup deserve to be modal?

I might wager to say: no. I would not be against having message boxes that popped under, with some sort of humble blinking (say, a flashing entry in the taskbar) informing me that something deserves my attention. I can’t think of a time when I was glad to have a popup interrupt my typing. Every single experience was one of annoyance or infuriation.

It was pointed out to me that Firefox add-ons (like NoScript) can help protect you from falling into the trap.

Anyway, it deserves to be said that the clever folks at Opera Software did something right in putting a feature on every alert box: A checkbox to stop the madness if you so desire. Try the demo page again in Opera, and see the difference. It would be good if Firefox did something similar.

No related posts.

“There is no such thing as right or wrong.”
[ ] Right   [ ] Wrong

No related posts.

[the rails devs] over-memoize waaaay too much. some of these methods will be faster running than looking up from memoize. in the case of certain rails code, it seems to be applied to any method that is stable, regardless of complexity or input

apeiros commented that

it’s often overmedication too since a simple def foo; @foo ||= begin; ...longcalc...; end; end would suffice

I do believe that people should not employ memoization too loosely, since I think that if you have a performance problem, you should first try to address it directly rather than blindly treat the symptom simply by slapping a method with the Memoizable mixin.

I asked raggi for an example of the problem, some code that I could run some benchmarks on. He directed my attention to request.rb of the ActionController module. Strolling through the code, I saw a memoized method which did nothing but return a hash value. apeiros and I thought that it couldn’t possibly be faster to memoize code like that, so I set out to benchmark some code.

Benchmark results

• Memoizing this method made it 14.5% slower.
• Rails memoization was 57.8% slower than classic memoization (i.e. @cached_content_length ||= @env['CONTENT_LENGTH'].to_i). Alternatively phrased: classic memoization was more than twice as fast as Rails’.
• The very act of mixing in Memoizable (without memoizing any methods) incurred an 8.3% speed penalty on method execution.

Here are the benchmarking code and the full benchmark results. The code makes use of better-benchmark, my library for statistically correct benchmarking.

So, employ Memoizable judiciously. Look over your method and consider whether memoization will really improve speed or not. It’s not guaranteed to do so in all cases.

No related posts.

It was originally designed to be used with Rails apps, but I saw that there was also a Merb plugin. Not wanting my favourite web framework to be left out, I made a Hoptoad notifier for Ramaze with the help of manveru (the Ramaze lead dev).

Install via Rubygems:

gem install hoptoad-notifier-ramaze --source http://purepistos.net

And usage is dead easy; just two lines:

require 'hoptoad-notifier' Ramaze::Helper::HoptoadNotifier.trait[ :api_key ] = 'your-hoptoad-project-api-key'

I’m already using it with my own Ramaze applications. Enjoy!

No related posts.

Well, reading the blog post piqued my curiosity because Ruby is my favourite programming language, and I’m also a pianist. So I examined the PDF of the piece, and thought that it didn’t look too difficult to play. I thought this might make a fitting next entry in my piano recording series.

So here I present my interpretation and rendition of Dave Thomas’ piece, For Thee. I took some liberties with tempo, as you can see by comparison with the recording linked in his blog post.

Related posts:

1. Chopin – Nocturne Op. 72, No. 1 in E minor
2. Chopin – Prelude Op. 28, No. 4 in E minor