Table of contents
- Node.js versus browser
- Promises
- Authentication
- Schemas, the QIX interface
- Generic object model
- JSON-RPC protocol
enigma.js as a library can be used both in a Node.js environment, as well as in a browser. This enables you to build projects that are portable, and behaves similarly on top of enigma.js. But this compatibility also introduces a few differences in configuration that we explain more in detail under the Configuration section.
Asynchronicity in the JavaScript world is commonly solved by using either promises or callbacks.
enigma.js makes heavy use of promises because we believe that it gives you several advantages compared to callbacks:
- cleaner code for the end-user,
- error handling can be deferred more easily,
- and is compatible with emerging standards (async/await).
All generated API methods returns a promise.
Read more:
enigma.js does not handle authentication due to the simple reason that different products and deployments handle it differently. We do however provide a couple of examples for the more common use cases which you can find on the link below.
Read more:
enigma.js uses schemas to generate a programmatic interface against QIX Engine. Below we will outline what a schema consists of, and what their purpose are.
An important note is that enigma.js normalizes the QIX method names into camelCasing,
while QIX Engine uses PascalCasing. GetObject in QIX Engine would be getObject
in enigma.js.
enigma.js allows you to invoke QIX methods by either using what is called 'position', which is an array of parameters, or by name, using an object with key/value pairs.
Example of using the different parameters:
doc.getObject('object-id');
doc.getObject({ qId: 'object-id' });Read more:
QIX classes are generic object interfaces
describing the available QIX methods you may interact with for that type. Depending
on the schema version used, there may be a number of different classes available
(if you are curious, check the specific schema file you are using for the available
classes and methods). You generally create, retrieve, and remove these from the Doc
interface.
Read more:
- Doc class
- Field class
- GenericBookmark class
- GenericObject class
- GenericDimension class
- GenericMeasure class
- Global class
The QIX Engine error codes have constants in the schema that you can use to make your error handling code easier to read.
Read more:
This section will give you a brief overview how the generic object model works. See the links at the end of this section for more in-depth information.
The QIX Engine uses what we call the generic object model within a document (also called app).
These generic objects all have unique identifiers, and can be interacted with using the QIX interface schema methods.
Consider this:
A document, document.qvf, contains generic object properties, data, load scripts, etc. When
you want to interact with that content, you generally use the generic object model. Let's say
you want to interact with a generic object with id my-object:
doc.getObject('my-object').then((api) => {
// api is now an object with QIX interface methods for the GenericObject struct
});When we do getObject, we will request a handle
for that object. Until that session is closed, QIX Engine will notify you of changes on that handle
every time it gets invalidated (either by changes related to the data model referenced in it, or property changes).
Note that these changes will only be triggered when QIX Engine changes the state from valid to invalid on that handle:
// bind 'changed' event to get notified when the state is invalid':
api.on('changed', () => console.log('The generic object changed'));
// `getLayout` will set the generic object state to 'valid' in QIX Engine,
// evaluating any hypercubes, expressions, etc. inside it:
api.getLayout().then(() => {
// 'getProperties' will give you the underlying properties describing
// the generic object layout, including the hypercube/expression sources etc.:
api.getProperties().then((props) => {
// modify some properties to you liking:
props.someValue = true;
// 'setProperties' will modify the generic object state from 'valid' to
// 'invalid' in QIX Engine, causing a 'changed' event in enigma.js:
api.setProperties(props).then(() => {
// the 'changed' event handler above should now have been invoked
});
});
})Read more:
QIX Engine uses JSON-RPC over websockets for communication. In short, it means the enigma.js gives you an API that will be translated into a JSON-RPC request object, and handle the JSON-RPC response sent back from QIX Engine, eventually back to you in a predictable format. Please see the links below for more details about the protocol.
Read more: