Hyper Open Edge Cloud

How To Use PDF Editor

How To showing how to use the PDF Editor to convert PDF documents into ERP5 compliant modules.
  • Last Update:2016-02-09
  • Version:001
  • Language:en

PDF Editor (aka. ScribusUtils) is a tool that allows you to convert a pdf based document (with some special field-implementation) into an ERP5 compliant Module.

Table of Contents

Background

The main document can be based on a paper form (filled by hand) and The final result is a Module in which you can add new objects by filling all the necessary fields. The script allow two kind of filling forms in ERP5 :

  • ERP5-like basic form (as most forms under ERP5)
  • PDF-like graphic form (same rendering as the original pdf document).

How to Use ScribusUtils to convert PDF Files in ERP5 compliant HTML form

Input Documents

Two files are needed to generate a conversion : .PDF & .SLA .

The SLA file has to be created as a final filling form under Scribus (as it is a Scribus file). A background is accepted but other special graphic objects (such as lines, circles, images, etc.) shoud be escaped in the final document.

The fields have to be created as 'PDF fields' and their type is chosen according to the final expected rendering.

Each field needs a name (in the name property). Whitespaces and special characters are not allowed as this name will be used as the object name in ERP5 (for example 'my_destination_last_name'). Beware the field's name must match ERP5 naming conventions.

The TooltipField holds other properties such as title, order, nb, etc. (exhaustive list and restrictions available further in this document) but you can also use properties available from the Scribus interface to define what you wish (text, integer, float, multiline, required, etc.).

Keep in mind priority is given to user-defined properties rather than scribus properties (this means that if field type is integer under Scribus, but user specified multiline text, the script will render a multiline field.

Once your document is finished, you save your .SLA document under the name of your choice and export also the result as a .PDF file (used to generated the PDF output under ERP5).

There it is, you now have all the files you need to generate a new module.

Running Script

Thanks to these two documents, you can now run the script.

For that you have to use your favourites : 'Create Module From Scribus' (calls the form 'createERP5Site_viewCreateModuleScribusDialog') and fill it with needed values. The left side refers to the Module properties while the right side is about Object.

Once this is done, you just have to link your .SLA and .PDF documents and check the kind of rendering you mant to generate and then click 'create'.

Depending on your documents'size and on your server connection the files can take up to some minutes to upload.

If everything is going well, you should be redirected to ERP5 main page once the module is generated.

Then you just have to select the new module in the module list available and chose 'Add Object'.

If an error occurs, you can check the ERP5 logfile to have more informations (the script tries to log as many usefull events as possible).

Using New Module

If no error is raised, a new object be created in the object list on the ERP main page.

Just click on it and then select from the Action list 'add MyObject'.

You should be redirected to the rendered output, PDF-like or ERP-like depending on your previous selections.

How Does This Work?

  • The script parses the .SLA file (which is in fact a XML file) and recover all the usefull properties by page.
  • From these objects properties and the Module information, it creates a new Object Form in the specified folder (by default the 'custom' folder) and generates the ERP5 fields inside. A Module Form is created to list the objects. If final rendering is graphic, then a CSS file is also generated to be able to resize the fields at the good place, and save background pictures in images also in the specified folder. Document and PropertySheet are created to save the properties.
  • When accessing to an object of the module, the form calls its relative PageTemplate ('form_view' for standard ERP5 rendering and 'form_html' for special rendering). The Page template renders each of the fields and call if necessary (only for special pdf-like rendering) the CSS class corresponding to the field. All the rendering is in fact done dynamically thanks to the page template that uses the objects from the form and the CSS class if necessary. This means you are able to modify and update some fields after ScribusUtils work (in fact you can modify almost everything in ERP-rendering), but beware that the CSS class will not be automatically modified afterward, and so the PDF-like rendering will be pretty much difficult to update and keep working.

Requirements

These softwares (only needed in Graphic rendering for background pictures generation) :

  • pdftoppm (from Xpdf)
  • convert (from ImageMagick)
  • scribus (to generate input files : you do not need scribus installed on the server if .sla files are already completed). Scribus file supports are 1.2.* / 1.3.0-1.3.1 / 1.3.2-1.3.4, but it is recommended to use 1.3.4 or later (if compliant with Scrivus description file format) to get better results and avoid bugs.

The following files:

  • ScribusUtils (at ERP5Form/)
  • ERP5Site_createModuleScribus (at ERP5Form/Extensions)
  • ERP5Site_updateModuleScribus (at ERP5Form/Extensions)

The Input form and Script (in ERP5):

  • ERP5Site_createModuleScribus
  • ERP5Site_updateModuleScribus
  • ERP5Site_viewCreateModuleScribusDialog
  • ERP5Site_viewUpdateModuleScribusDialog

Naming Conventions

Here are listed all the field properties you can specify on your fields by setting them in the tooltipfield.

The tooltipfield has to be considered as a dictionnary, with entry separator '#' and id/value separator ':'.

For example 'nb:020#title:Diagnostic#type:TextAreaField#order:Left'.

The properties order is not important and you can specify your properties the way you want, the only restriction is that you need the property_name ('nb', 'type', etc.) separated from the property_value with a ':', and all properties separated with a '#'.

Spaces and special caracters (except ':' and '#') are allowed in the properties_values.

[Global properties]

Creation number 'nb'

The creation number is used to specify the order of the fields when rendering as ERP5 basic form, and define the tabulation order in the PDF-like rendering. Numbers are integer only, but missing numbers are allowed (you can have number 10 but no number 9 for example). All fields with no creation number will be created at the end. The script automatically group field_numbers by page, this means creation order is processed for the first page, then for the second, etc. to preserve page integrity and prevent tab order to move from one page to the other.

Field title 'title'

The field title is used as a user-friendly text instead of the field-name (more abstract). It represents the main text in the ERP rendering (text on the left-side of the field), and is displayed as a tooltiptext in graphic output(when the user leaves the cursor over the field for a second).

Position order 'order'

This position order is only used for the ERP-based rendering to specify where the field will be rendered, and is ignored in graphic view (order is automatically recovered from the page_number). It can accept 'left' (default),'right', 'center' or 'bottom'.

The type specification 'type'

This property allows the user to specify by itsef the field type without using the Scribus Dialog boxes. It is needed for RelationStringField for example, which have no equivalent in PDF-fields. compliant values are : 'StringField','TextAreaField','RelationStringField','DateTimeField','IntegerField','CheckBoxField'. Default type is StringField

The required property 'required'

Specify if the field is required or not, i.e if the user has to enter a valid alue or if the field can stay empty. values : '0' (default) or '1'.

[String``Field, Integer``Field and Float``Field properties]

Maximum caracters allowed 'maximum_input'

for these fields, the user can specify the maximum number of caracters allowed, and when rendering as an ERP5 basic form the size of the field (to match exactly the maximum number allowed). This value can possibly be specified with the Scribus interface in the object's 'option' tab. It must be an integer-compliant (float will be automatically converted to the closest integer).

[Date``Time``Field properties]

The format specification 'input_order'

This property is used to specify in which order the dates will have to be filled. Allowed values are 'year/month/day' (default), 'day/month/year' and 'month/day/year'. For more efficiency you can just enter the first letter of each name : 'ymd', 'dmy' and 'mdy'. As the date format available under Scribus (through the Scribus Interface 'date field format') does not match the ERP5 presentation, ScribusUtils ignore them and only take care of the user specification in the tooltipfield.

The restriction 'date_only'

The date_only property permit to restrict the usage of a DateTimeField to a 'DateField' by escaping the time rendering. values are : '1' (default) or '0'

The specification 'date_separator'

This 'date_separator' property permit to define the separator between the different field values. This separator is displayed when filling the form in ERP5 rendering (the PDF-like rendering will only display the InputBoxes, without any other character), but is also used to process the PDF output final rendering (via the 'print' button). The value can be any String except ':' and '#' characters (for the moment). Default value is ' '. This can be very usefull to fill PDF fields wich have already '/' characters, or to expand date elements like '2006 02 01' instead of '2006 02 01'. Note that if you want to have empty spaces like ' ' or ' ', you have better no to insert the 'date_separator' property at the end of the tooltip (as the parsing procedure can not get the spaces at the end of the tooltipfield).

The second specification 'time_separator'

Works the same way as the 'date_separator' property, but specify the separation between hours and minutes. default is ' ' and same note apply (do not leave this property at the end of the tooltipfield if it contains spaces).

[Relation``String``Field properties]

'portal_type'

specify the portal_type related to the RelationStringField

'base_category'

specify the base_category to the RelationStringField

'catalog_index'

specify the catalog_index to the RelationStringField

'default_module'

specify the default_module to the RelationStringField

[RadioField properties]

To make RadioField, it is necessary to create a String field in the scribus file. And it is necessary to give the global proerty type in the tooltipfield. So for this field, it's type:RadioField You must also specify other porperties:

'items'

the property items is a suite of item separated by '|'. This property is also define in tooltiptooltipfield.

'orientation'

You have choice between two values: 'vertical' and 'horizontal'. If this property is not specify the value is 'vertical'

Example:

type:RadioField#items:young|adult|senior#orientation:horizontal

It is possible to make a RadioField only when you choose ERP5Form render and not with graphic render

[CheckBoxField properties]

To make CheckBoxField, it is necessary to create a CheckBox field in the scribus file. You can also specify globals porperties.

Related Articles