Extensible document types in Dreamweaver

XML provides a rich system for defining complex documents and data structures. 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 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 Dreamweaver document type definition files with the XML document type definition (DTD). Document type definition files in 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 Dreamweaver starts, it parses the document type definition files and creates an in-memory database of information regarding all defined document types.

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

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 Macromedia 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          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  />     </title>     <description>       <loadString  />     </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 Dreamweaver should use for the title and description for ASP-JS type documents. For more information about localized strings, see "Localized strings" on page 44.

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

Element Type		Required	Description
Tag	Attribute
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 Dreamweaver treats a file. The internaltype identifies whether the Design view is enabled for this document and handles special cases such as 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 Dreamweaver uses when the user saves a documenttype document. If two nonserver model-associated document types have the same file extension, 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 Macintosh. You specify multiple file extensions by using a comma-separated list. The first extension in the list is the extension that Dreamweaver uses when the user saves a documenttype document. If two nonserver model-associated document types have the same file extension, 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 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" on page 44. 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" on page 44. Formatting is allowed, so HTML tags can be specified.

NOTE

When the user saves a new document, Dreamweaver examines the list of extensions for the current platform that are associated with the document type (winfileextension and macfileextension). 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 Dreamweaver starts, it reads all document type definition files and builds a list of valid document types. Dreamweaver treats any entries within the definition files that have nonexistent server models as nonserver model document types. Dreamweaver ignores entries that have bad contents or IDs that are not unique.

If, while scanning the Configuration/DocumentTypes folder, Dreamweaver finds no document type definition files or if any of the definition files appear to be corrupt, 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          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          internaltype="DWTemplate"     dynamic     winfileextension="php.dwt"     macfileextension="php.dwt"     file="Default.php.dwt">     <title>PHP Template</title>     <description><![CDATA[Dreamweaver PHP Template document]]></   description> </documenttype> 

When a Dreamweaver user creates a new blank template of type DWTemplate_PHP, 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, Dreamweaver automatically adds a .php.dwt extension to the file. When the user saves an instance of the template, Dreamweaver adds the .php extension to the file.

Document extensions and file types

By default, 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 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\Macromedia\Dreamweaver 8\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/Macromedia:Dreamweaver 8/Configuration

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

NOTE

On multiuser platforms, if you edit the copy of Extensions.txt that resides in the Dreamweaver Configuration folder and not the one in the user's Configuration folder, Dreamweaver is not aware of the changes because Dreamweaver parses the copy of the Extensions.txt file in the user's Configuration folder, not the file in the 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:

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

To add a new document type:

1.	Make a backup copy of the Extensions.txt file in the Configuration folder.
2.	Open Extensions.txt in Dreamweaver or a text editor.
3.	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
4.	Save the Extensions.txt file.
5.	Restart Dreamweaver. To see the changes, select File > Open and click the pop-up menu of file types.

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

1.	Make a backup copy of the Extensions.txt file in the Configuration folder.
2.	Open Extensions.txt in Dreamweaver or a text editor.
3.	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.
4.	Save the Extensions.txt file.
5.	Restart 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:

1.	Place the following statement at the beginning of the document type definition file: <?xml version="1.0" encoding="utf-8"?>
2.	Declare the MMString name space in the <documenttypes> tag: <documenttypes xmlns:MMString="http://www.macromedia.com/schemes/data/string/">
3.	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 /> </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.
4.	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 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. Dreamweaver, when it starts, parses all XML files within the Configuration/Strings folder and loads these unique strings.

Rules for document type definition files

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()" on page 424.)

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 Dreamweaver user opens a file that has a .sam extension, Dreamweaver assigns the SAM document type to it, not ASP-JS.

Opening a document in Dreamweaver

When a user opens a file, Dreamweaver follows a series of steps to identify the document type based on the file's extension.

If Dreamweaver successfully finds a unique document type, Dreamweaver uses that type and loads the associated server model (if any) for the document that the user is opening. If the user has selected to use Dreamweaver UltraDev 4 server behaviors, Dreamweaver loads the appropriate UltraDev 4 server model.

If the file extension maps to more than one document type, Dreamweaver performs the following actions:

• If a static document type is among the list of document types, it gets preference.

• If all the document types are dynamic, Dreamweaver creates an alphabetical list of the server models that are associated with these document types and then calls the canRecognizeDocument() function in each server model (see "canRecognizeDocument()" on page 424). Dreamweaver collects the return values and determines which server model returned the highest valued positive integer. The document type whose server model returns the highest integer is the document type that Dreamweaver assigns to the document being opened. If, however, more than one server model returns the same integer, Dreamweaver goes through the alphabetical list of those server models, picks the first in the list, and uses that document type. For example, if both ASP-JS and ASP-VB claim an ASP document and if their respective canRecognizeDocument() functions return equal values, Dreamweaver assigns the document to ASP-JS (because, alphabetically, ASP-JS is first).

If Dreamweaver cannot map the file extension to a document type, Dreamweaver opens the document as a text file.

Customizing workspace layouts

Dreamweaver lets you customize the workspace layout, including which panels are in the specified layout, as well as other attributes such as the positions and sizes of the panels, their collapsed or expanded states, the position and size of the application window, and the position and size of the Document window.

The workspace layout is specified in XML files stored in the Configuration/Workspace layouts folder. The following sections describe the syntax of the XML tags. Optional attributes are marked in the attribute lists with curly braces ({}); all attributes not marked with curly braces are required.

<panelset>

Description

Outermost tag, which signals the start of the panel set description.

Attributes

None.

Contents

This tag may contain one or more <application>, <document>, or <panelset> tags.

Container

None.

Example

 <panelset> <!-- panelset tags here --> </panelset> 

<application>

Description

Specifies the application window's initial position and size.

Attributes

 rect, maximize 

• rect specifies the position and size of the application window. The string is in the form "left top right bottom" specified as integers.

• maximize is a Boolean value: TRue if the application window should be maximized on startup; false otherwise. The default value is TRue.

Contents

None.

Container

This tag must be contained in a panelset tag.

Example

 <panelset>   <application rect="0 0 1000 1200" maximize="false">   </application> </panelset> 

<document>

Description

Specifies the Document window's initial position and size.

Attributes

 rect, maximize 

• rect specifies the position and size of the Document window. The string is in the form "left top right bottom" specified as integers. If the maximize value is true, the rect value is ignored.

• maximize is a Boolean value: TRue if the Document window should be maximized on startup; false otherwise. The default value is TRue.

Contents

None.

Container

This tag must be contained in a panelset tag.

Example

 <panelset>   <document rect="100 257 1043 1200" maximize="false">   </document> </panelset> 

<panelframe>

Description

Describes an entire panel group.

Attributes

 x, y, {width, height}, dock, collapse 

• x specifies the left position of the panel group. Its value can be an integer or a value that is relative to the screen. If the integer value is not on the screen, the panel group appears in the closest screen position possible to make it visible on the screen. Relative values can be "left" or "right"; these values indicate which edge of the panel group to align with which edge of the virtual screen.

• y specifies the top position of the panel group. Its value can be an integer or a value that is relative to the screen. If the integer value is not on the screen, the panel group appears in the closest screen position possible to make it visible on the screen. Relative values can be "top" or "bottom"; these values indicate which edge of the panel group to align with which edge of the virtual screen.

• width is the width, in pixels, of the panel group. This attribute is optional. If the width is not specified, the built-in default for the panel group is used.

• height is the height, in pixels, of the panel group. This attribute is optional. If the height is not specified, the built-in default for the panel group is used.

• dock is a string value that specifies to which edge of the application frame to dock the panel group. This attribute is ignored on the Macintosh because panel groups cannot be docked.

• collapse is a Boolean value: true indicates that the panel group is collapsed: false indicates that the panel group is expanded. This attribute is ignored on the Macintosh because panels are floating.

Contents

This tag must contain one or more panelcontainer tags.

Container

This tag must be contained in a panelset tag.

Example

 <panelset>   <panelframe rect="196 453 661 987" visible="true" dock="floating">     <!-- panelcontainer tags here -->   </panelframe> </panelset> 

<panelcontainer>

Description

Describes an entire panel group.

Attributes

 expanded, title,{ height,} activepanel, visible, maximize, maxRestorePanel,  maxRestoreIndex, maxRect, tabsinheader 

• expanded is a Boolean value: TRue if the panel is expanded; false otherwise.

• title is a string that specifies the title of the panel.

• height is an integer that specifies the height of the panel in pixels. This attribute is optional. If height is not specified, the build-in default for each panel is used.

  NOTE

  Width is inherited from the parent.

  
  

• activepanel is a number that is the ID of the front panel.

• visible is a Boolean value: true if the panel is visible; false otherwise.

• maximize is a Boolean value: true if the panel should be maximized when it appears initially; false otherwise.

• maxRestorePanel is a number that is the ID of the panel to restore to.

• maxRect is a string that indicates the position and size of the panel when it is maximized. The string is in the form "left top right bottom", specified as integers.

• tabsinheader is a Boolean value: true indicates that tabs should be positioned in the header instead of below the header bar; false otherwise.

Contents

This tag must contain one or more panel tags.

Container

This tag must be contained in a panelframe tag.

Example

 <panelset>   <panelframe rect="196 453 661 987" visible="true" dock="floating">     <panelcontainer title="Color" height="250" visible="true" expanded="true"  activepanel="20">       <!-- panel tags here --->     </panelcontainer>   </panelframe> </panelset> 

<panel>

Description

Specifies the panel that appears in the panel container.

Attributes

 id, visibleTab 

• id is a number that indicates the ID for the panel. The following table contains a list of values:

  Product	ID	Panel
  Flash	1	Properties
  	2	Actions
  	3	Align
  	4	Behaviors
  	5	Components
  	6	Component Inspector
  	7	Color Mixer
  	8	Color Swatches
  	9	History
  	10	Info
  	11	Library
  	12	Movie Explorer
  	13	Output
  	14	Properties
  	15	Project
  	16	Transform
  	17	Scene
  	18	Strings
  	19	Debugger
  	101 110	Library Panels
  Dreamweaver	1	Properties
  Zorn	1	Properties

  
  

• visibleTab is a Boolean value: true if the tab and the panel should be visible; false otherwise.

Contents

None.

Container

This tag must be contained in a panelcontainer tag.

Example

 <panelset>   <panelframe rect="196 453 661 987" visible="true" dock="floating">     <panelcontainer title="Color" height="250" visible="true" expanded="true"  activepanel="20">        <panel ></panel>     </panelcontainer>   </panelframe> </panelset> 

Customizing the Code view toolbar

The Code view toolbar displays 15 buttons initially. This is a subset of the buttons that are available. You can customize the Code view toolbar by changing the buttons that appear on the toolbar and the order in which they appear by editing the file Configuration/Toolbars/Toolbars.xml. You can also insert your own buttons into the toolbar through the Extension Manager.

To change the order of button:

1.	Open the file Configuration/Toolbars/toolbars.xml.
2.	Locate the Code view toolbar section by searching for the following comment: <!-- Code view toolbar -->
3.	Copy and paste the button tags so that they appear in the order you want on the toolbar.
4.	Save the file.

To remove a button:

1.	Open the file Configuration/Toolbars/toolbars.xml.
2.	Locate the Code view toolbar section by searching for the following comment: <!-- Code view toolbar -->
3.	Surround the button you want to remove with a comment. The following example shows a button that is surrounded by comments so that it does not appear on the toolbar: <!-- remove button from Code view toolbar <button image="Toolbars/images/MM/T_ExpandAll_Sm_N.png" disabledImage="Toolbars/images/MM/T_ExpandAll_Sm_D.png" tooltip="Expand All" domRequired="false" enabled="dw.getFocus(true) == 'textView' || dw.getFocus(true) == 'html'" command="if (dw.getFocus(true) == 'textView' || dw.getFocus(true) == 'html') dw .getDocumentDOM().source.expandAllCodeFragments();" update="onViewChange" /> -->
4.	Save the file.

To make any buttons that are not visible in the toolbar appear, you remove the comment that surrounds a button in the XML file.