Specifications

Data Translators 229
Returns
A string that contains the translated document or an empty string if nothing is translated.
Example
The following instance of liveDataTranslateMarkup() calls the C function translateASP(),
which is contained in a DLL (Windows) or a code library (Macintosh) called ASPTrans:
function liveDataTranslateMarkup(docName, siteRoot, docContent){
var translatedString = "";
if (docContent.length > 0){
translatedString = ASPTrans.translateASP(docName, siteRoot, docContent);
}
return translatedString;
}
Determining what kind of translator to use
All translators are the same to a certain extent: They must contain the getTranslatorInfo()
and
translateMarkup() functions, and they must reside in the Configuration/Translators
folder. They differ, however, in the kind of code that they insert into the user’s document and in
how that code must be inspected.
• To translate small pieces of server markup that determine attribute values or that conditionally
add attributes to a standard HTML tag, write an attribute translator. Standard HTML tags
that contain translated attributes can be inspected with the Property inspectors that are built
into Dreamweaver. It is not necessary to write a custom Property inspector (see “Adding a
translated attribute to a tag” on page 229).
• To translate an entire tag (for example, a server-side include) or a block of code (for example,
JavaScript, ColdFusion, PHP, or other scripting), write a block/tag translator. The code that is
generated by a block/tag translator cannot be inspected with the Property inspectors that are
built into Dreamweaver. You must write a custom Property inspector for the translated
content if you want users to be able to change the properties of the original code (see “Locking
translated tags or blocks of code” on page 234).
Adding a translated attribute to a tag
Attribute translation relies heavily on the ability of the Dreamweaver parser to ignore server
markup. Dreamweaver already ignores the most common kinds of server markup (including ASP,
CFML, and PHP) by default; if you use server markup that has different start and end markers,
you must modify the third-party tag database to ensure that your translator works properly. For
more information on modifying the third-party tag database, see “Customizing Dreamweaver” in
Using Dreamweaver.
When Dreamweaver handles the preservation of the original server markup, the translator
generates a valid attribute value that can be viewed in the Document window. (If you use server
markup only for attributes that do not have a user-visible effect, you do not need a translator.)
The translator creates an attribute value that has a visible effect in the Document window by
adding a special attribute,
mmTranslatedValue, to the tag that contains the server markup. The
mmTranslatedValue attribute and its value are not visible in the HTML panel or in Code view,
nor are they saved with the document.