Extensible document types in Adobe Dreamweaver

XML provides a rich system for defining complex documents and data structures. Adobe Dreamweaver uses several XML schemas to organize information about server behaviors, tags and tag libraries, components, document types, and reference information.

When you create and work with extensions in Adobe Dreamweaver, there are many instances in which you create or modify existing XML files to manage the data that your extension uses. In many cases, you can copy an existing file from the appropriate subfolder within the Configuration folder to use as a template.

Document type definition file

The central component of extensible document types is the document type definition file. There might be several definition files, all of which are located in the Configuration/DocumentTypes folder. Each definition file contains information about at least one document type. For each document type, essential information such as server model, color coding style, descriptions, and so forth, is described.

NOTE

Do not confuse Adobe Dreamweaver document type definition files with the XML document type definition (DTD). Document type definition files in Adobe Dreamweaver contain a set of documenttype elements, each of which defines a predefined collection of tags and attributes that are associated with a document type. When Adobe Dreamweaver starts, it parses the document type definition files and creates an in-memory database of information regarding all defined document types.

Adobe Dreamweaver provides an initial document type definition file. This file, named MMDocumentTypes.xml, contains the document type definitions provided by Adobe:

Document type	Server model	Internal type	File extensions	Previous server model
ASP.NET C#	ASP.NET-Csharp	Dynamic	aspx, ascx
ASP.NET VB	ASP.NET-VB	Dynamic	aspx, ascx
ASP JavaScript	ASP-JS	Dynamic	asp
ASP VBScript	ASP-VB	Dynamic	asp
ColdFusion	ColdFusion	Dynamic	cfm, cfml	UltraDev 4 ColdFusion
ColdFusion Component		Dynamic	cfc
JSP	JSP	Dynamic	jsp
PHP	PHP	Dynamic	php, php3
Library Item		DWExtension	lbi
ASP.NET C# Template		DWTemplate	axcs.dwt
ASP.NET VB Template		DWTemplate	axvb.dwt
ASP JavaScript Template		DWTemplate	aspjs.dwt
ASP VBScript Template		DWTemplate	aspvb.dwt
ColdFusion Template		DWTemplate	cfm.dwt
HTML Template		DWTemplate	dwt
JSP Template		DWTemplate	jsp.dwt
PHP Template		DWTemplate	php.dwt
HTML		HTML	htm, html
ActionScript		Text	as
CSharp		Text	cs
CSS		Text	css
Java		Text	java
JavaScript		Text	js
VB		Text	vb
VBScript		Text	vbs
Text		Text	txt
EDML		XML	edml
TLD		XML	tld
VTML		XML	vtm, vtml
WML		XML	wml
XML		XML	xml

If you need to create a new document type, you can either add your entry to the document definition file that Adobe provides (MMDocumentTypes.xml) or add a custom definition file to the Configuration/DocumentTypes folder.

NOTE

The NewDocuments subfolder resides in the Configuration/DocumentTypes folder. This subfolder contains default pages (templates) for each document type.

Structure of document type definition files

The following example shows what a typical document type definition file might look like:

<?xml version="1.0" encoding="utf-8"?><documenttypes 
 xmlns:MMString="http://www.macromedia.com/schemes/data/string/"> <documenttype  id="dt-ASP-JS" servermodel="ASP-JS" internaltype="Dynamic" winfileextension="asp,htm, html" macfileextension=asp, html" previewfile="default_aspjs_preview.htm" file="default_aspjs.htm" priorversionservermodel="UD4-ASP-JS" > <title> <loadString id="mmdocumenttypes_0title" /> </title> <description> <loadString id="mmdocumenttypes_0descr" /> </description> </documenttype> ... </documenttypes>

NOTE

Color coding for document types is specified in the XML files that reside in the Configuration/CodeColoring folder.

In the previous example, the loadstring element identifies the localized strings that Adobe Dreamweaver should use for the title and description for ASP-JS type documents. For more information about localized strings, see Localized strings.

The following table describes the tags and attributes that you can use within a document type definition file.

Element Type		Required	Description
Tag	Attribute	Required	Description
documenttype`(root)`		Yes	Parent node.
	id	Yes	Unique identifier across all document type definition files.
	servermodel	No	Specifies the associated server model (case-sensitive); by default, the following values are valid: ASP.NET C# ASP.NET VB ASP VBScript ASP JavaScript ColdFusion JSP PHP MySQL A call to the `getServerModelDisplayName()` functions returns these names. The server model implementation files are located in the Configuration/ServerModels folder. Extension developers can create new server models extending this list.
	internaltype	Yes	A broad classification of how Adobe Dreamweaver treats a file. The `internaltype` identifies whether the Design view is enabled for this document and handles special cases such as Adobe Dreamweaver templates or extensions. The following values are valid: `Dynamic` `DWExtension` (has special display regions) `DWTemplate` (has special display regions) `HTML` `HTML4` `Text` (Code view only) `XHTML1` `XML` (Code view only) All server model-related document types should map to `Dynamic`. HTML should map to `HTML`. Script files (such as CSS, JS, VB, and CS) should map to `Text`. If `internaltype` is `DWTemplate`, you should also specify `dynamicid`. If you omit `dynamicid` in this case, the new blank template that the New Document dialog box creates is not a recognized document type by the Server Behavior or Bindings panel. Instances of this template are simply an HTML template.
	dynamicid	No	A reference to the unique identifier of a dynamic document type. This attribute is meaningful only when `internaltype` is `DWTemplate`. This attribute lets you associate a dynamic template with a dynamic document type.
	winfileextension	Yes	The file extension that is associated with the document type on Windows. You specify multiple file extensions by using a comma-separated list. The first extension in the list is the extension that Adobe Dreamweaver uses when the user saves a `documenttype` document. If two nonserver model-associated document types have the same file extension, Adobe Dreamweaver recognizes the first one as the document type for the extension.
	macfileextension	Yes	The file extension that is associated with the document type on the iOS. You specify multiple file extensions by using a comma-separated list. The first extension in the list is the extension that Adobe Dreamweaver uses when the user saves a `documenttype` document. If two nonserver model-associated document types have the same file extension, Adobe Dreamweaver recognizes the first one as the document type for the extension.
	previewfile	No	The file that is rendered in the Preview area of the New Document dialog box.
	file	Yes	The file that is located in the DocumentTypes/NewDocuments folder that contains template content for new `documenttype` documents.
	priorversionservermodel	No	If this document's server model has a Adobe Dreamweaver UltraDev 4 equivalent, specify the name of the older version of the server model. UltraDev 4 ColdFusion is a valid prior server model.
title (subtag)		Yes	The string that appears as a category item under Blank Document in the New Document dialog box. You can place this string directly in the definition file or point to it indirectly for localization purposes. For more information on localizing this string, see Localized strings. Formatting is not allowed, so HTML tags cannot be specified.
description (subtag)		No	The string that describes the document type. You can place this string directly in the definition file or point to it indirectly for localization purposes. For more information on localizing this string, see Localized strings. Formatting is allowed, so HTML tags can be specified.

NOTE

When the user saves a new document, Adobe Dreamweaver examines the list of extensions for the current platform that are associated with the document type (winfileextension and macfileextension). Adobe Dreamweaver selects the first string in the list and uses it as the default file extension. To change this default file extension, you must reorder the extensions in the comma-separated list so the new default is listed first.

When Adobe Dreamweaver starts, it reads all document type definition files and builds a list of valid document types. Adobe Dreamweaver treats any entries within the definition files that have nonexistent server models as nonserver model document types. Adobe Dreamweaver ignores entries that have bad contents or IDs that are not unique.

If, while scanning the Configuration/DocumentTypes folder, Adobe Dreamweaver finds no document type definition files or if any of the definition files appear to be corrupt, Adobe Dreamweaver closes with an error message.

Dynamic templates

You can create templates that are based on dynamic document types. These templates are called dynamic templates. The following two elements are essential to defining a dynamic template:

The value of the internaltype attribute for the new document type must be DWTemplate.
The dynamicid attribute must be set, and the value must be a reference to the identifier of an existing dynamic document type.

The following example defines a dynamic document type:

<documenttype  id="PHP_MySQL"  servermodel="PHP MySQL"  internaltype="Dynamic"  winfileextension="php,php3"  macfileextension="php,php3" file="Default.php"> <title>PHP</title>  <description><![CDATA[PHP document]]></description></documenttype>

Now, you can define the following dynamic template, which is based on this PHP_MySQL dynamic document type:

<documenttype  id="DWTemplate_PHP"  internaltype="DWTemplate"  dynamicid="PHP_MySQL"  winfileextension="php.dwt"  macfileextension="php.dwt"  file="Default.php.dwt"> <title>PHP Template</title>  <description><![CDATA[Dreamweaver PHP Template document]]></description></documenttype>

When a Adobe Dreamweaver user creates a new blank template of type DWTemplate_PHP, Adobe Dreamweaver lets the user create PHP server behaviors in the file. Furthermore, when the user creates instances of the new template, the user can create PHP server behaviors in the instance.

In the previous example, when the user saves the template, Adobe Dreamweaver automatically adds a .php.dwt extension to the file. When the user saves an instance of the template, Adobe Dreamweaver adds the .php extension to the file.

Document extensions and file types

By default, Adobe Dreamweaver shows all the file types it recognizes in the File > Open dialog box. After creating a new document type, extension developers need to update the appropriate Extensions.txt file. If the user is on a multiuser system (such as Windows XP, Windows 2000, or Mac OS X), the user has another Extensions.txt file in their Configuration folder. The user must update the Extensions.txt file because it is the instance that Adobe Dreamweaver looks for and parses.

The location of the user's Configuration folder depends on the user's platform.

Windows 2000 and Windows XP platforms use the following location:

drive:\Documents and Settings\username\Application Data\Adobe\Dreamweaver\Configuration

NOTE

In Windows XP, this folder may be inside a hidden folder.

Mac OS X platforms use the following location:

drive:Users/username/Library/Application Support/Adobe:Dreamweaver/Configuration

If Adobe Dreamweaver cannot find the Extensions.txt file in the user's Configuration folder, Adobe Dreamweaver looks for it in the Adobe Dreamweaver Configuration folder.

NOTE

On multiuser platforms, if you edit the copy of Extensions.txt that resides in the Adobe Dreamweaver Configuration folder and not the one in the user's Configuration folder, Adobe Dreamweaver is not aware of the changes because Adobe Dreamweaver parses the copy of the Extensions.txt file in the user's Configuration folder, not the file in the Adobe Dreamweaver Configuration folder.

To create a new document extension, you can either add the new extension to an existing document type or create a new document type.

To add a new extension to an existing document type:

Edit MMDocumentTypes.xml.
Add the new extension to the winfileextension and macfileextension attributes of the existing document type.

To add a new document type:

Make a backup copy of the Extensions.txt file in the Configuration folder.
Open Extensions.txt in Adobe Dreamweaver or a text editor.
Add a new line for each new file type. In capital letters, enter the filename extensions that the new file type can have, separated by commas; then add a colon and a brief descriptive phrase to show in the pop-up menu for file types that appears in the File > Open dialog box.
For example, for JPEG files, enter JPG,JPEG,JFIF:JPEG Image Files
Save the Extensions.txt file.
Restart Adobe Dreamweaver.
To see the changes, select File > Open and click the pop-up menu of file types.

To change the Adobe Dreamweaver default File > 0pen file type:

Make a backup copy of the Extensions.txt file in the Configuration folder.
Open Extensions.txt in Adobe Dreamweaver or a text editor.
Cut the line that corresponds to the new default, and paste it at the beginning of the file, to make it the first line of the file.
Save the Extensions.txt file.
Restart Adobe Dreamweaver.
To see the changes, select File > Open and click the pop-up menu of file types.

Localized strings

Within a document type definition file, the <title> and <description> subtags specify the display title and description for the document type. You can use the MMString:loadstring directive in the subtags as a placeholder for providing localized strings for the two subtags. This process is similar to server-side scripting where you specify a particular string to use in your page by using a string identifier as a placeholder. For the placeholder, you can use a special tag or you can specify a tag attribute whose value is replaced.

To provide localized strings, perform the following steps:

Place the following statement at the beginning of the document type definition file:
```
<?xml version="1.0" encoding="utf-8"?>
```

Declare the MMString name space in the <documenttypes> tag:

 <documenttypes  xmlns:MMString="http://www.macromedia.com/schemes/data/string/">

At the location in the document type definition file where you want to provide a localized string, use the MMString:loadstring directive to define a placeholder for the localized string. You can specify this placeholder in one of the following ways:
```
<description> <loadstring>myJSPDocType/Description</loadstring></description>
```
or
```
<description> <loadstring id="myJSPDocType/Description" /></description>
```
In these examples, myJSPDocType/Description is a unique string identifier that acts as a placeholder for the localized string. The localized string is defined in the next step.

In the Configuration/Strings folder, create a new XML file (or edit an existing file) that defines the localized string. For example, the following code, when placed in the Configuration/Strings/strings.xml file, defines the myJSPDocType/Description string:

<strings>... <string id="myJSPDocType/Description"  value= "<![CDATA[JavaServer&nbsp;Page with <em>special</em> features]]>"  />...</strings>

NOTE

String identifiers, such as myJSPDocType/Description in the previous example, must be unique within the application. Adobe Dreamweaver, when it starts, parses all XML files within the Configuration/Strings folder and loads these unique strings.

Rules for document type definition files

Adobe Dreamweaver lets document types that are associated with a server model share file extensions. For example: ASP-JS and ASP-VB can claim .asp as their file extension. (For information on which server model gets preference, see canRecognizeDocument().)

Adobe Dreamweaver does not let document types that are not associated with a server model share file extensions.

If a file extension is claimed by two document types where one type is associated with a server model and the other is not, the latter document type gets preference. Suppose you have a document type called SAM, which is not associated with a server model, that has a file extension of .sam, and you add this file extension to the ASP-JS document type. When a Adobe Dreamweaver user opens a file that has a .sam extension, Adobe Dreamweaver assigns the SAM document type to it, not ASP-JS.