Screens: Code generation

Template packs

The App menuTemplate Pack Management screen is where you create and edit the template packs used for source code generation. A template pack holds the templates that each produce one file, the groups that organize them, the type mappings of the target language, and the variables that the people using the pack fill in. How to add a pack to a project and generate code from tables is explained in Generating source code.

Where you can use itWebDesktopWithout signing inSigned inLocal projectsAccount projects

What's on the screen

No.NameDescription
1New buttonOpens the window for creating a new pack (see 'Creating a pack' below).
2Import... buttonImports a pack from a folder or a ZIP file (see 'Exporting and importing' below).
3Store buttonBrowses public packs and brings them into your list. It cannot be pressed when the server is unreachable. See Template store.
4Pack listYour packs. A lock mark means private and a globe mark means public. A pack with saved changes that have not been deployed has a blue name. Deployed packs carry their latest version (v2 and so on), and when you are signed in, favorite and role marks are shown.
5Button rowOn the left the Delete Pack button (the Leave Pack button for co-editors), on the right the Export..., Copy Pack and Save Pack buttons. Packs opened while signed in also have the Deploy button and the visibility button.
6Detail fieldsThe name, author and description can be edited. The language is set when the pack is created and does not change. When you are signed in, the visibility is shown too.
7Pack Configuration tabOn the left the tree of groups and templates, on the right the editor of the selected template or group.
8Settings tabDefines variables and type mappings (see 'Defining variables and type mappings' below). Packs opened while signed in also have the Members and Versions tabs.
  • Once you start editing, the Save Pack button turns on. Your edits are kept only when you save. You can also save with Ctrl+S (Cmd+S on macOS).
  • Edits to templates, groups and variables are all saved together with this one button. Templates are not saved one by one.

Where to open the screen

  • In the app menu at the left end of the header, open the App menuTemplate Pack item and click the App menuTemplate Pack Management item.
  • The App menuCreate Template Pack... item in the same menu opens the create window directly, then opens this screen with the new pack selected.
  • You can also create and open packs from the template pack card and list on the home screen (Home).

On the desktop this screen opens as one work tab (ScreenTemplate Pack Management). When you move to a project tab the screen is not closed but stays hidden, so you can edit a pack, try generating code in a project, and come back to find your edits intact. If you have unsaved edits, you are asked when you close the tab. The web app has no tab bar, and moving to another screen leaves this one (Work tabs).

Where a pack is stored depends on whether you are signed in. The rule is the same as for data dictionary assets (Data dictionary manager).

Desktop, not signed inSigned in (desktop, web)
Packs you create, import or copyPacks on this devicePacks in your account
Packs from the StoreA copy of the published version downloaded to this deviceA copy cloned into your account, or a favorite you use without editing
Deploy, versions, visibility, membersNot availableAvailable. Packs created on this device while not signed in stay packs on this device after you sign in, so they do not have these
Export, importFolder or ZIPFolder or ZIP on the desktop, ZIP on the web

Creating a pack

  1. Click the New button (1).
  2. Enter a name in the Template Pack Name field.
  3. In the Language field, choose the language to generate code in.
  4. Click the Save button. The new pack appears in the list and opens on the right.
  • The Java, TypeScript, Python and C# presets in the language list (2) fill in the type mappings and commonly used variables for that language. For a language not in the list, choose the Custom… (write your own) item and enter its name in the Language name field. The type mappings and variables then start empty.
  • The name field (1) and the language are required. The language cannot be changed later, so create a new pack if you need another language.
  • To start from an existing pack, open it and click the Copy Pack button. A new pack is created with _copy at the end of its name.

Building templates and groups

In the Pack Configuration tab you arrange templates and groups in the tree. Groups are folders that organize templates, and the code generation window shows the same tree.

  • When you pick tags in the tag selection field (1), only templates that have all of those tags stay in the tree.
  • The New Group and Add New Template buttons (2) add a group or template at the top level.
  • Clicking a group (3) shows its name, icon and description on the right, along with the groups and templates inside it. The description appears as a tooltip in the tree.
  • An R mark next to a template means its Read Only setting is on, and an O mark means its Overwrite setting is on (4).
  • Right-clicking a group or template opens a menu (5). On a group you choose the Add Sub-group, Add Template or Delete Group item, and on a template the Delete Template... item. Right-clicking an empty area shows the Add Top-level Group and Add Template items.
  1. Click the New Group button and enter the group name on the right.
  2. Right-click the group and choose the Add Template item. A new template is created in that group and opens on the right.
  3. To move a template to another group, drag it in the tree. Groups can also be dragged into another group or before or after one.
  4. Click the Save Pack button.
  • Templates in the same group are always sorted by name. You cannot reorder them by dragging; only the order of groups changes.
  • Deleting a group does not delete the templates and subgroups in it; they move up one level.

Editing a template

Clicking a template in the tree opens its editor on the right. The upper part holds the template's properties and install rules, and the lower part its body.

No.NameDescription
1Group fieldWhere this template sits in the tree. You do not change it here; move the template in the tree instead.
2Name field, Type fieldRequired. The type is the kind of file, such as Java, TypeScript or XML, and decides the icon in the tree.
3Installation switchWhen on, the generated code is written as a file in the project folder. When off, the code is only viewed, copied or downloaded in the code generation window. Writing files works only on the desktop.
4Installation Type itemThe Write or Replace item creates a new file or replaces an existing one. The Inject snippet item finds the text entered in the Place Holder field in an existing file and replaces it with the generated code.
5Read-only, Overwrite, Git Add switchesWhether to make the file read-only, whether to overwrite an existing file, and whether to run git add after creating it. Only for file creation and replacement.
6Installation Path fieldThe path including the file name. Variables can be used with the same syntax as the body. For snippet injection this is the File to inject into field.
7Alternative path when file exists fieldWhen overwrite is off and the file already exists, the file is written to this path instead.
8Tags fieldType to create a new tag or pick a tag already in the pack. The code generation window filters templates by tag.
9Body editorThe template body. Expand it with the button at the top right. Find with Ctrl+F (Cmd+F on macOS) and replace with Ctrl+R (Cmd+R on macOS).

The body is written in Apache Velocity syntax. When code is generated, the table comes in as $entity, a single column as $field, and the global variables filled in for the project as $env, and tools such as $codegen and $types convert names and pick types. The full list of values and tools is in Template syntax.

public class $codegen.toUpperCamel($entity.name) {
#foreach($field in $entity.fields)
    private $field.mappedType.target $codegen.toLowerCamel($field.name);
#end
}
  • The install path is relative to the location (Location) of the project generating the code. A leading / and .. are cleaned up so the path never leaves that location.
  • If two templates with install turned on have the same install path, the pack cannot be saved. On save, the template with the problem opens and tells you what is missing.
  • This screen has no preview. You see the result in the project's code generation window, as in 'Saving and checking the result' below.

Defining variables and type mappings

In the Settings tab you define the variables that people using the pack fill in, and the rules that turn column types into types of this language.

  • The mark at the top (1) is the pack's language. The Reset to defaults button resets all variables and type mappings to that language's preset. A Custom language goes back to empty.
  • Each row in the Global Variables table (2), the Entity Variables table (3) and the Field Variables table (4) is one variable. Add rows with the Add button.
  • The type mapping (5) is a table where you enter this language's type for each intermediate type that NeoSQL converts DBMS column types into. Types left blank use the value in the Fallback fields.
  • What you enter in the Target type column (6) goes into the generated code as is.
KindWhere the value is filled inHow a template reads it
Global VariablesThe Project settingsCode Generator tab, once per project$env.<key>
Entity VariablesPer table$entity.<key>
Field VariablesPer column$field.<key>

The screens where the values are filled in are explained in Generating source code.

ColumnContent
KeyThe name used in templates. Use only letters, digits and _. A global variable split with dots, such as package.core, is read as $env.package.core
Label, HelpThe name and description shown on the screen where the value is filled in
InputHow the value is filled in: text, multiple lines, an on/off switch, a choice from a list, several values and so on
Default, ReqThe initial value and whether the value must be filled in
Options (select)The choices of a list variable. Enter one value:label per line
  • A key that is empty, malformed or duplicated in the same table cannot be saved. Entity and field variables also cannot use names that $entity and $field already have (name, fields and so on). A list variable with no choices cannot be saved either.

Saving and checking the result

A pack saved on this screen is used right away for code generation in your projects. You see the preview in the window where a project generates code from tables.

  1. Click the Save Pack button.
  2. Open a project that uses this pack and right-click a table in the explorer or the ERD to open the code generation window. If you selected several tables, switch the table to preview at the top of the window.
  3. If something needs fixing, come back to this screen, fix it and save again. The Reapply Preview button in the code generation window generates again with the new content.
  • For your own packs (not favorites), you can also edit the body directly in the code generation window with the Template source edit mode item and save it. That save is kept in this pack too.
  • On the desktop, saving a pack makes the open projects reload it. You do not need to close and reopen the project.
  • For packs you can edit, your projects use your saved copy. Other people and their projects use the deployed version (see 'Deploy, visibility and members' below).

Deploy, visibility and members

These exist only for packs opened while signed in. Saving keeps changes only in your draft; deploying creates a version that others use. Drafts and versions, the versions tab and the members tab work the same as in the data dictionary and are explained in Publishing, versions and backup. Only the differences for template packs are listed here.

No.NameDescription
1Version mark, Unpublished changes markThe version your draft started from, and whether there are saved changes that have not been deployed.
2Update buttonAppears only when another member has deployed a newer version (Update (v3)). Clicking it replaces your draft with the content of the latest version.
3Deploy buttonReleases your saved draft as a version. It cannot be pressed when there are no undeployed changes. Shown to owners, maintainers and contributors.
4Make public buttonPublishes the pack to the Store. For a public pack it is the Make private button. Shown only to the owner.
5Members tab, Versions tabThe people editing with you and the list of deployed versions. Favorite packs do not have them.
6Marks in the listThe favorite mark is a pack you favorited in the Store; any other mark is your role in that pack.
  1. Edit the pack and click the Save Pack button.
  2. Click the Deploy button (3).
  3. Click the Deploy as new version button. For a pack deployed at least once, there is also the Overwrite current version button.
  • If you deploy with unsaved edits, they are saved first and then deployed.
  • To make a pack public, it needs at least one template and a filled-in Author field. If there are undeployed changes, you are told that what becomes public is the last deployed version.
  • Favorite packs are read-only. To edit one, create your own pack with the Clone to edit button; to stop using it, click the Remove favorite button.
  • Member roles are the same as in the data dictionary, except that the Viewer role can also edit and save its own draft; it just cannot deploy.

Exporting and importing

Export saves one pack as a folder or a ZIP file. Use it to move a pack to another device or account, or to edit templates in an external editor.

  1. Open the pack and click the Export... button. If there are unsaved edits, you are asked whether to save first.
  2. On the desktop, click either the ZIP file button or the Folder (for external editing) button and choose where to save. The web app downloads a ZIP file right away.
  3. Where you are moving it, open this screen and click the Import... button. On the desktop choose either the From ZIP file button or the From folder button; in the web app choose a ZIP file.
  4. If the same pack is already in the list, click either the Apply to existing pack button or the Add as new pack button.
  • A folder and a ZIP have the same structure. tp-config.json at the top holds the pack details and language profile, and under the group path each template has its own folder with the body (template.vm) and settings (config.json).
  • 'The same pack' is matched by the pack identifier written in the file, not by name. You are asked when you import a pack exported from this screen back into the same place.
  • A pack with no templates cannot be exported.
  • Versions, members and visibility are not included. An imported pack becomes a pack on this device or an account pack depending on whether the screen is signed in.

Deleting or leaving a pack

  1. Open the pack from the list.
  2. Click the Delete Pack button on the left of the button row. For a pack you were invited to as a co-editor, it is the Leave Pack button.
  3. Read the confirmation and confirm.
  • If a project uses this pack, it cannot be deleted and the project names are shown. Remove the pack from that project's code generation settings first.
  • Leaving removes the pack from your list and also deletes your undeployed draft. The pack and the other members are not affected.

Things to keep in mind

  • What you save is used right away for code generation in your projects. To avoid overwriting files with a template you are still working on, save, check the result in the code generation window first, and then install.
  • A template with the Overwrite switch on replaces existing files in the project folder without asking. Where hand-edited files may exist, turn it off and use an alternative path.
  • Once another member has deployed a newer version, you cannot deploy your draft. Deploying shows the Another editor deployed v3, so your workspace is based on an older version. Deploying now would erase their changes, so nothing was deployed. Export your edits to keep them, use the Update button to get the latest version, then reapply your edits and deploy. notice and the update button (2) appears. Receiving the update discards your unsaved or undeployed edits, so export them first, then receive the update and redo your edits.
  • The Overwrite current version button changes the content of the latest version. Other people's projects using that version change immediately, so deploy a new version if you are not sure.
  • A public pack can be taken from the Store even by users who are not signed in. Making it private again does not remove copies already taken.
  • Packs on this device exist only on this device. Before removing the app or changing devices, export them.
  • If you got a pack made by someone else, read the templates' install paths and bodies before installing. A pack creates and changes files in the project folder.