Working with Creo.JS

Creo.JS Scripts

The JavaScript code executed by Creo.JS must be included in the <script> tag, which has the type set as text/creojs. The src attribute is supported for scripts included in the web page. The scripts must be located relative to the HTML page location.

Absolute scripts references, for example, src=http://some-server/foobar.creojs are not supported.

After a web page loads, Creo.JS framework scans the DOM of the web page. It loads all the Creo.JS scripts in the connected Creo session. The scripts are executed by Creo.JS engine.

Creo.JS scripts are loaded in Creo and executed in the order of their appearance on the web page. The Creo.JS scripts are loaded and executed asynchronously when the web page loads.

When the web page fully loads, Creo.JS scripts may not have been fully loaded, even though all page elements onload event listeners are executed. If you want the web page to wait for Creo.JS initialization and termination events, set the event listeners CreoJS.$ADD_ON_LOAD and CreoJS.$ADD_ON_UNLOAD respectively.

The CreoJS.$ADD_ON_LOAD adds an event handler that executes the initialization script only after all the Creo.JS scripts are loaded. To ensure that the initialization code which interacts with Creo.JS code is executed after all page scripts are initialized, set Creo.JS onload event handler inside the onload event handler of the page in the <body> tag. See the following sample code:

<html>
    <head>
        <script src="creojs.js"></script>
        <script type="text/creojs" src="browser.creojs"></script>
        <script type="text/creojs">
            function getActiveModelName () {
                return pfcGetCurrentSession ().GetActiveModel ().FileName;
            }
        </script>
    </head>
    <body onload="CreoJS.$ADD_ON_LOAD (initialize)">
        <b>Active model:</b> <span id="MODELNAME"></span>
        <script>
            function initialize () {
                CreoJS.getActiveModelName ()
                    .then (function (name) {
                        MODELNAME.innerHTML = name;
                    })
            }
        </script>
    </body>
</html>

Use the CreoJS.$ADD_ON_UNLOAD event handler to execute the deinitialization code when the browser unloads the page. These handlers execute the script before Creo.JS destroys context associated with the page being unloaded. You can also release the Creo resources allocated by the page.

Each web page has its own isolated context inside the Creo.JS engine. The context is created when the web page is loading and destroyed when the web page is unloading. The pages can communicate with each other using the Creo.JS session storage, which maintains a global context of Creo.JS engine. This is similar to the browser property Window.sessionStorage.

Embedded Scripts

It is recommended to use the id attribute for embedded Creo.JS scripts. The id are returned in errors which further helps to identify location of the problem.

The following example shows an embedded script.

<script type="text/creojs" id=”example1.creojs”>
    function getActiveModelName () {
        let session = pfcGetCurrentSession ();
        let model = session.GetActiveModel ();
        return model ? model.FileName : null
    }
</script>

External Scripts

When you use external Creo.JS scripts it is recommended to use .creojs extension. Do not use .js extensions for external scripts. The .js scripts may not load properly in the web page due to the file type association of the system.

If scripts do not load in Creo with .creojs extension , check your system for .creojs file type association. If there is a default program assigned to handle .creojs files, remove it to resolve this problem.

This following example shows an external script.

<script type=”text/creojs” src=”test/example3.creojs”></script>

Calling Creo.JS Code from Browser Code

Browser code can call any globally declared Creo.JS function using the syntax CreoJS.functionName(parameters). Such calls are executed asynchronously and return a Promise object, which is used to access the result when it is ready . The input arguments are serialized as JSON, which are sent to Creo.JS environment along with the function name. When Creo.JS environment is ready to run the call, it is asynchronously executed by the engine and a JSON serialized result is sent back to the browser page. To process the result, the browser code subscribes to it by providing a processing callback function to the method then(). The callback function is available in the Promise object returned by Creo.JS function call.

In the example below, the browser code calls getModelType function, which is declared in <script type=”text/creojs”> section. A callback function is registered to consume the result and use the result value to render the HTML text in the current document.

<script type="text/creojs" id=”curmodelname.creojs”>
    let session = pfcGetCurrentSession ()
    function getModelType (filename) {
        try {
            let model = session.GetModelFromFileName (filename)
            return model ? model.Type.string () : null
        }
        catch (ex) {
            return null
        }
    }
</script>

<script>
    var filename = document.getElementById ('filenameinput').value
    CreoJS.getModelType (filename).then (function (modelType) {
        var type = modelType || 'not found'
        var text = filename + ' has type "' + type + '"'
        document.appendChild (document.createTextNode (text))
    })
</script>

JavaScript which runs in the browser uses the CreoJS.functionName (parameters) syntax to call a function, which is declared in the Creo.JS. This call returns a Promise. A Promise represents a return value, which is available when the calling function exits. The return value is delivered asynchronously from Creo.JS to the browser environment. To consume the return value, the code that calls it must have a callback function. When Creo.JS sends the result to the browser environment, the callback function is called with the return value. Use Promise.then (valueConsumingCallback) syntax to register the callback.

Creo.JS Exception Handling

You can handle Creo.JS exceptions in its code. This ensures that exceptions are not thrown between the browser and Creo environment. If the exceptions are not caught on the Creo side, they can be processed by the browser callbacks. There are two types of interceptors for exception handling:

•

Errors are handled by onError() interceptor. onError() is used to process JavaScript error objects or exceptions derived from JavaScript error objects.

Such exceptions contain traceback information and can be used for more detailed problem reporting.

•

Application exceptions are handled by onException() interceptor. onException() is used to process all other thrown objects.

You can also use catch() to setup a callback that handles any type of throw objects.

The following example shows how to handle exceptions.

<script type="text/creojs" id=”exceptions.creojs”>
    function testException (isError) {
        if (isError) {
            throw new Error ('this is error')
        }
        else {
            throw {test: 'this is application exception'}
        }
    }
</script>

<script>
    var isError = document.getElementById ('iserrorcheckbox').checked
    CreoJS.testException (isError)
        .onError (function (err) {
                // catches new Error ('this is error') 
            })
        .onException (function (ex) {
                // catches {test: 'this is application exception'}
            })
</script>

Use Promise to call finally(). The function is called after the execution of the Creo.JS function either after then() or catch() callback.

Chaining Promises are used to simplify the sequences of asynchronous calls.

Note

The Creo embedded browser supports Internet Explorer, which does not have embedded support for Promises. Due to this limitation of Internet Explorer, a small subset of the Promise features, then, catch(), and finally(), are supported. There is no support for async and await, which are keywords of ECMAScript specification. However, full Promise interface is supported in Creo.JS.

Calling Browser from Creo.JS

Creo.JS code can call the global functions declared in the browser page. These calls are asynchronous and also return Promise. Use the browser object to access the browser functions. You can call all the global functions, which are available in the browser environment. For example, alert(), prompt(), and confirm(), and so on.

<script type="text/creojs" id=”callbrowser.creojs”>
    function callBrowser (message) {
        Browser.alert ('this is alert: ' + message)
        Browser.addTextNode (message)
    }
</script>

<script>
    function addTextNode (message) {
        document.appendChild (document.createTextNode (message))
    }
    CreoJS.callBrowser ('Just text')
</script>

ECMAScript 8 keywords async and await can be used to synchronously call browser code from Creo.JS. In the following example, Creo.JS script uses the browser method prompt() to make two browser calls to enquire about the first and last name of the user. It uses browser method alert() to display the full name.

In the example below, the function askFullName is declared as async and is executed asynchronously by Creo.JS environment. However, internally it synchronizes with two browser prompt() calls using await construct. All the functions that are declared async return a Promise. The result is consumed with a callback lambda-function, which is set using Promise.then().

<script type="text/creojs" id=”askfullname.creojs”>
    async function asyncCall (message, response = '') {
        return Browser.prompt (message, response)
    }

    async function askFullName (fn, ln) {
        const first = await asyncCall ('What is your first name?', fn)
        const last = await asyncCall ('What is your last name?', ln)
        return {first, last}
    }

    const user = pfcGetCurrentSession ().GetEnvironmentVariable ('USERNAME')
    askFullName (user.slice (0,1).toUpperCase (),
                 user.slice (1,2).toUpperCase () + user.slice (2))
        .then (name =>
          Browser.alert (`Your name is ${name.first} ${name.last}`))
</script>

Recommended Best Practices

It is recommended to use the following best practices while creating Creo.JS applications:

•

Do not have frequent calls between environments. There are inter-process communication overheads of passing Creo.JS call parameters and its result between the browser and Creo processes.

•

Collect all the data required by a transaction and exchange it in a single call.

Enabling Security Settings

Every time the Internet Explorer or Chromium browser receives HTTP requests from unknown sites, which try to access Creo.JS or Web.Link methods and objects, a warning message appears. You are prompted to confirm if you want to allow the request from the site.

The warning message provides you with the ability to save the decision.

•

If the request from the site is allowed, in future all the requests from the site will be executed without any warning message.

•

If the request from the site is not allowed, in future all the requests from the site will not be executed, and the warning message is not displayed.

.