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 ).

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 ).

    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.