Kwartz-Ruby Users' Guide

release: $Release$

3   Ruby on Rails Support

This section shows how to use Kwartz with Ruby on Rails. See 'examples/rails1' and 'examples/rails2' for examples.


3-1   Support of Ruby on Rails

If you want to use Kwartz with Ruby on Rails, add the following code in your 'app/controllers/application.rb' and restart web server.

require 'kwartz/helper/rails'
ActionView::Base.register_template_handler('html', Kwartz::Helper::RailsTemplate)
#Kwartz::Helper::RailsTemplate.lang = 'rails'    # or eruby/ruby/erubis/pierubis
#Kwartz::Helper::RailsTemplate.pdata_suffix  = '.html'
#Kwartz::Helper::RailsTemplate.plogic_suffix = '.plogic'
#Kwartz::Helper::RailsTemplate.default_properties = { :escape=>false }
#Kwartz::Helper::RailsTemplate.use_cache = true
#Kwartz::Helper::RailsTemplate.debug = true

Layout files ('app/views/layouts/xxx.{html,plogic}') are also available. The following is an example to use layout files.

    <h1 id="page_title"></h1>
    <div id="page_content">
      <ul id="mark:list">
        <li id="mark:item"></li>
#list {
  logic: {
    for item in @list

#item {
  value:  item;
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
  <title id="mark:header_title"></title>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">

  <h1 class="title" id="replace_content_with_content:page_title"> title...</h1>
  <div id="replace_element_with_content:page_content"> content...

  <p>copyright&copy; 2006 all rights reserved.</p>

#header_title {
  cont:  'Member: ' + controller.action_name;

See the 'examples/rails2' directory for example of using Kwartz with Ruby on Rails.

3-2   link_to() method in Ruby on Rails

link_to() method in Ruby on Rails is a little incompatible with Kwartz because you must specify link label in both presentation data and presentation logic. It's not DRY.

presentation data
<a href="#" id="mark:link_to_new">Create new recipe</a>
presentation logic
#link_to_new {
  elem:  link_to 'Create new recipe', :action=>'new';

It is recommended to use start_link_tag() and start_remote_link_tag() instead of link_to() and link_to_remote() because the formers print only start tag of anchor.

presentation data
<a href="#" id="mark:link_to_new">Create new recipe</a>
presentation logic
#link_to_new {
  stag:  start_link_tag :action=>'new', :controller=>'recipes';
expected result
<a href="/recipes/new">Create new recipe</a>

To use start_link_tag() and start_remote_link_tag(), include Kwartz::Helper::ActionViewHelper to ApplicationHelper module in 'app/helpers/application_helper.rb'.

require 'kwartz/helper/rails'
module ApplicationHelper
  include Kwartz::Helper::ActionViewHelper

The following is the definition of start_link_tag() and start_remote_link_tag(). They are defined in Kwartz::Helper::ActionViewHelper module which is defined in 'kwartz/helper/rails.rb'.

definition of start_link_tag() and start_remote_link_tag()
module Kwartz::Helper::ActionViewHelper

  def start_link_tag(options = {}, html_options = nil, *parameters_for_method_reference)
    s = link_to('', options, html_options, *parameters_for_method_reference)
    s.sub!(/<\/a>\z/, '')
  alias anchor start_link_tag

  def start_remote_link_tag(options = {}, html_options = {})
    s = link_to_remote(options, html_options)
    s.sub!(/<\/a>\z/, '')
  alias anchor_remote start_remote_link_tag


3-3   Layout Option in Controller

  • layout() is available.
    class MemberController < ApplicationController
      layout 'members2', :except=>['show', 'edit']
  • render() with :layout parameter is available.
    class MemberController < ApplicationController
      def list
        @member_pages, @members = paginate :members, :per_page => 10
        render :layout => 'members2'

3-4   Scaffold Kwartz Template

There is no 'generate scaffold' script for Kwartz template. Instead, use Kwatable.

Kwatable is a script to generate severail files (SQL, DTO, Kwartz template, and so on) from table definition file. It's more sophisticated than Rails' scaffold generating script.

3-5   Rails Helper Methods

(Notice: this is experimental feature. The spec may be changed in the future.)

It is able to embed Rails' helper method in kw:d attribute.

## text_field, password_field
<input type="text" size="10" maxsize="20" kw:d="text_field 'user', 'name'">
 => <%= text_field 'user', 'name', :size=>10, :maxsize=>20 %>
<input type="text" name="user[name]" kw:d="text_field :size=>10">
 => <%= text_field "user", "name", :size=>10 %>
<input type="text" id="user_name" size="10" kw:d="text_field">
 => <%= text_field "user", "name", :size=>10 %>

## link_to, link_to_remote
<a href="#" kw:d="link_to :action=>'list'">Show list</a>
 => <%= link_to 'Show list', :action=>'list' %>

## start_link_tag, start_remote_link_tag
<a href="#" kw:d="start_link_tag :action=>'list'">Show list</a>
 => <%= start_link_tag 'action'=>'list' %>Show list</a>

## mail_to
<a href="" kw:d="mail_to">admin</a>
 => <%= mail_to "", "admin" %>

## form_tag
<form action="show" kw:d="form_tag :id=>2"> ... </form>
 => <%= form_tag :action=>"show", :id=>2 %> ... </form>

## submit_tag
<input type="submit" value="OK" kw:d="submit_tag">
 => <%= submit_tag "OK" %>

## text_area
<textarea cols="30" rows="3" id="user_desc" kw:d="text_area"></textarea>
 => <%= text_area "user", "desc", :cols=>30, :rows=>3 %>
<textarea cols="30" rows="3" name="user[desc]" kw:d="text_area"></textarea>
 => <%= text_area "user", "desc", :cols=>30, :rows=>3 %>

## hidden_field
<input type="hidden" id="user_id" kw:d="hidden_field">
 => <%= hidden_field "user", "id" %>
<input type="hidden" name="user[id]" kw:d="hidden_field">
 => <%= hidden_field "user", "id" %>

## check_box
<input type="checkbox" id="user_chk1" kw:d="check_box">
 => <%= check_box "user", "chk1" %>
<input type="checkbox" name="user[chk2]" kw:d="check_box">
 => <%= check_box "user", "chk2" %>

## radio_button
<input type="radio" id="user_radio" value="val1" kw:d="radio_button">
 => <%= radio_button "user", "radio", "val1" %>
<input type="radio" name="user[radio]" value="val2" kw:d="radio_button">
 => <%= radio_button "user", "radio", "val2" %>

## select, collection_select, country_select, time_zone_select, date_select, datetime_select
<select name="user[birth]" kw:d="date_select :start_year=>1970">
  <option value="2000">2000</option>
 => <% date_select "user", "birth", :start_year=>1970 %>

## image_tag, link_image_to, link_to_image
<img src="foo.gif" alt="text" width="20" heigth="10" kw:d="image_tag :size=>'30x40'">
 => <%= image_tag "foo.gif", :alt=>"text", :size=>'30x40' %>