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.

../_images/new_view_address.png

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 :

../_images/print_html_form_action.png

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.

../_images/simple_report.png
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

Table Of Contents

Previous topic

Creating Forms

Next topic

Delegates

This Page