Class: WebFlow::ViewStep

Inherits:
FlowStep show all
Defined in:
lib/webflow/view_step.rb

Overview

This class allows the controllers to create view steps. It adds the view_step method to the WebFlow::Base class evaluation so we can define view steps from the controllers.

Simple usage

view_step :view_name do
  on :success => :another_step
  on :back => :yet_another_step
end

The view name will be stored in the @view_name instance variable until it is needed.

If no method corresponding to @view_name is defined inside the calling controller upon execution, the ViewStep tries to render a file with the same name as the @view_step value. Therefore, it is not mandatory to define view_step methods in the flow controller.

The view_step instruction can also be used to batch define view steps. Just pass a comma separated list of view names. Note that the mappings defined in the following block will be applied to all the view steps in the given list.

view_step :view_name, :another_view_step

Advanced usage

You can define how to render the view steps directly in the mapping, instead of doing it in the action itself. This gives a more clean code and separates the rendering concern from the business logic. The to_render instruction does this job. Here’s a simple usage.

view_step :view_name do

  (...)

  to_render :my_event do
    render 'template/path'
  end
end

The to_render instruction tells the view step that upon the returning of the my_event event from the step implementation, we must render the ‘template/path’ file. As a matter of fact, all the to_render does is to call the given block right after the step definition execution. One could use the to_render mechanism as he wishes and therefore perform actions other than rendering.

The to_render can also take many event names as arguments simultaneously, as shown here :

view_step :view_name do

  (...)

  to_render :my_event, :some_other_event, :yet_more_events do
    render 'template/path'
  end
end

Inherited instructions

The ViewStep class inherits all the standard step methods defined in FlowStep class.

Instance Method Summary collapse

Methods inherited from FlowStep

#definition_required?, #handler, #handles?, #has_an_outcome_for?, #method, #on, #outcome, #upon

Constructor Details

#initialize(m_view_name) ⇒ ViewStep

Initializes the instance



95
96
97
98
99
100
101
102
103
104
 
# File 'lib/webflow/view_step.rb', line 95

def initialize( m_view_name )
  
  # Holds the view name to render once the execution is complete
  @view_name = m_view_name
  
  # Tells the framework that no method definition is required for
  # this step type
  @definition_required = false
  
end

Instance Method Details

#execute(*args) ⇒ Object

This method is required by the WebFlow::Base and will be called once it relays the execution to this step instance



109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/webflow/view_step.rb', line 109

def execute(*args)

  # Verify if the controller answers to the @view_name value
  if args[0].respond_to? lookup_method_to_call(@view_name)
  
    # The controller defines a method with the same name as @view_name.
    # Kewl! A 'someone else problem' !!!
    
    # Launch execution
    result = args[0].send( lookup_method_to_call(@view_name) )
      
  else
  
    # Do we have to do everything here? lazy user...
  
    # Render something but only if the user hasn't
    # defined a custom render block.
    args[0].send :render, :action => lookup_method_to_call(@view_name) unless renders.has_key?('render')
    
    # Return the :render event
    result = WebFlow::Event.new(:render)
  
  end
  
  # Verify if we have to override the render result.
  # Execute if necessary.
  # Also validate that the return type is an event, or let go and it will
  # crash as soon as execution completes anyways...
  if result.kind_of?(WebFlow::Event) && renders.has_key?(result.name)
  
    # Execute the render block
    args[0].instance_eval( &renders.fetch( result.name ) )
    
  end
    
  result
     
end

#on_render(&block) ⇒ Object

Raises:



181
182
183
184
185
186
187
188
189
 
# File 'lib/webflow/view_step.rb', line 181

def on_render(&block)

  # Make sure we have a block as a parameter
  raise(WebFlow::WebFlowError.new, "The renders instruction takes a block as a parameter. Use the 'do' format. See API.") unless block_given?

  # Associate render event with the received block
  renders.store "render", block

end