Participant EDML files | Developing Extensions for Macromedia Dreamweaver 8

< Day Day Up >

These tags and attributes are valid within the EDML participant files.

<participant>

Description

This tag contains all the specifications for a single participant.

Parent

None.

Type

Block tag.

Required

Yes.

<participant> attributes

The following items are valid attributes of the participant tag.

version

Description

This attribute defines which version of Dreamweaver server behavior processing the current server behavior targets. For Dreamweaver 8, the version number is 7. If no version is specified, Dreamweaver assumes version 7. For this release of Dreamweaver, all groups and participants that the Server Behavior Builder creates have the version attribute set to 7.0.

NOTE

The participant version attribute overrides the group version attribute if they are different. But, the participant file will use the group version attribute if the participant does not specify one.

For participant files, this attribute determines if code-block merging should occur. For participants without this attribute (or have it set to 4 or earlier), the inserted code blocks are not merged with other code blocks on the page. Participants that have this set to version 5 or later are merged with other code blocks on the page when possible. Please note that code-block merging occurs only for participants above and below the HTML tag.

Parent

 participant

Type

Attribute.

Required

No.

<quickSearch>

Description

This tag is a simple search string that is used for performance reasons. It cannot be a regular expression. If the string is found in the current document, the rest of the search patterns are called to locate specific instances. This string can be empty to always use the search patterns.

Parent

 participant

Type

Block tag.

Required

No.

Value

The searchString value is a literal string that exists on the page if the participant exists. The string should be as unique as possible to maximize performance, but the string does not have to be definitively unique. It is not case-sensitive, but be careful with nonessential spaces that can be changed by the user, as shown in the following example:

 <quickSearch>Response.Redirect</quickSearch>

If the quickSearch tag is empty, it is considered to match, and more precise searches use the regular expressions that are defined in the searchPattern tags. This is helpful if a simple string cannot be used to express a reliable search pattern and regular expressions are required.

<insertText>

Description

This tag provides information about what to insert in the document and where to insert it. It contains the text to insert. Parts of the text that are customized should be indicated by using the @@parameterName@@ format.

In some cases, such as a translator-only participant, you might not need this tag.

Parent

 implementation

Type

Block tag.

Required

No.

Value

The value is the text to insert in the document. If any parts of the text need customizing, they can be passed in later as parameters. Parameters should be embedded within two at (@@) signs. Because this text can interfere with the EDML structure, it should use the CDATA construct, as shown in the following example:

 <insertText location="aboveHTML">   <![CDATA[<%= @@recordset@@).cursorType %>]]> </insertText>

When the text is inserted, the @@recordset@@ parameter is replaced by a recordset name that the user supplies. For more information on conditional and repeating code blocks, see the "Adding Custom Server Behaviors" chapter in Getting Started with Dreamweaver

<insertText> attributes

The following items are valid attributes of the insertText tag.

location

Description

This attribute specifies where the participant text should be inserted. The insert location is related to the whereToSearch attribute of the searchPatterns tag, so be sure to set both carefully (see whereToSearch on page 353).

Parent

 insertText

Type

Attribute.

Required

Yes.

Values

 aboveHTML[+weight], belowHTML[+weight], beforeSelection, replaceSelection,  wrapSelection, afterSelection, beforeNode, replaceNode, afterNode,  firstChildOfNode, lastChildOfNode, nodeAttribute[+attribute]

The aboveHTML[+weight] value inserts the text above the HTML tag (suitable only for server code). The weight can be an integer from 1 to 99 and is used to preserve relative order among different participants. By convention, recordsets have a weight of 50, so if a participant refers to recordset variables, it needs a heavier weight, such as 60, so the code is inserted below the recordset, as shown in the following example:
```
 <insert location="aboveHTML+60"> 
```
If no weight is provided, it is internally assigned a weight of 100 and is added below all specifically weighted participants, as shown in the following example:
```
 <insert location="aboveHTML"> 
```
The belowHTML[+weight] value is similar to the aboveHTML location, except that participants are added below the closing /HTML tag.
The beforeSelection value inserts the text before the current selection or insertion point. If there is no selection, it inserts the text at the end of the BODY tag.
The replaceSelection value replaces the current selection with the text. If there is no selection, it inserts the text at the end of the BODY tag.
The wrapSelection value balances the current selection, inserts a block tag before the selection, and adds the appropriate closing tag after the selection.
The afterSelection value inserts the text after the current selection or insertion point. If there is no selection, it inserts the text at the end of the BODY tag.
The beforeNode value inserts the text before a node, which is a specific location in the DOM. When a function such as dwscripts.applySB() is called to make the insertion, the node pointer must pass in as a paramObj parameter. The user-definable name of this parameter must be specified by the nodeParamName attribute (see "nodeParamName" on page 351).
In summary, if your location includes the word node, make sure that you declare the nodeParamName tag.
The replaceNode value replaces a node with the text.
The afterNode value inserts the text after a node.
The firstChildOfNode value inserts the text as the first child of a block tag; for example, if you want to insert something at the beginning of a FORM tag.
lastChildOfNode inserts the text as the last child of a block tag; for example, if you want to insert code at the end of a FORM tag (useful for adding hidden form fields).
nodeAttribute[+attribute] sets an attribute of a tag node. If the attribute does not already exist, this value creates it.
For example, use <insert location="nodeAttribute+ACTION" nodeParamName="form"> to set the ACTION attribute of a form. This variation changes the user's FORM tag from <form> to <form action="myText">.
If you do not specify an attribute, the nodeAttribute location causes the text to be added directly to the open tag. For example, use insert location="nodeAttribute" to add an optional attribute to a tag. This can be used to change a user's INPUT tag from <input type="checkbox"> to <input type="checkbox" <%if(foo)Reponse.Write("CHECKED")%>>.

NOTE

For the location="nodeAttribute" attribute value, the last search pattern determines where the attribute starts and ends. Make sure that the last pattern finds the entire statement.

nodeParamName

Description

This attribute is used only for node-relative insert locations. It indicates the name of the parameter that passes the node in at insertion time.

Parent

 insertText

Type

Attribute.

Required

This attribute is required only if the insert location contains the word node.

Value

The tagtype__Tag value is a user-specified name for the node parameter that passes with the parameter object to the dwscripts.applySB() function. For example, if you insert some text into a form, you might use a form__tag parameter. In your server behavior applyServerBehavior() function, you could use the form__tag parameter to indicate the exact form to update, as shown in the following example:

 function applyServerBehavior(ssRec) {   var paramObj = new Object();   paramObj.rs = getRecordsetName();   paramObj.form__tag = getFormNode();   dwscripts.applySB(paramObj, sbObj); }

You can indicate the form__tag node parameter in your EDML file, as shown in the following example:

 <insertText location="lastChildOfNode" nodeParamName="form__tag">   <![CDATA[<input type="hidden" name="MY_DATA">]]> </insertText>

The text is inserted as the lastChildOfNode value, and the specific node passes in using the form__tag property of the parameter object.

<searchPatterns>

Description

This tag provides information about finding the participant text in the document, and it contains a list of patterns that are used when searching for a participant. If multiple search patterns are defined, they must all be found within the text being searched (the search patterns have a logical AND relationship), unless they are marked as optional using the isOptional flag.

Parent

 implementation

Type

Block tag.

Required

No.

<searchPatterns> attributes

The following items are valid attributes of the searchPatterns tag.

whereToSearch

Description

This attribute specifies where to search for the participant text. This attribute is related to the insert location, so be sure to set each attribute carefully (see "location" on page 349).

Parent

 searchPatterns

Type

Attribute.

Required

Yes.

Values

 directive, tag+tagName, tag+*, comment, text

The directive value searches all server directives (server-specific tags). For ASP and JSP, this means search all <% ... %> script blocks.
NOTE

Tag attributes are not searched, even if they contain directives.
The tag+tagName value searches the contents of a specified tag, as shown in the following example:
```
 <searchPatterns whereToSearch="tag+FORM"> 
```
This example searches only form tags. By default, the entire outerHTML node is searched. For INPUT tags, specify the type after a slash (/). In the following example, to search all submit buttons, use the following code:
```
 <searchPatterns whereToSearch="tag+INPUT/SUBMIT">. 
```
The tag+* value searches the contents of any tag, as shown in the following example:
```
 <searchPatterns whereToSearch="tag+*"> 
```
This example searches all tags.
The comment value searches only within the HTML comments <! ... >, as shown in the following example:
```
 <searchPatterns whereToSearch="comment"> 
```
This example searches tags such as .
The text value searches only within raw text sections, as shown in the following example:
```
 <searchPatterns whereToSearch="text">   <searchPattern>XYZ</searchPattern> </searchPatterns> 
```
This example finds a text node that contains the text XYZ.

<searchPattern>

Description

This tag is a pattern that identifies participant text and extracts parameter values from it. Each parameter subexpression must be enclosed in parentheses ().

You can have patterns with no parameters (which are used to identify participant text), patterns with one parameter, or patterns with many parameters. All non-optional patterns must be found, and each parameter must be named and found exactly once.

For more information about using the searchPattern tag, see "Finding server behaviors" on page 369.

Parent

 searchPatterns

Type

Block tag.

Required

Yes.

Values

 searchString, /regularExpression/, <empty>

The searchString value is a simple search string that is case-sensitive. It cannot be used to extract parameters.
The /regularExpression/ value is a regular expression search pattern.
The <empty> value is used if no pattern is given. It is always considered a match, and the entire value is assigned to the first parameter.
In the following example, to identify the participant text <%= RS1.Field.Items("author_id") %>, you can define a simple pattern, followed by a precise pattern that also extracts the two parameter values:
```
 <searchPattern>Field.Items</searchPattern> <searchPattern paramNames="rs,col">   <![CDATA[   /<%=\s*(\w+)\.Field\.Items\("(\w+)"\)/   ]]> </searchPattern> 
```
This example matches the pattern precisely and assigns the value of the first subexpression (\w+) to parameter "rs" and the second subexpression (\w+) to parameter "col".
NOTE

It is important that regular expressions start and end with a slash (/). Otherwise, the expression is used as a literal string search. Regular expressions can be followed by the regular-expression modifier "i" to indicate case-insensitivity (as in /pattern/i). For example, VBScript is not case-sensitive, so it should use /pattern/i. JavaScript is case-sensitive and should use /pattern/.

Sometimes you might want to assign the entire contents of the limited search location to a parameter. In that case, provide no pattern, as shown in the following example:
```
 <searchPatterns whereToSearch="tag+OPTION">   <searchPattern>MY_OPTION_NAME</searchPattern>   <searchPattern paramNames="optionLabel" limitSearch="innerOnly">   </searchPattern> </searchPatterns> 
```
This example sets the optionLabel parameter to the entire innerHTML contents of an OPTION tag.

<searchPattern> attributes

The following items are valid attributes of the searchPattern tag.

paramNames

Description

This attribute is a comma-separated list of parameter names whose values are being extracted. These parameters are assigned in the order of the subexpression. You can assign single parameters or use a comma-separated list to assign multiple parameters. If other parenthetical expressions are used but do not indicate parameters, extra commas can be used as placeholders in the Parameter Name list.

The parameter names should match the ones that are specified in the insertion text and the update parameters.

Parent

 searchPattern

Type

Attribute.

Required

Yes.

Values

 paramName1, paramName2, ...

Each parameter name should be the exact name of a parameter that is used in the insertion text. For example, if the insertion text contains @@p1@@, you should define exactly one parameter with that name:

 <searchPattern paramNames="p1">patterns</searchPattern>

To extract multiple parameters using a single pattern, use a comma-separated list of parameter names, in the order that the subexpressions appear in the pattern. Suppose the following example shows your search pattern:

 <searchPattern paramName="p1,,p2">/(\w+)_(BIG|SMALL)_(\w+)/</searchPattern>

There are two parameters (with some text in between them) to extract. Given the text: <%= a_BIG_b %>, the first subexpression in the search pattern matches "a", so p1="a". The second subexpression is ignored (note the ,, in the paramName value). The third subexpression matches "b", so p2="b".

limitSearch

Description

This attribute limits the search to some part of the whereToSearch tag.

Parent

 searchPattern

Type

Attribute.

Required

No.

Values

 all, attribute+attribName, tagOnly, innerOnly

The all value (default) searches the entire tag that is specified in the whereToSearch attribute.
The attribute+attribName value searches only within the value of the specified attribute, as shown in the following example:
```
 <searchPatterns whereToSearch="tag+FORM">   <searchPattern limitSearch="attribute+ACTION">     /MY_PATTERN/   </searchPattern> </searchPatterns> 
```
This example indicates that only the value of the ACTION attribute of FORM tags should be searched. If that attribute is not defined, the tag is ignored.
The tagOnly value searches only the outer tag and ignores the innerHTML tag. This value is valid only if whereToSearch is a tag.
The innerOnly value searches only the innerHTML tag and ignores the outer tag. This value is valid only if whereToSearch is a tag.

isOptional

Description

This attribute is a flag that indicates that the search pattern is not required to find the participant. This is useful for complex participants that might have non-critical parameters to extract. You can create some patterns for distinctly identifying a participant and have some optional patterns for extracting non-critical parameters.

Parent

 searchPattern

Type

Attribute.

Required

No.

Values

 true, false

The value is true if the searchPattern is not necessary to identify the participant.
The value is false (default) if the searchPattern tag is required.

For example, consider the following simple recordset string:

 <% var Recordset1 = Server.CreateObject("ADODB.Recordset"); Recordset1.ActiveConnection = "dsn=andescoffee;"; Recordset1.Source = "SELECT * FROM PressReleases"; Recordset1.CursorType = 3; Recordset1.Open(); %>

The search patterns must identify the participant and extract several parameters. However, if a parameter such as cursorType is not found, you should still recognize this pattern as a recordset. The cursor parameter is optional. In the EDML, the search patterns might look like the following example:

 <searchPattern paramNames="rs">/var (\w+) = Server.CreateObject/ </searchPattern> <searchPattern paramNames="src">/ActiveConnection = "([^\r\n]*)"/</searchPattern> <searchPattern paramNames="conn">/Source = "([^\r\n]*)"/</searchPattern> <searchPattern paramNames="cursor" isOptional="true">/CursorType = (\d+)/ </searchPattern>

The first three patterns are required to identify the recordset. If the last parameter is not found, the recordset is still identified.

<updatePatterns>

Description

This optional advanced feature lets you update the participant precisely. Without this tag, the participant is updated automatically by replacing the entire participant text each time. If you specify an <updatePatterns> tag, it must contain specific patterns to find and replace each parameter within the participant.

This tag is beneficial if the user edits the participant text. It performs precise updates only to the parts of the text that need changing.

Parent

 implementation

Type

Block tag.

Required

No.

<updatePattern>

Description

This tag is a specific type of regular expression that lets you update participant text precisely. There should be at least one update pattern definition for every unique parameter that is declared in the insertion text (of the form @@paramName@@).

Parent

 updatePatterns

Type

Block tag.

Required

Yes (at least one, if you declare the updatePatterns tag).

Values

The value is a regular expression that finds a parameter between two parenthetical subexpressions, in the form /(pre-pattern)parameter-pattern(post-pattern)/. You need to define at least one update pattern for each unique @@paramName@@ in the insertion text. The following example shows how your insertion text might look:

 <insertText location="afterSelection">   <![CDATA[<%= @@rs@@.Field.Items("@@col@@") %>]]> </insertText>

A particular instance of the insertion text on a page might look like the following example:

 <%= RS1.Field.Items("author_id") %>

There are two parameters, rs and col. To update this text after you insert it on the page, you need two update pattern definitions:

 <updatePattern paramName="rs" >   /(\b)\w+(\.Field\.Items)/ </updatePattern> <updatePattern paramName="col">   /(\bItems\(")\w+("\))/ </updatePattern>

The literal parentheses, as well as other special regular expression characters, are escaped by preceding them with a backslash (\). The middle expression, defined as \w+, is updated with the latest value that passed in for parameters "rs" and "col", respectively. The values "RS1" and "author_id" can be precisely updated with new values.

Multiple occurrences of the same pattern can be updated simultaneously by using the regular expression global flag "g" after the closing slash (such as /pattern/g).

If the participant text is long and complex, you might need multiple patterns to update a single parameter, as shown in the following example:

 <% ...   Recordset1.CursorType = 0;   Recordset1.CursorLocation = 2;   Recordset1.LockType = 3; %>

To update the recordset name in all three positions, you need three update patterns for a single parameter, as shown in the following example:

 <updatePattern paramName="rs">   /(\b)\w+(\.CursorType)/ </updatePattern> <updatePattern paramName="rs">   /(\b)\w+(\.CursorLocation)/ </updatePattern> <updatePattern paramName="rs">   /(\b)\w+(\.LockType)/ </updatePattern>

Now you can pass in a new value for the recordset, and it is precisely updated in three locations.

<updatePattern> attributes

The following items are valid attributes of the updatePattern tag.

paramName

Description

This attribute indicates the name of the parameter whose value is used to update the participant. This parameter should match the ones that are specified in the insertion text and search parameters.

Parent

 updatePattern

Type

Attribute.

Required

Yes.

Values

The value is the exact name of a parameter that is used in the insertion text. In the following example, if the insertion text contains an @@rs@@ value, you should have a parameter with that name:

 <updatePattern paramName="rs">pattern</updatePattern>

<delete>

Description

This tag is an optional advanced feature lets you control how to delete a participant. Without this tag, the participant is deleted by removing it completely but only if no server behaviors refer to it. By specifying a <delete> tag, you can specify that it should never be deleted or that only portions should be deleted.

Parent

 implementation

Type

Tag.

Required

No.

<delete> attributes

The following items are valid attributes of the delete tag.

deleteType

Description

This attribute is used to indicate the type of delete to perform. It has different meanings, depending on whether the participant is a directive, a tag, or an attribute. By default, the entire participant is deleted.

Parent

 delete

Type

Attribute.

Required

No.

Values

 all, none, tagOnly, innerOnly, attribute+attribName, attribute+*

The all value (default) deletes the entire directive or tag. For attributes, it deletes the entire definition.
The none value is never automatically deleted.
The tagOnly value removes only the outer tag but leaves the contents of the innerHTML tag intact. For attributes, it also removes the outer tag if it is a block tag. It is meaningless for directives.
The innerOnly value, when applied to tags, removes only the contents (the innerHTML tag). For attributes, it removes only the value. It is meaningless for directives.
The attribute+attribName value, when applied to tags, removes only the specified attribute. It is meaningless for directives and attributes.
The attribute+* value removes all attributes for tags. It is meaningless for directives and attributes.

If your server behavior converts selected text into a link, you can remove the link by removing the outer tag only, as shown in the following example:

 <delete deleteType="tagOnly"/>

This example changes a link participant from <A HREF="...">HELLO</A> to HELLO.

<translator>

Description

This tag provides information for translating a participant so that it can be rendered differently and have a custom Property inspector.

Parent

 implementation

Type

Block tag.

Required

No.

<searchPatterns>

Description

This tag lets Dreamweaver find each specified instance in a document. If multiple search patterns are defined, they must all be found within the text being searched (the search patterns have a logical AND relationship), unless they are marked as optional using the isOptional flag.

Parent

 translator

Type

Block tag.

Required

Yes.

<translations>

Description

This tag contains a list of translation instructions where each instruction indicates where to search for the participant and what to do with the participant.

Parent

 translator

Type

Block tag.

Required

No.

<translation>

Description

This tag contains a single translation instruction that includes the location for the participant, what type of translation to perform, and the content that should replace the participant text.

Parent

 translations

Type

Block tag.

Required

No.

<translation> attributes

The following items are valid attributes of the translation tag.

whereToSearch

Description

This attribute specifies where to search for the text, which is related to the insert location, so be sure to set each location carefully (see "location" on page 349).

Parent

 translation

Type

Attribute.

Required

Yes.

limitSearch

Description

This attribute limits the search to some part of the whereToSearch tag.

Parent

 translation

Type

Attribute.

Required

No.

translationType

Description

This attribute indicates the type of translation to perform. These types are preset and give the translation specific functionality. For example, if you specify "dynamic data", any data that is translated should behave the same as Dreamweaver dynamic data; that is, it should have the dynamic data placeholder look in the Design view (curly braces ({}) notation with dynamic background color) and appear in the Server Behaviors panel.

Parent

 translation

Type

Attribute.

Required

Yes.

Values

dynamic data, dynamic image, dynamic source, tabbed region start, tabbed region end, custom

The dynamic data value indicates that the translated directives look and behave the same as Dreamweaver dynamic data, as shown in the following example:
```
 <translation whereToSearch="tag+IMAGE"   limitSearch="attribute+SRC"   translationType="dynamic data"> 
```
The dynamic image value indicates that the translated attributes should look and behave the same as Dreamweaver dynamic images, as shown in the following example:
```
 <translation whereToSearch="IMAGE+SRC"   translationType="dynamic image"> 
```
The dynamic source value indicates that the translated directives should behave the same as Dreamweaver dynamic sources, as shown in the following example:
```
 <translation whereToSearch="directive"    translationType="dynamic source"> 
```
The tabbed region start value indicates that the translated <CFLOOP> tags define the beginning of a tabbed outline, as shown in the following example:
```
 <translation whereToSearch="CFLOOP"    translationType="tabbed region start"> 
```
The tabbed region end value indicates that the translated </CFLOOP> tags define the end of a tabbed outline, as shown in the following example:
```
 <translation whereToSearch="CFLOOP"    translationType="tabbed region end"> 
```
The custom value is the default case in which no internal Dreamweaver functionality is added to the translation. It is often used when specifying a tag to insert for a custom Property inspector, as shown in the following example:
```
 <translation whereToSearch="directive"   translationType="custom"> 
```

<openTag>

Description

This optional tag can be inserted at the beginning of the translation section. This tag lets certain other extensions, such as custom Property inspectors, find the translation.

Parent

 translation

Type

Block tag.

Required

No.

Values

The tagName value is a valid tag name. It should be unique to prevent conflicts with known tag types. For example, if you specify <openTag>MM_DYNAMIC_CONTENT</openTag> the dynamic data is translated to the MM_DYNAMIC_CONTENT tag.

<attributes>

Description

This tag contains a list of attributes to add to the translated tag that is specified by the openTag tag. Alternatively, if the openTag tag is not defined and the searchPattern tag specifies tag, this tag contains a list of translated attributes to add to the tag that is found.

Parent

 translation

Type

Block tag.

Required

No.

<attribute>

Description

This tag specifies a single attribute (or translated attribute) to add to the translated tag.

Parent

 attributes

Type

Block tag.

Required

Yes (at least one).

Values

The attributeName="attributeValue" specification sets an attribute to a value. Typically, the attribute name is fixed, and the value contains some parameter references that are extracted by the parameter patterns, as shown in the following example:

 <attribute>SOURCE="@@rs@@"</attribute> <attribute>BINDING="@@col@@"</attribute>

 <attribute>   mmTranslatedValueDynValue="VALUE={@@rs@@.@@col@@}" </attribute>

<display>

Description

This tag is an optional display string that should be inserted in the translation.

Parent

 translation

Type

Block tag.

Required

No.

Values

The displayString value is any string comprising text and HTML. It can include parameter references that are extracted by the parameter patterns. For example, <display>{@@rs@@.@@col@@}</display> causes the translation to render as {myRecordset.myCol}.

<closeTag>

Description

This optional tag should be inserted at the end of the translated section. This tag enables certain other extensions, such as custom Property inspectors, to find the translation.

Parent

 translation

Type

Block tag.

Required

No.

Values

The tagName value is a valid tag name; it should match a translation openTag tag.

Example

If you specify the value <closeTag>MM_DYNAMIC_CONTENT</closeTag>, the dynamic data is translated to end with the </MM_DYNAMIC_CONTENT> tag.

< Day Day Up >