hobo 0.8.5 → 0.8.6

data/taglibs/rapid_lifecycles.dryml

@@ -1,10 +1,22 @@
+<!-- Contains view-layer support for Hobo's lifecycles. Note that lifecycle forms are generated automatically in `app/views/taglibs/auto/rapid/forms.dryml` - this library contains only lifecycle push-buttons. -->
+
+<!-- A push-button to invoke a lifecycle transition either as a page-reload or as an ajax call.
+  
+### Attributes
+
+ - `transition` - the name of the transition to invoke. Required
+ - `update` - one or more DOM IDs of ajax parts to update after the transition
+ - `label` - the label on the button. Defaults to the name of the transition
+
+All of the [standard ajax attributes](/api_taglibs/rapid_forms) are also supported. 
+  -->
 <def tag="transition-button" attrs="transition, update, label"><%= 
     transition = transition.name unless transition.is_a?(String)
     ajax_attributes, html_attributes = attributes.partition_hash(Hobo::RapidHelper::AJAX_ATTRS)
 
     url = object_url(this, transition, :method => :put)
     add_classes!(html_attributes, "transition-button #{transition}-button")
-    label ||= transition.titleize
+    label ||= transition.to_s.titleize
     if update || !ajax_attributes.empty?
       ajax_attributes[:message] ||= label
       func = ajax_updater(url, update, ajax_attributes)
@@ -16,6 +28,11 @@
   %>
 </def>
   
+
+<!-- Renders a div containing transition buttons for every transition available to the current user.
+  
+For example, you could use this on a `Friendship` card: the person invited to have friendship would automatically see 'Accept' and 'Decline' buttons, while the person initiating the invite would see 'Retract'.
+  -->  
 <def tag="transition-buttons">
   <div class="transitions">
     <% this.lifecycle.available_transitions_for(current_user).each do |t| %>

data/taglibs/rapid_navigation.dryml

@@ -1,10 +1,32 @@
-<!-- Navigation
-     Main nav bar, account nav bar (login, signup...), page nav
-  -->
-
-<!--- General Navigation -->
-
-<!-- General purpose navigation bar. Renders a `<ul class="navigation">` -->
+<!-- Support for navigation links, account navigation (log in, out etc.) and pagination navigation. -->
+
+<!-- General purpose navigation bar. Renders a `<ul class="navigation">`. This tag is intended to be used in conunction with `<nav-item>`. The main feature of this pair of tags (over, say, just using a plain `<ul>` list), is that it's easy to have a 'current' CSS class added to the appropriate nav item (so you can highlight the page/section the user is)
+  
+The main navigation in the default hobo app is implemented with `<navigation>` but this tag is also appropriate for any sub-navigation.
+  
+### Attributes
+
+ - `current` - the textual content of the nav item that should have the 'current' CSS class added (see example) 
+ 
+### Example
+
+The normal usage is to define your own navigation tag that calls `<navigation>`.
+
+    <def tag="sub-nav">
+      <navigation merge>
+        <nav-item>Red</nav-item>
+        <nav-item>Green</nav-item>
+        <nav-item>Blue</nav-item>
+      </navigation>
+    </def>
+
+Then in your pages you can call the tag like this
+
+ - On the 'red' page: `<sub-nav current="red"/>`
+ - On the 'green' page:  `<sub-nav current="green"/>`
+ - and so on.
+ 
+   -->
 <def tag="navigation" attrs="current">
   <ul class="navigation" merge-attrs>
     <set-scoped current-navigation="&current">
@@ -13,6 +35,8 @@
   </ul>
 </def>
 
+
+<!-- Renders a single item in a `<navigation>` menu. See [`<navigation`>](/api_tag_defs/navigation). -->
 <def tag="nav-item">
   <% body = parameters.default 
      body = h(this.to_s) if body.blank? -%>
@@ -23,76 +47,41 @@
 </def>
 
 
-<!--- Account Navigation (log in / out / signup) -->
+<!-- Account Navigation (log in / out / signup)
+  
+When logged in, this renders:
+
+ - "Logged in as ..."
+ - Link to account page
+ - Log out link
+
+When not logged in, renders:
+
+ - Log in link
+ - Sign up link
+ 
+This is a simple tag - just look at the source if you need to know more detail.
 
+  -->
 <def tag="account-nav">
-  <dev-user-changer/>
   <do with="&current_user">
     <ul class="navigation account-nav" param>
+      <li if="&RAILS_ENV == 'development'"><dev-user-changer/></li>
       <if test="&logged_in?">
         <li class='nav-item' param="logged-in-as"><a to="&current_user">Logged in as <name/></a></li>
         <li class='nav-item' param="account"><a action="account">Account</a></li>
         <li class='nav-item' param="log-out"><a href="&logout_url">Log out</a></li>
       </if>
       <else>
-        <set user="&Hobo::User.default_user_model"/>
-        <li class='nav-item' param="log-in"><a href="&login_url(user)">Log in</a></li>
-        <li if="&signup_url(user)" class="nav-item" param="sign-up"><a href="&signup_url(user)">Sign up</a></li>
+        <li class='nav-item' param="log-in"><a href="&login_url">Log in</a></li>
+        <li if="&signup_url" class="nav-item" param="sign-up"><a href="&signup_url">Sign up</a></li>
       </else>
     </ul>
   </do>
 </def>
 
 
-<!--- Pagination Navigation -->
-
+<!--- A simple wrapper around the `will_paginate` helper. All options to `will_paginate` are available as attributes -->
 <def tag="page-nav">
   <%= will_paginate this, attributes.symbolize_keys.reverse_merge(:inner_window => 2, :prev_label => "&laquo; Prev") %>
 </def>
-
-
-<def tag="page-n-of-count">
-  Page <%= this.current_page %> of <%= this.page_count %>
-</def>
-
-
-<def tag="previous-page-link">
-  <a if="&this.try.previous_page"
-     href="&url_for(params.merge(:page => this.previous_page))">
-    <do param="default">&laquo; Previous page</do>
-  </a>
-</def>
-
-
-<def tag="next-page-link">
-  <a if="&this.try.next_page"
-     href="&url_for(params.merge(:page => this.next_page))">
-    <do param="default">Next page &raqou;</do>
-  </a>
-</def>
-
-
-<def tag="first-page-link">
-  <a if="&this.try.current_page && this.current_page != 1"
-     href="&url_for(params.merge(:page => 1))">
-    <do param="default">&laquo; First page</do>
-  </a>
-</def>
-
-
-<def tag="last-page-link">
-  <a if="&this.try.current_page && this.current_page != this.page_count"
-     href="&url_for(params.merge(:page => this.page_count))">
-    <do param="default">Last page &raquo;</do>
-  </a>
-</def>
-
-
-<def tag="dev-user-changer">
-  <set user="&Hobo::User.default_user_model"/>
-  <select-menu if="&user && RAILS_ENV == 'development'"
-               first-option="Guest" options="&user.all(:limit => 10).*.login"
-               onchange="location.href = '/dev/set_current_user?login=' + this.options[this.selectedIndex].value"
-               selected="#{current_user.login}"
-               class="dev-user-changer"/>
-</def>

data/taglibs/rapid_pages.dryml

@@ -1,17 +1,34 @@
+<!-- Rapid-Pages provides tags for working with entire pages. It includes the main `<page>` tag which is the starting point for all pages in Rapid, various supporting tags for things such as stylesheet and javascript includes. Also defines the standard error pages for permission-denied and not-found.
+-->
+  
+<!-- The basic page structure for all the pages in a Hobo Rapid application. Providing the doctype, page title, standard stylesheet javascript includes, the ajax progress spinner, default header with app-name, account navigation, main navigation, and live search, empty section for the page content, flash message (if any) and an empty page footer.
+  
+The easiest way to see what this tag does is to look at the source.
+  
+### Attributes
+
+ - `title` - the page title, will have ": `<app-name>`" appended
+ - `full-title` - the full page title. Set this if you do not want the app name suffix.
+  
+-->
 <def tag="page" attrs="title, full-title">
   <% full_title ||= "#{title} : #{app_name}" %>
   <html merge-attrs>
     <head param>
       <title param><%= strip_tags full_title %></title>
       <do param="stylesheets">
+        <!-- note that this is probably overridden in your app/views/taglibs/themes/xxx/xxx.dryml --> 
         <stylesheet name="reset, hobo-rapid"/>
-        <theme-stylesheet/>
+        <theme-stylesheet />
         <stylesheet name="application" param="app-stylesheet"/>
       </do>
 
       <do param="scripts">
         <javascript param name="prototype, effects, dragdrop, controls, lowpro, hobo-rapid"/>
-        <if-ie version="lt IE 7" param="fix-ie6"><javascript name="IE7"/></if-ie>
+        <if-ie version="lt IE 7" param="fix-ie6">
+          <javascript name="IE7"/>
+          <javascript name="ie7-recalc"/>
+        </if-ie>
         <do param="custom-scripts"/>
         <javascript param="application-javascript" name="application"/>
       </do>
@@ -21,9 +38,9 @@
       <set-scoped flash-rendered="&false">
         <ajax-progress param/>
         <header class="page-header" param>
+          <account-nav if="&login_url(Hobo::User.default_user_model)" param/>
           <h1 param="app-name"><a href="#{base_url}/"><app-name/></a></h1>
           <live-search param if="&defined_route? :site_search"/>
-          <account-nav if="&login_url(Hobo::User.default_user_model)" param/>
           <main-nav current="&title" param/>
         </header>
         <section with-flash-messages param="content"/>
@@ -35,7 +52,7 @@
 </def>
 
 
-
+<!-- Renderes dynamically generated JavaScript required by `hobo-rapid.js`, including the information required to perform automatic part updates -->
 <def tag="page-scripts">
   <script type="text/javascript" param="default">
     <hobo-rapid-javascripts/>
@@ -44,12 +61,22 @@
 </def>
 
 
+<!-- nodoc. -->
 <def tag="index-page" polymorphic/>
+<!-- nodoc. -->
 <def tag="new-page"   polymorphic/>
+<!-- nodoc. -->
 <def tag="show-page"  polymorphic/>
+<!-- nodoc. -->
 <def tag="edit-page"  polymorphic/>
 
+<!-- The page rendered by default in the case of a permission-denied error
+  
+### Attributes
 
+ - `message` - The main message to display. Defaults to "That operation is not allowed"
+ 
+  -->
 <def tag="permission-denied-page" attrs="message">
   <% message ||= "That operation is not allowed" %>
   <page merge>
@@ -57,12 +84,25 @@
     <content: param>
       <header param="content-header">
         <h2 param="heading"><message/></h2>
+        <div class="debug" if="&Rails.env.development?">
+          <h3>Exception:</h3>
+          <pre><%= h @permission_error.pretty_inspect %></pre>
+          <h3>params:</h3>
+          <pre><%= h params.pretty_inspect %></pre>
+        </div>
       </header>
     </content:>
   </page>
 </def>
 
 
+<!-- The page rendered by default in the case of a not-found error
+  
+### Attributes
+
+ - `message` - The main message to display. Defaults to "The page you were looking for could not be found"
+ 
+  -->
 <def tag="not-found-page" attrs="message">
   <% message ||= "The page you were looking for could not be found" %>
   <page merge>
@@ -76,6 +116,20 @@
 </def>
 
 
+<!-- Renders one of five HTML DOCTYPE declarations, according to the `version` attribute.
+  
+### Attributes
+ - 'version' - the doctype version, must be one of:
+ 
+   - HTML 4.01 STRICT
+   - HTML 4.01 TRANSITIONAL
+   - XHTML 1.0 STRICT
+   - XHTML 1.0 TRANSITIONAL
+   - XHTML 1.1
+  
+See the source for the actual output
+
+ -->
 <def tag="doctype" attrs="version"><%=
   case version.upcase
     when "HTML 4.01 STRICT"
@@ -96,6 +150,13 @@
   end
 %></def>
 
+
+<!-- Renders an `<html>` tag along with the DOCTYPE specified in the `doctype` attribute.
+  
+### Attributes
+ 
+ - `doctype` - the version of the DOCTYPE required. See the `version` attribute to `<doctype>`
+ -->
 <def tag="html" attrs="doctype">
   <% doctype ||= 'XHTML 1.0 TRANSITIONAL' -%>
   <doctype version="&doctype"/>
@@ -106,27 +167,51 @@
 </def>
 
 <!-- empty tags should be written as <br> in HTML and <br /> in XHTML -->
+<!-- nodoc. -->
 <def tag="empty-tag" attrs="tag-name"><%= element(tag_name, attributes, nil, true, true) %></def>
+<!-- nodoc. -->
 <def tag="base"><empty-tag tag-name="base" merge/></def>
+<!-- nodoc. -->
 <def tag="meta"><empty-tag tag-name="meta" merge/></def>
+<!-- nodoc. -->
 <def tag="link"><empty-tag tag-name="link" merge/></def>
+<!-- nodoc. -->
 <def tag="img"><empty-tag tag-name="img" merge/></def>
+<!-- nodoc. -->
 <def tag="br"><empty-tag tag-name="br" merge/></def>
+<!-- nodoc. -->
 <def tag="hr"><empty-tag tag-name="hr" merge/></def>
+<!-- nodoc. -->
 <def tag="frame"><empty-tag tag-name="frame" merge/></def>
+<!-- nodoc. -->
 <def tag="area"><empty-tag tag-name="area" merge/></def>
+<!-- nodoc. -->
 <def tag="param"><empty-tag tag-name="param" merge/></def>
+<!-- nodoc. -->
 <def tag="col"><empty-tag tag-name="col" merge/></def>
 
+
+<!-- Renders a conditional comment in order to have some content ignored by all browsers other than Internet Explorer
+  
+### Example 
+
+
+    <if-ie version="lt IE 7"> ... </if-ie>
+    
+ -->
 <def tag="if-ie" attrs="version">
   <%= "<!--[if #{version || 'IE'}]>" %><do param="default"/><%= "<![endif]-->" %>
 </def>
 
+<!-- Simple wrapper for the `stylesheet_link_tag` helper. The `name` attribute can be a comma-separated list of stylesheet names.
+ -->
 <def tag="stylesheet" attrs="name">
   <%= stylesheet_link_tag *(comma_split(name) + [attributes]) %>
 </def>
 
 
+<!-- Simple wrapper for the `javascript_include_tag` helper. The `name` attribute can be a comma-separated list of script file names.
+ -->
 <def tag="javascript" attrs="name">
   <if test="&name.is_a?(Symbol)">
     <%= javascript_include_tag name %>
@@ -139,36 +224,35 @@
 </def>
 
 
+<!-- Renders a Rails flash message wrapped in a `<div>` tag
+
+### Attributes
+
+ - `type` - which flash message to display. Defaults to `:notice`
+  
+### CSS Classes
+
+The flash is output in a `<div class="flash notice">`, where `notice` is the `type` specified.
+
+  -->
 <def tag="flash-message" attrs="type">
   <% type = type ? type.to_sym : :notice -%>
   <div class="flash #{type}" if="&flash[type]" merge-attrs><%= flash[type] %></div>
 </def>
 
 
+<!-- Renders `<flash-message>` for every flash type given in the `names` attribute (comma separated), or for all flash messages that have been set if `names` is not given -->
 <def tag="flash-messages" attrs="names"><%=
   scope.flash_rendered = true
   names = names.nil? ? flash.keys : comma_split(names)
   names.map { |name| flash_message :type => name }
 %></def>
 
+<!-- Renders `<div id="ajax-progress"><div><span id="ajax-progress-text"></span></div></div>`. The theme will style this as an ajax progress 'spinner' -->
 <def tag="ajax-progress">
-  <div id="ajax-progress">
+  <div id="ajax-progress" merge-attrs>
     <div>
       <span id="ajax-progress-text"></span>
     </div>
   </div>
 </def>
-
-
-<def tag="default-page-title"><%= t = this.to_s; ; "#{t.blank? ? '' : t + ' - '}#{app_name}" %></def>
-
-
-<def tag="with-primary-collection" attrs="name"><%
-  ivar = "@#{this.class.name.underscore}_#{name}"
-    
-  if (collection = instance_variable_get(ivar))
-    %><do with="&collection" param="default"/><%
-  else
-    %><do field="&name" param="default"/><%
-  end
-%></def>

data/taglibs/rapid_plus.dryml

@@ -1,6 +1,15 @@
+<!-- Tags that define higher level interactive 'widgets' -->
+
+<!-- An enhanced version of Rapid's `<table>` that has support for column sorting, searching and pagination.
+  
+This tag calls `<table merge-params>`, so the parameters for `<table>` are also available.
+
+An [worked example](/tutorials/agility#improve_the_project_page_with_a_searchable_sortable_table) of this tag is available in the [Agility Tutorial](/tutorials/agility)
+
+-->
 <def tag="table-plus" attrs="sort-field, sort-direction, sort-columns" >
   <% sort_field ||= @sort_field; sort_direction ||= @sort_direction; sort_columns ||= {} %>
-  <% sort_columns['this'] ||= this.member_class.name_attribute %>
+  <% sort_columns['this'] ||= this.member_class.try.name_attribute %>
   <div class="table-plus" merge-attrs="&attributes - attrs_for(:with_fields) - attrs_for(:table)">
     <div class="header" param="header">
       <div class="search">
@@ -41,15 +50,34 @@
 </def>
 
 
+<!-- An enhanced version of Rapid's `<collection>` tag that supports drag-and-drop re-ordering. 
+  
+Each item in the collection has a `<div class="ordering-handle" param="handle">` added, which can be used to drag the item up and down.
+  
+### Attributes
+
+ - `sortable-options` - a hash of options to pass to the `sortable_elemnt` helper. Default are:
+
+        { :constraint => :vertical,
+          :overlap => :vertical,
+          :scroll => :window,
+          :handle => 'ordering-handle',
+          :complete => [visual_effect(:highlight, attributes[:id])] }
+          
+### Controller support 
+
+This tag assumes the controller has a `reorder` action. This action is added automatically by Hobo's model-controller if the model declares `acts_as_list`. See also [Drag and Drop Reordering](/manual/controllers#drag_and_drop_reordering) in the [Controllers and Routing](/manual/controllers) chapter of the manual.
+ -->
 <def tag="sortable-collection" attrs="sortable-options"><%
   singular_name = this.member_class.name.underscore
   attributes[:id] ||= "#{singular_name}_ordering"
-  reorder_url = send("reorder_#{singular_name.pluralize}_url")
+  route_method = subsite ? "#{subsite}_reorder_#{singular_name.pluralize}_url" : "reorder_#{singular_name.pluralize}_url"
+  reorder_url = send(route_method)
 %>
   <collection class="sortable" merge>
     <item: id="#{singular_name}_#{this.id}" param>
       <div class="ordering-handle" param="handle">&uarr;<br/>&darr;</div>
-      <card param/>
+      <do param="default"><card param/></do>
     </item:>
   </collection>
   <%= if Hobo::Dryml.last_if
@@ -67,6 +95,7 @@
 </def>
 
 
+<!-- Captures the common pattern of a list of "the first few" cards, along with a link to the rest. -->
 <def tag="preview-with-more" attrs="name">
   <% name ||= collection_name.pluralize -%>
   <section class="#{name.gsub(' ', '-').dasherize} preview-with-more" param="default">
@@ -77,12 +106,21 @@
 </def>
 
 
+<!-- Renders a gravatar (see [gravatar.com](http://gravatar.com)) image in side a link to `this`. Requires `this` to have an `email_address` field. Normally called with a user record in context.
+
+### Attributes 
+
+ - `size` - Size in pixels of the image. Defaults to 80.
+ - `rating` - The rating allowed. Defaults to 'g'. See [gravatar.com](http://gravatar.com) for information on ratings.
+
+ -->
 <def tag="gravatar" attrs="size, rating">
   <% size ||= 80; rating ||= 'g'; digest = Digest::MD5.hexdigest(this.email_address) -%>
   <a class="gravatar"><img class="gravatar" src="http://www.gravatar.com/avatar/#{digest}?s=#{size}&r=#{rating}" merge-attrs/></a>
 </def>
 
 
+<!-- Provides an ajax-powered *find-as-you-type* live search field which is hooked up to Hobo's site-side search feature. At the moment this tag is not very flexible. It is not easy to use if for anything other than Hobo's site-wide search. -->
 <def tag="live-search">
   <div class="search">
     <label for="search-field">Search</label><input type="search" class="live-search"/>
@@ -94,12 +132,22 @@
   </section>
 </def>
 
+<!-- A `<select>` menu intended to act as a filter for index pages.
+  
+See [Filtering stories by status](/tutorials/agility#filtering_stories_by_status) in the [Agility Tutorial](/tutorials/agility) for an example.
+
+### Attributes
 
-<def tag="filter-menu" attrs="param-name, options, no-filter">
+ - `param-name` - the name of the HTTP parameter to use for the filter
+ - `options` - an array of options for the menu. 
+ - `no-filter` - The text of the first option which indicates no filter is in effect. Defaults to 'All'
+  -->
+<def tag="filter-menu" attrs="param-name, options, no-filter, id">
   <% no_filter ||= "All" %>
-  <form action="&request.request_uri" method="get" class="filter-menu">
+  <form action="&request.request_uri" method="get" class="filter-menu" merge-attrs="id">
     <div>
-      <select-menu name="&param_name" options="&options" selected="&params[param_name.gsub('-', '_')]"
+      <% selected = options.detect {|o| o.to_s==params[param_name.gsub('-', '_')] } %>
+      <select-menu name="&param_name" options="&options" selected="&selected"
                    first-option="&no_filter" merge-params/>
     </div>
   </form>