Exports

Exporting data from your application's classes is done using a premade export helper, which adds a export button to your application.

Adding export helpers to classes

In the Blueprint editor, click the "Actions" button at the top left of the screen, followed by the "Add action" button. Give a name to the new action, then pick the class you want to add the helper to. You can now select the "Export" helper from the "Helper type" drop down menu. Make sure to save your action.
An export button will now appear for this particular class in your application (relevances influence visibility for different user groups, set these at the "Relevance" tab in the action properties). You can set the export button to appear at the search results level and/or the record details level, set this under the "Properties" tab.

The standard export dialogue

When the export button in the application is clicked and no records are selected a small dialogue is presented with the question: "Do you want to select all records?" If the user selected records before clicking the export button the application goes directly to the export dialogue where selecting a field separator, fields to be exported, possibly a character set, et cetera can be set.

Notes

A common problem with exports is that the data itself contains the field separator, for example a semicolon (;) or a tab (indicated by ). In those cases choose a more obscure separator like a pipe (|) or tilde (~) or even a sequence of characters if necessary.
Often users want to be able to open an export in Excel. An option for export to an Excel file is included in the export dialogue. However, you may encounter some quirks. Say a text field contains the value "8-2", for example a house number. Excel will think this is a date field and may display it as "8-February", or international phone numbers like "+31203726574" may erroneously be interpreted as a calculation.
Should you encounter these problems, an alternate strategy is to save your export as text with a valid separator character. Remember Excel only allows a single separator! Open Excel and open the exported text file. In the succeeding dialogue, you will be asked to indicate whether this file is a character separated file (yes), what the character separator is, along with some other options. Finally, you can also indicate the datatype for each column. If you choose "text" here for the problematic columns, Excel will treat your data correctly.

Advanced options and predefined exports

In some cases, you may wish to skip the dialogue and predefine an export. This presents a more user-friendly interface for your users, and if your export requirements do not change often this is probably more convenient. It can also be used to expand the export format. You tune the export with a few simple parameters. In the blueprint editor, go to the action at hand, and go to the export helper parameters by clicking "Edit parameters" underneath the helper type. Parameters are described by their tooltips. We will focus on 2 here:

Export specification url

Here you can specify the fields for the export by using: '$record.get(field name)'. Sometimes, field data in your database must be transformed to a different format for an export. Let's say there is a field called "type" in your database with possible values "c" and "e". However, the export requires this field to contain the words "Customer" and "Employee". You can use a velocity file to do this.

The export action expects the velocity file to contain 1 line for each field to be exported. A line containing pure velocity statements is not considered a field line. A line containing velocity code may not be preceded by tabs or spaces. So an export specification would look like this example:

#if($record.get("type") == "c") 
    #set($type = "Customer") 
#else 
    #set($type = "Employee") 
#end
$record.get("last_name")
$type

If you want to add an empty column than add a blank line. Note that this parameter alone will not be preceded by a header. This may be defined in another velocity file, assigned to the "header row url" parameter.

Header row url

Obviously, this parameter is mainly used in combination with the export specification url. The specification should be a velocity file returning a list. To communicate with the export action, the list variable should be called $return. It is already a list when the header specification is read. In case of the example above, the header specification could look like this:

$return.add("last_name") 
$return.add("type")

If you added blank line in de export specification url than this column must have a header as well.

Free format

If you want even more control, you can use the free format option. Again a velocity file describes the output of the export.
Add the following settings:

the location of this file is set using the "export specification url"
file name
free format to "yes"

There is an important difference in the way the export handles this file. In all other case, the content of this field is evaluated against a single record of the database table (or object of a class if you prefer). This is done until there are no more records in the table. When using free format, the velocity file is evaluated only once using the full table of records as input variable.

The reason for this is to give you more freedom to create the output . You may want for example a page break or an empty line after a certain number of records, or a header and a footer. The example exports to an xml file

<xml>
#foreach($record in $table)
  <person>
      <last_name>$record.get("last_name")</last_name>
      <type>$record.get("type")</type>
  </person>
#end
</xml>

200810320011DOKE  NAME$record.get("name")GENDER$record.get("gender")1RECORDEND