About XSL Transformation

XSL Transformation

The XSL Transformation server behavior allows you to import XML data in your pages and process it in a human-readable form using an XSL file.

This chapter contains the following topics:

  • Requirements and Supported Platforms

  • Applying the XSL Transformation

  • Removing an XSL Transformation

  • Configuring the XSL Transformation

  • Run-time Errors and Design Errors

  • Generated Code


Requirements and Supported Platforms

XSL Transformation requires that you have one of the following XML/XSL libraries installed on your server, depending on your current development platform.

For PHP developers

  • PHP 4.2.x – Sablotron

  • PHP 4.3.x – Sablotron (API changed)

  • PHP 4.3.x – DOMXML/XSL

  • PHP 5.0.x – DOMXML/XSL (API Changed)

For ColdFusion developers

  • ColdFusion MX and MX 6.1 – XSL Transform Tag

  • ColdFusion MX and MX 6.1 – Java (for XSL parameters)

  • ColdFusion MX 7 – XSL Transform Tag

  • ColdFusion MX 7 – Java (for XSL parameters)

For ASP developers

  • ASP VBScript – MsXML 2.6/MsXML 3.0

  • ASP JScript – MsXML 2.6/MsXML 3.0

  • ASP .NET

  • ASP .NET VB – System.Xml.*

  • ASP .NET C# – System.Xml.*

Related topics:

  • Run-time Errors and Design Errors


Applying the XSL Transformation

The XSL Transformation command is accessible from two places in the Dreamweaver interface:
The Application Tab from the Insert bar:

The Server Behaviors menu from the Application panel:

After you configure the XSL Transformation server behavior and apply it to your page, the following operations are performed:

  • The corresponding code in generated in your page. You can view it in Dreamweaver Code View:

  • A translator is inserted in your page, at the current mouse cursor position, if you are in Design View or Split View.

  • The XSL Transformation server behavior is listed in the Server Behaviors tab of the Application panel.

  • The \includes\MM_XSLTransform\ folder is generated in the current site root and the corresponding run-time library (MM_XSLTransform) is copied there, if the file was not previously copied.

  • The generated folder and run-time library are uploaded on the testing server.

You can save, upload and preview your page in the browser. The XSL file specified in the server behavior will transform the data stored in the XML file and display it in the browser.

Related topics:

  • Configuring the XSL Transformation


Removing an XSL Transformation

You can remove an XSL Transformation from your page in one of the following ways:

  • Select the corresponding server behavior in the Server Behaviors tab of the Application panel and click the Minus (-) button.

  • Run the Undo Add Server Behavior command from the Edit menu or use the CTRL+Z keys, if the XSL Transformation was the last action performed on the page.

  • Select the generated translator in Dreamweaver Design View and hit Delete.

  • Manually delete all generated code in Dreamweaver Code View (not recommended).

Note: Removing the generated code only partially will break this server behavior, marking it with a red exclamation sign in the Server Behaviors panel or making it disappear from the list of server behaviors.

Removing the XSL Transformation server behavior from your page will not remove the run-time library from the includes folder, or the XML and XSL files used in the transformation. You must delete them manually from your site root folder, if they are no longer needed.


Configuring the XSL Transformation

After launching the XSL Transformation server behavior, the following interface is displayed:

To create an XSL Transformation in your page, configure the following options:

  • XSL file – specify a local XSL file. The path can be relative to the document or to the site root. You can also use the Browse button to select the file. If the file is located outside your site root folder, you will be prompted to copy the file to the site folder.

  • XML URI – type the URL path to a remote XML file, or use the Browse button next to this text box to select a local XML file. The Browse button opens a typical Select File window. If you use a local XML file located outside your site root folder, you will be prompted to copy the file to the site folder. The path can be an URL (such as http://www.domain.org/news.xml), or a local path relative to the document (such as folder/news.xml) or relative to the site root (/folder/news.xml).

To document: XML file will be automatically selected based on XSL selection.

  • XSL parameters – Use the + and - buttons to add or remove XSL parameters. The currently defined XSL parameters are displayed in the list. You can edit the name, value, and default value of a parameter by selecting it in the list and clicking the Edit button. Read more in Using Parameters in the XSL Transformation.

  • Click OK to apply the XSL Transformation server behavior or to confirm your changes. Click Cancel to dismiss the XSL Transformation window and call off any changes.

  • The Help button opens this page.

Related topics:

  • Using Parameters in the XSL Transformation

  • Editing the XSL Transformation


Using Parameters in the XSL Transformation

You can also define parameters for the XSL Transformation. Parameters are used by the specified XSL file to better control how the XML file is processed. For instance, you could use a parameter in order to identify and list a specific article in news feed from a media agency website. Each parameter can have a name, a run-time value and a default value.

Adding parameters

To add an XSL parameter to an XSL Transformation, follow the next steps:

  • In the XSL Transformation window, click the Plus (+) button in the XSL parameters area. The Add Parameter dialog window is displayed:

  • Configure the Add Parameter dialog window by specifying the following settings:

    • Name – specify a name for the parameter. The name can only contain alphanumeric characters. Spaces are not allowed.

    • Value – either type in a runtime value in this text box, or click the lightning bolt icon next to it to open up the Dynamic Data window:

      Configure the Dynamic Data dialog window as follows:

      • You must have at least one source of dynamic data defined in the Bindings tab of the Application panel, in order to select it as a value for the XSL parameter. If no data sources appear in the list, or if the available data sources don’t meet your needs, define a new data source.

      • If desired, select a data format for the text.

      • If desired, modify the code Dreamweaver will insert in your page for the parameter's runtime value.

      • Click OK when done.

    • Default Value - specify the value the parameter should use if no runtime value is returned.

    • Click OK to confirm your settings.

To document: XSL parameter list will be auto-populated with the parameters defined in the XSL file.

Editing parameters

To edit an XSL parameter, follow the next steps:

  • In the XSL Transformation window, select the parameter from the XSL parameters list. Its value and default value are displayed in the right.

  • Click Edit to open the Edit Parameter dialog window.

  • Change the desired settings.

  • Click OK when done.

Removing parameters

To remove an XSL parameter, select it from the XSL parameters list and click the Minus (-) button.

How XSL parameters work in the browser

The following example shows how to use two XSL parameters to display a list of employees. Because the original XML file might store a large number of employees, you will display only five records per page and allow users to navigate through the list using "next" and "previous" links.
The original list is stored in the employees.xml file having the following structure:

The XML file is processed by the employees.xsl file, that uses the elementsPerPage parameter to display a fixed number of employees per page, and the page URL parameter, to navigate through pages of the same list.

The XSL file displays all employees in a table having a fixed number of rows per page (specified by the parameter elementsPerPage), and containing their ID, name and position in the company.
Apply an XSL Transformation server behavior on a page of your site, and configure it as follows:
  • XML file: employees.xml
  • XSL file: employees.xsl
  • XSL parameters:
    • page, with the runtime value equal to the value of the URL parameter page, and the default value set to 1.
    • elementsPerPage, with the runtime value set to 5, and the default value set to 5.
The configured interface should look like this:

Click OK, save your page and preview it in the browser. Clicking the "next" link will pass as URL parameter the page number:


Editing the XSL Transformation

You can edit an existing XSL Transformation in one of two ways:

  • Double-click its name in the Server Behaviors panel. The XSL Transformation window opens, and is populated with the corresponding data and parameters from the page. Change the desired option(s) and click OK.

  • Switch to Dreamweaver Code View and edit the generated code. You can change only the XML and XSL filenames and the defined parameters. The changes will be immediately reflected in the Server Behaviors panel and in the XSL Transformation interface.
    Note    : Changing more than the specified settings in the generated code can break this server behavior, marking it with a red exclamation sign in the Server Behaviors panel or making it disappear from the list of server behaviors.

After editing the XSL Transformation server behavior, the included files are copied to the current site folder, if they were not already copied.


Run-time Errors and Design Errors

Design-time errors

  • The XML URI field cannot be empty.

You cannot perform an XSL Transformation without specifying the source of data in XML format. Please select an XML file in the XML file field.

  • The XSL file field cannot be empty.

You cannot perform an XSL Transformation without specifying the file responsible for transforming the original XML. Please select an XSL file in the XSL file field.

  • The value specified in the XML URI field is not an XML file.

You have selected a file having a format other than XML. Please make sure the file you point to has the extension .xml and is valid.

  • The value specified in the XSL file field is not an XSL file.

You have selected a file having a format other than XSL. Please make sure the file you point to has the extension .xsl and is valid.

  • The XSL file must be a local one. No URL values are accepted.

You have specified a remote path to an XSL file. XSL files cannot be remote. Please copy the file to your testing server, then change its path in the XSL Transformation server behavior, and try again.

  • Only the http and https protocols are supported for the XML file.

You have specified a different web service for accessing a remote XML file, such as FTP or NNTP. You can only specify a remote path (URL) that uses HTTP (http://) or HTTPS (https://) services.

Run-time errors

  • XML source cannot be empty.

You have not specified an XML file to be transformed. Please edit the XSL Transformation server behavior to select an XML file or edit the generated code to add one.

  • XSL source cannot be empty.

You have not specified an XSL file to perform the transformation. Please edit the XSL Transformation server behavior to select an XSL file or edit the generated code to add one.

  • Error opening [URL].

You have specified a remote XML file that cannot be accessed by the XSL Transformation server behavior. Please make sure the entered URL is correct and it points to a valid remote XML file.

  • [filename] is not a valid XML document.

The XML file you have specified does not contain standard XML content. Please refer to the World Wide Web Consortium Recommendation on the Extensible Markup Language for more information on XML.

  • [filename] is not a valid XSL document.

The XSL file you have specified does not contain standard XSL content. Please refer to the WC3 Extensible Stylesheet Language Family for more information on XSL.

  • Transformation error.

The XSL Transformation could not be performed with the specified files and parameters. Please check that you have correctly defined the XSL parameters.

Server-specific errors

For ColdFusion developers

  • The specified file [filename] could not be found.

You have entered an XML or XSL file that does not exist on the server. Please make sure you upload the file to your testing server, and that its name and path are correctly specified in the XSL Transformation server behavior interface.

For PHP developers

  • The specified file [filename] could not be found.

You have entered an XML or XSL file that does not exist on the server. Please make sure you upload the file to your testing server, and that its name and path are correctly specified in the XSL Transformation server behavior interface.

  • Could not find a valid XSL processor.

The server you are testing on is not one of the supported platforms or does not have one of the required XML/XSL libraries installed.

  • Error opening [URL]. Possible causes are incorrect URL or lack of support for OpenSSL.

You have either specified a wrong URL path in the XML URI field, or you are trying to access the XML file using the secure HTTP service (https://), which is not supported by your current server configuration. In the later case, you may need to install or enable the OpenSSL library for the Secure Sockets Layer protocol. Read more about OpenSSL.

  • Error opening [URL]. HTTPS protocol is supported starting from PHP 4.3.0.

You are trying to access a remote XML file using the HTTPS service, which is not supported by your current server configuration. Please make sure your server is one of the supported platforms.

  • The specified file [filename] is not readable.

You have specified an XML or an XSL file that does not have read permissions. You need to grant reading rights for the file or contact your server administrator.

For ASP developers

  • Required object from Microsoft XML Core Services (MSXML) is not installed. Download and install the latest version from http://msdn.microsoft.com/xml before continuing.

You have attempted to perform an XSL Transformation on a server that does not have the required XML/XSL libraries installed or enabled. Make sure your server configuration meets the specified requirements.

  • [path] is not a valid path.

You have entered an invalid URI for the XML file. Please make sure the path is correct.

  • An error occurred while loading XSL document [filename].

You are trying to use an XSL file that is currently inaccessible. Please verify if the file exists and the path is correct.

  • An error occurred while loading XML document [filename].

You are trying to use an XML file that is currently inaccessible (e.g.: an Internet connection cannot be established to the remote XML or the file is locked by some process). Please verify if the file exists and the path is correct.

  • Error while transforming [filename].
The XSL Transformation could not be performed with the specified files and parameters. Please check that you have correctly defined the XSL parameters and that the XML and XSL files have a correct syntax.

International error messages

You can easily translate the error messages in any language you want, in order to match the current regional settings of your site. All you have to do is:

  1. Find the MM_XMLXSL_strings.xml file in your current Dreamweaver Configuration folder (usually located in C:\Documents and Settings\username\Application Data\Macromedia\Dreamweaver MX 2004\Configuration\Strings\).

  2. Open it using a code or text editor and translate the messages.

  3. Save the file and close it.

Note: You must re-open Dreamweaver after you change the MM_XMLXSL_strings.xml file, for the changes to take effect. Make sure you edit only the error message and not the variable names.

Related topics:

Requirements and Supported Platforms


Generated Code

The Generated Code

The XSL Transformation server behavior uses the MM_XSLTransform runtime library to generate object-oriented code. Error handling and the application logic are encapsulated in this extensible library. The library is responsible for fetching the XML and XSL files, performing the transformation and outputting the result in the page.
This section contains samples of code generated on each server model by the XSL Transformation server behavior.

  • Generated Code for ColdFusion Developers

  • Generated Code for ASP Developers

  • Generated Code for ASP.NET Developers

  • Generated Code for PHP Developers


Generated Code for ColdFusion Developers

Generated Code for ColdFusion

The code generated on ColdFusion is similar to this one:

<cfinvoke component="apis.includes.MM_XSLTransform.MM_XSLTransform" method="transform" returnvariable="output">

<cfinvokeargument name="xml" value="news.xml">

<cfinvokeargument name="xsl" value="news.xsl">

<cfinvokeargument name="pageNo" value="#URL.pageNo#">

<cfinvokeargument name="elementsPerPage" value="5">

</cfinvoke>

<cfoutput>

#MM_output#

</cfoutput>


Generated Code for ASP Developers

The code generated on ASP VBScript is similar to the following:

<!--#include file="includes/MM_XSLTransform/MM_XSLTransform.class.asp" -->

<body>

<%

Dim mm_xsl1_param1: mm_xsl1_param1 = "1"

IF Request.QueryString("pageNo") <> "" Then

mm_xsl1_param1 = request.QueryString("pageNo")

End If

%>

<%

Dim mm_xsl1: Set mm_xsl1 = new MM_XSLTransform

mm_xsl1.setXML "news.xml"

mm_xsl1.setXSL "news.xsl"

mm_xsl1.addParameter "pageNo", mm_xsl1_param1

mm_xsl1.addParameter "elementsPerPage", "5"

Response.write mm_xsl1.Transform()

%>

</body>

The code generated on ASP JavaScript is similar to the following:

<!--#include file="includes/MM_XSLTransform/MM_XSLTransform.class.asp" -->

<body>

<%

var mm_xsl1_param1 = "1";

if (String(Request.QueryString("pageNo")) != "undefined" &&

String(Request.QueryString("pageNo")) != "") {

mm_xsl1_param1 = String(Request.QueryString("pageNo"));

}

%>

<%

var mm_xsl1 = new MM_XSLTransform();

mm_xsl1.setXML("news.xml");

mm_xsl1.setXSL("news.xsl");

mm_xsl1.addParameter("pageNo", mm_xsl1_param1);

mm_xsl1.addParameter("elementsPerPage", "5");

Response.write (mm_xsl1.Transform());

%>

</body>


Generated Code for ASP.NET Developers

The code generated on ASP.NET C# is similar to the following:

<%@ Assembly Src="includes/MM_XSLTransform/MM_XSLTransform.cs"%>

<body>

<%

string mm_xsl1_param1 = "1";

if (Request.QueryString["pageNo"]!=null && Request.QueryString["pageNo"].ToString().Length > 0) {

mm_xsl1_param1 = Request.QueryString["pageNo"];

}

%>

<%

MM.XSLTransform mm_xsl1 = new MM.XSLTransform();

mm_xsl1.setXML(Server.MapPath("news.xml"));

mm_xsl1.setXSL(Server.MapPath("news.xsl"));

mm_xsl1.addParameter("pageNo", mm_xsl1_param1);

mm_xsl1.addParameter("elementsPerPage", "5");

Response.Write(mm_xsl1.Transform());

%>

</body>

The code generated on ASP.NET VB is similar to the following:

<%@ Assembly Src="includes/MM_XSLTransform/MM_XSLTransform.vb" %>

<body>

<%

Dim mm_xsl1_param1 As String = "1"

If Request.QueryString("pageNo") <> "" Then

mm_xsl1_param1 = Request.QueryString("pageNo")

End If

%>

<%

Dim mm_xsl1 As MM.XSLTransform = new MM.XSLTransform()

mm_xsl1.setXML(Server.MapPath("news.xml"))

mm_xsl1.setXSL(Server.MapPath("news.xsl"))

mm_xsl1.addParameter("pageNo", mm_xsl1_param1)

mm_xsl1.addParameter("elementsPerPage", "5")

Response.write(mm_xsl1.Transform())

%>

</body>


Generated Code for PHP Developers

The code generated on PHP_MySQL is similar to this one:

<? require('includes/MM_XSLTransform/MM_XSLTransform.class.php'); ?>

<body>

<?php

$mm_xsl1_param1 = "1";

if (isset($_GET['pageNo'])) {

$mm_xsl1_param1 = (get_magic_quotes_gpc()) ? $_GET['pageNo'] : addslashes($_GET['pageNo']);

}

?>

<?php

$mm_xsl1 = new MM_XSLTransform();

$mm_xsl1->setXML("news.xml");

$mm_xsl1->setXSL("news.xsl");

$mm_xsl1->addParameter("pageNo", $mm_xsl1_param1);

$mm_xsl1->addParameter("elementsPerPage", "5");

echo $mm_xsl1->Transform();

?>

</body>

Previous