Dev Tools

These CLI tools can or have to be used to make form development faster and easier.

Exporter

The exporter merges primary HTML files in Includes projects but can also be used to compile TypeScript and SASS. It also removes these and other unneeded files (e.g. .map files) and replaces sourceMappingURL references in JS files from TypeScript development with sourceURL references for better debbuging in production environments.

Note

We recommend using this tool for all projects, as unnecessary files are cleaned up.

Usage

1. Navigate to the root of the formDev-project

2. Call the export script with the Form Template folder path you want to export:
   npm run export -- --formDefPath=relPath/to/your/form-template-folder

3. The exported Form Template is copied to the export folder in your formDev root:
   formDev/export/form-template-folder/

Possible arguments:

argument	How to use	Description
--formDefPath	--formDefPath=relPath/to/your/form-template-folder	Relative path to the Form Template folder.
--outputPath	--outputPath=relPath/to/your/custom/export-folder	Relative path to the Output folder.
--outputPostfix	--outputPostfix=customFolderPostfix	Append custom postfix to the exported folder name.
--switch	--switch=customSwitch	Define which placeholder from the placeholder.json should be used. See "Placeholders"
--excludeFiles	--excludeFiles=someImage.jpg,*.xml	Defines a list of files that should not be exported. Provide a comma seperated list of strings and/or glob patterns.
--update­Version­Date	--updateVersionDate=true/false	Update the Date property on the Form version tag, see Form Version. Default is true
--compileFiles	--compileFiles=true/false	Compile TypeScript and SASS files. Default is true
--formatHtml	--formatHtml=true/false	Format HTML file after processing. Default is true
--templateVersion	--templateVersion=major	Set Version property on the Form version tag, see Form Version. Allowed values are Semver version string (X.Y.Z), major (increase major by one), minor (increase minor by one) and patch (increase patch by one)
--help	--help	Display help.

Uploader

The uploader is a handy CLI tool to upload Form Template files to a given server. It supports all used authentication methods available for HybridForms.

Note

AzureAD authentication must either use ClientID and ClientSecret or allow an additional redirect url to use OAuth authentication. The default redirect url is http://localhost:8484 but the port can be changed.

Usage

1. Navigate to the root of the formDev-project

2. Call the script:
   npm run upload

3. Fill in all asked properties

Possible arguments:

argument	How to use	Description
-s, --server	-s "yourServer.hybridforms.net"	The server url to connect.
-u, --user	-u "yourUser@example.com"	The username of the AD for ADFS and Basic Auth. ClientID of AzureAD user.
-p, --password	-p "yourPassword"	The password of the AD user for ADFS and Basic Auth. ClientSecret of AzureAD user.
-c, --client	-c "clientName"	The client name or ID to connect.
-t, --templates	"[Name on server or itemID]@[Path to folder or ZIP]" "[Name on server or itemID]@[Path to folder or ZIP]"	Templates to upload.
-D, --delete	-D	Delete all files from server which are not going to be uploaded.
-d, --download	-d	Download Form Template files as ZIP. This will not upload the Form Template.
-q, --quiet	-q	Disable all output.
-v, --verbose	-v	Will print verbose info for the execution.
-h, --help	-h	Display help for command.
-fnt, --force-new-token	-fnt	Force getting new auth token.
--oauth	--oauth	Use OAuth for authentication.
--oauth-port	--oauth-port 8080	The local port to use for OAuth.
--prevent-store	--prevent-store	Prevent storing of the access token.
--disable-ssl	--disable-ssl	Disable SSL verification.
--backup	--backup	Download backup of Form Template before upload.
--ignore-flags	--ignore-flags	Do not upload flags.json.

Boilerplate

The boilerplate is a CLI tool to create a starting point for Form Template development. It creates the absolute minimum of files to start creating an own HybridForms form template.

Usage

1. Navigate to the root of the formDev-project

2. Call the script:
   npm run createForm -- projectName

3. Fill in all asked properties

Possible arguments:

argument	How to use	Description
projectName	npm run createForm -- projectName	The name of the FormDefiniton. Snake Case (All Caps) prefered, e.g. EXAMPLE_PROJECT
-p, --path	-p relPath/to/your/form-template-folder	The path to create template.
-h, --help	-h	Display help for command.
--sass	--sass	Use Scss as prefered CSS library.
--ts	--ts	Use TypeScript as prefered JS library.
--includes	--includes	Create includes project.
--index	--index	Add index.json to project.

Translation Key Generator

HybridForms helper tool to generate translation keys for multilingual forms. Replaces predefined contents of html attributes, data-hf-options and text content with translation keys, saves the original contents to a translation.json and generates an Excel.

1. Navigate to the root of the formDev-project

2. Call the script:
   npm run generateTranslations -- --formDefPath=./form-templates/form-template-folder --langCultures=de-DE,en-US

Usage

Possible arguments:

argument	How to use	Description
formDefPath	--formDefPath=./form-templates/form-template-folder	Relative path to the form-template folder. Required
langCultures	--langCultures=de-DE,en-US	Provide a comma-seperated list of languages that should be included in the translation files, eg: "en-US,de-DE,zh-CN". The first provided culture is used as default. Required
outputPath	--outputPath=./form-templates/TranslationExport	Relative path to the Output folder. Default folder is "TranslationExport" in the Form Template folder.Optional
translatePlaceholder	--translatePlaceholder=true	If set to true all "data-ph-*" placeholders get replaced by keys. Default: false
excludePlaceholderRegExp	--excludePlaceholderRegExp='.*[iI]d$%.*prefix$'	Provide a list of regular expressions for placeholders that should not be translated. Use the character "%" for seperating the regular expressions.
addHtmlAttributes	--addHtmlAttributes=some-attribute,another-attribute	Provide a comma-seperated list of html attributes that should be translated.
addDataWinOptions	--addDataWinOptions=some-attribute,another-attribute	Provide a comma-seperated list of data-hf-options that should be translated.
translateTextContent	--translateTextContent=true	If set to true, the key generator tool replaces text content of all elements with keys. This option should be used with care, sometimes it's hard to detect if text nodes are really text contents that should be translated. Default: false

Default html attributes that get replaced:

• alt
• title
• placeholder
• aria-label
• data-hf-options
• data-hf-include

Default data-hf-options that get replaced:

• label
• htmlLabel
• tooltip
• placeholder
• emptyContent
• buttonLabel
• buttonHeading
• descriptionStart
• descriptionEnd
• hintText
• hintHtml
• errorText
• errorHTML
• dialogText

Translation Compare

Because git diff cannot show differences of Excel files, this helper script can be used to check what has been changed in translation.xlsx files.

1. Navigate to the root of the formDev-project

2. Call the script:
   npm run compareTranslations -- path/to/compare/source.xlsx path/to/compare.xlsx --outFile=path/to/compare/diff.json

   • npm run compareTranslations
     • first parameter: filepath to the xlsx source file
     • second paramater: filepath to the xlsx file that should be compared with the first one

Usage

Possible arguments:

argument	How to use	Description
-h, --help	-h	Display help for command.
--outFile	--outFile=path/to/diff.json	If set, the diff output is saved to the given file. Optional

Email Template

MJML is used as an email templating framework. It keeps developing responsive emails and project footprint simple. For detailed docs please visit official documentation: https://documentation.mjml.io/.

MJML files get compiled via CLI tool or the HybridForms Exporter. The Exporter converts the original file to [original_filename].txt.

Usage

1. Navigate to the root of the formDev-project

2. Call the script:
   npm run email -- path/to/mjml/file -o path/to/output/file.txt

Excel Field Mapper

This feature is intended to parse an Excel file where IDs (of controls/fields) are defined along with validators (or other data-hf-option properties) in another column. These validators are then mapped to the corresponding controls during export and on-the-fly in formDev.

To achieve this, you need:

• An Excel file ending with "*.mapping.xlsx"
• A configuration JSON file

Example:

{
    "fieldsToMap": [
        {
            "fieldName": "data-hf-options.validator",
            "columnName": "D"
        }
    ],
    "idColumn": {
        "name": "A",
        "startRow": 2
    },
    "worksheetName": "Mapping"
}

You could set these fields described in the JSON via the exporter's CLI options, but the method above is recommended.

However, what needs to be set through the exporter's CLI is the flag --mapExcelFields=true:

npm run export -- --formDefPath=relPath/to/your/form-template-folder/form-template --outputPath=relPath/to/your/custom/export-folder --mapExcelFields=true

HTML V9 Migration

There is a script for migrating HTML files from Form Templates v8 to Form Templates v9. Use this for automatical migration.

Info

Deprecation warnings are logged and an error message is shown in the FormDev environment.

• RadioBoxes need value attribute to ensure saving the correct shadow value for a radio group. The value attribute must be added to the RadioBox. The migration script adds the attribute value="selected".

• inline style display:none This style is used by conditions and should be avoided on HTML elements. Use class hf-hide instead. The migration script replaces inline display: none with class hf-hide.

• disabled, readonly attribute To ensure that readonly conditions work correctly, FormControls must be disabled using the disabled: true option. The migration script replaces disabled and readonly attributes with the disabled: true option.

Usage

1. Navigate to the root of the formdev-project

2. Call the script:
   node sources/htmlMigrateV9.js path/to/html/file

Possible arguments:

argument	How to use	Description
-d, --debug	-d	Run with debug logging.
-h, --help	-h	Display help for command.

HTML Template Migration

There is a script for migrating HTML files from old Form Templates to new. Use this for automatical migration.

• Title Templates

• Form Blocks

• Form Controls

Usage

1. Navigate to the root of the formDev-project

2. Call the script:
   node sources/htmlMigrateTemplate.js path/to/html/file

Possible arguments:

argument	How to use	Description
-d, --debug	-d	Run with debug logging.
-h, --help	-h	Display help for command.

HybridForms Node

There is a CLI for the HybridForms Node package.

1. Navigate to the root of the formdev-project

2. Call the script:
   npm run hybridforms -- <command>

Usage

Possible arguments:

argument	How to use	Description
-h, --help	-h <command>	Display help for command.

There are several commands to execute. To list them all, use: --help. For a detailed argument list use command: --help <command>.