Customizing the interpretation of third-party tags

Server-side technologies such as ASP, Adobe ColdFusion, JSP, and PHP use special non-HTML code in HTML files; servers create and serve HTML content based on that code. When Adobe Dreamweaver encounters non-HTML tags, it compares them with information in its third-party tag files, which define how Adobe Dreamweaver reads and displays non-HTML tags.

For example, in addition to regular HTML, ASP files contain ASP code for the server to interpret. ASP code looks almost like an HTML tag, but is marked by a pair of delimiters: it begins with <% and ends with %>. The Adobe Dreamweaver Configuration/ThirdPartyTags folder contains a file named Tags.xml, which describes the format of various third-party tags, including ASP code, and defines how Adobe Dreamweaver displays that code. Because of the way ASP code is specified in Tags.xml, Adobe Dreamweaver does not try to interpret anything between the delimiters; instead, in Design view, it displays an icon that indicates ASP code. Your own tag database files can define how Adobe Dreamweaver reads and displays your tags. Create a new tag database file for each set of tags, to tell Adobe Dreamweaver how to display the tags.

NOTE

This section explains how to define the way Adobe Dreamweaver displays a custom tag, but doesn't describe how to provide a way to edit the content or properties of a custom tag. For information on how to create a Property inspector to inspect and change the properties of a custom tag, see .

Each tag database file defines the name, type, content model, rendering scheme, and icon for one or more custom tags. You can create any number of tag database files, but all of them must reside in the Configuration/ThirdPartyTags folder to be read and processed by Adobe Dreamweaver. Tag database files have the .xml file extension.

TIP

If you are working on several unrelated sites at once (for example, as a freelance developer), you can put all the tag specifications for a particular site in one file. Then simply include that tag database file with the custom icons and Property inspectors that you hand over to the people who will maintain the site.

You define a tag specification with an XML tag called tagspec. For example, the following code describes the specification for a tag named happy:

<tagspec tag_name="happy" tag_type="nonempty" render_contents="false" content_model="marker_model" icon="happy.gif" icon_width="18" icon_height="18"></tagspec>

You can define two kinds of tags using tagspec:

  • Normal HTML-style tags

    The happy tag example is a normal HTML-style tag. It starts with an opening <happy> tag, contains data between opening and closing tags, and ends with a closing </happy> tag.

  • String-delimited tags

    String-delimited tags start with one string and end with another string. They are like empty HTML tags (such as img) in that they don't surround content and don't have closing tags. If the happy tag were a string-delimited tag, the tag specification would include the start_string and end_string attributes. An ASP tag is a string-delimited tag; it starts with the string <% and ends with the string %>, and it has no closing tag.

The following information describes the attributes and valid values for the tagspec tag. Attributes marked with an asterisk (*) are ignored for string-delimited tags. Optional attributes are marked in the attribute lists with curly braces ({}); all attributes not marked with curly braces are required.

<tagspec>

Description

Provides information about a third-party tag.

Attributes

tag_name, {tag_type}, {render_contents}, {content_model}, {start_string}, {end_string}, {detect_in_attribute}, {parse_attributes}, icon, icon_width, icon_height, {equivalent_tag}, {is_visual}, {server_model}
  • tag_name is the name of the custom tag. For string-delimited tags, tag_name is used only to determine whether a given Property inspector can be used for the tag. If the first line of the Property inspector contains this tag name with an asterisk on each side, the inspector can be used for tags of this type. For example, the tag name for ASP code is ASP. Property inspectors that can examine ASP code should have *ASP* on the first line. For information on the Property inspector API, see .
  • tag_type determines whether the tag is empty (as the img tag is), or whether it contains anything between its opening and closing tags (as the code tag does). This attribute is required for normal (nonstring-delimited) tags. It's ignored for string-delimited tags because they're always empty. Valid values are "empty" and "nonempty".
  • render_contents determines whether the contents of the tag should appear in the Design view or whether the specified icon should appear instead. This attribute is required for nonempty tags and is ignored for empty tags. (Empty tags have no content.) This attribute applies only to tags that appear outside attributes. The contents of tags that appear inside the values of attributes of other tags are not rendered. Valid values are "true" and "false".
  • content_model describes what kinds of content the tag can contain and where in an HTML file the tag can appear. Valid values are "block_model", "head_model", "marker_model", and "script_model":
    • block_model specifies that the tag can contain block-level elements such as div and p, and that the tag can appear only in the body section or inside other body-content tags such as div, layer, or td.
    • head_model specifies that the tag can contain text content and that it can appear only in the HEAD section.
    • marker_model specifies that the tag can contain any valid HTML code, and that it can appear anywhere in an HTML file. The HTML validator in Adobe Dreamweaver ignores tags that are specified as marker_model. However, the validator doesn't ignore the contents of such a tag; so even though the tag itself can appear anywhere, the contents of the tag may result in invalid HTML in certain places. For example, plain text cannot appear (outside a valid head element) in the head section of a document, so you can't place a marker_model tag that contains plain text in the head section. (To place a custom tag containing plain text in the head section, specify the tag's content model as head_model instead of marker_model.) Use marker_model for tags that should be displayed inline (inside a block-level element such as p or div--for example, inside a paragraph). If the tag should be displayed as a paragraph of its own, with line breaks before and after it, don't use this model.
    • script_model lets the tag exist anywhere between the opening and closing HTML tags of a document. When Adobe Dreamweaver encounters a tag with this model, it ignores all of the tag's content. Used for markup (such as certain ColdFusion tags) that Adobe Dreamweaver shouldn't parse.
  • start_string specifies a delimiter that marks the beginning of a string-delimited tag. String delimited tags can appear anywhere in the document where a comment can appear. Adobe Dreamweaver does not parse tags or decode entities or URLs between start_string and end_string. This attribute is required if end_string is specified.
  • end_string specifies a delimiter that marks the end of a string-delimited tag. This attribute is required if start_string is specified.
  • detect_in_attribute indicates whether to ignore everything between start_string and end_string (or between opening and closing tags if those strings are not defined) even when those strings appear inside attribute names or values. You should generally set this to "true" for string-delimited tags. The default is "false". For example, ASP tags sometimes appear inside attribute values, and sometimes contain quotation marks ("). Because the ASP tag specification specifies detect_in_attribute="true", Adobe Dreamweaver ignores the ASP tags, including the internal quotation marks, when they appear inside attribute values.
  • parse_attributes indicates whether to parse the attributes of the tag. If this is set to "true" (the default), Adobe Dreamweaver parses the attributes; if it's set to "false", Adobe Dreamweaver ignores everything until the next closing angle bracket that appears outside quotation marks. For example, this attribute should be set to "false" for a tag such as cfif (as in <cfif a is 1>, which Adobe Dreamweaver cannot parse as a set of attribute name/value pairs).
  • icon specifies the path and filename of the icon associated with the tag. This attribute is required for empty tags, and for nonempty tags whose contents do not appear in the Document window's Design view.
  • icon_width specifies the width of the icon in pixels.
  • icon_height specifies the height of the icon in pixels.
  • equivalent_tag specifies simple HTML equivalents for certain ColdFusion form-related tags. This is not intended for use with other tags.
  • is_visual indicates whether the tag has a direct visual effect on the page. For example, the ColdFusion tag cfgraph doesn't specify a value for is_visual (so the value defaults to "true"); the ColdFusion tag cfset is specified as having is_visual set to "false". Visibility for server markup tags is controlled by the Invisible Elements category of the Preferences dialog box; visibility for visual server markup tags can be set independent of visibility for nonvisual server markup tags.
  • server_model, if specified, indicates that the tagspec tag applies only on pages that belong to the specified server model. If server_model is not specified, the tagspec tag applies on all pages. For example, the delimiters for ASP and JSP tags are the same, but the tagspec tag for JSP specifies a server_model of "JSP", so when Adobe Dreamweaver encounters code with the appropriate delimiters on a JSP page, it displays a JSP icon. When it encounters such code on a non-JSP page, it displays an ASP icon.

Contents

None (empty tag).

Container

None.

Example

<tagspec tag_name="happy" tag_type="nonempty" render_contents="false" content_model="marker_model" icon="happy.gif" icon_width="18" icon_height="18"></tagspec>

How custom tags appear in the Design view

The way that custom tags appear in the Design view of the Document window depends on the values of the tag_type and render_contents attributes of the tagspec tag. (See .) If the value of tag_type is "empty", the icon specified in the icon attribute appears. If the value of tag_type is "nonempty" but the value of render_contents is "false", the icon appears as it would for an empty tag. The following example shows how an instance of the happy tag defined earlier might appear in the HTML:

<p>This is a paragraph that includes an instance of the <code>happy</code>tag (<happy>Joe</happy>).</p>

Because render_contents is set to "false" in the tag specification, the contents of the happy tag (the word Joe) are not rendered. Instead, the start and end tags and their contents appear as a single icon.

For nonempty tags that have a render_contents value of "true", the icon does not appear in the Design view; instead, the content between the opening and closing tags (such as the text between the tags in <mytag>This is the content between the opening and closing tags</mytag>) appears. If View > Invisible Elements is enabled, the content is highlighted using the third-party tag color specified in Highlighting preferences. (Highlighting applies only to tags defined in tag database files.)

To change the highlighting color of third-party tags:

  1. Select Edit > Preferences, and select the Highlighting category.
  2. Click the Third-Party Tags color box to display the color picker.
  3. Select a color, and click OK to close the Preferences dialog box. For information about selecting a color, see Using Adobe Dreamweaver.

Avoiding rewriting third-party tags

Adobe Dreamweaver corrects certain kinds of errors in HTML code. For details, see Using Adobe Dreamweaver. By default, Adobe Dreamweaver refrains from changing HTML in files with certain filename extensions, including .asp (ASP), .cfm (ColdFusion), .jsp (JSP), and .php (PHP). This default is set so that Adobe Dreamweaver does not accidentally modify the code contained in any such non-HTML tags. You can change the Adobe Dreamweaver default rewriting behavior so that it rewrites HTML when it opens such files, and you can add other file types to the list of types that Adobe Dreamweaver does not rewrite.

Adobe Dreamweaver encodes certain special characters by replacing them with numerical values when you enter them in the Property inspector. It's usually best to let Adobe Dreamweaver perform this encoding because the special characters are more likely to display correctly across platforms and browsers. However, because such encoding can interfere with third-party tags, you may want to change the Adobe Dreamweaver encoding behavior when you're working with files that contain third-party tags.

To allow Adobe Dreamweaver to rewrite HTML in more kinds of files:

  1. Select Edit > Preferences, and select the Code Rewriting category.
  2. Select either of the following options:
    • Fix Invalidly Nested and Unclosed Tags
    • Remove Extra Closing Tags
  3. Do one of the following:
    • Delete one or more extensions from the list of extensions in the Never Rewrite Code: In Files with Extensions option.
    • Deselect the Never Rewrite Code: In Files with Extensions option. (Deselecting this option lets Adobe Dreamweaver rewrite HTML in all types of files.)

To add file types that Adobe Dreamweaver should not rewrite:

  1. Select Edit > Preferences, and select the Code Rewriting category.
  2. Select either of the following options:
    • Fix Invalidly Nested and Unclosed Tags
    • Remove Extra Closing Tags
  3. Make sure the Never Rewrite Code: In Files with Extensions option is selected, and add the new file extensions to the list in the text field.

If the new file type doesn't appear in the file-types pop-up menu in the File > Open dialog box, you might want to add it to the Configuration/Extensions.txt file. For details, see .

To turn off Adobe Dreamweaver encoding options:

  1. Select Edit > Preferences, and select the Code Rewriting category.
  2. Deselect either or both Special Characters options.

For information on the other Code Rewriting preferences, see Using Adobe Dreamweaver.