Packages

A package is a collection of data that can be loaded into Showcase.

Package can contain one or more component definitions, new data types, dynamic libraries that will be loaded in the Showcase client, and assets and other data the components use.

Package structure

A package is defined in a JSON file with name [package name].package, for example my-awesome-plugin.package. This file should be in the root of your package folder. Each package folder should only have a single package definition file, use different folders for different packages.

In the same folder you should have the dynamic library that contains your compiled plugin, schema files that define your components and optionally description files and screenshots of your components to be displayed in the Editor.

If your components use any extra data files like images or CSS files, they should be in a separate data folder inside the package folder.

Example package folder structure:

example-package/
├── data
│   └── example-component.css
├── example-package.package
├── example-component.schema
├── example-component-description.html
├── example-component-screenshot.png
└── libexample-plugin.so

Package files

The package definition file defines the package metadata like package name and version, and lists all components, libraries and assets included in the package. Note that package name must be unique, if Showcase finds multiple packages with the same name, they are treated as different versions of the same package. In that case Showcase picks the best match to load based on the package's version and required Showcase version.

Example package definition file:

{
  "name" : "Example package",
  "package-version" : "1.0.0",
  "libraries" : [ "example-plugin" ],
  "required-showcase-version" : "SHOWCASE_VERSION",

  "components" : {
    "example-component" : {
      "type" : "ui",
      "priority" : 10,
      "data-folders" : [ "data" ],
      "css-files" : [ "example-component.css" ],
      "schema" : "example-component.schema",
      "description" : "example-component-description.html",
      "ui-name" : "Example component"
    }
  },

  "data-types" : {
    "example-data-type" : {
      "schema" : "example-data-type.schema",
      "ui-name" : "Example data type",
      "editor-icon" : "fa fa-file"
    }
  }
}

Supported fields in package definition.

• name. Name of this package, each package must have a unique name.
• package-version. Internal version number of the package. Showcase always uses the newest available version.
• libraries. List of dynamic libraries included in this package. If library prefix and suffix are not included, they are handled automatically. If string SHOWCASE_VERSION is included, it's replaced during runtime with the current version of Showcase. Note that libraries are loaded in the order they are listed here.
• required-showcase-version. Version of Showcase that is required for this package. Showcase uses semantic versioning. Package is accepted if patch version of Showcase core is greater or equal to this version and major and minor versions are same. Again SHOWCASE_VERSION is replaced during runtime with current Showcase core version.
• components. List of components contained within this package. Component names must be unique, and should only contain alphabetic characters and hyphens.
• data-types. List of any data types included in this package. Data types names must be unique, and should contain only alphabetic characters and hyphens.

Fields for components in the package definition file.

• type. Available types are ui, service, theme-default, graph-node-generator and graph-property-generator.
• priority. Numerical priority to use this component whenever Editor is automatically creating components, for example when dropping assets from media library to structure. Editor chooses the component with highest priority if multiple options are available. It is not usually necessary to set this.
• data-folders. These folders will be added to application search paths. Files in these folders can be referenced with “component-name:file”.
• css-files. These files are automatically loaded into the application.
• schema. Name of the schema file that defines this component. The schema file is expected to be in the same folder as the package file.
• description. You can define an html file to add an optional description for this component. The description is visible in the Editor component editor.
• ui-name. You can define the name that appears for this component in the Editor. By default the visible name is the component's name with hyphens replaced with spaces and the leading character capitalized.

Fields for data types in the package definition file.

• schema. Name of the schema file that defines this data type.
• ui-name. Name that appears for this data type in the Editor.
• editor-icon. Icon the Editor will use to display this data type.

Schema files

Each component should have a schema file that defines the component. The schema files are JSON files. Schema file defines everything about the component including how the component can be used with other components (roles), how it can use other components (slots) and how it can be configured (attributes).

Below is a full list of supported fields in schema files. Most schemas only use a small subset of these fields.

General schema fields:

"includes" : [ "showcase-package:widget.schema" ],
"roles" : [ "background", "main" ],
"data-types" : [ "asset" ],
"subtype" : "toolbar",
"data-gathering" : true,

• includes. You can include other schema files to inherit properties for this component.
• roles. Roles this component can fill. If another component has a slot “main”, this component can be added to that slot if it has the role “main”.
• data-types. List of data-types this component supports.
• subtype. Subtype is used to group components in shared slots. For example the default Showcase toolbar has role decoration and subtype toolbar. It can be added to any decoration slot. If you create your own toolbar with the same role and subtype, only one of the toolbars can be added to a widget at a time.
• data-gathering. Enable data gathering for this component. This will enable automatic data gathering events such as widget created, widget destroyed etc. for this component.

Defining slots in schemas:

"slots" : {
  "toolbar" : {
    "type" : "ui-component",
    "min" : 0,
    "max" : 1,
    "ui-name" : "Toolbar",
    "description" : "Choose a toolbar.",
    "shared" : true

• slot-name. Name of this slot, if the slot type is “ui-component” only components that have a role matching this name can be added to this slot.
• type. Slot type can be either “ui-component” or “graph”. You can add other components with a matching role to a “ui-component” slot. If the slot type is “graph”, you can add a content set to the slot and define “node-attributes”.
• min. Minimum number of components in this slot.
• max. Maximum number of components in this slot.
• ui-name. Name to appear in the Editor for this slot.
• description. Optional description to appear in the Editor for this slot.
• shared. If slot is shared, a component added to this slot is given a name in the Editor, and the same named component can be reused in other shared slots.

Defining attributes in schemas:

"attributes" : [
  {
    "attribute-name": "text",
    "type": "string",
    "ui-name": "Displayed text",
    "default" : "Hello world!",
    "description": "This is an example attribute."
  }
]

• attribute-name. Name of this attribute. This must match an attribute of the target widget or node.
• type. Type of this attribute, for example float, string, ui-component, asset.
• ui-name. Name that appears in the Editor for this attribute.
• default. Default value for this attribute that will be displayed in the Editor. Should match the default value set in code or CSS.
• description. Description that’s displayed in the Editor for this attribute.

Other supported fields for attributes in schemas:

"min" : -10,
"max" : 10,
"step" : 1,

"advanced" : true,
"mime-filters" : [ "image/*" ],
"required" : false,

"visibility" : "hidden",
"visibility" : [
  { "role" : "content-viewer", "value" : "hidden" },
  { "value" : "visible" }
],

"has-auto-generated-value": true,
"in-theme" : false,
"multiple" : true,
"component-role" : "content-viewer",

"type" : "multiple-choice",
"choices" : [
  {
    "name" : "Option 1",
    "value" : "none"
  },
    "name" : "Option 2",
    "value" : "auto"
  }
],
"default-ui-name" : "Option 2",

• min. Minimum value for this attribute (for numeric attributes). Defining both min and max values for a numeric attributes enables a slider for setting the attribute value.
• max. Maximum value for this attribute (for numeric attributes).
• step. If the attribute has a slider for setting the value, you can define the step size.
• advanced. If advanced is set to true, the attribute is listed under the advanced attributes in the Editor.
• mime-filters. If this is an asset attribute, you can set mime filters for files that can be dropped to this attribute field in the Editor.
• required. If the attribute is set as required, it must be filled before the component can be used in the application.
• visibility. If set to hidden, the attribute is not displayed in the editor, but can still be used internally. You can also set the visibility to depend on the role the component is assigned to, so the attribute is hidden when the component is assigned as content viewer for example.
• has-auto-generated-value. Used internally by the Editor for attributes that the Editor can auto-generate values for.
• in-theme. If set to false, this attribute is only visible in the content editor and won’t appear in theme editor.
• multiple. If enabled, expand this attribute to multiple attributes similar to shared slots. One attribute for each available component/subtype appears in the Editor.
• component-role. If attribute type is ui-component, you can set a role requirement for components that can be used for this attribute.
• multiple-choice. You can configure a list of options for this attribute so user can choose from a drop-down list. Set the visible name and a matching attribute value for each option.
• default-ui-name. Only valid for multiple-choice attributes. Set the default choice using the UI name.

You can add a slot with type graph to add a content set to the component:

"slots" : {
  "content" : {
    "type" : "graph",
    "supported-types" : [ "asset", "url" ],
    "node-attributes" : [
      {
        "attribute-name" : "content-viewer",
        "type" : "ui-component",
        "component-role" : "content-viewer",
        "in-theme" : false,
        "required" : [
          { "type" : "node", "value" : false },
          { "value" : true }
        ]

• supported-types. Limit the types of content nodes this component accepts.
• node-attributes. Attributes that appear for each node in this graph. Same options as component attributes.