ScribusGenerator
Create beautiful documents with data. Open source pdf (and Scribus) template and mail-merge alternative.
Install / Use
/learn @berteh/ScribusGeneratorREADME
ScribusGenerator
Mail-Merge-like extension to Scribus, to generate Scribus and pdf documents automatically from external data (spreadsheet, database and more).
Open source high-quality pdf template and mail-merge alternative. Your imagination is the limit for creating beautiful yearbooks, personalised weedings invitations, game cards decks, clubs rosters, art or work portfolio and many more.
What is Scribus Generator?
Scribus comes with a broad set of page layout features and functionality. One feature missing is to replace text with data dynamically. This kind of feature you may already know as the typical mail merge functionality in your preferred office application.
Scribus Generator provides this functionality. It allows you to:
- replace texts and images dynamically
- change object colors, position, text font or size dynamically
- generate separate PDF (or Scribus) files for each data entry, or a single file from all your data
- work directly in Scribus with a nice user interface, or from the command line
- use any data source (Excel, OpenOffice, MySQL, Notepad, ...) that can export to CSV.
- and much more...
Generally speaking, Scribus Generator replaces text with data to automatically generate files (e.g. SLA, PDF). It has been originally written by Ekkehard Will and further extended by Berteh.
A short how to video introduces this Scribus Generator. 6 first minutes for the basic overview, 12 last for some more advanced features.
How to install Scribus Generator ?
For recent Scribus (1.7.1, 1.6.x, 1.5.6+,...): download the latest ScribusGenerator version. Most recently added features include a GUI for MacOS users.
For legacy Scribus 1.4.x to 1.5.5: Download the older ScribusGenerator archived script. It is not supported any longer, but just works with older (python2-based) systems.
Uncompress the script anywhere on the local machine in a folder your user can write to. Scribus Generator can then be started by choosing the script (ScribusGenerator.py) within the dialog: «Scribus → Script → Execute Script», or from the command line.
How to use Scribus Generator
Create your Scribus "template" file
Create and design your Scribus file as any other. At the positions where you need to replace text with data, just add %VAR_name% where name is the column your data file. Check out our gallery of examples to see what others did. Any existing Scribus file can be used as template.
You can place the variable at any position within a Text Frame. Apply all format and style to the variable that you wish to apply to the final text.
If you wish to generate one page (or many) for each data entry you're done, congratulations ! If you would rather display many data entries on a single page simply add the text %SG_NEXT-RECORD% before each entry but the first: ScribusGenerator will automatically load the new data record as soon as it detects this token.
Create your (csv) Data File
Scribus Generator expects a CSV file (Comma Separated Values), which is very simple to create with a standard spread sheet editor (such as LibreOffice, Excel or GoogleDoc): enter the data and save/export as CSV. Just make sure your CSV file is encoded in UTF-8 to have a full character set (accents, braille, math, cyrillic, symbols,...).
It is important to make sure the columns have the same name as the variables (%VAR_name%) you reference in the Scribus template file you have designed.
We recommend saving in UTF-8 encoding to enable the full set of accentuated characters, chinese, cyrillic, math symbols, arrows, braille, symbols and many more. Simply copy-paste those for which you lack a keyboard combination.
To export well-formated CSV in UTF-8 encoding is easy as pie with OpenOffice or LibreOffice Calc, less so with Excel. If you are using Microsoft's Excel you may be interested in this free add-in that provides good export/import features: http://www.csvio.net/
CSV files can easily be generated from many existing data sources (incl. enterprise-grade ETL platforms, most databases like MySQL, PostgreSQL, SQLite3 and more, ), see our wiki page for using other data sources
Run the Generator Script - Settings (Linux and Windows)
Run the script via the menu: Script > execute Script and launch ScribusGenerator.py.
In the script dialog you can configure the input and output settings for Scribus Generator.
| Input Setting | explanation | | ---- | ---- | | Scribus File | Choose the Scribus File containing the variables to replace. Click ⏏ to open a file explorer, and ↺ to load the Scribus Generator settings from that file. | | Data File | Choose the Data File containing the comma separated values. Click ⏏ to open a file explorer. | | Data Field Separator | Character that delimitates data field in your CSV file, comma (,) by default. | | From - To | To run Scribus Generator on a subset of your data mention the starting and/or last lines of this subset, not counting the header line. Simply leave empty to generate from the beginning (or to the last) data entry.|
| Output Setting | explanation |
| ---- | ---- |
| Output Directory | Choose the path to an existing directory where to save the result. Click ⏏ to open a file explorer. |
| Output File Name | You can use the same variables as defined in the Scribus File/Data File. You can also use variables and the dedicated %VAR_COUNT% index reflecting the row position in the Data File. It is used by default if you leave the field empty.|
| Save Settings | Store the current Scribus Generator settings in the source SLA file, for future use. |
| Merge in Single File | Select to generate a single output (SLA and/or PDF) file that combines all data rows. |
| Output Format | Choose the Output Format of the generated files, either PDF or Scribus. |
| Keep Scribus Files | Select to keep the generated Scribus Files. Otherwise they will be deleted after pdf generation. This option has no effect if you choose Scribus output format.|
Additional (more technical) options can be set to tailor the automatic recording of Scribus Generators actions in your system by editing the logging.conf file. You may, for instance, want to move the location of the log file (scribusGenerator.log by default) to a directory that does not need admin rights to edit in Windows (C:\tmp\scribusGenerator.log), or replace file-logging with your default system logger (SysLogHandler in Linux, NTEventLogHandler on Windows). All settings (and more) are described in the Python logging documentation.
Run the Generator Script - Settings (MacOS)
Run the appropriate script via the menu: Script > execute Script and launch ScribusGeneratorMac.py.
The Mac version of the script uses the Scribus Plugin API which has support for a very limited GUI, so you will instead have to enter and confirm your settings in a series of dialog boxes:
This dialog just lets you know that Scribus Generator is now running, and tells you that you will be presented with a series of dialogs collecting the needed input infos. Kindly follow the very detailed ScribusGeneratorMac guide for a step-by-step walktrough. Many thanks to kmcreative for this nice addition to ScribusGenerator.
Mac users can also use the command line version of Scribus Generator, from a terminal window.
Dynamic Images
Images references can also be dynamically modified with Scribus Generator. See the screencast video @6:10.
All images supported by Scribus can be used. However, to work with ScribusGenerator, they must all be located in a single folder containing all images. This folder can be located anywhere on your PC. Duplicate any image in this folder and rename it %VAR_pic% (and similarly for any other variable name you need to use for pictures, %VAR_pic2%, %VAR_photo%).
Add an Image Frame anywhere in the Scribus file («Scribus → Insert → Insert Image Frame») and open the dialog for getting an image (e.g. right click Image Frame → Get Image... on selected frame). Select the needed "placeholder" picture.
The images file can be defined just like any other vari
