The Connection API

 < Day Day Up > 

To create a new type of connection, including the dialog box with which users interact, you must implement the following three functions: findConnection(), inspectConnection(), and applyConnection(). You write these three functions and include them in the JavaScript implementation file that is associated with your new connection type (see Step 2 "Create a JavaScript file that implements at least the following elements:" on page 606).

The applyConnection() function returns an HTML source within an include file. You can see examples of the HTML source in "The generated include file" on page 611. The findConnection() function takes the HTML source and extracts its properties. You can implement findConnection() to use the search patterns in XML files to extract the information that returns from applyConnection(). For an example of such an implementation, see the following two JavaScript files:

  • connection_ado_conn_string.js is located in Configuration/Connections/ASP_Js folder.

  • connection_common.js is located in Configuration/Connections/Shared folder.

When the user opens a site, Dreamweaver goes through each file in the Connections folder, opens it, and passes the contents to findConnection(). If the contents of a file match the criteria for a valid connection, findConnection() returns a connection object. Dreamweaver then lists all the connection objects in the Database Explorer panel.

When the user opens a connection dialog box and selects to create a new connection or duplicate or edit an existing connection, Dreamweaver calls the inspectConnection() function and passes back the same connection object that findConnection() created. This process lets Dreamweaver populate the dialog box with the connection information.

When the user clicks OK in a connection dialog box, Dreamweaver calls the applyConnection() function to build the HTML, which is placed in the connection include file that is located in the Configuration/Connections folder. The applyConnection() function returns an empty string that indicates there is an error in one of the fields and the dialog box should not be closed. The include file has the default file extension type for the current server model.

When the user adds to the page a server behavior that uses the connection, such as a recordset or a stored procedure, Dreamweaver adds a statement to the page that includes the connection include file.

findConnection()

Availability

Dreamweaver UltraDev 4.

Description

Dreamweaver calls this function to detect a connection in the specified HTML source and to parse the connection parameters. If the contents of this source file match the criteria for a valid connection, findConnection() returns a connection object; otherwise, this function returns a null value.

Argument

 htmlSource 

The htmlSource argument is the HTML source for a connection.

Returns

A connection object that provides values for a particular combination of the properties that are listed in the following table. The properties for which this function returns a value depend on the document type.

Property

Description

name

Name of the connection

type

If useHTTP is false, indicates which DLL to use for connecting to database at runtime

string

Runtime connection string. For ADO, it is a string of connection parameters; for JDBC, it is a connection URL

dsn

Data source name used for ODBC or Cold Fusion runtime connections

driver

Name of a JDBC driver used at runtime

username

Name of the user for the runtime connection

password

Password used for the runtime connection

designtimeString

Design-time connection string (see string)

designtimeDsn

Design-time data source name (see dsn)

designtimeDriver

Name of a JDBC driver used at design time

designtimeUsername

Name of the user used for the design-time connection

designtimePassword

Password used for the design-time connection

designtimeType

Design-time connection type

usesDesigntimeInfo

When false, Dreamweaver uses runtime properties at design time; otherwise, Dreamweaver uses design-time properties

useHTTP

String containing either true or false: true specifies to use HTTP connection at design time; false specifies to use DLL

includePattern

Regular expression used to find the file include statement on the page during Live Data and Preview In Browser

variables

Object with a property for each page variable that is set to its corresponding value. This object is used during Live Data and Preview In Browser

catalog

String containing a database identifier that restricts the amount of metadata that appears

schema

String containing a database identifier that restricts the amount of metadata that appears

filename

Name of the dialog box used to create the connection


If a connection is not found in htmlSource, a null value returns.

NOTE

Developers can add custom properties (for example, metadata) to the HTML source, which applyConnection() returns along with the standard properties.


inspectConnection()

Availability

Dreamweaver UltraDev 4.

Description

Dreamweaver calls this function to initialize the dialog box data for defining a connection when the user edits an existing connection. This process lets Dreamweaver populate the dialog box with the appropriate connection information.

Argument

 parameters 

The parameters argument is the same object that the findConnection() function returns.

Returns

Nothing.

applyConnection()

Availability

Dreamweaver UltraDev 4.

Description

Dreamweaver calls this function when the user clicks OK in the connection dialog box. The applyConnection() function generates the HTML source for a connection. Dreamweaver writes the HTML to the Configuration/Connections/connection-name.ext include file, where connection-name is the name of your connection (see "Create the layout for the connection dialog box." on page 605), and .ext is the default extension that is associated with the server model.

Arguments

None.

Returns

The HTML source for a connection. Dreamweaver also closes the connection dialog box. If a field validation error occurs, applyConnection() displays an error message and returns an empty string to indicate that the dialog box should remain open.

     < Day Day Up > 


    Developing Extensions for Macromedia Dreamweaver 8
    Developing Extensions for Macromedia Dreamweaver 8
    ISBN: 0321395409
    EAN: 2147483647
    Year: 2005
    Pages: 282

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net