= Widgeon

Widgeon is a widget system for Ruby on Rails.

=== Installation

$ ./script/plugin install http://talia.discovery-project.eu/svn/talia/repository/widgeon/trunk

=== Uninstallation

$ ./script/plugin delete widgeon

Notice: this operation will *destroy* all your widgets.

== Using an existing widget

In your view files:
<%= widget(:widget_name) %>

You can also pass params:
<%= widget(:widget_name, :param_one => 'one', :param_two => 'two') %>

=== Style sheets and javascript files

The widget may contain stylesheet (css) and javascript files (if it doesn't, you
don't need to worry). 

Stylesheets are easy - they will be automatically inlined in your HTML
if you don't do anything special. 

If you want to use javascript files, or if you want to link the stylesheet as
separate files, you have to include them in the header file:

* Use the <tt>widget_stylesheet_links(*args)</tt> method for css stylesheets
* Use the <tt>widget_javascript_links(*args)</tt> method for javascript files

If you place those *directly* in your layout *and* you don't use widgets in
the layout itself, just use this methods without parameters. Otherwise they may
need a little help - check their documentation on how to do this.

If you use the stylesheet links, the inline stylesheets will automatically be
deactivated for good.

The style sheets, javascripts may either be served by the widget system, or 
directly as static files. See below on how to configure Widgeon for those 
different options.

== Anatomy of a widget

All the files for a widget are contained in a single folder. A basic widget
needs just two files to work.

The two basic files are the widget's template file (a standard Rails template)
and the widget's code file (containing a subclass of Widgeon::Widget).

Here's how the widget folder looks like:

 - hello_world
   +- code (*)
     +- hello_world_widget.rb (*)
   +- views (*)
     +- _hello_world_widget.html.erb (*)
   +- public
     +- javascripts
     +- stylesheets

Only the files marked with (*) are required, the rest is optional - as you see
it's just the code file and the template file.

== Configuring the widget system

The widget system can be configured using the standard initializer method 
from Rails.

=== Serving assets (stylesheets, javascripts, etc)

There are two ways to serve static assets:
 
* The default method will serve the files directly through the widget system.
  This will invoke a rails action, take the static file from the widget directory
  and send it to the browser.
* The widget system may be configured to use Rails' default 'public' directory.
  If you set <tt>Widgeon::Widget.asset_mode = :install</tt> in the initializer
  all the static files are copied to 'public/widgets/...'.


* The <tt>:install</tt> method can be much faster; and the javascript and
  stylesheet links (see above) will use the standard Rails helpers. This means
  that you benefit from all built-in optimizations.
* The <tt>:install</tt> method will use different URLs for serving the data.
  The helpers will automatically take care of this, but take not of it when
  you reference files manually. The "default" URLs will still work, the 
  framework will create a permanent redirect to the new resource.

== Developing a widget

First create a widget (see related section), the process will create two files:
and helper and a class.
For convention all params passed to the <tt>widget</tt> method will be available
in the widget object.

Example:
  <%= widget(:sidebar, :entries => 1..3) %>
  
  @sidebar_widget.entries #=> 1..3

Now you can easily guess that in your helpers you can use an instance variable
called (by convention) with the 'underscored' name of the class
(HelloWorldWidget #=> @hello_world_widget).

Now I can image that it isn't enough for you ;-) and I know you want to
manipulate the params passed to #widget. Ok, I have a solution: implement
#before_render in your class and this will be called for you. :-P

Example:
  app/views/index.rhtml:
  <h1><%= widget(:greeter, :name => 'luca') %></h1>

  widgets/greeter_widget.rb:
  class GreeterWidget < Widgeon::Widget
    def on_init
      name = name.titleize
    end
  end

  app/views/widgets/greeter/_greeter.rhtml:
  Welcome <%= w.name %>!!
  
  The result will be:
  <h1>Welcome Luca!!</h1>

As you can see the widget is made available as <tt>w.</tt> in the templates. 
Basically, if you want to access the widget's methods and variables, just prefix
the name with <tt>w.</tt>.

When you write your widget code, remember that *rails helpers are available to
the widget methods* - you can write the widget methods in the same way that 
you write helpers. (For example, you could use <tt>url_for</tt> in a widget
method).

<tt>on_init</tt> is a special method that is called when the widget is 
initialized. All the options passed to the widget will be available in this method,
as well as the options from the config file.

=== Javascripts and stylesheets

You can use the <tt>style</tt> and <tt>script</tt> methods to declare which 
stylesheets and javascript files should be included in the header links. By default,
this will just include all existing styles and scripts automatically.

=== Options

You can pass a hash of options to the <tt>widget()</tt> call. All options will
be set as class variables with read and write accessors. An option hash can
also be defined in a YAML file (named like the widget. The config options from
the file will be loaded into the widget automatically when it is rendered.

=== Remote calls

See also Widgeon::Helpers

Using the <tt>widget_remotelink</tt> helper, one can make a remote call to the 
current widget. The call will initialize the widget, but *not* call the
<tt>before_render</tt> method.

A remote call will then call the handler that has been defined inside the
widget's class. A handler can be defined like this:

  remote_call :my_handler do |page|
    # modifying code
  end

The page object can be used in the same way as in a RJS template.

=== Backlinks to widget

See also the Widgeon::Helpers page

Using the <tt>widget_backlink</tt> helper, you may create a backlink to an exsting widget.
The widget backlink will call the current widget, passing the given options to
it. 

It renders the widget in the "normal" way and replaces the widget's <tt><div></tt>
 element with new HTML; the widget's element is referenced by the widget id. 

The backlink will also work without Javascript; in this case the whole page will
be re-rendered.

In any case, the <tt>is_callback</tt> propery will be set on the widget. Using
this property, a widget may discover if it's rendered as a result of a backlink
(or as part of a page that is the result of a backlink).

=== Widget state

Inside the widget, the <tt>widget_session</tt> will be used. This is a hash
that will stored in the user's session between widget calls. The hash is
identified by the widget's id, thus it will be shared between all widgets with
the same id.

=== Stylesheets

You may include a stylesheet file with the name <tt><widget_name>.css</tt> in
a widget's directory. By default, the stylesheet will be rendered as
an inline <style> element in the HTML code. You can disable this
behaviour by setting <tt>Widgeon::Widget::inline_styles = false</tt>.

If you disable the inline styles, you will have to provide the widget's
CSS styles by another mechanism.
  
== Create a widget

  $ ./script/generate widget HelloWorld

This creates <tt>widgets/hello_world_widget.rb</tt> and
<tt>app/views/widgets/hello_world/_hello_world_widget.rhtml</tt>.

== Destroy a widget

  $ ./script/destroy widget HelloWorld

This deletes <tt>widgets/hello_world_widget.rb</tt> and
<tt>app/views/widgets/hello_world/_hello_world_widget.rhtml</tt>.