Hobo 1.4 Changes
{: .document-title}

Documents the changes made in Hobo 1.4 and the changes required to
migrate applications to Hobo 1.4

Contents
{: .contents-heading}

- contents
{:toc}

# Installation

## Creating a new application

Hobo 1.4 gems have not yet been released, so the standard instructions
of "gem install hobo; hobo new foo" do not yet work.

If you're on Linux you'll have to install a javascript runtime.
On Ubuntu 11.10 you can get one by typing `apt-get install
nodejs-dev`.  Other Linuxes should be similar.  Windows & OS X users
should already have a javascript scripting host installed.  The list
of compatible javascript runtimes is [here](https://github.com/sstephenson/execjs).

Next you'll need to download the hobo source

    git clone git://github.com/tablatom/hobo

Now you have two options: create gems, or use the source.

### Via gems

    cd hobo
    rake gems[install]
    cd wherever-you-want-to-generate-your-app
    hobo new foo

Once you've generated an app, you may wish to go in and replace the
version strings for the hobo_* gems with `:git => "git://github.com/tablatom/hobo"

### Via source

(This won't work on Windows)

    export HOBODEV=`pwd`/hobo
    $HOBODEV/hobo/bin/hobo new foo

## Updating an existing installation

There are several changes that need to be made to your application to
upgrade from Hobo 1.3 to Hobo 1.4.   Most of these changes are
required by the addition of the asset pipeline which was introduced in
Rails 3.1.

Follow the asset pipeline upgrade steps outlined here:
http://guides.rubyonrails.org/asset_pipeline.html#upgrading-from-old-versions-of-rails

The easiest way to upgrade an existing Hobo 1.3 application is to
generate a new Hobo 1.4 application and copy differences from the new
app into your existing app.

### Gemfile

You'll need to add the gems required for the asset pipeline, add the
jquery-rails and jquery-ui-themes gem, and adjust the version numbers
for rails, hobo and perhaps others.

Hobo has also gained several additional gems, so you will have to add
dependencies for those.  hobo_rapid is the Hobo tag library,
hobo_jquery is the javascript for hobo_rapid, and hobo_clean is the
default theme.   Instead of or as well as hobo_clean you can use
hobo_clean_admin or hobo_clean_sidemenu.  Hopefully there will be
additional themes available soon.

### config/

All of the changes in config/ are due to the assets pipeline.  See
http://guides.rubyonrails.org/asset_pipeline.html#upgrading-from-old-versions-of-rails

Additionally, the Hobo 1.4 generator installs the
[rails-dev-tweaks](https://github.com/wavii/rails-dev-tweaks) gem.  We
adjust the configuration so that rails-dev-tweaks applies only to
assets, not to XHR.

### application.dryml or front_site.dryml

Replace

    <set-theme name="clean"/>

with

    <include gem='hobo_rapid'/>
    <include gem='hobo_jquery'/>
    <include gem='hobo_clean'/>

Note that the default Hobo generation now always creates both a
front_site.dryml and an application.dryml, even if you don't create
any subsites.

### move public/ to app/assets/

In Rails 3.1, images, javascripts and stylesheets are loaded from
app/assets/ rather than from public/ so you'll have to move them.
Note that the following are Rails and/or Hobo assets that are now
included via the pipeline and can be deleted rather than moved:

    images/rails.png
    hobothemes/**
    javascripts/controls.js,dryml-support.js,hobo-rapid.js,ie7-recalc.js,prototype.js,blank.gif,dragdrop.js,effects.js,IE7.js,lowpro.js,rails.js
    stylesheets/reset.css,hobo-rapid.css

Note how Hobo organizes the app/assets directory.   There will be a
directory called app/assets/javascripts/application/ and a directory
called app/assets/javascripts/front/.   If you have added a subsite
called admin there will also be a directory called
app/assets/javascripts/admin/.   Any files in application/ will always
be included, and the files in front/ or admin/ will be included only
on the corresponding subsite.

# Changes from Hobo 1.3 & hobo-jquery 1.3

## Javascript framework changed to jQuery

Hobo 1.3 and earlier versions used prototype.js for its Ajax support.
In Hobo 1.4 all of our javascript code has been rewritten to use
jQuery instead of prototype.js.

In the process of rewriting the code many tags have been updated to
add AJAX support, and tags that used non-standard AJAX mechanisms have
been updated to use standard Hobo form AJAX.   The most visible of
these changes have been to the editors.

## The Asset Pipeline

Hobo 1.4 uses the asset pipeline features introduced in Rails 3.1.
Hobo 1.4 does not work out of the box with the asset pipeline turned
off.  It'd certainly be possible to copy all Hobo assets into public/,
but you would have to do that manually.

## :inverse_of recommended

For correct behaviour, please ensure that all accessible associations
have their :inverse_of option set in both directions.

## set-theme deprecated

The old Hobo theme support has never worked well, and has been
replaced.   Themes are now Hobo plugins and work like every other Hobo
1.4 plugin.

Replace:

    <set-theme name="clean"/>

with

    <include gem="hobo_clean"/>

and add

    *= require hobo_clean

to your app/assets/stylesheets/front.css.  Some themes may also
include javascript which would require them to be added to front.js as
well.

## default doctype changed

The default doctype has been changed from `XHTML 1.0 TRANSITIONAL` to
`html`, also known as "standards mode" in Internet Explorer 8 and 9
and "html5" in other browsers.

## default field-list changed

The default for `<field-list>` has changed to `<feckless-fieldset>`.
The old behaviour is still available in `<field-list-v1>`.   Please
provide feedback: we are open to reversion before final release.

## Helper rearrangement

In previous versions of Hobo, all Hobo helpers were available in both
the controllers and the views.   In this version, some helpers are
only available in the views.   If there is a helper function that you
need to access in your controller, you can call in your controller:

    HoboTypeHelper.add_to_controller(self)

Other Helper classes not included in the controller by default are
HoboDebugHelper, HoboDeprecatedHelper and HoboViewHintHelper.

Several helpers have been moved into
app/helpers/hobo_deprecated_helper.rb

If your application depends on any of these, you can set
config.hobo.include_deprecated_helper.

## Rails 3.1 required

Hobo 1.4 currently requires Rails 3.1 for operation.  We expect to be
on Rails 3.2 before final release.

## Enhancements

### Nested caching

See the docs for `<nested-cache>` and the blog post I'm going to
eventually write...

### push-state

AJAX now supports a new AJAX option 'push-state' if you have
History.js installed.   It was inspired by [this
post](http://37signals.com/svn/posts/3112-how-basecamp-next-got-to-be-so-damn-fast-without-using-much-client-side-ui)
which uses push-state and fragment caching to create a very responsive
rails application.    Hobo has always supported fragment caching
through Rails, but push-state support is new.

The easiest way to install History.js is to use the [jquery-historyjs](https://github.com/wweidendorf/jquery-historyjs)
gem.  Follow the instructions in the [README at the
link](https://github.com/wweidendorf/jquery-historyjs).

push-state blurs the line between AJAX and non-AJAX techniques,
bringing the advantages of both to the table.   It's considerably more
responsive than a page refresh, yet provides allows browser bookmarks
and history navigation to work correctly.

For example, if the foos and the bars pages have exactly the same
headers but different content, you can speed up links between the
pages by only refreshing the content:

    <%# foos/index.dryml %>
    <index-page>
      <content:>
        <do part="content">
          <a href="&bars_page" ajax push-state new-title="Bars">Bars</a>
          ...
        </do>
      </content:>
    <index-page>

Note to Hobo 1.3 users: We're using the new `ajax` attribute instead of
`update="content"` because the link is inside the part.  Outside of the
part we'd use `update="content"` instead of `ajax`.

The `new-title` attribute may be used with push state to update the
title.  If you want to update any other section in your headers, you
can put that into a part and list it in the update list as well.
However the new page cannot have new javascript or stylesheets.
Avoiding the refresh of these assets is one of the major reasons to
use push-state!

push-state is well suited for tasks that refreshed the current page
with new query parameters in Hobo 1.3, like `filter-menu`, pagination and
sorting on a `table-plus`.  Thus these tags have been updated to
support all of the standard ajax attributes.

Of course, ajax requests that update only a small portion of the page
will update faster than those that update most of the page.   However,
a small update may mean that a change to the URL is warranted, so you
may want to use standard Ajax rather than push-state in those cases.
Also, push-state generally should not be used for requests that modify
state

push-state works best in an HTML5 browser.  It works in older browsers
such as IE8, IE9 or Firefox 3, but results in strange looking URL's.   See
the README for History.js for more details on that behaviour.

### plugin generators

Hobo has gained two new generators.

`hobo generate install_plugin` may be used from inside a Hobo
application to install a Hobo plugin.   It modifies the Gemfile,
application.dryml or X_site.dryml and adds the plugin to
app/assets/javascripts and app/assets/stylesheets.

`hobo plugin` is used from outside of a Hobo application to create the
skeleton for a new plugin.   See [the plugin manual page](FIXME) for
more details.

### multiple parts

I've updated DRYML so that it emits a different DOM ID if you
re-instantiate a part.  (The first use of a part retains the DOM
ID=partname convention for backwards compatibility) "update=" requires
a DOM ID, so I've also added 2 new AJAX attributes that can be used
instead of "update=".

The first one is "updates=".  Instead of a comma separated list of DOM
ID's, it takes a CSS selector.

The other one is "ajax".  If used inside of a part, it indicates that
the containing part should be updated.  If used outside of a part,
AJAX will be used but no parts will be updated.

These three Ajax attributes may be used simultaneously.

Example:

    <collection:stories>
       <div part="inner">
          <form ajax>
             <input:title/>
          </form>
       </div>
     </collection>

### allowing errors in parts

Older versions of Hobo did not render a part update if the update did
not pass validation.

This behaviour may now be overridden by using the 'errors-ok'
attribute on your form.  (or formlet or whatever other tag initiates
the Ajax call).

The 'errors-ok' attribute is processed in update_response.   If you've
supplied a block to hobo_update you will be responsible for
implementing this functionality yourself.

### AJAX file uploads

If you have malsup's form plugin installed, Ajax file uploads should
"just work", as long as you don't have debug_rjs turned on in your
config/initializers/development.rb.

### AJAX events

The standard 'before', 'success', 'done' and 'error' callbacks may
still be used.   Additionally, the AJAX code now triggers
'rapid:ajax:before', 'rapid:ajax:success', 'rapid:ajax:done' and
'rapid:ajax:error' events to enable you to code more unobtrusively.

If your form is inside of a part, it's quite likely that the form will
be replaced before the rapid:ajax:success and rapid:ajax:done events
fire.  To prevent memory leaks, jQuery removes event handlers from all
removed elements, making it impossible to catch these events.
If this is the case, hobo-jquery triggers these events on the document
itself, and passes the element as an argument.

      $(document).ready(function() {
         jQuery(document).on("rapid:ajax:success", function(event, el) {
            // `this` is the document and `el` is the form
            alert('success');
         });
      });

### before callback

A new callback has been added to the list of Ajax Callbacks: before.
This callback fires before any Ajax is done.   If you return false
from this, the Ajax is cancelled.  So you should probably ensure you
explicitly return true if you use it and don't want your ajax
cancelled.

### callbacks

Normally in HTML you can attach either a snippet of javascript or a
function to a callback.

    <button onclick=fbar/>

This doesn't work in DRYML because the function is not defined in
Ruby, it's only defined in Javascript.

In Hobo 1.3 you would thus be forced to do this to get equivalent behaviour:

    <form update="foo" success="return fbar.call(this);"/>

Now you can just return the function name:

    <form ajax success="fbar"/>

### `hide` and `show` ajax options

There are two new ajax options: `hide` and `show`.  These are passed
directly to the jQuery-UI `hide` and `show` functions.  See
(here)[http://jqueryui.com/demos/show/] and
(here)[http://docs.jquery.com/UI/Effects] for more documentation on
these two functions.  Due to ruby to javascript translation
difficulties, you may not drop optional middle parameters.

Examples:

     <form ajax hide="puff,,slow" show="&['slide', {:direction => :up}, 'fast', 'myFunctionName']/>

     <form ajax hide="drop" show="&['slide', nil, 1000, 'alert(done);']"/>

These two options have global defaults which are TBD.  They may be overridden by passing options to the page-script parameter of `<page>`:

     <extend tag="page">
       <old-page merge>
         <page-scripts: hide="&['slide',{:direction => :up}, 'fast']" show="&['slide',{:direction => :up},'fast']"/>
       </old-page>
     </extend>

To disable effects entirely:  FIXME.

### spinner options

By default, the spinner is now displayed next to the element being
updated.  Besides the old `spinner-next-to` option, there are a number
of new options that control how the spinner is displayed.

- spinner-next-to: DOM id of the element to place the spinner next to.
- spinner-at: CSS selector for the element to place the spinner next to.
- no-spinner: if set, the spinner is not displayed.
- spinner-options: passed to [jQuery-UI's position](http://jqueryui.com/demos/position/).   Defaults are `{my: 'right bottom', at: 'left top'}`
- message: the message to display inside the spinner

These options may be overridden globally by adding them as attributes to the `page-scripts` parameter for the page.

     <extend tag="page">
       <old-page merge>
         <page-scripts: spinner-at="#header" spinner-options="&{:my => 'left top', :at => 'left top'}" />
       </old-page>
     </extend>

### hjq-datepicker

hjq-datepicker now automatically sets dateFormat to the value
specified in your translations:  (I18n.t :"date.formats.default").

### sortable-collection

sortable-collection now supports the standard Ajax callbacks

### delete-button

The new `delete-button` behaviour is not as much different from the
old `delete-button` as a comparison of the documentation would have
you believe, however its Ajax triggering behaviour has changed slightly.

The `fade` attribute is no longer supported.   Instead use the new
standard ajax attribute `hide`.

### autocomplete

`hjq-autocomplete` has been renamed to `autocomplete`.  It has gained
the attribute `nil-value` and the ability to work with the standard
Hobo autocomplete and hobo_completions controller actions.

`name-one` is now a simple backwards-compatibility wrapper around
`autocomplete`.

### input-many

`hjq-input-many` and `input-many` have been merged into `input-many`.
The new standard ajax attributes `hide` and `show` are also now
supported.

Differences from old `input-many`:

- supports hobo-jquery delayed initialization.
- new attributes: add-hook, remove-hook, hide, show

Differences from `hjq-input-many`:

- name of the main parameter is `default` rather than `item`.
- rapid:add, rapid:change and rapid:remove events added.
- new attributes: hide, show

### filter-menu

filter-menu now accepts AJAX attributes.

### a

the a tag now accepts AJAX attributes.  This is especially useful with
the new 'push-state' option.

### dialog-box

`hjq-dialog` has been renamed to `dialog-box`.  (`dialog` has already
been taken in HTML5).

The helper functions have been renamed.   For instance,
`hjq.dialog.formletSubmit` has been renamed to
`hjq_dialog_box.submit`.

Dialog positioning has been updated and should work better now.   See
the documentation for more details.

### live-search

`live-search` works in a substantially different fashion now, it has
almost completely lost its magic, instead using standard ajax forms
and parts.   It should now be possible to customize using standard
Hobo techniques.   See the documentation for `<live-search>` and
`<search-results>` for more details.

`live-search` has temporarily lost it's live-ness.  Currently you have
to press 'return' to initiate the search.  This should be easy to fix
in hjq-live-search.js -- the hard part will probably be in doing it in
a way that works in all possible browsers.

### hot-input

see tag documentation

### page-nav

The params attribute now defaults to
recognize_page_path.slice(:controller,:action,:id).

Standard form ajax attributes are now also supported, and behave
similar to `<a>`.

### query_params

The old query_params helper has been removed.   You can use
Rails (request.query_parameters | request.request_parameters) instead
if you still need it.

There's a new helper function called query_parameters_filtered that
returns query parameters with the ajax parameters removed.

## Editors

Editors are no longer special-cased, they now use the standard DRYML
part mechanism.

There are two types of editors: `<click-editor>` and `<live-editor>`.
click-editor is the click-to-edit type of control similar to what
Rapid currently uses for a string, and live-editor always renders the
input, and is similar to what Rapid currently uses for Boolean's and
enum-strings.

Please refer to the documentation for `click-editor` and `live-editor`
for more details.

`<editor>` is now a polymorphic input that uses either `<click-editor>` or
`<live-editor>`.

TBD: Right now live-editor and click-editor use `<formlet>`.  The
major advantage of formlet is that it is safe to use inside of a form.
I can't think of any good use cases for that behaviour, but it does
seem like something people might do by accident.

The alternative is to use `<form>`.   Since this implementation of
editor starts with an input and switches to a view via Javascript,
using a form would allow reasonable javascript-disabled behaviour.

## Changes behind the scenes

### reloading of part context

[This change](https://github.com/tablatom/hobo/commit/6048925) ensures that
DRYML does not reload the part context if it is already in `this`.

### i18n

These commits will require translation updates for languages other
than English.  (Presumably this list will get larger because right now
the change is one I could do myself...)

- https://github.com/tablatom/hobo/commit/e9460d336ef85388af859e5082763bfae0ad01f5

### controller changes

Due to limitations on Ajax file uploads, multipart forms are not sent with the proper Ajax headers.   If your controller action may receive multipart forms, rather than using:

    respond_to do |wants|
      wants.js { hobo_ajax_response }
      wants.html {...}
    end

use

    if request.params[:render]
      hobo_ajax_response
    else
      ....
    end

for more information see http://jquery.malsup.com/form/#file-upload

### hobo_ajax_response

the `hobo_ajax_response` function now has a different signature.
Standard usage doesn't supply any arguments to hobo_ajax_response.
This use case has not changed.

However, if you have code that supplied arguments to
hobo_ajax_response, that code likely will need to be updated for 1.4.

FIXME: pointer to AJAX background documentation.

### Dryml.render

Dryml.render now has an additional argument: imports.   The template
environment no longer automatically imports ActionView::Helpers.

### View helpers imported

All application helpers are now available in the template
environment.

# jQuery rewrite

FIXME: pull into separate document, along with interface specs

## Framework Agnosticism

jQuery support is being written in a manner that should make it easier to support other frameworks if we ever decide to do so.   Basically all this means is that we're annotating our HTML and the javascript is picking up the information from the annotations rather than calling functions or setting variables.

## Unobtrusiveness

The agnosticism is a side benefit -- really the main reason its written this way is so that we're coding using "unobtrusive javascript" techniques.

Hobo currently many different mechanisms to pass data to javascript:

- classdata ex class="model::story:2"
- non-HTML5-compliant element attributes: ex hobo-blank-message="(click to edit)"
- variable assignment: ex hoboParts = ...;
- function calls: ex onclick="Hobo.ajaxRequest(url, {spinnerNextTo: 'foo'})"

hobo-jquery currently uses JSON inside of comments:

    <!-- json_annotation ({"tag":"datepicker","options":{},"events":{}}); -->

We are switching all 5 of these mechanisms to use HTML5 data
attributes.  HTML5 data attributes are technically illegal in HTML4
but work in all browsers future and past (even IE6).  The illegality
of them is the reason that I didn't choose them in Hobo-jQuery, but
it's now 2011.

We mostly use a single attribute: `data-rapid`.  This is a JSON hash
where the keys are the tag names and the values are options hashes.
DRYML has been modified to appropriately merge this tag in a fashion
similar to what it currently does for the `class` tag.  For example,
live-search will have the attribute
`data-rapid='{"live-search":{"foo": 17}}'`.  When hobo-jquery
initializes, it will then attempt to initialize a jQuery plugin named
`hjq_live_search`, which we provide in
public/javascripts/hobo-jquery/hjq-live-search.js.   The plugin will
get passed the options hash {"foo": 17}.

`data-rapid-page-data` contains data required by the javascript
library, such as the part information.

One last attribute that may be set is `data-rapid-context`.  This
contains a typed_id of the current context.  This is used to assist
tags like `delete-button` with DOM manipulation.

## Compatibility

Obviously compatibility with hobo-rapid.js is not going to be
maintained, since that's written in prototype.

The internal structure of hobo-jquery has changed completely.  We have
switched to using a more standard jQuery plugin style.

# Running the integration tests:

hobo-jquery is being tested using capybara & qunit.js.

Unfortunately, 2 of the integration tests fails on firefox, which
works out of the box, so we also have to install capybara-webkit and
selenium-chrome.

     $ git clone -b jquery git://github.com/Hobo/agility-gitorial.git
     $ cd agility-gitorial

Make sure you have the prerequisites for capybara-webkit:
https://github.com/thoughtbot/capybara-webkit/wiki/Installing-QT

     $ bundle install
     $ rake db:migrate

Download the selenium-chrome server and place in your path:
http://code.google.com/p/chromium/downloads/list

     $ rake test:integration

Email the list and/or bryan@larsen.st if you get any failures.