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¶