JavaScript Libraries
Overview
Add-on libraries have been a staple part of PTC Arbortext Layout Developer for many years. Libraries provide a way to deliver libraries of code to the application or to templates in a way which provides a great level of customisation. For 12.0.0.0 we provide the ability to use JavaScript files rather than macro files, and also introduce new objects in the Formatting Object Model to help use libraries.
Library Objects
For this release, a number of new objects and methods have been introduced to support JavaScript libraries.
The fApplication object now provides the fApplication.libraries property, which is an fLibraries object. fApplication also provides fApplication.libraryPath which provides the location from which libraries are being loaded (remember that the library location can be set using the —I command-line parameter in sargsw.3ad).
The fLibraries object has a rescan() method to tell Layout Developer to look for new libraries. It also provides a location for all the libraries loaded by Layout Developer. Each loaded library will appear as a property of this object. For example, if you have a ‘dev’ library, it will appear as application.libraries.dev. Each of these properties is an fLibrary object which carries its own properties and methods. The libraries will be listed regardless of whether the ‘libcfg’ file is JavaScript or macro-based.
The fLibrary object represents the individual library and therefore is used to manage the library. The properties of this object are:
• displayName — this is the name of the library as shown under the Library menu in Layout Developer
• manualAlways — a boolean property which states whether the library can only ever be manually loaded (rather than automatically)
• manualEnable — a boolean property which tells Layout Developer whether the library can be manually loaded (true) or automatically (false)
• name — the internal name of the library as generated by the folder name
• path — an fPath object which indicates the location of the folder of the library
• startFile — the path to the location where the start file of the library is located/to be loaded from (see below)
• startFunction — a JavaScript function alternative to the start file
• stopFile — the path to the location where the stop file of the library is located/to be loaded from (see below)
• stopFunction — a JavaScript funtion alternative to the stop file
• state — the current state of the library, which is one of fLibrary.LibraryStates constant values (new, disabled, enabled, loaded or unloaded)
• submenuString — the string used to generate the submen for the library under the library name in the Library menu
• version — the version string used on the library folder name
The fLibrary object also has a couple of methods:
• load() — load the library
• unload() — unload the library
As the library can now use JavaScript files, some additional JavaScript tools are useful for setting up libraries:
• fApplication.setString() — this method can be used to set a string to some text — for example, application.setString(11001101, “Hello”); will set the Layout Developer string 11001101 to ‘Hello’. With libraries, this can be used to create dialog boxes or sub-menus
• fApplication.getString() — gets the text value of a given string number provided as an argument
• fApplication.loadStrings() — loads the strings from the file at the path provided as the argument to the method
Library Files
As described above, library files can now be JavaScript. The library configuration file can now be a JavaScript file, the .js version being looked for before the .3m version of the file. The ‘libcfg.js’ file is run when the library is loaded. When it is run, the ‘this’ object for the script is the fLibrary object which has been created for the library. Therefore, from within the libconfig file it is possible to do things like this:
this.displayName = "My Dev Library";
this.manualEnable = false;
this.startFile = "start.js";
this.submenuString = "Tools|||80000001";
And start.js can contain:
application.setString(80000001, "Toolbars|||80000002\nShow dialog|||wdbm 80000003");
application.setString(80000002, "Use old toolbars|||trun 80000010\nUse new toolbars|||trun 80000011\n");
...
As with ‘libcfg’, start and stop scripts have ‘this’ set to the current library object too.