Section 24.4. Inserting and Formatting XML

24.4. Inserting and Formatting XML

Now you know the basics of creating and using XSLT style sheets. But how do you actually add and format XML data? Dreamweaver makes this process easy, and if you've used the program's database tools, you already know how to do it: just use the Bindings panel. Once you create an XSL file and attach the XML file to it, Dreamweaver reads all of the tags in the XML file and adds them to the Bindings panel (see Figure 24-4).

Figure 24-4. When using Dreamweaver's XSLT tools, the Bindings panel lists all of the tags and properties in the XML file you're formatting. Dreamweaver includes a few visual clues about the XML file: <> represents an XML tag and is the most common icon you'll encounter; the @ icon represents a tag property (also called an attribute; for example, in the tag <item id="154">,"id" is an attribute); and next to some tags, you'll see a small + sign (circled in this image) or a ? symbol. The + indicates that the tag is repeated multiple times; in the National Exasperator XML file on Section 24.1.1, for example, the "entry" tag is repeated multiple times (once for each news headline in the file). The ? symbol (not shown here) means the tag is optional, and it appears next to tags inside of other repeated tags (the one with the + symbol).

You can drag any element in the Bindings panel into your XSLT style sheet page, just as you'd drag information from a database recordset. That means you can place XML information in a table cell , in a footer, in a bannerin short, anywhere you can place regular HTML elements on a page.

You should keep a couple things in mind when inserting XML by using this dragging method:

Only the contents of the XML tags and properties are inserted, not the tags or property names themselves . For example, in Figure 24-4, dragging the <title> tag that appears inside the <channel> tag onto a document just prints the text inside this tag, not the tag itself. This is a good thing: you don't usually want to include the tags<title>An Important Story</title>. Instead, you just want the text: An Important Story.
Dragging a tag that includes other tags often results in a hard-to-read mess. That's because Dreamweaver includes text from each of the nested tags, as well. For example, Figure 24-5 shows what happens when the root element"rss"is dragged from the Bindings panel pictured in Figure 24-4. Text from all of the other tagsthe channel, the title, the description, and so on, as well as each of the repeated "item" tagsis included as one long paragraph. Dreamweaver treats this as a single big blob. To get around this, drag tags that don't include other nested tags. (Nested tags are called child tags.) For example, in Figure 24-4, the title tag that appears directly inside the channel tag doesn't have any tags inside it. Likewise, a repeating tagitem, for exampleincludes tags that don't have any children: "title," "link," "description," "pubDate." These are all good candidates for adding to a document.

Figure 24-5. If you use an XML tag that's too high up on the food chainthat is, other tags are nested inside of ityou can end up with a large chunk of hard-to-read text.

You can also insert XML into a Web page by choosing Insert XSLT Objects Dynamic Text or by clicking the Dynamic Text button on the XSLT panel of the Insert bar (see Figure 24-6). Either method opens the XPath Expression Builder window (Figure 24-7). An XPath Expression is just a way of identifying a particular elementcalled a nodeinside an XML file (see Section 24.1.2).

To add the dynamic text, select the XML tag or property you wish to insert. In the Expression box in the bottom half of the window, you'll see the XPath code required to locate your selection. For example, in Figure 24-7, the expression is rss/channel/description . This is shorthand for: Find the "description" tag, which is inside the "channel" tag, which is located inside the "rss" tag. In other words, this expression lists the order in which the tags are nested (in this sense, it's very much like the document window's tag selector [see Section 1.2.1]).

Figure 24-6. Dreamweaver's XSLT tab includes five buttons for adding XSLT objects. The comment object just inserts an XSL commentlike an HTML comment (see Section 9.2.1)so you probably won't use it much, if ever.

Figure 24-7. Use the Format drop-down menu to apply a format to the XML data. Unfortunately, the formats are aimed almost entirely at formatting numbersadding a $ sign to currency data, for exampleso they won't do anything for text-only XML data.

Dreamweaver also lets you apply some formatting options to the selected text using the Format menu. Almost all of the options have to do with formatting numbers, so if you're inserting text that's actually a numeric value, these formatting controls can come in handy. For example, say you add a tag that's used to indicate a price<price>3.25</price>. Selecting any of the currency options will add a $ sign in front of the number when it's displayed on the page. If you're dealing with big sums of money<price id="Trump Tower">34589585</price>then the "Currency group to 3 digits, 2 decimal places" is a good option. Then, the output would be something like this: $34,589,585.00. Again, all but two of the options are for formatting numbers , and the two that help format text aren't very useful.

After selecting a tag and setting a formatting option (if desired), click OK to insert the dynamic text. Dreamweaver adds a placeholder to the page: it has a blue background and displays the XPath expression inside of curly brackets (for example, {rss/channel/title}).

Tip: You can summon the XPath Expression Builder window again by double-clicking any dynamic XML text placeholder on the page.

Click an XML text placeholder to select it. You can then apply a CSS style to it, format it as a header or paragraph, or drag it to another spot on the page, just as you would any other HTML element.

24.4.1. Inserting a Repeat Region

XML files frequently contain the same tag repeated multiple times. For example, an XML file that's a list of employees might use the tag <employee> to begin each employee listing. For every employee in the company, the <employee> tag will appear once. The XML might look something like this:

 <companyInfo> <company> <name>Big Co.</name> <phone>555-3333</phone> </company> <employeeList> <employee id="485734"> <name>Mark</name> <phone>555-3333 x405</phone> </employee> <employee id="38753"> <name>Jane</name> <phone>555-3333 x406</phone> </employee> </employeeList> </companyInfo>

If you added the <name> tag inside the first <employee> tag to an XSLT style sheet, attached that XSL file to a dynamic page, and then previewed it in a Web browser, you would see just a single name: the first employee name in the XML file. But just as with recordsets, you'll usually want to display multiple XML records. The answer is Dreamweaver 8's XSLT Repeat Region object. To use it:

Insert elements that appear within a tag that is repeated multiple times. (Use any of the methods described on Section 24.4.)

The Bindings panel lets you know if an XML tag is repeated multiple times: check for a + sign to the right of the <> icon in the panel (see Figure 24-4).

So, in the above employee-list example, you wouldn't insert the <name> tag that appears inside the <company> tag, since <company> appears only once in the file. You would, however, insert the <name> tag and perhaps the <phone> tag inside the <employee> tag, since these are both "children" of a tag that's repeated twice in the document.

Note: This example points out a sometimes confusing aspect of XML: tags with the same name may appear as children within different kinds of tags. The <name> tag, for instance, appears both within the <company> and <employee> tags, but obviously refers to two different thingsthe name of a business and the name of a person.

Articles in a Web feed are another case. For example, the RSS standard (see Section 24.1) requires that each news item delivered in an RSS XML document be surrounded by an <item> tag with the following children: <title>, <link>, and <description>. Therefore, for an RSS feed, the elements you'd want to add to the page (and repeat once for each news item) would be <title>, <link>, and <description>.
Select (by dragging, for example) the XML placeholders and any other content that you want to be repeated once for each instance in the XML file .

This would at least include the XML placeholders you inserted in step 1, but may also include other HTML elements, such as a graphic that's repeated once for each item, or a <div> tag that contains the XML data you're repeating. You can select only elements that are together: you can't, for instance, select an XML element at the top of the page and another at the bottom of the page, and use the same Repeat Region object.

Tip: You can, however, include multiple repeat regions on a page, so you could repeat the same XML data in several locations on a page, by adding multiple Repeat Region objects.
Choose Insert XML Objects Repeat Region, or click the Repeat Region button on the XSLT tab (see Figure 24-6) .

The XPath Expression Builder window appears (see Figure 24-8). This is a similar window to the one that appears when you insert dynamic text (Figure 24-7). However, instead of a format menu, the window includes a "Build Filter" option.
Select the repeating tag .

This tag will always have a + to the right of its <> icon and is usually the parent tag of the tags you inserted in step 1. So, in the employee list example above, you would select the <employee> tag; in the case of an RSS feed, it would be the <item> tag.
Build a filter to limit the information retrieved from the XML file .

An XSLT filter works similarly to filters on recordsets (see Section 21.1.3). It's a way to select only certain information from the XML file. For example, you might want to select only employees whose last name is Smith, or product tags that have only an <instock> XML tag containing the word "true." Filters are discussed on Section 24.4.1.1.
Click OK to insert the repeat region .

Dreamweaver adds a gray border around the repeating elements and adds a gray tab labeled "xsl: for-each." (If you don't see these, make sure invisible elements are turned on: View Visual Aids Invisible Elements or using the Visual Aids menu on the document window (see Figure 6-24 on Section 6.7.4.1).

You can see the effect by pressing F12 (Option-F12): Dreamweaver translates all of that XSLT gobbledy-gook into a temporary HTML file. But to see the final presentation, you need to attach the XSLT style sheet to a dynamic page (steps 811 on Section 24.3) or XML file (steps 12 on Section 24.2), and preview it in a browser.

If you want to edit the repeat region, click the gray tab to select it and, in the Property inspector, click the lightning-bolt icon to open the Repeat Region window again (Figure 24-8).

Figure 24-8. Display repeating XML data using the XPath Expression Builder for repeat regions.

To remove a repeat region, right-click (Control-click) on the gray "xsl: for-each" tab, and select "Remove Tag: <xsl:for-each>." You can also click anywhere inside the repeat region, right-click (Control-click) on "xsl: for-each" in the tag selector (see Section 1.2.1), and then choose Remove Tag. Don't try to remove the tag by hand in Code view: The code used to specify the tags inside the region also must be changed; Dreamweaver does this automatically and accurately.

24.4.1.1. Building a repeat-region filter

If the XML file you're using has lots and lots of repeating items, or you just want to home in on a single item, you can build an XSLT filter that lets you search and select XML elements that match certain criteria. For example, you might want to display only employee tags with a "department" property whose value is "marketing." Dreamweaver 8 lets you create very complex filters. In a nutshell , to filter a repeat region:

Follow steps 14 on Section 24.4.1 to insert a repeat region .
In the XPath Expression Builder (Repeat Region) window, click Build Filter to display the filter tools (see Figure 24-9), and then click the + button to add a filter .

You build a filter by first selecting a tag that contains the information you wish to compare to a certain value.

Figure 24-9. Limit the XML data displayed by creating a filter that includes only XML tags that match certain criteria. Here's an example using the "employee list" XML code on Section 24.4.1.
Click in the Filter By column and, from the pop-up menu, select a tag .

This menu lists the repeating tag, its parent tag, its parent's parent tag, and so on, up the food chain, until it reaches the top (root) element. You'll just leave it as the repeating tag you selected in step 4 on Section 24.4.1 (finish reading these steps and then read the following note to understand why this is the case).

Note: Note (hold onto your thinking caps) : A filter lets you select criteria that each repeated region is tested against. If it passes the test, the XML data is displayed. For example, the "id" property of the <employee> tag will vary with each employee listing. In a repeated region, the only elements that change are either a property of the tag that's repeated or the contents of other tags inside the repeated tag. That's why you should always select the repeated tag from the "Filter By" menu; the parent (and grandparent, and so on) of the repeated tag doesn't change with each region that repeats. If the parent has a property named "version," that property value will be the same whenever the filter is applied to a repeat region. In other words, the filter will either always be true or never be true, and you'll either get all of the XML data or none of the XML data from the repeated tags. Dreamweaver 8 includes a more flexible tool for displaying or hiding information based on some "test" or condition: conditional regions (see Section 24.4.2).
Click in the Where column, and select an option from the pop-up menu .

This menu will list any properties of the repeated tag, and all the repeated tag's child tags. In the employee-list code (Section 24.4.1), for example, each <employee> tag has a property named "id" and children tags called <name> and <phone>. So in this case, those options would be listed in the "Where" menu. Tag properties begin with a @ symbol, so in this example, the "id" property would be listed as "@id" in the menu (see Figure 24-9).

To continue with the employee-list example, if you wanted to display only employees whose employee id number was less than a certain number (perhaps to list the company's first 200 employees), you'd choose "@id" from the menu.

Note: Note to Power Users : If you're up on your XPath expressions (and who isn't?), you can actually click in the Where column and type your own path to identify tags and properties located deeper in the tag structure.
Select a comparison method from the Operator menu .

Your options are = (equal to), != (not equal to), < (less than), <= (less than or equal to), > (greater than), and >= (greater than or equal to). If the property or tag you selected in step 4 contains a number, you can use any of these comparison operators (as they're called). So if you wanted to find employees whose id number was less than 200, you'd select <.

For properties and tags that contain text (<department>marketing</department>, for example) stick to either the = or != options. That way, a repeat region would show only employees who are either in the "marketing" department (use the = sign) or not in it (use the != operator).
Type a comparison value in the value box .

The value is what you're testing against. For example, if you're looking for employee IDs that are less than 200, type 200 ; for <department> tags that contain the word "marketing" type marketing .
If you want to add more filters, select either "and" or "or" from the "and/or" menu, click the + button to add another filter, and then repeat steps 47 .

This lets you add additional conditions that must be met in order to select XML data to include in the repeat region. For example, maybe you want to display employees who are both in the marketing department and are one of the first 200 employees. In this case, select the "and" option and add another filter. Or, you may want to display a list of employees who are either in the marketing department or the finance department: Select "or" and add a filter where the <department> tag is equal to "finance" as well.

The ability to add multiple filters lets you build up complex filters that either let you continually narrow the number of regions that are repeated (by adding more and more and options) or that include more and more data from the XML file (by using additional or filters).
After adding one or more filters, click the Close button to create a filtered repeat region .

Dreamweaver inserts the repeat region into the XSLT style sheet. You can edit or remove this region as described on Section 24.4.1.1.

24.4.2. Inserting a Conditional Region

At times, you may want to display a part of a page only if certain conditions are met. The "Filter" feature of the Repeat Region tool (see Section 24.4.1) offers some help, since it can display select XML data when a tag's property or contents pass a particular test: an id property that's less than 200, for example. But there are other occasions when the filter doesn't help. For example, say you want to display only the last item in a repeat region; there's no tag or property containing this information, so a filter won't work.

Note: If you use Dreamweaver templates, this problem may sound familiar. It's the same concept as a template optional region (see Section 17.4).

Or maybe you want to display a graphic or another part of a page only when a certain XML property appears. For example, perhaps an XML document listing products has a tag like this: <product stock="in">. The "stock" property serves to indicate whether a product's available (in which case, it's value is "in") or when it's not ("out"). In such cases, you could use a conditional region to display an "out of stock" button next to each product that's not available.

To use a conditional region:

Select the part of the pageeither the XSLT file, or XSLT fragmentyou want to display if a condition is true .

A simple example is an "out of stock" or "on sale" graphic. But you could also select XML data placeholders: maybe you want to display just the first five items inside a repeat region. In this case, select all the XML placeholders inside the repeat region (you need to add the repeat region first).

Note: Many Web designers find it useful to place conditional regions inside of repeat regions, since this lets them fine-tune the display of information on a per-item basis. For example, in a repeating list of products, showing an "on sale" graphic for only those products that are actually on sale.
Choose Insert XSLT Objects Conditional Region or click the Conditional Region button in the XSLT tab (see Figure 24-6) .

The Conditional Region window opens (see Figure 24-10).

Figure 24-10. The Conditional Region window lets you show or hide content on your page based upon certain conditions in the XML or XSL files.
Type a test condition in the Test box .

Duh! "But what am I supposed to type?" you're asking. This is the tricky part, since Dreamweaver doesn't really give you much help. Your test condition can actually be a number of different things, many of which can be quite complex. Here are a few examples:
- An XPath expression followed by some kind of comparison . For example, say you're working with the XML document on Section 24.4.1. You've created a repeat region listing all of your company's employees, and you want an "employee of the month" graphic to appear in the listing, but only next to the employee whose ID is, say, 38753. To make that happen, the condition you'd type would be @id=38753 . @id refers to the "id" property (@ is used before a property name) of the repeated tag (<employee>, in this example.) Likewise, if you wanted to highlight all employees whose name is Jane (that is, the text inside the <name> tag is 'Jane'), the condition would be name='Jane' . (Note that whenever you're testing whether a tag has text inside itas opposed to just numbersyou must place quotes around the word, like this: 'Jane'.)
- The position of an item in a repeated region . When applying conditions to content that comes from a repeat region, you can access an item's position using position( ). So, for example, if you wanted to have the selected page elements inside a repeat region appear only when the first item is displayed, you could type position()=first() ; for the last item, the condition would be position()=last() . And if you wanted to limit the repeat region to just 5 items (for example, if you want to show only the first 5 headlines from a news feed), you could use this expression: position() <=5.
- An XPath expression to determine if a tag or property exists . You can also just enter an XPath expression for a particular node (Section 24.1.2) in the document. If the node exists, then the selected element is displayed; otherwise , it's hidden. For example, say you have a repeat region that contains some optional tags. Again, using the employee list example, imagine if some employees had their own offices. For those employees, you might add an XML tag called <office> that includes the office number, like so: <office> Room 222</office>. You'd like to include the text "Office:" followed by the actual office number in your final Web page. However, if someone doesn't have an office (meaning that her entry in the XML file has no <office> tag), you don't want the word "Office:" to appear. To make that happen with a conditional region, type " Office :" somewhere inside the repeat region (perhaps on a line below the employee phone number); next, drag the <office> tag from the Bindings panel to the page, and then select both the text and the XML placeholder. Finally, add a conditional region as described on Section 24.4.2, and simply type office as the condition. Now "Office:" and the office number will appear only for <employee> tags that have an <office> tag inside them.
- Tag or property values that begin with one or more particular characters . Say you want to display only those employees whose names begin with 'M.' You can do this easily with the starts-with () function. In the Conditional Region box, you would type starts-with(name, 'M') . Translated from XSLT-speak, this means any <name> tag whose contents start with the letter M will appear on the final Web page; so <name>Mark</name> and <name> Mary</name> would match, but <name>Andrea</name> wouldn't.
Click OK to insert the conditional region .

Dreamweaver adds a gray border around the page elements you selected in step 1 and adds a gray tab labeled "xsl:if" to indicate the conditional region. (If you don't see these, make sure invisible elements are turned on by choosing View Visual Aids Invisible Elements or by using the Visual Aids menu on the document window (see Section 6.7.4.1).

You can still edit the page elements inside the conditional region's gray border: you can edit, add, or remove text, images, and XML placeholders.

If you want to edit the conditional test, click the gray "xsl:if" tab to select the conditional region, and change the test listed in the Property inspector.

To remove a conditional region, right-click (Control-click) the gray "xsl:if" tab, and then select "Remove Tag <xsl:if>." You can also click anywhere inside the conditional region, right-click "xsl:if" in the tag selector (see Section 1.2.1), and then choose "Remove Tag."

24.4.3. Using Multiple Conditional Regions

A conditional region is pretty straightforward: it either shows or hides part of the page based on the results of a simple test. But what if you wanted to display one thing if the condition is true, but show different stuff if the condition is false. For example, say you had two graphics called "In Stock" and "Out of Stock" that need to appear next to each product name in a repeat region. You could use two conditional regions: the first to display the "In Stock" image if the product tag's stock property was set to "in" (<product stock="in">) and another for out-of-stock products (<product stock="out").

Note: If you've ever done any computer programming, you'll recognize the upcoming maneuver as a variation on the venerable "if-then-else" statement.

But using conditional regions in that way requires far too much work on your part. Fortunately, Dreamweaver's Multiple Conditional Region tool makes it easy to deal with these "either/or" situations. Here's how to use it:

Select the part of the page you want to display if a condition is true .

For instance, this might be a graphical button with the text "In Stock" printed across it. This step is the same as a conditional region described on Section 24.4.2. In fact, most of the steps are the same.
Choose Insert XSLT Objects Multiple Conditional Region or click the Multiple Conditional Region button in the XSLT tab (see Figure 24-6) .

The Multiple Conditional Region window opens. Except for its title, the window's identical to the Conditional Region window (see Figure 24-10.)
Type a test condition in the Test box .

For example, @stock="in" would cause the region to display if the value of the repeating tag's stock property was "in." For more examples, see Section 24.4.2.
Click OK .

Dreamweaver inserts three different sections of XSL code, each marked with their own gray tab: XSL:choose, XSL:when, and XSL:otherwise. The XSL:when section contains the actual condition or test you set in step 3.

The XSL:otherwise section is the part of the page that will display if the test isn't true. Dreamweaver adds "Contents goes here" to that area.
Select and delete "Contents goes here" and then add the page elements you wish to display if the test from step 3 isn't true .

This would be the alternative to the content selected in step 1for example, an "Out of Stock" icon.

You can edit the contents of either the XSL:when or XSL:otherwise sections. To edit the test, either click the gray XSL:when tab or click anywhere inside the XSL: when section and use the tag selector (see Section 1.2.1) to select the <xsl:when> tag. The Property inspector displays the test condition: edit it, and press Enter or Return.

Removing a multiple conditional region is a bit trickier. You can't just right-click (Control-click) the gray "xsl:choose" tab and then select "Remove Tag <xsl: choose>" to remove all of the multiple conditional region code. You must remove each of the three sections separately. To do so, follow the same process as required when removing a conditional tag, as described on Section 24.4.3.