Reviewers: ,
Please review this at http://codereview.tryton.org/376002/
Affected files:
M doc/topics/wizard.rst
Index: doc/topics/wizard.rst
===================================================================
--- a/doc/topics/wizard.rst
+++ b/doc/topics/wizard.rst
@@ -15,6 +15,23 @@
* The states of the wizard are attributes that are instances of
:class:`trytond.wizard.State`.
+Purpose
+=======
+
+When starting a wizard, each state will be executed in a sequence. A state
+may be :
+
+ * A :class:`trytond.wizard.StateView`, which is linked to
+ :class:`trytond.model.ModelView`. As such, it may have fields, and is
+ associated to a xml view which will be displayed when it is time to
+ be executed.
+
+ * A :class:`trytond.wizard.StateTransition`, which is a pure virtual
state
+ which only exists through code. When defining a StateTransition, it
is
+ mandatory to define a method named "transition_state_name(self,
session)"
+ which will be called when the state is executed, and must return a
string
+ containing the name of the next state.
+
Example
=======
@@ -24,32 +41,93 @@
class TranslationExport(Wizard):
"Export translation"
+
+ # The _name is mandatory and will be used as a key to reference the
+ # wizard for instance when trying to map it to an xml action.
_name = "ir.translation.export"
+ # The 'start_state' attribute will be called to decide which state
must
+ # be called first when starting the wizard.
+ # It may be a .StateView as well as a StateTransition.
+ start_state = 'start'
+
+ # This is the declaration of a StateView.
+ # Arguments are :
+ # - the name of a :class:`trytond.model.ModelView`. It will be
used
+ # to compute the fields which may be used by the state and
stored
+ # in the session.
start = StateView('ir.translation.export.start',
+ # - The id of the view which will be used when displaying the
State.
+ # It should be a view associated to the model corresponding
to the
+ # first argument.
'ir.translation_export_start_view_form', [
+ # - A list of buttons. Buttons control the flow of the wizard
and
+ # have three arguments :
+ # * A name, which is a label which will be used on the
button
+ # * The name of the state which must be called when clicking
+ # on the button. It must be the name of either a
StateView or
+ # that of a StateTransition.
+ # * The name of an image file which will be used as an icon
for
+ # the button.
Button('Cancel', 'end', 'tryton-cancel'),
+ # * The 'default' attribute sets which button will be
highlighted
+ # when displaying the view.
Button('Export', 'export', 'tryton-ok', default=True),
])
+
+ # StateTransitions are easier to define...
export = StateTransition()
+
+ # This is another StateView, whose creation pattern is identical
to the
+ # previous StateView, 'start'
result = StateView('ir.translation.export.result',
'ir.translation_export_result_view_form', [
Button('Close', 'end', 'tryton-close'),
])
+ # We created a StateTransition named 'export', so we must define
the
+ # method which will be called when the state is executed (that
would be
+ # when the user clicks on the 'Export' button on the 'start'
view) :
def transition_export(self, session):
pool = Pool()
translation_obj = pool.get('ir.translation')
+
+ # Whatever the code being executed here, what matters it the
use of
+ # 'session' to get data.
+ # 'session' is a parameter of every method that might be called
+ # when executing a wizard. It can be used to get a direct
access to
+ # each state of the wizard through 'session.state_name', and
thus
+ # to the fields of those states.
+ # In this particular case, we use the input from the view
+ # associated to the 'start' state (language.code, module.name)
in
+ # the method to compute something.
file_data = translation_obj.translation_export(
session.start.language.code, session.start.module.name)
+
+ # It is also possible to write in a non-yet-displayed state,
even
+ # though it is not enough to display it (see default_result) :
session.result.file = buffer(file_data)
+
+ # All transition_ methods must return a string which is the
name of
+ # the next state to be executed. When the current state is the
+ # final state of the wizard, the keyword 'end' must be used.
return 'result'
+ # It is possible to define A default method for each state of the
+ # wizard. This method takes the current session as an argument,
which
+ # allows for previous states dependant initialization.
+ # Here we created a file at the end of the previous state, so we
want
+ # to set it as the default value of the matching field of
the 'result'
+ # state :
def default_result(self, session, fields):
+ # It returns a dictionnary which takes the fields of the state
+ # model as keys. Those field will be updated with the
associated
+ # value before displaying.
return {
'file': session.result.file,
}
+ # Wizards must be instanciated !
TranslationExport()
Instantiating the class registers the wizard class in the framework. Later
the
--
[email protected] mailing list
