bm-thing-transformer
v2.1.6
Published
Develop in ThingWorx with a proper IDE.
Downloads
502
Readme
Intro
A tool that allows the development of Thingworx models in a real IDE. This repo contains the following:
- The
bm-thing-transformer
module, which is a typescript transformer that converts TypeScript source files into Thingworx entity XML files. - The declarations of the decorators and thingworx specific types that are interpreted by the transformer
- The declarations of the standard thingworx entities such as
GenericThing
andInfoTableFunctions
Index
Usage
You should primarily use this via the Thingworx VSCode Project Template. For more information, refer to that repository.
Nevertheless, you can use this standalone as well, by including it in your project with npm install bm-thing-transformer
.
This must be used together with the typescript compiler api. Create a TWConfig object then use the transformer factory as a transformer in your TypeScript project in both the before
and after
phases of the transformation e.g.
import { TWThingTransformerFactory, TWConfig, TWThingTransformer } from 'bm-thing-transformer';
// Initialize the typescript program
const program = ...
// Create a twconfig object
const twConfig: TWConfig = {
projectName: 'MyProject',
store: {} // This should be empty
}
// Use the transformer factory in both the before & after phases
const emitResult = program.emit(undefined, () => {}, undefined, undefined, {
before: [
TWThingTransformerFactory(program, path, false, false, twConfig)
],
after: [
TWThingTransformerFactory(program, path, true, false, twConfig)
]
});
// Fire post transform actions, which enable features like data shape inheritance
for (const key in twConfig.store) {
// Exclude non-transformer entries
if (key.startsWith('@')) continue;
twConfig.store[key].firePostTransformActions();
}
After the emit finishes, the transformers will properties to the store
object of your twconfig object. This is an object whose keys are the names of the generated entities and their values are each an instance of the transformer. Beyond those related to the actual transformation, the transformer has the following public methods that can be invoked after the program's emit method returns:
toXML(): string
- Returns a string that represents the XML definition of the entitytoDeclaration(): string
- Returns a string that represents the declaration of the entity in its relevant collection. For example, with a Thing, the declaration will be something like:
declare interface Things { MyThing: MyThing }
write(path?: string): void
- Writes the result oftoXML()
to a file at the specified path, inpath/build/Entities/<CollectionName>/<EntityName>.xml
. The path defaults to the project path.
Development
Pre-Requisites
The following software is required:
- NodeJS: needs to be installed and added to the
PATH
. You should use the LTS version.
The following software is recommended:
- Visual Studio Code: An integrated developer environment with great javascript and typescript support. You can also use any IDE of your liking, it just that most of the testing was done using VSCode.
Development Environment
In order to develop this extension you need to do the following:
- Clone this repository
- Run
npm install
. This will install the development dependencies for the project. - Start working on the project.
File Structure
ThingTransformer
│ README.md // this file
│ package.json // node package details
│ LICENSE // license file
└───scripts // build scripts
│ │ clean.js // clean script
└───src // main folder where your development will take place
│ │ file1.ts // typescript file
| | ...
└───static // folder containing declarations to be used in a thingworx project
└───dist // files used in the distribution
Build
To build the project, run npm run build
in the root of the project. This will generate the appropriate files in the dist
folder.
Contributors
- BogdanMihaiciuc: main developer.
- dwil618: support for min/max aspects and date initializers.
- stefan-lacatus: support for inferred types in property declarations, method helpers, bug fixes, support for the
@exported
decorator and API generation, data shape inheritance,declare
modifier on members, upgrade from typescript 4 to typescript 5. - elena-bi: bug fixes
- s-amory:
SQLThing
type definition. - CozminM: compatiblity with thingworx 8.5
- kklorenzotesta: thingworx API typing updates