Creating a ThingWorx Widget Extension

Creating a ThingWorx Extension¶

The following topic covers the process of using the ThingWorx Visual SDK Utility to create a widget extension. You can use the utility as a global CLI tool from any location on your system.

Setting Up Your Environment for the CLI¶

Download and extract the twx-wc-sdk-utility-[VERSION].zip file, and then run the following commands:

Change your directory to the utility folder:
```
  cd twx-wc-sdk-utility
```
then run:
```
npm link
```

Using the Command Line Interface¶

Utility input¶

Before running the utility, create a working folder. You can create the folder on any location on your system. Your working folder should have the following file structure:

input/widgets.json - Specifies the web component widgets that you want to include
.npmrc - Specifies the configuration options that are required to connect your component to an npm registry. Make sure the file contains the following configuration options:
```
registry=<REGISTRY_URL>_auth=<ENCODED_STRING_OF_YOUR_CREDENTIALS>
always-auth=true 
email=<YOUR_EMAIL>
```
input/widgets/ - Specifies properties for the widget extension
input/ui/ - Specifies ThingWorx-related wrapping code that adapts the web components to ThingWorx widgets. All components inherit from the widgetWrapper code (which is also in this folder).
input/styles - Contains theming files for the widget

Running the utility¶

Open a command prompt, and then change your directory to your working folder.
Run the following command to create the extension:
```
mub
```

The utility creates a ThingWorx a extension that can you can import and use in Mashup Builder.

You can use the following options to configure the utility:

Parameter	Description
`--debug`	Sets the logger level to debug.
`--skip-pack`	Creates the extension without compressing the output into a ZIP archive.
`-s, --skip-install`	Skips the installation step when running the utility. The install step is only required for the first time.
`--lock`	Generates a `package-json.lock` file (don't use `--no-lock` mode)'.
`--excludelibraries`	Specifies the library names to exclude. See `mub/input/static/ootbLibs.json` to check what libraries are already included or excluded from the ptcs-widgets package. You should specify the excluded folder names as they appear in `node_modules`. For example: `gulp --excludelibraries @polymer,mocha,@webcomponents`
`clean`	Removes the latest artifact and all temporary code that is used to build it.

Running the utility without using an npm registry¶

Before using the SDK utility, we recommend that you publish your web components to an npm registry. By default, the SDK utility retrieves the web component using the link and user credentials that are stored in the .npmrc file. You can run the utility without this file, unless it is required by a dependency in your widgets.json file. To use the utility without using a .npmrc file, perform the following steps:

Create a folder named tmp/ on the same level as your input/ folder.
Copy your web component folder manually to the tmp/ folder.

Edit the htmlImports section in the <web_component>.json file of your web component input/widgets folder to specify the location of your component:

"htmlImports": [
  {
    "from": "npm",
    "id": "simple-el",
    "version": "file:simple-el",
    "url": "simple-el/simple-el.js"
  }
]

Run the SDK utility using the mub command.

Utility output¶

When you run the utility, the generated files are placed under the dist folder:

By default, the generated files are compressed into a ZIP file named dist/{package name or extension name}.zip that you can import into the ThingWorx Platform.
When you run the utility with the --skip-pack parameter, a folder is created and the extension files are placed under dist/target.

Viewing logs¶

You can view the logs for the utility under the log folder of your working folder. The folder contains two files:

combined.log - Contains all log messages
error.log - Contains error log messages

Advanced configuration¶

For more detailed information about widget configuration, refer to Packaging a Web Component as a ThingWorx Widget.