Using Script Components in ScriptBuilder 3.0

Introducing Script Components
 
Working with Script Components
Adding Script Components to Your Web Page
Setting Properties
Calling Methods
Assigning Events
 
Getting Information About a Script Component
Viewing Properties, Methods, and Events
Viewing Component Meta Information
Viewing Component Help
Removing a Component From Your Web Page
 
Deploying Your Web Page
 

Introducing Script Components

JavaScript is emerging as the de facto scripting language for the Web and is becoming a core “glue” technology for building Web applications. And its momentum is only strengthening with the adoption of the ECMAScript standard by all other major Web players, including Netscape and Microsoft. But as the popularity of JavaScript continues to rise rapidly among Web developers for both the client and server, there remains a key capability missing from JavaScript: the ability to package script source code as components. As a result, scripting is often inefficient and code reuse is difficult for Web development teams.

In lieu of an open component standard, many developers have chosen to utilize standard JavaScript Include (.js) files in an effort to reuse their code. While .js files provide a better solution for reuse than simply embedding script code into HTML files, they are far less optimal than a component-based approach to application development.

NetObjects created script components to fill this void. Script components:

You can take advantage of script components that are included with ScriptBuilder 3.0 as well as create your own to "compontentize" your code.


Working With Script Components

This section describes how you can work with script components in your Web pages.

Adding Script Components to Your Web Page

Before you can use a script component, you need to add it to your Web page. To do so:

  1. Select the desired script component from the Component Gallery.
  2. Insert the script component by dragging-&-dropping into the current document. You can also insert the component by selecting the Insert item from the Component Gallery's popup menu.

When you perform this action, ScriptBuilder will insert code into the current document that will be used to initialize the component when the document is loaded at runtime. Specifically, the following items are added to your document:

<SCRIPT LANGUAGE="JAVASCRIPT" SRC="ComponentSource.js" PURPOSE="COMPONENT" 
        CLASSNAME="ComponentName"></SCRIPT>

This references the SRC for runtime usage, and PURPOSE and CLASSNAME used for design-time usage.

<SCRIPT LANGUAGE="JAVASCRIPT" PURPOSE="INITIALIZER" SRC="DocumentName_init.js"></SCRIPT>

ScriptBuilder stores the code in a separate .js include file identified as the SRC attribute value. This file will be created in the same directory as the current document.

IMPORTANT: Do not modify either the component include or initializer blocks. This code is maintained completely by ScriptBuilder. 

You will also notice the Component Inspector window will be displayed when a component is inserted. The Component Inspector is the primary tool you will use when working with components on your page.

Component Inspector is used to set properties and event handlers.

Once you have added the script component, you can now use it as a resource inside of your Web page. Exactly how you work with it next will depend on the specific component itself and what it was designed to do. In some cases, adding the component to the page only enables you to use it, but it does nothing until a method is called or an event handler is assigned. In other cases, the component will perform a process when it is initialized, so you will may only need to set its properties to customize the action of the component. The sections below describe these various activities. You will want to be familiar with each of these to maximize your usage of script components.

Setting Script Component Properties

Most script components will have properties that can be set at design-time. If a component has properties, they will appear on the Property Page of the Component Inspector. You can use this page to modify the start-up properties for a component. When you add or change a property value, ScriptBuilder automatically updates the value in the Component Initializer Block for you.

If you want to set the properties of a component at runtime during the execution of your code, you can set it just as you would any other object inside of JavaScript. For example, to assign the size property to an instance of the HistoryNav component, you could write the following code:

<SCRIPT LANGUAGE="JavaScript"> 
        // Sets the size property at runtime
        HistoryNav1.size = 10; 
</SCRIPT>
NOTE: You should change the instance name of a component only with the Component Inspector. 

Calling Script Component Methods

Most of the functionality behind a typical script component lies in its methods. So, in order for the component to actually do something, you will need to call the appropriate method inside of your scripting code block. For example, if you wanted to call the render() method of the HistoryNav instance, you would add the following line to your script block:

<SCRIPT LANGUAGE="JavaScript"> 
        // Sets the size property at runtime
        HistoryNav1.size = 10;  
        // Calls the method render the list 
        HistoryNav1.render(); 
</SCRIPT>

Each method will have its own set of methods which can be called. For details on how to view available methods, see the Viewing Properties, Methods, and Events section below.

Assigning Script Component Events

You may want to have certain functions within your Web page execute when a specific event is triggered for the component. For example, suppose you have a component that connects to a database and fires an OnConnect event when a connect successfully established and a OnConnectFailed event when it fails. You can write event handling code in your Web page. When the component detects that an event occurs, it will call the function (if any) specified by the user for that event.

To assign event handler, use the Component Inspector. While you have already used the Component Inspector to set component properties, you can also use the Component Inspector to access and create a component's event handlers. By clicking the Events page on the Component Inspector, you can see a list of available events for the currently selected component.

The easy part is creating the event handler; the programming comes into play as you write the actual JavaScript code for the event.

To assign an event handler to a component event:

1. Go to the Event page of the Component Inspector.

2. In the blank space beside the desired event, double-click the space to create the default event handler for the component. Whenever you double-click an event inside of the Component Inspector, ScriptBuilder generates the code for that event's handler. The editor window is activated showing the new event handler. For example, if you wanted to create a handler for onRender of the DigitalClock component, ScriptBuilder generates the following event handler code:

<SCRIPT LANGUAGE="JAVASCRIPT" PURPOSE="EVENTHANDLER">
function DigitalClock1_onRender() {

}
</SCRIPT>
NOTE: You can also assign a function already defined on your Web page to serve as the event handler. To do so, click the arrow on the space beside the event to display a list of all functions inside of your page. Select the desired function from the list. 

3. Complete the event handler by adding the code you want to execute when the event is called. For example, if you wanted to display a test message when on the onRender handler is called, you could use the following called:

<SCRIPT LANGUAGE="JAVASCRIPT" PURPOSE="EVENTHANDLER">
 function DigitalClock1_onRender() {
  alert( 'DigitalClick rendered.' ); 
 }
</SCRIPT>

Getting Information About Your Component

Viewing Properties, Methods, and Events

To view a component's list of available properties, methods, and events, right-click on a component in the Component Gallery or in the Component Map. The popup menu that is displayed will contain a complete list of these attributes.

By selecting a specific attribute's menu item, you can insert this text into your document at the current cursor position.

Viewing Component Meta Information

To view meta-information related to a component, right-click on a component in the Component Gallery or in the Component Map and select the About item. A dialog box will be displayed that contains additional information about the script component.  

Viewing Component Help

Script components can optionally contain a HTML file that provides Help assicated with the component's interface and instructions on how to use the component. To view Help related to a component, right-click on a component in the Component Gallery or in the Component Map and select the Help item. The HTML document will be displayed in the InfoBrowser (or default external browser) depending on user preferences.

Removing a Script Component From Your Web Page

To delete a component from your document, use the Component Map. Within the Component Map, right-click to display the popup menu and select the Delete menu item. You will be asked to confirm this action. If you continue, ScriptBuilder will remove the script component reference from your Web page.

IMPORTANT: We strongly recommend that you do not manually delete a script component by removing the component include and initializer blocks in the editor.

 

Deploying Your Web Page

When you are ready to publish a document containing script components, you first need to deploy the script components associated with that document. This step ensures that all files needed for the Web page are included with the document when you place it on your Web server. To deploy a document, choose the Tools | Deploy option. Follow instructions within the dialog to copy files to the desired directory.

Last modified: September 22, 1998
Copyright ©1998 NetObjects, Inc.