### Navigation

- index
- modules |
- next |
- previous |
- Camelot v0.1 documentation »
- Camelot Documentation contents »
- Camelot Documentation »

# Actions

Release: | 0.1
Date: | July 02, 2010

Besides displaying and editing data, every application needs the functions to manipulate data or create reports. In the Camelot framework this is done through actions. Actions appear as buttons on the side of a form and a table. When the user clicks on an action button, a predefined function is called.

> an action is available to show the address on a map

Camelot comes with a set of standard actions that are easily extended to manipulate data or create reports.

This section describes how to put any of the predefined action buttons next to a form or a table.

## Form view actions

All Form view actions are subclasses of the FormAction class, the FormAction class specifies the name and the icon of the button to trigger the action. Its run method will be called whenever the action is triggered.

class `camelot.admin.form_action.``FormAction`(name, icon=None)

  Abstract base class to implement form actions

  `enabled`(entity)

    Overwrite this method to have the action only enabled for certain states of the entity displayed

    Parameter: | entity – the entity currently in the form view
    Returns: | True or False, returns True by default

  `get_icon`()

    Returns: | the Icon to be used in the button to trigger the

    action

  `get_name`()

    Returns: | the name to be used in the button to trigger the action

  `render`(parent, entity_getter)

    Returns: | a QWidget the user can use to trigger the action, by default

    returns a Button that will trigger the run method when clicked

  `run`(entity_getter)
    Overwrite this method to create an action that does something

### Actions to generate documents

Generating reports and documents is an important part of any application. Python and Qt provide various ways to generate documents. Each of them with its own advantages and disadvantages.

> Method | Advantages | Disadvantages
> PDF documents through reportlab | Perfect control over layout Excellent for mass creation of documents | Relatively steep learning curve User cannot edit document
> HTML | Easy to get started Print preview within Camelot No dependencies | Not much layout control User cannot edit document
> Docx Word documents | User can edit document | Proprietary format Word processor needed

Camelot leaves all options open to the developer.

Please have a look at Creating a Report with Camelot to get started with generating documents.

#### Printing through Html documents

class `camelot.admin.form_action.``PrintHtmlFormAction`(name, icon=Icon('tango/16x16/actions/document-print.png'))

  Create an action for a form that pops up a print preview for generated html. Overwrite the html function to customize the html that should be shown:

      class PrintMovieAction(PrintHtmlFormAction):

        def html(self, movie):
          html = '<h1>' + movie.title + '</h1>'
          html += movie.description
        return html

      class Movie(Entity):
        title = Field(Unicode(60), required=True)
        description = Field(camelot.types.RichText)

        class Admin(EntityAdmin):
          list_display = ['title', 'description']
          form_actions = [PrintMovieAction('summary')]

  will put a print button on the form :

  the rendering of the html can be customised using the HtmlDocument attribute :

  `HtmlDocument`

  the class used to render the html, by default this is a QTextDocument, but a QtWebKit.QWebView can be used as well.

  `HtmlDocument`
    alias of `QTextDocument`
  `html`(obj)
    Overwrite this function to generate custom html to be printed :param obj: the object that is displayed in the form :return: a string with the html that should be displayed in a print preview window

#### Generating PDF, TXT and others

class `camelot.admin.form_action.``OpenFileFormAction`(name, icon=Icon('tango/22x22/actions/document-print.png'))

  Form action used to open a file in the prefered application of the user. To be used for example to generate pdfs with reportlab and open them in the default pdf viewer.

  `suffix`

  Set the suffix class attribute to the suffix the file should have eg: .txt or .pdf, defaults to .txt

  `write_file`(file_name, obj)

    Parameters: | file_name – the name of the file to which should be written obj – the object displayed in the form
    Returns: | None

    Overwrite this function to generate the file to be opened, this function will be called when the user triggers the action. It should write the requested file to the file_name. This file will then be opened with the system default application for this type of file.

#### DOCX Word documents

class `camelot.admin.form_action.``DocxFormAction`(name, icon=Icon('tango/16x16/mimetypes/x-office-document.png'))

  Action that generates a .docx file and opens it using Word. It does so by generating an xml document with jinja templates that is a valid word document. Implement at least its get_template method in a subclass to make this action functional.

  `document`(obj)

    Parameter: | obj – the object displayed in the form
    Returns: | the xml content of the generated document. This method calls get_environment,

    get_template and get_context to create the final document.

  `get_context`(obj)

    Parameter: | obj – the object displayed in the form
    Returns: | a dictionary with objects to be used as context when jinja fills up the xml document,

    by default returns a context that contains obj

  `get_environment`(obj)

    Parameter: | obj – the object displayed in the form
    Returns: | the jinja environment to be used to render the xml document, by default returns an

    empty environment

  `get_template`(obj)

    Parameter: | obj – the object displayed in the form
    Returns: | the name of the jinja template for xml document. A template can be constructed by

    creating a document in MS Word and saving it as an xml file. This file can then be manipulated by hand to include jinja constructs.

## List view actions

class `camelot.admin.list_action.``ListAction`(name, icon=None)

  Abstract base class to implement list actions

  `Options`

  Use the class attribute Options, to let the user enter some options for the action. Where options is a class with and admin definition. The admin definition will be used to pop up an interface screen for an object of type Options. Defaults to None.

  `render`(parent, collection_getter, selection_getter)
    Returns a QWidget the user can use to trigger the action
  `run`(collection_getter, selection_getter)

    Overwrite this method to create an action that does something. If the Options attribute is specified, the default implementation of run will pop up a dialog requesting the user to complete the options before executing the action.

    Parameters: | collection_getter – a method that returns an iterator over all objects in the list selection_getter – a method that returns an iterator over all selected objects in a list
    Returns: | None if there was no Options class attribute or if Cancel was pressed, otherwise

    an object of of type Options

### Navigation

- index
- modules |
- next |
- previous |
- Camelot v0.1 documentation »
- Camelot Documentation contents »
- Camelot Documentation »