Specifying a configuration¶
PyBill uses a configuration to customize the rendering of the PDF documents generated from the XML accounting documents in PBD format. This configuration can specify:
- the emitter data: name, logo, address,
- the emitter bank data: name, account number,
- the footer to be written below the PDF documents,
- the separators used in number rendering,
- the agreement text that will be written on the pro-forma documents,
- the localization of the terms used by PyBill in the PDF generation.
The following sections detail how to specify these items. For a more formal view, you can read the XML Schema delivered with PyBill. For a more practical view, you can have a look at the examples delivered with PyBill.
Root element¶
The root element of a PyBill configuration is a config element. This element must have the following attributes:
- format-version
- Attribute containing the name of the version of the format used for the configuration specification. Currently, its only possible value is PBD-1.0 for PyBill Document 1.0.
- name
- Attribute containing the name of the configuration. This name is not used in the PDF generation but is useful to discriminate one configuration from another.
The root element contains the following elements, that are all mandatory:
- company
- Element containing data about the company that emits the accounting documents (logo, address, etc.). See Specifying the emitter data section.
- bank-data
- Element containing data about the bank of the company that emits the accounting documents (name, bank account, etc.). See Specifying the bank data section.
- agreement-intro
- Element containing the lines that are written on a pro-forma and that usually ask for a signature from the client as an agreement. See Specifying the agreement introduction section.
- footer
- Element containing the lines that are written in the footer of all the PDFs generated from the accounting documents. See Specifying the footer section.
- number-separators
- Element containing the separators used to nicely write the numbers in the PDFs. See Specifying the number separators section.
- localisation
- Element containing the localisation of the terms used by PyBill for the PDF generation. See Localizing the terms section
Specifying the emitter data¶
The company element is used to specify the data relative to the company or society that emits the accounting documents. It has the following child elements:
- logo-file
- Optional element containing the relative path to the image file containing the logo of the company. This element contains a string.
- orgname
- Mandatory element containing the name of the organization (company or society) that emits the accounting documents.
- address
Optional element describing the address of the company. The structure of this element is inspired by the DocBook standard and is similar to the one described for the accounting documents (see Sender and receiver addresses section). This element can have the following subelements:
- street
- Optional element containing a string that describes one line of the street specification. Several elements of this type can be defined.
- pob
- Optional element containing a string that describes the post box.
- postcode
- Optional element containing a string that describes the post code (for post process).
- city
- Optional element containing a string that describes the city.
- state
- Optional element containing a string that describes the state (not useful in all countries).
- country
- Optional element containing a string that describes the country.
- phone
- Optional element containing a string that describes the phone number.
- fax
- Optional element containing a string that describes the fax number.
- web
- Optional element containing a string that describes the web site address.
- Optional element containing a string that describes the email address.
The name of the emitter and its address will be displayed at the top of the accounting documents.
Here is an example of a specification of emitter data:
<company>
<logo-name>./my-logo.png</logo-name>
<orgname>My Company</orgname>
<address>
<street>3rd floor</street>
<street>Center Avenue, 124</street>
<postcode>3456</postcode>
<city>GLISBOW</city>
</address>
</company>
Specifying the bank data¶
The bank-data element is used to specify the data relative to the bank of the company or society that emits the accounting documents. It has the following child elements:
- line
- Element containing a string that describes one line of the bank data. Hence, the bank data is divided in several lines (e.g. paragraphs) that will be written at the end of the accounting documents the client must pay (bills, claim forms, downpayments). There can be zero or several line elements in the bank-data element.
Here is an example of a specification of the bank data:
<bank-data>
<line>Golden Squirrel Bank</line>
<line>IBAN: FR01 2345 6789 0123 4567 8901 234</line>
</bank-data>
Specifying the agreement introduction¶
The agreement-intro element is used to specify the text that will be inserted on the pro-formas and that usually asks the client to sign the document. It has the following child elements:
- line
- Element containing a string that describes one line of the agreement introducion. Hence, this text is divided in several lines (e.g. paragraphs) that will be written at the end of the pro-formas documents. There can be zero or several line elements in the agreement-intro element.
Here is an example of a definition of the agreement introduction text:
<agreement-intro>
<line>Please sign here to confirm the command</line>
</agreement-intro>
Specifying the number separators¶
The number-separators element specifies the various separators used to nicely write the numbers in the PDFs generated from the accounting documents. It has three child elements corresponding to the various separators:
- sign
- Element containing the separator inserted between the sign and the number. It contains a string (usually a single character) and is optional. If not specified, the default value for this separator is used (empty value).
- thousands
- Element containing the separator inserted between the thousands digit and the hundreds digit, the millions digit and the hundreds of thousand digit, and so on. It contains a string (usually a single character) and is optional. If not specified, the default value for this separator is used (empty value).
- digits
- Element containing the separator inserted between the integer and the digits. It contains a string (usually a single character) and is optional. If not specified, the default value for this separator is used (.).
Here is an example of the definition of the number separators for the traditional English rendering:
<number-separators>
<sign> </sign> <!-- non blank space -->
<thousands>,</thousands>
<digits>.</digits>
</number-separators>
Localizing the terms¶
The localisation element defines the localisation of the terms that are used by PyBill to write text in the PDFs generated from the accounting documents. Each child element is one of these terms. In order to have a correct generation of the PDFs, all the terms must be defined (that’s why all the following elements are mandatory).
- colon
- Colon that will be inserted after a keyword and before its value. In English, it is just : but in some langages it can be preceded by a non-blank space.
- phone-kw
- Name of the keyword preceding the phone numbers, for example Phone.
- fax-kw
- Name of the keyword preceding the fax numbers, for example Fax.
- web-kw
- Name of the keyword preceding the web site addresses, for example Web.
- email-kw
- Name of the keyword preceding the email addresses, for example Email.
- doc-ref-kw
- Name of the keyword preceding the document reference, for example Our ref or Ref.
- receiver-kw
- Name of the keyword preceding the name of the person the document is specifically sent to, for example c/o
- sender-kw
- Name of the keyword preceding the name of the person that sends the document, for example from.
- on-date
- Introductory phrase preceding the date, for example on, as in Paris, on April 14th.
- bill
- Name designating a bill, typically Bill.
- claim-form
- Name designating a claim form, typically Claim Form.
- downpayment
- Name designating a downpayment, typically Downpayment.
- debit
- Name designating a debit, typically Debit.
- pro-forma
- Name designating a pro-forma, typically Pro-Forma.
- number
- Introductory phrase or symbol preceding the identifier or number of an accounting document, for example #.
- dated
- Introductory phrase written before the date of a document, for example dated on.
- valid-until
- Introductory phrase written before the expiration date of a pro-forma, for example valid until.
- intro-detail
- Text that is written at the beginning of all the accounting document, for example All the amounts are written in Euros.
- quantity
- Name of the keyword designating the quantity of an item, for example Qty.
- description
- Name of the keyword designating the description of an item, for example Desc.
- vat-rate
- Name of the keyword designating the VAT rate of an item, for example VAT rate.
- unit-price
- Name of the keyword designating the unit price of an item, for example Unit Price.
- tf-unit-price
- Name of the keyword designating the tax-free unit price of an item, for example TF Unit Price.
- price
- Name of the keyword designating the price, for example Price.
- tf-price
- Name of the keyword designating the tax-free price, for example TF Price.
- it-price
- Name of the keyword designating the including-taxes price, for example IT Price.
- holdback-on
- Phrase representing the holdback on expression, typically Holdback on.
- ita-est
- Phrase representing the ita est expression, for example i.e. or that is.
- total
- Name of the keyword designating the total, for example Total.
- tf-total
- Name of the keyword designating the tax-free total, for example TF Total.
- vat-amount
- Name of the keyword designating a VAT amount, for example VAT Amount.
- it-total
- Name of the keyword designating the including-taxes total, for example IT Total.
- including
- Phrase representing the including expression, typically including.
- holdback
- Name designating a holdback, typically Holdback.
- on-tf
- Expression designating an holdback that concerns TF amounts, typically on TF amounts.
- on-vat
- Expression designating an holdback that concerns VAT amounts, typically on VAT amounts.
- debit-total
- Name of the keyword designating the total of a debit, for example Debit Total.
- charged-downpayment
- Name designating a previously charged downpayment, typically Downpayment.
- charged-on
- Expression introducing the date when a previous downpayment was charged, for example charged on.
- issued-debit
- Name designating a previously issued debit, typically Debit.
- issued-on
- Expression introducing the date when a previous debit was issued, for example issued on.
- to-be-paid
- Name of the keyword designating the total to be paid, for example To be paid.
- payment-terms
- Name of the keyword designating the payment terms (for the bills, the claim forms and the downpayments), typically Payment Terms.
- to-bring-forward
- Name of the keyword designating the amount to be brought forward (when having multiple pages), for example To bring fwd.
- carry-forward
- Name of the keyword designating the carry forward (when having multiple pages), for example Carry fwd.
The following terms are only used for compatibility with older formats (PyBill 0.X). Nevertheless, they should also be defined:
- your-ref-kw
- Name of the keyword designating the reference given by the receiver to the current exchange, for example Your ref..
- purch-ref-kw
- Name of the keyword designating the reference of the purchase, for example Purch..
- supplier-ref-kw
- Name of the keyword designating the reference given by the receiver to the sender as one of his suppliers, for example Suppl..