Actions¶

Introduction¶

Besides displaying and editing data, every application needs the functions to manipulate data or create reports. In Camelot this is done through actions. Actions can appear as buttons on the side of a form or a table, as icons in a toolbar or as icons in the home workspace.

_static/entityviews/new_view_address.png

Every Action is build up with a set of Action Steps. An Action Step is a reusable part of an Action, such as for example, ask the user to select a file. Camelot comes with a set of standard Actions and Action Steps that are easily extended to manipulate data or create reports.

When defining Actions, a clear distinction should be made between things happening in the model thread (the manipulation or querying of data), and things happening in the gui thread (pop up windows or reports). The The Two Threads section gives more detail on this.

Summary¶

In general, actions are defined by subclassing the standard Camelot camelot.admin.action.Action class

from camelot.admin.action import Action
from camelot.view.action_steps import PrintHtml
from camelot.core.utils import ugettext_lazy as _
from camelot.view.art import Icon

class PrintReport( Action ):

    verbose_name = _('Print Report')
    icon = Icon('tango/16x16/actions/document-print.png')
    tooltip = _('Print a report with all the movies')

    def model_run( self, model_context ):
        yield PrintHtml( 'Hello World' )

Each action has two methods, gui_run() and model_run(), one of them should be reimplemented in the subclass to either run the action in the gui thread or to run the action in the model thread. The default Action.gui_run() behavior is to pop-up a ProgressDialog dialog and start the model_run() method in the model thread.

model_run() in itself is a generator, that can yield ActionStep objects back to the gui, such as a PrintHtml.

The action objects can than be used a an element of the actions list returned by the ApplicationAdmin.get_actions() method:

    def get_actions(self):
        from camelot.admin.action import OpenNewView
        from camelot_example.model import Movie
        
        new_movie_action = OpenNewView( self.get_related_admin(Movie) )
        new_movie_action.icon = Icon('tango/22x22/mimetypes/x-office-presentation.png')

        return [new_movie_action]

or be used in the ObjectAdmin.list_actions or ObjectAdmin.form_actions attributes.

The Add an import wizard to an application tutorial has a complete example of creating and using and action.

What can happen inside `model_run()`¶

`yield` events to the GUI¶

Actions need to be able to send their results back to the user, or ask the user for additional information. This is done with the yield statement.

Through yield, an Action Step is send to the GUI thread, where it creates user interaction, and sends it result back to the ‘model_thread’. The model_thread will be blocked while the action in the GUI thread takes place, eg

yield PrintHtml( 'Hello World' )

Will pop up a print preview dialog in the GUI, and the model_run method will only continue when this dialog is closed.

Events that can be yielded to the GUI should be of type camelot.admin.action.base.ActionStep. Action steps are reusable parts of an action. Possible Action Steps that can be yielded to the GUI include:

camelot.view.action_steps.change_object.ChangeObject

camelot.view.action_steps.change_object.ChangeObjects

camelot.view.action_steps.print_preview.PrintChart

camelot.view.action_steps.print_preview.PrintPreview

camelot.view.action_steps.print_preview.PrintHtml

camelot.view.action_steps.print_preview.PrintJinjaTemplate

camelot.view.action_steps.open_file.OpenFile

camelot.view.action_steps.open_file.OpenStream

camelot.view.action_steps.open_file.OpenJinjaTemplate

camelot.view.action_steps.gui.CloseView

camelot.view.action_steps.gui.MessageBox

camelot.view.action_steps.gui.Refresh

camelot.view.action_steps.gui.OpenFormView

camelot.view.action_steps.gui.ShowPixmap

camelot.view.action_steps.gui.ShowChart

camelot.view.action_steps.select_file.SelectFile

camelot.view.action_steps.select_object.SelectObject

keep the user informed about progress¶

An camelot.view.action_steps.update_progress.UpdateProgress object can be yielded, to update the state of the progress dialog:

This should be done regulary to keep the user informed about the progres of the action:

movie_count = Movie.query.count()

report = '<table>'
for i, movie in enumerate( Movie.query.all() ):
    report += '<tr><td>%s</td></tr>'%(movie.name)
    yield UpdateProgress( i, movie_count )
report += '</table>'

yield PrintHtml( report )

Should the user have pressed the Cancel button in the progress dialog, the next yield of an UpdateProgress object will raise a camelot.core.exception.CancelRequest.

manipulation of the model¶

The most important purpose of an action is to query or manipulate the model, all such things can be done in the model_run() method, such as executing queries, manipulating files, etc.

Whenever a part of the model has been changed, it might be needed to inform the GUI about this, so that it can update itself, the easy way of doing so is by yielding an instance of camelot.view.action_steps.orm.FlushSession such as:

movie.rating = 5
yield FlushSession( model_context.session )

This will flush the session to the database, and at the same time update the GUI so that the flushed changes are shown to the user by updating the visualisation of the changed movie on every screen in the application that displays this object. Alternative updates that can be generated are :

camelot.view.action_steps.orm.UpdateObject, if one wants to inform the GUI an object has been updated.

camelot.view.action_steps.orm.DeleteObject, if one wants to inform the GUI an object is going to be deleted.

camelot.view.action_steps.orm.CreateObject, if one wants to inform the GUI an object has been created.

raise exceptions¶

When an action fails, a normal Python Exception can be raised, which will pop-up an exception dialog to the user that displays a stack trace of the exception. In case no stack trace should be shown to the user, a camelot.core.exception.UserException should be raised. This will popup a friendly dialog :

When the model_run() method raises a camelot.core.exception.CancelRequest, a GeneratorExit or a StopIteration exception, these are ignored and nothing will be shown to the user.

handle exceptions¶

In case an unexpected event occurs in the GUI, a yield statement will raise a camelot.core.exception.GuiException. This exception will propagate through the action an will be ignored unless handled by the developer.

request information from the user¶

The pop-up of a dialog that presents the user with a number of options can be triggered from within the model_run() method. This happens by transferring an options object back and forth between the model_thread and the gui_thread. To transfer such an object, this object first needs to be defined:

class Options( object ):

    def __init__(self):
        self.earliest_releasedate = datetime.date(2000, 1, 1)
        self.latest_releasedate = datetime.date.today()

    class Admin( ObjectAdmin ):
        form_display = [ 'earliest_releasedate', 'latest_releasedate' ]
        field_attributes = { 'earliest_releasedate':{'delegate':delegates.DateDelegate},
                             'latest_releasedate':{'delegate':delegates.DateDelegate}, }

Than a camelot.view.action_steps.change_object.ChangeObject action step can be yield to present the options to the user and get the filled in values back :

        from PyQt4 import QtGui
        from camelot.view import action_steps
        options = NewProjectOptions()
        yield action_steps.UpdateProgress( text = 'Request information' )
        yield action_steps.ChangeObject( options )

Will show a dialog to modify the object:

When the user presses Cancel button of the dialog, the yield statement will raise a camelot.core.exception.CancelRequest.

Other ways of requesting information are :

camelot.view.action_steps.select_file.SelectFile, to request to select an existing file to process or a new file to save information.

Issue SQLAlchemy statements¶

Camelot itself only manipulates the database through objects of the ORM for the sake of make no difference between objects mapped to the database and plain old python objects. But for performance reasons, it is often desired to do manipulations directly through SQLAlchemy ORM or Core queries :

        model_context.session.query( BatchJobType ).update( values = {'name':'accounting audit'},
                                                            synchronize_session = 'evaluate' )

States and Modes¶

States¶

The widget that is used to trigger an action can be in different states. A camelot.admin.action.base.State object is returned by the camelot.admin.action.base.Action.get_state method. Subclasses of Action can reimplement this method to change the State of an action button.

This allows to hide or disable the action button, depending on the objects selected or the current object being displayed.

Modes¶

An action widget can be triggered in different modes, for example a print button can be triggered as Print or Export to PDF. The different modes of an action are specified as a list of camelot.admin.action.base.Mode objects.

To change the modes of an Action, either specify the modes attribute of an Action or specify the modes attribute of the State returned by the Action.get_state() method.

Action Context¶

Depending on where an action was triggered, a different context will be available during its execution in camelot.admin.action.base.Action.gui_run() and camelot.admin.action.base.Action.model_run().

The minimal context available in the GUI thread when gui_run() is called :

While the minimal contact available in the Model thread when model_run() is called :

Application Actions¶

To enable Application Actions for a certain ApplicationAdmin overwrite its ApplicationAdmin.get_actions() method:

from camelot.admin.application_admin import ApplicationAdmin
from camelot.admin.action import Action

class GenerateReports( Action ):

    verbose_name = _('Generate Reports')

    def model_run( self, model_context):
        for i in range(10):
            yield UpdateProgress(i, 10)

class MyApplicationAdmin( ApplicationAdmin )

    def get_actions( self ):
        return [GenerateReports(),]

An action specified here will receive an ApplicationActionGuiContext object as the gui_context argument of the the gui_run() method, and a ApplicationActionModelContext object as the model_context argument of the model_run() method.

Form Actions¶

A form action has access to the object currently visible on the form.

class BurnToDisk( Action ):
    
    verbose_name = _('Burn to disk')
    
    def model_run( self, model_context ):
        yield action_steps.UpdateProgress( 0, 3, _('Formatting disk') )
        time.sleep( 0.7 )
        yield action_steps.UpdateProgress( 1, 3, _('Burning movie') )
        time.sleep( 0.7 )
        yield action_steps.UpdateProgress( 2, 3, _('Finishing') )
        time.sleep( 0.5 )

To enable Form Actions for a certain ObjectAdmin or EntityAdmin, specify the form_actions attribute.

        #
        # create a list of actions available for the user on the form view
        #
        form_actions = [BurnToDisk()]

An action specified here will receive a FormActionGuiContext object as the gui_context argument of the gui_run() method, and a FormActionModelContext object as the model_context argument of the model_run() method.

List Actions¶

A list action has access to both all the rows displayed in the table (called the collection) and the rows selected by the user (called the selection) :

class ChangeRatingAction( Action ):
    """Action to print a list of movies"""
    
    verbose_name = _('Change Rating')
    
    def model_run( self, model_context ):
        #
        # the model_run generator method yields various ActionSteps
        #
        options = Options()
        yield ChangeObject( options )
        if options.only_selected:
            iterator = model_context.get_selection()
        else:
            iterator = model_context.get_collection()
        for movie in iterator:
            yield UpdateProgress( text = u'Change %s'%unicode( movie ) )
            movie.rating = min( 5, max( 0, (movie.rating or 0 ) + options.change ) )
        #
        # FlushSession will write the changes to the database and inform
        # the GUI
        #
        yield FlushSession( model_context.session )

To enable List Actions for a certain ObjectAdmin or EntityAdmin, specify the list_actions attribute:

        #
        # the action buttons that should be available in the list view
        #
        list_actions = [ChangeRatingAction()]

This will result in a button being displayed on the table view.

_static/entityviews/table_view_movie.png

An action specified here will receive a ListActionGuiContext object as the gui_context argument of th the gui_run() method, and a ListActionModelContext object as the model_context argument of the model_run() method.

Reusing List and Form actions¶

There is no need to define a different action subclass for form and list actions, as both their model_context have a get_selection method, a single action can be used both for the list and the form.

Available actions¶

Camelot has a set of available actions that combine the various ActionStep subclasses. Those actions can be used directly or as an inspiration to build new actions:

camelot.admin.action.application_action.OpenNewView

camelot.admin.action.application_action.OpenTableView

camelot.admin.action.application_action.ShowHelp

camelot.admin.action.application_action.ShowAbout

camelot.admin.action.application_action.Backup

camelot.admin.action.application_action.Restore

camelot.admin.action.application_action.Refresh

camelot.admin.action.form_action.CloseForm

camelot.admin.action.list_action.CallMethod

camelot.admin.action.list_action.OpenFormView

camelot.admin.action.list_action.OpenNewView

camelot.admin.action.list_action.ToPreviousRow

camelot.admin.action.list_action.ToNextRow

camelot.admin.action.list_action.ToFirstRow

camelot.admin.action.list_action.ToLastRow

camelot.admin.action.list_action.ExportSpreadsheet

camelot.admin.action.list_action.PrintPreview

camelot.admin.action.list_action.SelectAll

camelot.admin.action.list_action.ImportFromFile

camelot.admin.action.list_action.ReplaceFieldContents

Inspiration¶

Implementing actions as generators was made possible with the language functions of PEP 342.

The EuroPython talk of Erik Groeneveld inspired the use of these features. (http://ep2011.europython.eu/conference/talks/beyond-python-enhanched-generators)

Action steps were introduced to be able to take advantage of the new language features of PEP 380 in Python 3.3

Actions¶

Introduction¶

Summary¶

What can happen inside `model_run()`¶

`yield` events to the GUI¶

keep the user informed about progress¶

manipulation of the model¶

raise exceptions¶

handle exceptions¶

request information from the user¶

Issue SQLAlchemy statements¶

States and Modes¶

States¶

Modes¶

Action Context¶

Application Actions¶

Form Actions¶

List Actions¶

Reusing List and Form actions¶

Available actions¶

Inspiration¶

Project Versions

Table Of Contents

Previous topic

Next topic

This Page

Navigation

Actions¶

Introduction¶

Summary¶

What can happen inside model_run()¶

yield events to the GUI¶

keep the user informed about progress¶

manipulation of the model¶

raise exceptions¶

handle exceptions¶

request information from the user¶

Issue SQLAlchemy statements¶

States and Modes¶

States¶

Modes¶

Action Context¶

Application Actions¶

Form Actions¶

List Actions¶

Reusing List and Form actions¶

Available actions¶

Inspiration¶

Project Versions

RTD Search

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation

What can happen inside `model_run()`¶

`yield` events to the GUI¶