Adobe Extending Dreamweaver CS4 - Manual (Page 128)

122 EXTENDING DREAMWEAVER CS4
Insert bar objects
insertObject()
Availability
Dreamweaver MX.
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) {
// do some document manipulation here. Exercise left to the reader
}
return errMsg;
}