This section describes the functions in the objects API. You must define either the insertObject() or the objectTag() function. For details about these functions, see insertObject(). The remaining functions are optional.

canInsertObject()

Availability

Dreamweaver MX.

Description

This function determines whether to display the Object dialog box.

Arguments

None.

Returns

Dreamweaver expects a Boolean value.

Example

The following code tells Dreamweaver to check to see that the document contains a particular string before allowing the user to insert the selected object:

 function canInsertObject(){         
    var docStr = dw.getDocumentDOM().documentElement.outerHTML; 
    var patt = /hava/; 
    var found = ( docStr.search(patt) != -1 ); 
    var insertionIsValid = true;  
     if (!found){ 
        insertionIsValid = false; 
        alert("the document must contain a 'hava' string to use this object.");} 
    return insertionIsValid;}

displayHelp()

Description

If you define this function, it displays a Help button below the OK and Cancel buttons in the Parameters dialog box. This function is called when the user clicks the Help button.

Arguments

None.

Returns

Dreamweaver expects nothing.

Example

The following example opens the myObjectHelp.htm file in a browser; this file explains how to use the extension:

 function displayHelp(){ 
    var myHelpFile = dw.getConfigurationPath() + 
        '/ExtensionsHelp/myObjectHelp.htm'; 
    dw.browseDocument(myHelpFile); 
}

isDOMRequired()

Description

This function determines whether the object requires a valid DOM to operate. If this function returns a true value or if the function is not defined, Dreamweaver assumes that the command requires a valid DOM and synchronizes the Code and Design views for the document before executing. Synchronization causes all edits in the Code view to be updated in the Design view.

Arguments

None.

Returns

Dreamweaver expects a true value if a command requires a valid DOM to operate; false otherwise.

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; 
}

objectTag()

Description

The objectTag() and insertObject() functions are mutually exclusive: If both are defined in a document, the objectTag() function is used. For more information, see insertObject().

This function inserts a string of code into the user’s document. Returning an empty string, or a null value (also known as "return"), is a signal to Dreamweaver to do nothing.

Note:

The assumption is that edits have been made manually before the return statement, so doing nothing in this case is not equivalent to clicking Cancel.

In Dreamweaver, if the focus is in Code view and the selection is a range (meaning that it is not an insertion point), the range is replaced by the string that the objectTag() function returns. This is the value true, even if the objectTag() function returns an empty string or returns nothing. The objectTag() function returns an empty string or a null value because edits to the document have already been made manually. Otherwise, double quotation marks (" ") often delete the edit by replacing the selection.

Arguments

None.

Returns

Dreamweaver expects the string to insert into the user’s document.

Example

The following example of the objectTag() function inserts an OBJECT/EMBED combination for a specific ActiveX control and plug-in:

 function objectTag() { 
return '\n' + 
'<OBJECT CLASSID="clsid:166F1OOB-3A9R-11FB-8075444553540000" \n'¬ 
+ 'CODEBASE="http://www.mysite.com/product/cabs/¬ 
myproduct.cab#version=1,0,0,0" \n' + 'NAME="MyProductName"> \n' ¬ 
+ '<PARAM NAME="SRC" VALUE=""> \n' + '<EMBED SRC="" HEIGHT="" ¬ 
WIDTH="" NAME="MyProductName"> \n' + '</OBJECT>' 
}

windowDimensions()

Description

This function sets specific dimensions for the Options dialog box. If this function is not defined, the window dimensions are computed automatically.

Note:

Do not define this function unless you want an Options dialog box that is larger than 640 x 480 pixels.

Arguments

platform

  • The value of the platform argument is either "macintosh" or "windows", depending on the user’s platform.

Returns

Dreamweaver expects a string of the form "widthInPixels,heightInPixels".

The returned dimensions are smaller than the size of the entire dialog box because they do not include the area for the OK and Cancel buttons. If the returned dimensions do not accommodate all options, scroll bars appear.

Example

The following example of the windowDimensions() function sets the dimensions of the Parameters dialog box to 648 x 520 pixels for Windows and 660 x 580 pixels for the Macintosh:

 function windowDimensions(platform){ 
     var retval = "" 
    if (platform = = "windows"){ 
    retval = "648, 520"; 
    }else{ 
    retval = "660, 580"; 
    } 
    return retval; 
}

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy