Macromedia dreamweaver 8-extending dreamweaver User Manual

The Objects API

163

Description 

This function is required if the 

objectTag()

 function is not defined. It is called when the 

user clicks OK. It either inserts code into the user’s document and closes the dialog box or 
displays an error message and leaves the dialog box open. This works as an alternate function 
to use in objects instead of the 

objectTag()

 function. It does not assume that the user is 

inserting text at the current insertion point and allows data validation when the user clicks 
OK. You should use the 

insertObject()

 function if one of the following conditions exists: 

■

You need to insert code in more than one place.

■

You need to insert code somewhere other than the insertion point.

■

You need to validate input before inserting code. 

If none of these conditions apply, use the 

objectTag()

 function.

Arguments 

None. 

Returns

Dreamweaver expects a string that contains an error message or an empty string. If it returns 
an empty string, the Object dialog box closes when the user clicks OK. If it is not empty, 
Dreamweaver displays the error message and the dialog box remains.

Enabler

canInsertObject()

Example 

The following example uses the 

insertObject()

 function because it needs to validate input 

before inserting code:

function insertObject() { 
   var theForm = document.forms[0];
   var nameVal = theForm.firstField.value;
   var passwordVal = theForm.secondField.value;
   var errMsg = "", 
   var isValid = true; 
 
   // ensure that field values are complete and valid 
   if (nameVal == "" || passwordVal == "") {
     errMsg = "Complete all values or click Cancel."
   } else if (nameVal.length < 4 || passwordVal.length < 6) {
     errMsg = "Your name must be at least four characters, and your password 

at 

least six";
   } 
    
   if (!errMsg) {