Module: RailsWidget

Defined in:
lib/rails_widget.rb,
lib/rails_widget/assets.rb,
lib/rails_widget/widgets.rb

Overview

RailsWidget allows you to group your client-side assets into distributable “widgets”

  • Attach assets and render partials with a single widget call

  • Configure widgets via an options.rb file

  • Supports flash, images, javascripts, partials, stylesheets, and textarea templates

Example

What is a widget?

Each directory in app/widgets is considered a widget. Let’s make a widget called alert.

app/
  widgets/
    alert/
      options.rb
      flash/
      images/
      javascripts/
        alert.js
        init.js
      partials/
        _init.html.erb
      stylesheets/
        init.css
        style.css
      templates/

Init files are rendered directly into the layout (inline, dynamically generated).

options.rb

{ :id => 'alert', :message => 'Hello world!', :color => 'red' }

javascripts/alert.js

function alertWidget(options) {
  alert(options.message);
}

javascripts/init.js

alertWidget(<%= options.to_json %>);

partials/_init.html.erb

<div id="<%= id %>" class="alert">
  You just got alerted.
</div>

stylesheets/init.css

#<%= id %> { color:<%= color %>; }

stylesheets/style.css

.alert { font-size:18px; }

Layout view

<html>
  <head>
    <%= javascripts %>
    <%= stylesheets %>
  </head>
  <body>
    <%= yield %>
  </body>
</html>

Action view

<%= widget :alert, :id => 'alert1', :color => 'blue' %>
<%= widget :alert, :id => 'alert2' %>

Resulting HTML

<html>
  <head>
    <script src="/javascripts/widgets/alert/alert.js?1220593492" type="text/javascript"></script>
    <script type='text/javascript'>
      alertWidget({ id: 'alert', message: 'Hello world!', color: 'red' });
    </script>
    <link href="/stylesheets/widgets/alert/style.css?1220593492" media="screen" rel="stylesheet" type="text/css" />
    <style type="text/css">
      #alert1 { color:blue; }
      #alert2 { color:red; }
    </style>
  </head>
  <body>
    <div id="alert1" class="alert">
      You just got alerted.
    </div>
    <div id="alert2" class="alert">
      You just got alerted.
    </div>
  </body>
</html>

Inheritance

Defined Under Namespace

Classes: Assets, Widgets

Instance Method Summary collapse

Instance Method Details

#flash_path(*path) ⇒ Object

Returns a path for a flash asset.

Example

<%= flash_path :some, :widget, 'flash.swf' %>
# => 'app/widgets/some/widget/flash/flash.swf'



18
19
20
21
 
# File 'lib/rails_widget/widgets.rb', line 18

def flash_path(*path)
  flash = path.pop
  "/flash/widgets/#{path.join('/')}/#{flash}"
end

#image(*path) ⇒ Object

Returns an image tag for a image asset.

Example

<%= image :some, :widget, 'image.png', :border => 0 %>
# => '<img src="app/widgets/some/widget/images/image.png" border=0 />'



29
30
31
32
33
 
# File 'lib/rails_widget/widgets.rb', line 29

def image(*path)
  options = path.extract_options!
  image = path.pop
  image_tag "widgets/#{path.join('/')}/#{image}", options
end

#image_path(*path) ⇒ Object

Returns an image path for a image asset.

Example

<%= image_path :some, :widget, 'image.png' %>
# => 'app/widgets/some/widget/images/image.png'



41
42
43
44
 
# File 'lib/rails_widget/widgets.rb', line 41

def image_path(*path)
  image = path.pop
  "/images/widgets/#{path.join('/')}/#{image}"
end

#javascripts(*paths, &block) ⇒ Object

Adds or renders javascript assets based on whether parameters are given or not.

Layout view

<html>
  <head>
    <%= javascripts %>
  </head>
  <%= yield %>
</html>

Action view

<% javascripts 'script1', 'script2' do -%>
  alert('Hello world!');
<% end -%>
Content goes here.

Resulting HTML

<html>
  <head>
    <script src="/javascripts/script1.js?1220593492" type="text/javascript"></script>
    <script src="/javascripts/script2.js?1220593492" type="text/javascript"></script>
    <script type='text/javascript'>
      alert('Hello world!');
    </script>
  </head>
  Content goes here.
</html>

Calling javascripts with path parameters or a script block will store the asset for later rendering.

Calling javascripts without parameters renders the assets in the order they were added.

The method accepts all options supported by javascript_include_tag.



37
38
39
40
 
# File 'lib/rails_widget/assets.rb', line 37

def javascripts(*paths, &block)
  @assets ||= Assets.new binding, controller, logger
  @assets.javascripts *paths, &block
end

#partial(*path) ⇒ Object

Renders a partial asset.

Example

<%= partial :some, :widget, 'partial', :locals => { :x => true } %>
# => render :partial => 'app/widgets/some/widget/partials/partial', :locals => { :x => true }



52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/rails_widget/widgets.rb', line 52

def partial(*path)
  options = path.extract_options!
  partial = path.pop
  path << options
  widgets, options = widget_instances path
  options = {
    :locals  => options.merge(:options => options),
    :partial => "#{path.join('/')}/partials/#{partial}"
  }
  render options
end

#stylesheets(*paths, &block) ⇒ Object

Adds or renders stylesheet assets based on whether parameters are given or not.

Layout example

<html>
  <head>
    <%= stylesheets %>
  </head>
  <%= yield %>
</html>

Action example

<% stylesheets 'style1', 'style2' -%>
Content goes here.

Result

<html>
  <head>
    <link href="/stylesheets/style1.css?1224923418" media="screen" rel="stylesheet" type="text/css" />
    <link href="/stylesheets/style2.css?1224923418" media="screen" rel="stylesheet" type="text/css" />
  </head>
  Content goes here.
</html>

Calling stylesheets with path parameters will store the asset for later rendering.

Calling stylesheets without parameters renders the assets in the order they were added.

The method accepts all options supported by stylesheet_link_tag.



71
72
73
74
 
# File 'lib/rails_widget/assets.rb', line 71

def stylesheets(*paths, &block)
  @assets ||= Assets.new binding, controller, logger
  @assets.stylesheets *paths, &block
end

#templates(*options, &block) ⇒ Object

Adds or renders textarea-based templates based on whether parameters are given or not.

Use this with something like PURE <beebole.com/pure> or TrimPath’s JST <trimpath.com>.

Layout example

<html>
  <%= yield %>
  <%= templates %>
</html>

Action example

<% templates :id => 'myid', :partial => 'some_action/partial', :locals => { :x => 'Hello world' } -%>
<% templates do -%>
  Template goes here.
<% end -%>
Content goes here.

Partial example (some_action/partial)

<%= x %>!

Result

<html>
  Content goes here.
  <textarea id='template_myid' style='display:none'>
    Hello world!
  </textarea>
  <textarea id='template' style='display:none'>
    Template goes here.
  </textarea>
</html>

Calling templates with path parameters or a block will store the asset for later rendering.

Calling templates without parameters renders the assets in the order they were added.



111
112
113
114
 
# File 'lib/rails_widget/assets.rb', line 111

def templates(*options, &block)
  @assets ||= Assets.new binding, controller, logger
  @assets.templates *options, &block
end

#widget(*path) ⇒ Object

See RailsWidget.



5
6
7
8
9
10
 
# File 'lib/rails_widget/widgets.rb', line 5

def widget(*path)
  @assets  ||= Assets.new  binding, controller, logger
  @widgets ||= Widgets.new @assets, binding, controller, logger
  options = path.extract_options!
  @widgets.build path, options
end