External module package

Package Definition

In the quickstart we already created a very simple package definition in the file package.json. Although it's sufficient to get us started, there are a lot more settings to be discovered.

Localization

Every text that appears in the user interface of PiWeb can be localized. Simply replace the plain text with a localization dictionary:

{
    "piweb_extension": {        
        "display": "MyExtension"        
    }
}

{
    "piweb_extension": {        
        "display": {
            "" : "My invariant Extension",
            "en-US": "My Extension",
            "de-DE": "Meine Erweiterung"
        }   
    }
}

As you can see, the localized version contains an entry for the invariant culture, which is also used as a fallback value in case the required culture is not translated. Later in this chapter, all localizable properties are marked as localizable string properties.

Dictionaries

Some properties are marked as dictionary, which means they are accepting an object with custom keys and a defined value. In the example below, the items property accepts a dictionary, and myFirstItem as well as mySecondItem are user defined entries in this dictionary.

{
    "items": {
        "myFirstItem": {
            "name" : "My first item",
            "value" : "red"
        },
        "mySecondItem": {
            "name" : "My second item",
            "value" : "green"
        }  
    }
}

Enumerations

The enumeration datatype indicates that only certain strings are accepted. The set of accepted strings is listed in the description of the property.

Package Format

Structure

• name string
• version string
• main string
• engines object
  • piweb string
• piweb_actions object
  • load string
• piweb_extension object
  • type enumeration
  • categories dictionary
    • name localizable string
    • priority number
  • variables dictionary
    • title localizable string
    • description localizable string
    • category string
    • measurement_data_type enumeration
    • raw_data_sources enumeration
    • volume_sources string
    • fetch_defects boolean
    • fetch_formplots boolean
    • parameters dictionary
      • name localizable string
      • description localizable string
      • datatype enumeration

Top Level Properties

name string

Custom string that is used to identify the package internally. Must be composed from lower case characters, digits and a set of special characters: '$', '-', '_', '.', '+', '!', '*', '\'', '(', ')', ','. It must have a length between 1 and 214 characters and may not start with a dot (.) or an underscore (_).

version string

A valid semantic version string containing three numbers, separated by dots. For more information about semantic versioning, visit the project website.

main string

Path to folder that contains the index.js file. In case you used typescript, it is the value of the property outDir in the tsconfig.json file.

engines object

Defines the supported engine versions of this variable. Please read the chapter 'engines' for further information.

piweb_actions object

Defines additional actions. Please read the chapter 'PiWeb actions' for further information.

piweb_extension object

Defines the content of the extension. Please read the chapter 'PiWeb extensions' for further information.

Engines

piweb string

A valid semantic version string containing three numbers, separated by dots. It identifies the toolset that PiWeb will use to execute the extension. For more information about semantic versioning, visit the project website.

PiWeb Actions

load string

A string describing actions, that will be executed when the package loads. Currently, the only recognized value is compile_typescript, which will trigger the typescript compiler.

PiWeb Extensions

type enumeration

Identifies the extension type. Variable extensions use the identifier variable.

categories dictionary

Describes additional categories for the variable editor in PiWeb Designer. Please read the chapter 'categories' for further information.

variables dictionary

Describes the variables that are defined by the package. The actual variable name is the dictionary key. The variable name can be retrieved with the piweb.environment.variableName property.

Please read the chapter 'variables' for further information.

Categories

name localizable string

The name of the category that is displayed in the variable editor.

priority number

The priority determines where the category is placed relative to the existing categories.

Variables

title localizable string

Sets the display name of the variable in the variable editor.

description localizable string

Sets the description of the variable in the variable editor.

category string

Sets the category under which the variable appears in the PiWeb variable editor. The value must appear as dictionary key in the categories dictionary or be equal to one of the built in category keys of PiWeb:

Key	Description
Global	Common variables
Math	Mathematical variables
String	Character string variables
TimeSpan	Date- and time variables
List	Variables to work with lists
Comparison	Variables to compare values
TypeConversions	Variables to convert values
UserDefined	User defined variables (default)

measurement_data_type enumeration

Determines, which kind of data is fetched for this extension. Possible values are measurement_values, measurements and none. The default value is measurement_values. Settings this property to measurements or none might improve the loading performance of your extension in case you don't need measurement values or even measurements.

raw_data_sources enumeration

Determines, which entities are searched for raw data that can be accessed by the extension. Possible values are part, characteristic, measurement, measurement_value and none. The default value is none. You can specify and array with multiple of these values in case you need raw data from multiple sources. Be aware, that fetching raw data might be very performance intensive.

volume_sources enumeration

Determines, which entities are searched for volume data that can be accessed by the extension. Possible values are part, characteristic, measurement, measurement_value and none. The default value is none. You can specify and array with multiple of these values in case you need volume data from multiple sources. Be aware, that fetching volume data might be very performance intensive.

fetch_defects boolean

Determines, whether or not to fetch defect data for the extension. The default value is false. Be aware, that fetching defect data might be very performance intensive.

fetch-formplots boolean

Determines, whether or not to fetch formplot data for the extension. The default value is false. Be aware, that fetching formplot data might be very performance intensive.

Parameters

Describes a dictionary of parameters that can be fetched when calculating the variables result. The key is the parameter name, by which the value can be accessed.

piweb.parameters.getParameter("myparameter");

name localizable string

Describes the localizable name of the parameter that is displayed in the variable Editor.

description localizable string

Describes the localizable description of the parameter that is displayed as tooltip in the variable Editor.

datatype enumeration

Describes the desired datatype of the parameter. The datatype is used to filter user input in the variable editor. It's still possible to pass all kind of data into the parameter. Valid values for this property are integer, double, string and datetime.