package | PiWeb Plot Extension API Reference

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

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 plot. 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. Currently, the only accepted value is plot, which identifies a PiWeb plot extension.

display localizable string

Sets the display name of the element in the PiWeb Designer toolbox.

description localizable string

Sets the description of the element in the PiWeb Designer toolbox, which is visible when the user hovers over the entry.

icon string

Path to the icon, relative to the package.json file. Usually, you simply specify the filename, and place the icon next to your package.json file. The icon is used on several places in PiWeb Designer, such as the toolbox, the page structure and the element properties tab. PiWeb can handle the following file formats: bmp, gif, ico, jpg, png, tiff, wmp.

PiWeb will scale the image to a size of 16*16 and 32*32 pixels. To achieve the best result, use an ico file that contains bitmaps of both sizes.

measurement_data_type enumeration

Determines, which kind of data is fetched for this plot. 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 plot. 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 plot. 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 plot. 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 plot. The default value is false. Be aware, that fetching formplot data might be very performance intensive.

toolbox object

If you want multiple toolbox entries to be generated by your plot (e.g. because your extension provides a full infrastructure of elements), you can define them here. Please read the chapter 'toolbox properties' for further information.

propertygrid object

Determines the properties of the plot that can be adjusted by the user in PiWeb Designer. Please read the chapter 'propertygrid properties' for further information.

Toolbox Properties

categories dictionary

Describes additional categories for the element toolbox in PiWeb Designer. Please read the chapter 'toolbox categories' for further information.

items dictionary

Describes the entries for the element toolbox in PiWeb Designer. Please read the chapter 'toolbox elements' for further information.

Toolbox Categories

name localizable string

The name of the category that is displayed on top of it in PiWeb Designer.

priority number

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

Toolbox Elements

name localizable string

Sets the display name of the element in the PiWeb Designer toolbox.

description localizable string

Sets the description of the element in the PiWeb Designer toolbox, which is visible when the user hovers over the entry.

icon string

Sets the icon of the element in the PiWeb Designer toolbox. Please read the chapter 'icon' for further information.

category string

Sets the category under which the element appears in the PiWeb Designer toolbox. 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	English Name	German Name
`Audit`	Audit calculations	Auditberechnungen
`AutoShapes`	Autoshapes	Autoformen
`Container`	Container	Container
`PlotExtensions`	Extensions	Erweiterungen
`Formplots`	Form plots	Formplots
`General`	General	Allgemein
`Images`	Images	Bilder
`InteractiveElements`	Interactive elements	Interaktive Elemente
`Statistics`	Statistics	Statistik
`TablesAndDirectories`	Tables & Directories	Tabellen & Verzeichnisse
`Templates`	Templates	Vorlagen

element_size object

Describes the initial size of the element when created on the report. Please read the chapter 'element size' for further information.

Element Size

width number

The initial element width on the report in millimeters.

height number

The initial element height on the report in millimeters.

Propertygrid Properties

categories dictionary

Describes the categories of the PiWeb Designer that are used by the plot extension. Please read the chapter 'propertygrid categories' for further information.

entries dictionary

Describes the additional property grid entries of the plot. The defined property grid entries are added to a set of default properties that every element has. Please read the chapter 'propertygrid entries' for further information.

Propertygrid Categories

name localizable string

The name of the category that is displayed in the PiWeb Designer property grid.

priority number

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

Propertygrid Entries

name localizable string

The name that will be displayed in the property tab of PiWeb Designer.

description localizable string

The info text that will be displayed when hovering the property with the mouse.

category string

The key of the entry in the categories dictionary to which this property is associated. In case you want to use existing categories, like General, Appearance or Layout, you have to use the following keys:

Key	English name (en-US)	German name (de-DE)
`General`	General	Allgemein
`Axis`	Axis	Achsen
`Appearance`	Appearance	Darstellung
`Layout`	Layout	Layout
`GaugeIntegration`	Measuring device integration	Messmittelanbindung
`Misc`	Misc	Sonstiges

type enumeration

The datatype that determines which kind of editor is shown for the property:

Type	Description	Editor
`string`	Unicode text
`integer`	Integral number
`double`	Floating point number
`boolean`	Yes/No value
`enum`	Selection of an option
`color`	Color with opacity
`colorscheme`	Array of well composed colors
`brush`	Color or gradient with opacity
`pen`	Pen with color, thickness, dashstyle and opacity
`font`	Font with family, color, size and style, as well as textdecorations

default_value any

Each datatype accepts a different default value:

string

"default_value": "value"

Any unicode string is accepted.

integer

"default_value": 1

Integral numbers are accepted.

double

"default_value": 1.0

Floating point or integral numbers are accepted.

boolean

"default_value": true | false

true and false are accepted.

enum

"default_value": "value"

The keys of the options property are accepted.

color

"default_value": "#ff0000"

Strings in the form of #rrggbb.

brush

"default_value": {
    "type": "solid" | "lineargradient" | "radialgradient",
    "color": "#ff0000", 
    "color2": "#0000ff", // only gradient brushes
    "opacity" 1.0,       // [0..1] where 1 is opaque
    "angle": 0,          // Only for linear gradient
    "center": {          // Only for radial gradient
        "x" : 0.5,       // [0..1] 0 = left, 1 = right
        "y" : 0.5        // [0..1] 0 = top, 1 = bottom
    }
}

Accepts an object of the specified structure. Some properties are only used for special brush types.

pen

"default_value": {
    "color": "#ff0000",
    "thickness" 0.3     // Millimeters
}

Only pens with solid color and thickness are accepted.

font

"default_value": {
    "color": "#ff0000",
    "family": "Arial",
    "size": 10,
    "bold": false,
    "italic": false,
    "underline": false,
    "strikethrough": false,
}

Accepts a font description object with the properties shown above.

options dictionary

Determines the possible values of a property with type enum. The plot will get the key of the selected entry as value for the property. Please read the chapter 'option properties' for further information.

Option Properties

name localizable string

The name that is displayed in the dropdown.

description localizable string

The description that is displayed when hovering an option in the dropdown with the mouse.