Rails源代码分析（11）：ActionController::Layout(2)

1.     module ClassMethods
2.       # If a layout is specified, all rendered actions will have their result rendered
3.       # when the layout <tt>yield</tt>s. This layout can itself depend on instance variables assigned during action
4.       # performance and have access to them as any normal template would.
5.       def layout(template_name, conditions = {}, auto = false)
6.         add_layout_conditions(conditions) 
7.         write_inheritable_attribute "layout", template_name # 设置layout属性
8.         write_inheritable_attribute "auto_layout", auto # 设置不需要自动
9.       end
11.       def layout_conditions #:nodoc:
12.         @layout_conditions ||= read_inheritable_attribute("layout_conditions")
13.       end
15.       def default_layout(format) #:nodoc:
16.         layout = read_inheritable_attribute("layout") # 获取layout
17.         return layout unless read_inheritable_attribute("auto_layout") # 如果是当前controller设置的layout则返回layout
18.         @default_layout ||= {}
19.         @default_layout[format] ||= default_layout_with_format(format, layout)
20.         @default_layout[format]
21.       end
23.       def layout_list #:nodoc:
24.         Array(view_paths).sum([]) { |path| Dir["#{path}/layouts/**/*"] } # 获取所有layout页面
25.       end
27.       private
28.         # 继承layout的实现
29.         def inherited_with_layout(child)
30.           inherited_without_layout(child)
31.           unless child.name.blank?
32.             layout_match = child.name.underscore.sub(/_controller$/, '').sub(/^controllers///, '')
33.             # 如果子类没有layout，那么设置为自动layout
34.             child.layout(layout_match, {}, true) unless child.layout_list.grep(%r{layouts/#{layout_match}(/.[a-z][0-9a-z]*)+$}).empty?
35.           end
36.         end
38.         # 增加layout条件
39.        def add_layout_conditions(conditions)
40.           write_inheritable_hash "layout_conditions", normalize_conditions(conditions) 
41.         end
43.         # 将conditions合并
44.        def normalize_conditions(conditions)
45.           conditions.inject({}) {|hash, (key, value)| hash.merge(key => [value].flatten.map {|action| action.to_s})}
46.         end
48.           # 根据格式来取得layout
49.         def default_layout_with_format(format, layout)
50.           list = layout_list
51.           if list.grep(%r{layouts/#{layout}/.#{format}(/.[a-z][0-9a-z]*)+$}).empty?
52.             (!list.grep(%r{layouts/#{layout}/.([a-z][0-9a-z]*)+$}).empty? && format == :html) ? layout : nil
53.           else
54.             layout
55.           end
56.         end
57.     end

1.     # Returns the name of the active layout. If the layout was specified as a method reference (through a symbol), this method
2.     # is called and the return value is used. Likewise if the layout was specified as an inline method (through a proc or method
3.     # object). If the layout was defined without a directory, layouts is assumed. So <tt>layout "weblog/standard"</tt> will return
4.     # weblog/standard, but <tt>layout "standard"</tt> will return layouts/standard.
5.     # 获取当前layout
6.     def active_layout(passed_layout = nil)
7.       layout = passed_layout || self.class.default_layout(response.template.template_format)
8.       active_layout = case layout
9.         when String then layout
10.         when Symbol then send!(layout)
11.         when Proc   then layout.call(self)
12.       end
14.       # Explicitly passed layout names with slashes are looked up relative to the template root,
15.       # but auto-discovered layouts derived from a nested controller will contain a slash, though be relative
16.       # to the 'layouts' directory so we have to check the file system to infer which case the layout name came from.
17.       if active_layout
18.         if active_layout.include?('/') && ! layout_directory?(active_layout)
19.           active_layout
20.         else
21.           "layouts/#{active_layout}"
22.         end
23.       end
24.     end
26.     protected
27.       def render_with_a_layout(options = nil, extra_options = {}, &block) #:nodoc:
28.         template_with_options = options.is_a?(Hash)
30.         if (layout = pick_layout(template_with_options, options)) && apply_layout?(template_with_options, options) # 如果能找到并且能使用
31.           options = options.merge :layout => false if template_with_options
32.           logger.info("Rendering template within #{layout}") if logger
34.           content_for_layout = render_with_no_layout(options, extra_options, &block)
35.           erase_render_results
36.           add_variables_to_assigns
37.           @template.instance_variable_set("@content_for_layout", content_for_layout)
38.           response.layout = layout
39.           status = template_with_options ? options[:status] : nil
40.           render_for_text(@template.render_file(layout, true), status)
41.         else
42.           render_with_no_layout(options, extra_options, &block)
43.         end
44.       end
47.     private
48.       def apply_layout?(template_with_options, options)
49.         return false if options == :update
50.         template_with_options ?  candidate_for_layout?(options) : !template_exempt_from_layout?
51.       end
52.      
54.       # 如果render有layout key 并且选项中没有:text, :xml, :json, :file, :inline, :partial, :nothing
55.       # 并且模板没有被从layout中免除
56.      def candidate_for_layout?(options)
57.         (options.has_key?(:layout) && options[:layout] != false) ||
58.           options.values_at(:text, :xml, :json, :file, :inline, :partial, :nothing).compact.empty? &
59.           !template_exempt_from_layout?(options[:template] || default_template_name(options[:action]))
60.       end
62.       #根据layout option获取layout
63.      def pick_layout(template_with_options, options)
64.         if template_with_options
65.           case layout = options[:layout]
66.             #如果layout=>false 那么返回nil
67.             when FalseClass
68.               nil
69.           # 如果是nil或者true并且拥有layout返回layout
70.             when NilClass, TrueClass
71.               active_layout if action_has_layout?
72.             else
73.           # 如果没有条件直接返回当前layout
74.               active_layout(layout)
75.           end
76.         else
77.          # 没有条件 则返回
78.           active_layout if action_has_layout?
79.         end
80.       end
82.       def action_has_layout?
83.         if conditions = self.class.layout_conditions
84.           case
85.           # 如果only包含=>true
86.             when only = conditions[:only]
87.               only.include?(action_name)
88.             # 如果except包含=>false
89.             when except = conditions[:except]
90.               !except.include?(action_name)
91.             else
92.             #默认true
93.               true
94.           end
95.         else
96.          # 没有条件true
97.           true
98.         end
99.       end
101.       def layout_directory?(layout_name)
102.         @template.finder.find_template_extension_from_handler(File.join('layouts', layout_name))
103.       end