base.rb 8.4 KB
Newer Older
J
Jeremy Kemper 已提交
1 2
require 'active_support/core_ext/module/attr_internal'
require 'active_support/core_ext/module/delegation'
J
Jeremy Kemper 已提交
3
require 'active_support/core_ext/class/attribute'
J
Jeremy Kemper 已提交
4
require 'active_support/core_ext/array/wrap'
X
Xavier Noria 已提交
5
require 'active_support/ordered_options'
6
require 'action_view/log_subscriber'
J
Jeremy Kemper 已提交
7

D
Initial  
David Heinemeier Hansson 已提交
8
module ActionView #:nodoc:
9 10
  # = Action View Base
  #
11
  # Action View templates can be written in several ways. If the template file has a <tt>.erb</tt> (or <tt>.rhtml</tt>) extension then it uses a mixture of ERb
12 13
  # (included in Ruby) and HTML. If the template file has a <tt>.builder</tt> (or <tt>.rxml</tt>) extension then Jim Weirich's Builder::XmlMarkup library is used.
  #
A
Akira Matsuda 已提交
14
  # == ERB
15
  #
A
Akira Matsuda 已提交
16
  # You trigger ERB by using embeddings such as <% %>, <% -%>, and <%= %>. The <%= %> tag set is used when you want output. Consider the
D
Initial  
David Heinemeier Hansson 已提交
17 18 19
  # following loop for names:
  #
  #   <b>Names of all the people</b>
A
Akira Matsuda 已提交
20
  #   <% @people.each do |person| %>
D
Initial  
David Heinemeier Hansson 已提交
21 22 23
  #     Name: <%= person.name %><br/>
  #   <% end %>
  #
24
  # The loop is setup in regular embedding tags <% %> and the name is written using the output embedding tag <%= %>. Note that this
A
Akira Matsuda 已提交
25
  # is not just a usage suggestion. Regular output functions like print or puts won't work with ERB templates. So this would be wrong:
D
Initial  
David Heinemeier Hansson 已提交
26
  #
X
Xavier Noria 已提交
27
  #   <%# WRONG %>
D
Initial  
David Heinemeier Hansson 已提交
28 29
  #   Hi, Mr. <% puts "Frodo" %>
  #
X
Xavier Noria 已提交
30
  # If you absolutely must write from within a function use +concat+.
31 32
  #
  # <%- and -%> suppress leading and trailing whitespace, including the trailing newline, and can be used interchangeably with <% and %>.
D
Initial  
David Heinemeier Hansson 已提交
33
  #
34
  # === Using sub templates
D
Initial  
David Heinemeier Hansson 已提交
35 36 37 38 39 40 41 42 43 44 45 46
  #
  # Using sub templates allows you to sidestep tedious replication and extract common display structures in shared templates. The
  # classic example is the use of a header and footer (even though the Action Pack-way would be to use Layouts):
  #
  #   <%= render "shared/header" %>
  #   Something really specific and terrific
  #   <%= render "shared/footer" %>
  #
  # As you see, we use the output embeddings for the render methods. The render call itself will just return a string holding the
  # result of the rendering. The output embedding writes it to the current template.
  #
  # But you don't have to restrict yourself to static includes. Templates can share variables amongst themselves by using instance
47
  # variables defined using the regular embedding tags. Like this:
D
Initial  
David Heinemeier Hansson 已提交
48 49 50 51
  #
  #   <% @page_title = "A Wonderful Hello" %>
  #   <%= render "shared/header" %>
  #
P
Pratik Naik 已提交
52
  # Now the header can pick up on the <tt>@page_title</tt> variable and use it for outputting a title tag:
D
Initial  
David Heinemeier Hansson 已提交
53 54 55
  #
  #   <title><%= @page_title %></title>
  #
56
  # === Passing local variables to sub templates
57
  #
D
Initial  
David Heinemeier Hansson 已提交
58 59
  # You can pass local variables to sub templates by using a hash with the variable names as keys and the objects as values:
  #
60
  #   <%= render "shared/header", { :headline => "Welcome", :person => person } %>
D
Initial  
David Heinemeier Hansson 已提交
61
  #
P
Pratik Naik 已提交
62
  # These can now be accessed in <tt>shared/header</tt> with:
D
Initial  
David Heinemeier Hansson 已提交
63 64 65 66
  #
  #   Headline: <%= headline %>
  #   First name: <%= person.first_name %>
  #
67 68 69 70 71 72 73 74 75
  # If you need to find out whether a certain local variable has been assigned a value in a particular render call,
  # you need to use the following pattern:
  #
  #   <% if local_assigns.has_key? :headline %>
  #     Headline: <%= headline %>
  #   <% end %>
  #
  # Testing using <tt>defined? headline</tt> will not work. This is an implementation restriction.
  #
76
  # === Template caching
D
Initial  
David Heinemeier Hansson 已提交
77
  #
78 79
  # By default, Rails will compile each template to a method in order to render it. When you alter a template,
  # Rails will check the file's modification time and recompile it in development mode.
D
Initial  
David Heinemeier Hansson 已提交
80 81 82
  #
  # == Builder
  #
A
Akira Matsuda 已提交
83
  # Builder templates are a more programmatic alternative to ERB. They are especially useful for generating XML content. An XmlMarkup object
84
  # named +xml+ is automatically made available to templates with a <tt>.builder</tt> extension.
D
Initial  
David Heinemeier Hansson 已提交
85 86 87
  #
  # Here are some basic examples:
  #
88 89 90 91 92
  #   xml.em("emphasized")                                 # => <em>emphasized</em>
  #   xml.em { xml.b("emph & bold") }                      # => <em><b>emph &amp; bold</b></em>
  #   xml.a("A Link", "href" => "http://onestepback.org")  # => <a href="http://onestepback.org">A Link</a>
  #   xml.target("name" => "compile", "option" => "fast")  # => <target option="fast" name="compile"\>
  #                                                        # NOTE: order of attributes is not specified.
93
  #
D
Initial  
David Heinemeier Hansson 已提交
94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116
  # Any method with a block will be treated as an XML markup tag with nested markup in the block. For example, the following:
  #
  #   xml.div {
  #     xml.h1(@person.name)
  #     xml.p(@person.bio)
  #   }
  #
  # would produce something like:
  #
  #   <div>
  #     <h1>David Heinemeier Hansson</h1>
  #     <p>A product of Danish Design during the Winter of '79...</p>
  #   </div>
  #
  # A full-length RSS example actually used on Basecamp:
  #
  #   xml.rss("version" => "2.0", "xmlns:dc" => "http://purl.org/dc/elements/1.1/") do
  #     xml.channel do
  #       xml.title(@feed_title)
  #       xml.link(@url)
  #       xml.description "Basecamp: Recent items"
  #       xml.language "en-us"
  #       xml.ttl "40"
117
  #
D
Initial  
David Heinemeier Hansson 已提交
118 119 120 121 122 123 124
  #       for item in @recent_items
  #         xml.item do
  #           xml.title(item_title(item))
  #           xml.description(item_description(item)) if item_description(item)
  #           xml.pubDate(item_pubDate(item))
  #           xml.guid(@person.firm.account.url + @recent_items.url(item))
  #           xml.link(@person.firm.account.url + @recent_items.url(item))
125
  #
D
Initial  
David Heinemeier Hansson 已提交
126 127 128 129 130 131 132 133
  #           xml.tag!("dc:creator", item.author_name) if item_has_creator?(item)
  #         end
  #       end
  #     end
  #   end
  #
  # More builder documentation can be found at http://builder.rubyforge.org.
  class Base
134
    include Helpers, ::ERB::Util, Context
135

136 137 138 139
    # Specify the proc used to decorate input tags that refer to attributes with errors.
    cattr_accessor :field_error_proc
    @@field_error_proc = Proc.new{ |html_tag, instance| "<div class=\"field_with_errors\">#{html_tag}</div>".html_safe }

140 141 142 143 144
    # How to complete the streaming when an exception occurs.
    # This is our best guess: first try to close the attribute, then the tag.
    cattr_accessor :streaming_completion_on_exception
    @@streaming_completion_on_exception = %("><script type="text/javascript">window.location = "/500.html"</script></html>)

145
    class_attribute :helpers
146
    class_attribute :_routes
147

148 149 150
    class << self
      delegate :erb_trim_mode=, :to => 'ActionView::Template::Handlers::ERB'
      delegate :logger, :to => 'ActionController::Base', :allow_nil => true
151 152 153 154 155 156 157 158

      def cache_template_loading
        ActionView::Resolver.caching?
      end

      def cache_template_loading=(value)
        ActionView::Resolver.caching = value
      end
J
José Valim 已提交
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183

      def process_view_paths(value)
        value.is_a?(PathSet) ?
          value.dup : ActionView::PathSet.new(Array.wrap(value))
      end

      def xss_safe? #:nodoc:
        true
      end

      # This method receives routes and helpers from the controller
      # and return a subclass ready to be used as view context.
      def prepare(routes, helpers) #:nodoc:
        Class.new(self) do
          if routes
            include routes.url_helpers
            include routes.mounted_helpers
          end

          if helpers
            include helpers
            self.helpers = helpers
          end
        end
      end
184 185
    end

186
    attr_accessor :view_renderer
J
José Valim 已提交
187
    attr_internal :config, :assigns
188

189
    delegate :lookup_context, :to => :view_renderer
190
    delegate :formats, :formats=, :locale, :locale=, :view_paths, :view_paths=, :to => :lookup_context
191

192
    def assign(new_assigns) # :nodoc:
193
      @_assigns = new_assigns.each { |key, value| instance_variable_set("@#{key}", value) }
194 195
    end

J
José Valim 已提交
196
    def initialize(context = nil, assigns = {}, controller = nil, formats = nil) #:nodoc:
197
      @_config = {}
198

199 200 201 202 203 204 205
      # Handle all these for backwards compatibility.
      # TODO Provide a new API for AV::Base and deprecate this one.
      if context.is_a?(ActionView::Renderer)
        @view_renderer = context
      elsif
        lookup_context = context.is_a?(ActionView::LookupContext) ?
          context : ActionView::LookupContext.new(context)
206 207 208
        lookup_context.formats  = formats if formats
        lookup_context.prefixes = controller._prefixes if controller
        @view_renderer = ActionView::Renderer.new(lookup_context)
209
      end
210

J
José Valim 已提交
211 212
      assign(assigns)
      assign_controller(controller)
213
      _prepare_context
D
Initial  
David Heinemeier Hansson 已提交
214 215
    end

216
    ActiveSupport.run_load_hooks(:action_view, self)
D
Initial  
David Heinemeier Hansson 已提交
217 218
  end
end