Library Objects

Active Web

Trail: PROIV Documentation > Developer > Active Web  > PROIV Web Development > Script Objects > Library Objects

The Library Object

Libraries are now deprecated and may be removed from a future release. They should not be used in new development. You should use Fragment Objects for this functionality.

A Library is an object holding script code defined in a file. A Library object is a subset of the Fragment object with slightly different behaviour. The differences between Fragment objects and Library objects are shown below:

• Library objects can only have script code and can not have markup code.

• There is only one instance of a Library object for each library file and this is shared among all scripts. This means that all Library object properties are shared by all scripts using the library.

• All functions in a Library object are public and can be used without creating a property reference to the functions.

• Library objects do not have a constructor function. Instead they have an initialization function (called init) that is run only once when the Library object is put into the script server cache. The initialization function will only be run again when the script server is restarted or the contents of the library file is changed.

• Library objects do not use the this reference. Instead they use the special reference library to refer to the library object.

A library object can have properties and these properties will last as long as the server remains running. To access these properties from your script page you just treat the library like any other script object. To access these properties from functions inside the library you must use the special reference ‘library’. This special reference is only available to script code inside a library and always refers to the library object itself. For example from functions inside the library the object ‘library.myDefault’ can be used to read and write default data and can be seen from outside the library as ‘myLibrary.myDefault’.

You must be careful how you use library properties as they are shared by all scripts using the library. A common way of using library properties is to treat them as constants set by the init function.

Library objects are of class Library.

Library Object Properties

The Library object can have any number of properties defined by the script developer in addition to the ones shown below.

Library Object Functions

The Library object can have any number of functions defined by the script developer in addition to the ones shown below.

When to Use Library Objects

Library objects have a more limited functionality than Fragment objects, but what they do have is a global nature and persistence. A Library object is shared by all scripts using it and persists while the server is running. This allows you to use the initialization function to do some processing, the results of which can then be shared by all subsequent users of the Library.

Library objects are not so useful as Fragment objects for code reuse as they can not hold markup code except as write statements in script code.

Library objects are also not as useful as Fragments for creating complex script objects with inheritance.

The Library Constructor

Using the new Operator with the Library Constructor

The Library constructor is used to create new Library objects.

var myLibrary = new Library(name);

A new Library object for the file identified by the name is created. The file holds the script code for the library. The name uses the script file reference to identify the file. Absolute file references can not be used for libraries and all library files must be under the servlet web application root. If the library file does not exist then a runtime error is generated and the script stops processing.

The script server has a cache for libraries and if the library is already in the cache then a reference to the cached library is returned. If the library is not in the cache then a new library object is created, put in the cache and a reference to the library returned. The cache will be reloaded if the library file has been changed.

The Library object created by the Library Constructor is given the prototype referenced by the prototype property in the Library Constructor. This property can be changed in the Library Constructor and any Library Objects will then have the new property as their prototype. The default prototype is the Library Prototype and each Library Constructor will have its own copy of the prototype.
Shown below is the Library object prototype chain.

Calling the Library Constructor as a Function

When the constructor is run as a function without the new operator it has exactly the same behaviour as using the new operator.

Library Constructor Properties

The Library constructor has no predefined properties. In particular it does not have a prototype property. This is because there can be many different Library objects (each identified by its file name) and each one can have its own prototype. To set the prototype for all Library objects of a particular type use the setPrototype function (see below).

It is not possible to add new properties to the Constructor.

Library Constructor Functions

The Library Prototype

This is the default prototype that is shared among all Library objects created from the same file. Each Library Constructor has its own copy of this prototype object.

Library Prototype Properties

Library Prototype Functions

The this reference used here always refers to the object that was used to run the function.

Comment on this topic

Topic ID: 150070