Fragment Objects

Active Web

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

The Fragment Object

A Fragment is an object holding HTML and script code defined in a file.

The script code can define functions and these functions can be called using the Fragment object.

Fragments provide a powerful way of reusing code. A Fragment file can be written to contain markup or script or a combination of the two. The Fragment object can then be created in any other script page and the code used as if it had be locally defined. By using the prototype chain Fragments can become prototypes for other objects and thus provide new user defined functionality for objects. Fragments can also become prototypes for other fragments thus providing object inheritance.

Fragment objects are of class Fragment.

Fragment Object Properties

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

Fragment Object Functions

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

The Fragment Constructor Function

When a new Fragment is created it will attempt to automatically run a constructor function. This function must have the same name as the root file name of the Fragment file. For example if the Fragment file is 'building.html' the Constructor function is called 'building()'. This function is passed any parameters following the name that are supplied in the new statement. A Fragment does not have to have a Constructor function.

Note: that Fragment file and constructor names are case sensitive. For example in a Windows environment should you have a fragment called myfrag.js and attempt to load it using new Fragment(“MYFRAG.js") then it will load due to the case insensitive nature of the Windows filesystem; however the constructor function (myfrag) will not be found as the file has been loaded with the name MYFRAG.

Fragment Instance Properties

A fragment can be given properties by declaring them in Fragment code using the 'this' operator (see Script objects). These properties can be accessed from outside the Fragment file by using the property name and the 'dot' operator.

this.bname = "Mansion House";

This line is inside the Fragment object constructor function and creates a property called bname and puts it in the fragment object.

var buildingName = myBuilding.bname;

This line access the same property from outside the Fragment object by using the name of the property.

The properties created in the Fragment Constructor are instance properties and are only available in this instance of the Fragment object. If another instance of the Fragment object is created then it will have its own version of these properties. These properties can be accessed from outside the function in the same way as all object properties are accessed.

Note that the keyword "this" has been used, "this" refers to the current instance of the Fragment object (in this case the new one we are creating). So the reference 'this.bname' means access the property 'bname' in the current instance of the Fragment object.

Fragment Functions

In order to call Fragment functions from outside the fragment there must be an instance property reference to the function. By default all functions inside a Fragment are private to that Fragment and can not be called from outside it. Creating a property that is a function reference using the 'this' operator makes the function visible.

this.close = closeBuilding;

This line is inside the Fragment object constructor function and makes the closeBuilding() function a property with the name close.

myBuilding.close();

This line runs the closeBuilding() function in the myBuilding instance of the Fragment object from outside the fragment by using the close property.

The addition of the line 'this.close = closeBuilding;' in the Fragment Constructor creates a function reference to the closeBuilding() function. Note that the name of the function reference can be (but does not need to be) the same as the name of the function.

An Example of Using the Fragment Object

The Fragment file 'building.html' contains the following code:

<h2>This is a Building Fragment</h2>
Building Type, Name, Status<script runat="server">write(this.type+', '+this.name+', '+this.status);</script><br>
<br><br>
<script runat=“server">
 function building(type) {
   this.type = type;
   this.status = “Open";
   this.close = closeBuilding;
 }
 function closeBuilding() {
   this.status = “Closed";
 }
</script>

The calling script contains the following section of code:

var myBuilding = new Fragment(“building.html", “Office");
myBuilding.execute();
myBuilding.name = “Mansion House";
myBuilding.closeBuilding();
myBuilding.execute();

Running this section causes the following output:

This is a Building Fragment

Building Type, Name, Status: Office, , Open

This is a Building Fragment

Building Type, Name, Status: Office, Mansion House, Closed

This example shows the following features:

• A Fragment instance being created.

• A Constructor function being executed.

• The Constructor function being given a parameter.

• Instance properties being created both in the constructor function and from outside the Fragment.

• Instance properties being accessed from non function code inside the Fragment.

• HTML and script code not inside a Fragment function being reused.

• A function being called inside the Fragment.

The Fragment Constructor

Using the new Operator with the Fragment Constructor

The Fragment constructor is used to create new Fragment objects.

var myFragment = new Fragment(name[, arg1[, arg2......]]);

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

The arguments following the name (if any) are passed on to the constructor function inside the fragment when the Fragment object is created.

A Fragment file can be either a script file or a markup file.

A script file can contain only script code and can not contain any markup code (XML, WML, HTML etc) except that embedded in script write statements. A script file does not need '<SCRIPT>' tags as all code is assumed to be script code. A script file is identified by having an extension of 'js'.

A markup file contains markup code and any script code must be inside the '<SCRIPT>' tags (this is normal HTML code). A markup file is identified by any other recognized extension ('.html', '.htm', '.xml', '.wml' etc).

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

Shown below is the Fragment object prototype chain.

Calling the Fragment 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.

Fragment Constructor Properties

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

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

Fragment Constructor Functions

The Fragment Prototype

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

Fragment Prototype Properties

Fragment 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: 150055