Acces to db made easy

- Prev: SqlTable
- Next: Browsing data

# Printing

Sqlkit adds printing capability throught OpenOffice.org template module that in turn uses templates created with Openoffice.org and very simple syntax.

In this module ‘print’ is used in a loose way. In all situations ‘print’ means producing a printable file, it can be an `.odt` file or a `.pdf` one.

Note

In a network environment you’ll probably use a remote server that means the file will not be generated locally. Openoffice 3.1 comes with python2.6 interpreter and uno module even under Windows. So that there’s no problem using that interpreter or using a different interpreter but pointing to it’s modules. If you need to have uno modules under windows you can follow instructions in this tutorial or on stackoverflow

## Sqlkit printing

Each sqlwidget has a `printing` attribute that manages printer entries that is an instance of `PrintTool`.

A standard way should be as easy as just setting a directory where templates should be found and adding menu entries via `add_menu_entry`. The default template dir is a subdir of the current directory named `templates`.

Templates present in this directory -if named as the nick of the sqlwidget- will be automatically added, but you will normally want to customize the context or adding variable to it or adding formatting functions (e.g. to transform numbers into monetary format), that can be easily done connecting to context-ready signal.

The default way of filling the context wraps each object into an `ObjectProxy`` that uses Fields to present each value in a human readable format, that means also that it tries hard to follow foreign keys and substitute values retrieved by foreign key description & search field.

## Tables: iteration on records

Oootemplate offers a powerfull way to iterate over lines via the `++` syntax. It requires you to define a table’s name matching an entry in the context. For SqlTables the default name for such table is Table1 and all records in the table end up there.

For SqlMask the default behaviour is to add an entry in the context for each related attribute (eg: movies for the director‘s mask). Each such entry holds all the related records as per sqlelchemy class definition. In the director/movie example the default context would be:

    context = {
       'obj' : <Director: my displayed director>,
       'movies' : [(<Movie: movie1>, <Movie: movie2>)]
    }

It’s up to you to prepare the openoffice file to be used as template with a table named `movies`: you do that interactively editing oowriter’s table attributes. If you prefere to have to have a different table’s name or you need to customize the content of the record, you simply connet to ‘context-ready’ signal and prepare the context directly.

## ObjProxy

What stated above is only partially true... each object is wrapped in another object that allows you to write `direct_id` but really returns what you would really want: a human representation of the id exactly as returned by `field.lookup_value(id)`.

## API

class `sqlkit.misc.printing.``PrintTool`(master)

  A print obj that is able to create a default context to handle to oootemplate.

  `__init__`(master)

    Initializes the printing tool setting a default template dir and checks for availability of module ‘uno’ from openoffice. If uno is missing the printing capabilities are made invisible.

    If templates are found with the name `nick.odt` where the nick is the nick of the sqlwidget, entries are automatically added. This way you can generate templates and use them w/o even the need for a single line of code (unless you need to customize the context, of course)

    Parameter: | master – the table or mask instance of which this is a printing tool

  `add_menu_entry`(description, template_name, server=None, port=None, mode='pdf', output_name=None, accel=None, tip=None, action_name=None)

    Add menu entry with ‘description’ using ‘template’ Both are fake printers in the sense that are ‘printer to file’

    Parameters:

    - description – the description that will appear in the menu entry
    - template_name – the template name to be used
    - mode – the mode of the printer: pdf or odt
    - output_name – the output name. Can be a callable that will receive `template_name` as parameter. If `self.output_dir` is defined `output_name` will be joined with `self.ouput_dir` to retrieve it from the client
    - accel – accelerator to be used with this
    - tip – tip for the entry
    - action_name – action name (defaults to templ_ + template_name)

  `prepare_context`(context)

    This function is meant to be overridden by a customized one

    Parameter:

    context –

    the automatically prepared `oootemplate.Context`. It contains 2 keys:
    - ‘obj’: the current object for mask and normally None for tables
        (unless an object was edited, in which case it will point to that object)
    - ‘Table1’ : the list of record currently loaded in this sqlwidget

    You can add any keys but remember to use the correct syntax for tables (a dict with lists as <values).

    This is normally used to set totals or arrange so that related table’s record are used in Tables. Read example 76.

  `template_dir`
    The directory where templates are searched for. Default is cwd/templates. It’s a path significant for the openoffice server
  `server`
    the openoffice server to connect to for printing
  `port`
    the port to use to connect to the server
  `output_dir`
    the output dir when server is remote as viewed from client (may be an URL)
  `remote_output_dir`
    the output dir when server is remote as viewed from server (a local file for the server)
  `pdf_viewer`
    the preferred viewer for pdf files
  `odt_viewer`
    the preferred viewer for openoffice templates
  `add_to_table`(context, table_name, obj_list, master=None, reset=True, format=None)

    Add to an openoffice table a list of objects wrapped in ObjProxy

    Parameters:

    - context – the context to be manipulated
    - table_name – the table_name where objects list must be added
    - master – the master where to retrieve fields
    - obj_list – the list of objects to be added
    - reset – boolean. If True the list becomes the only list, otherwise it’s added. Defaults to True

  `obj_proxy_class`
    The `ObjProxy` to use to wrap objects. Can be changed any time. You can customize it so that __getattr__ can return fancy personalization of the attributes

class `sqlkit.misc.printing.``ObjProxy`(obj, master=None)

  A proxy that returns a “human value” for each attribute. The default behaviour is to use the fields defined for the object in the SqlWidget i.e.: field’s `get_human_value`. You can customize ObjProxy changing `__getattr__` or simply adding methods whose name is `class_name__attribute_name` as in:

      class MyObjProxy(ObjProxy):
          def Movie__director_id(self, value):
              return value.title()
      table.printing.obj_proxy_class = MyObjProxy

  in this context value is already the value returned by `sqlkit.fields.Field.get_human_value()`

## Signals

context-ready:

the context has been prepared. You can connect to this signal to add element to the context.

`context_ready_cb(printtool, context, template_name, sqlwidget):`

  Parameters:

  - printer – the printing.PrintTool object that emitted the signal
  - context – the context
  - template_name – the template name that is rendered
  - sqlwidget – the sqlwidget