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, remove them and other unneeded files (e.g. .map files) and replace sourceMappingURL references in JS files from TypeScript development with sourceURL references for better debbuging in production environments.

Note

We reccomend the usage for all projects because of the clean up of unnecessary files

Usage

To export the command line or a bash script can be used:

1. Navigate to the root of the formdev-project

2. call the export script with the formdefinition folder path you want to export:
   npm run export -- --formDefPath=relPath/to/your/formdefinition-folder

3. The exported formdefinition gets copied to export folder in your formDev root:
   formDev/export/formdefinition-folder/

Possible arguments:

argument	How to use	Description
--formDefPath	--formDefPath=relPath/to/your/formdefinition-folder	Relative path to the FormDefinition folder.
--outputPath	--outputPath=relPath/to/your/custom/export-folder	Relative path to the Output folder.
--outputPostfix	--outputPostfix=customFolderPostfix	Append custom postfix to exported folder name.
--switch	--switch=customSwitch	Define which placeholder from the placeholder.json should be used. See also "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 a 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 FormDefinition 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 localhost:8484/oauth but the port can be changed.

Usage

To upload the command line or a bash script can be used:

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 form server which are not are not going to be uploaded.
-d, --download	-d	Download FormDefinition files as ZIP. This will not upload the FormDefinition.
-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 access token.
--disable-ssl	--disable-ssl	Disable SSL verification.
--backup	--backup	Download backup of FormDefinition before upload.
--ignore-flags	--ignore-flags	Do not upload flags.json.

Boilerplate

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

Usage

To create a form the command line or a bash script can be used:

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/formdefinition-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.

HTML Key Generator

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

1. Navigate to the root of the formdev-project

2. call the script:
   npm run generateTranslations -- --formDefPath=./formdefinitions/formDefinitionFolder --langCultures=de-DE,en-US

Usage

Possible arguments:

argument	How to use	Description
formDefPath	--formDefPath=./formdefinitions/formDefinitionFolder	Relative path to the FormDefinition 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
outputFolder	--outputFolder=./formdefinitions/TranslationExport	Relative path to the Output folder. Default folder is "TranslationExport" in the formDefinition 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-win-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, it´s sometimes hard to detect if text nodes are really text content that should be translated. Default: false.

Default html attributes that get replaced:

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

Default data-win-options that get replaced:

• label
• htmlLabel
• tooltip
• placeholder
• emptyContent
• buttonLabel
• buttonHeading
• descriptionStart
• descriptionEnd
• hintText
• hintHtml
• errorText
• errorHTML
• dialogText
• 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

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

Email Template

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

MJML files gets translated via CLI tool or the HybridForms Exporter. The Exporter convert 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

HTML Formatter

There is a custom formatter for HTML files predefined and registered for VSCode. To use it, the extension Custom Local Fomatters (killian.custom-local-formatters) or simply all recommended extensions must be installed via Visual Studio Marketplace. To format HybridForms FormDefinition HTML files a custom JS script format-html-files.js located in sources folder is used by the extension.

By default VSCode use this extension to format HTML files. The setting can be found in the .code-workspace file.

Usage

1. Setup Custom Local Fomatters:

Add following part to settings JSON to specify which script to use and which languages to format with it.

"customLocalFormatters.formatters": [
    {
        "command": "node ./sources/format-html-files.js",
        "languages": [
            "html"
        ]
    }
],

2. Set the extension as default formatter:

• Add following part to settings JSON to set the extension as default formatter.

"[html]": {
    "editor.defaultFormatter": "jkillian.custom-local-formatters",
}

• Right click on the file and select Format Document With.... Chosse the right formatter.

Note

Use editor.formatOnSave setting to format files on save.

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-win-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 (an example is attached) located with the form definition and ending with "*.mapping.xlsx." A configuration JSON file also located with the form definition (an example is attached):

{
    "fieldsToMap": [
        {
            "fieldName": "data-win-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 above method is recommended.

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

npm run export -- --formDefPath=../../../Shared/FormDefinitions/area.PolizeiDE-TH/OWOZGInc_AndereStrafanzeige --outputPath=../../../Shared/FormDefinitions/area.PolizeiDE-TH/Exported --mapExcelFields=true

HTML V9 Migration

There is a script for migrating HTML files from FormDefintion v8 to FromDefintion v9. Some widley common used practices are deprecated, which are automatically migrated.

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

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 for one command use --help <command>.