XslGenerator

Class	XslGenerator
Namespace	Avectra.netForum.eWeb.controls.XslGenerator
Developer	Avectra

Note: This is about the eWeb version of XslGenerator. For the iWeb version see XslGenerator (iWeb)

netFORUM CMS supports the use of web services with a specialized .NET user control (ASCX) called XslGenerator.ascx. Combined with a Extensible Stylesheet Language (XSL) stylesheet, a netFORUM eWeb Page Detail can consume a web service and transform the XML response through XSL to output well formatted HTML on the web page. A web developer can leverage the power of web services through the CMS Toolkit without writing any programming code.

XSL is a language similar to CSS (Cascading Style Sheet) that formats a raw XML document into a user-friendly HTML page.

Additionally, the XslGenerator control can leverage netFORUM’s native DynamicXmlBuilder to create multidimensional XML documents with netFORUM data and transform that XML into readable HTML through an XSL stylesheet. Check below for Samples.

Features

The XslGenerator is similar to the List SQL content type. It can be used to pull data from netFORUM or from a web service and then output that data on a page through a Page Detail or a Default pane.

Although the List SQL content type can be simpler to use, the XslGenerator offers more power and flexibility in the follwing ways:

• XslGenerator can display parent and child (and infinite grandchild) hierarchical data. FOr example, you might want to output a series of events, nesting sessions under each event, and nesting speakers under each session. Doing this with a List SQL is essentially impossible. The XslGenerator makes this easy.

• XslGenerator can consume public web services (such as RSS feeds) that do not require authentication and output the results on a page.

• XslGenerator allows you to work with Extensible Stylesheet Language which is much more powerful than the HTML that you can type into the content area of a List SQL.

Usage and Examples

To use the XslGenerator in eWeb, follow the next four steps, explained in detail below.

1. First you will add a web Page Detail.
2. Second, you will set the source of the Xml data using one of four options.
3. Third, you will define the Xsl that will render the Xml data you set in Step 2.
4. Fourth, optionally, you may define additional Xslt Arguments.

The rest of this page outlines more advanced scenarios and features, and lists various samples and case studies.

Step 1 - Page Detail Configuration

Add a website page detail to a website page. Choose Control (ASCX) for the content type and enter ~/controls/XslGenerator.ascx in the control/file field.

Next, in the design text area, you will enter certain metatags to direct the control to the source of the XML data and XSL stylesheet. There are four options for XML data source and two options for XSL data source.

Step 2 - Configuring the XML Data Source

The source of the XML data may come from one of four sources, each of which is outlined below:

• a web service or a response from a HTTP Post result, or an XML file accessible from a public URL
• a physical XML file accessible from the web server
• The results of a netFORUM DynamicXmlBuilder
• The results of a Dynamic Xml Builder definition in the page detail.

Option a. Web Service

If the XML data source is to come from the result of calling a web service or performing a web request (such as getting a response from an HTTP Post) then use this option. Enclose the URL address of the web service between the {BeginPostUrl} and {EndPostUrl} metatags. If there are any querystring parameters then enclose them between {BeginPostData} and {EndPostData} metatags as shown here:

{BeginPostUrl}http://weather.yahooapis.com/forecastrss{EndPostUrl}
{BeginPostData}p=94089{EndPostData}

Technically, you may append a question mark (?) and the value in {BeginPostData} to the {BeginPostUrl}. The two sets of metatags are created for the benefit of structural clarity. Here is a combined version, which will produce the same result as the split version:

{BeginPostUrl}http://weather.yahooapis.com/forecastrss?p=94089{EndPostUrl}

Both the PostUrl and PostData metatag pairs may include parsed values from the querystring, Façade Objects, or search results from a page detail using the Find.ascx control. (See eWeb Find for a case study on this.)

If there are no querystring values, then the PostData metatags may be omitted.

If you have an external xml file on another server, but it is accessible over HTTP via a public URL, then this method will work, even if the URL is not really a true "web service" but is simply the location of an XML document. For example, if you are using XslGenerator to develop navigational menus in eWeb, and the menu metadata is in a XML file accessible over HTTP, then you could do this:

{BeginPostUrl}http://dev.zzz.org/templates/includes/navigation.xml{EndPostUrl}

Option b. Static XML File Option

You may point the data source to an XML file on the web server by enclosing the file name between {BeginXmlFileName} and {EndXmlFileName} metatags as shown here:

{BeginXmlFileName}Temp/xml/eventXml.xml{EndXmlFileName}

This file location example above assumes the following folder structure on the web server, with a folder called xml under the Temp folder under the eweb folder.

Ensure that the IIS anonymous access user can access this folder.

Choose this option if you have a collection of static XML files that you want to output. For example, you might receive a weekly batch of XML files from an external source and you need to output them in eWeb.

If the static XML file is an external xml file on another server, but it is accessible over HTTP via a public URL, then use the #Option_a._Web_Service option described above. This option will work even if the URL is not really a true "web service" but is simply the location of an XML document. For example, if you are using XslGenerator to develop navigational menus in eWeb, and the menu metadata is in a XML file accessible over HTTP, then you could do this:

{BeginPostUrl}http://dev.zzz.org/templates/includes/navigation.xml{EndPostUrl}

Option c. DynamicXmlBuilder Option

You may generate the XML data source from the DynamicXmlBuilder feature in netFORUM. The DynamicXmlBuilder can create multi-dimensional XML documents (for example, Events and Sessions and Prices). An XSL stylesheet can then output the results and group child records under their parent. For example, you could group sessions under their parent event. See DynamicXmlBuilder for more information.

To use this option, you must include these tags as shown in this example:

{BeginXmlBuilderService}ABCWebService.ABCWebServiceLibrary{EndXmlBuilderService}
{BeginXmlBuilderMethod}EventCalendar{EndXmlBuilderMethod}
{BeginXmlBuilderParams}eventType={evt_code};EventTitle={evt_title}{EndXmlBuilderParams}

The {BeginXmlBuilderService} and {EndXmlBuilderService} metatags points to the web service definition; the {BeginXmlBuilderMethod} and {EndXmlBuilderMethod} metatags point to the web service method.

The {BeginXmlBuilderParams} and {EndXmlBuilderParams} metatags list the parameter name and value pairs, delimited by semicolons. The values may be either static or parsed values. The name and value pairs must be formatted in this syntax:

Param1name=Param1Value;Param2Name=Param2Value

The {XmlBuilderService} and {XmlBuilderMethod} metatags must match up with a Dynamic Xml Web Service and Method, respectively, and any parameters included in the {XmlBuilderParams} will be passed into the Dynamic Xml Builder.

Here, for example, is the Dynamic Xml Builder definition that aligns with the metatags above:

Note how the web service name matches with the {XmlBuilderService} tags and the web method matches with the {XmlBuilderMethod} metatag. Additionally, the node definition for Event will contain parsed value parameters that match with the {XmlBuilderParams}. Note the parameter for eventType in the WHERE clause of the node sql of the Event node:

It is not necessary to actually deploy an actual web service based on this web service method definition. The XslGenerator simply needs for the node definitions to be set up to construct the XML document.

Option d. DynamicXmlBuilder Node Definition in Page Detail

Important! The SQL commands on this page can be improved with SQL 2005's FOR XML PATH mode syntax. This feature is available in the 2007.01 build and later. Please see XWeb:ExecuteMethod_Case_Study1 for details on how to work with this new feature. These samples are still valid, but it is recommended that you use the newer syntax if your netFORUM site is on 2007.01 or later. Both DynamicXmlBuilder and XslGenerator work with this newer SQL syntax.

This option works almost the same as Option c., only instead of configuring the DynamicXmlBuilder nodes in the web service/method section in netFORUM, you may enter the nodes definition directly in the page detail. The entry in the page detail will be in the form of an XML document, with each main node having an XML element called sql which will contain the sql statement that would have been entered in the node sql of the DynamicXmlBuilder definition. This entry will be between the {BeginXmlBuilderXml} and {EndXmlBuilderXml} metatags as shown:

The illustration above is the definition of a XmlDocument that will take this shape:

                
                    <Members>
                
                
	<Member>
		<cst_key>8ffe1bb1-6b39-417b-ad08-167542419601</cst_key>
		<Name>ABAC solutions</Name>
		<Employees>
			<Employee>
				<Name>Mike Smith</Name>
				<Title>CEO</Title>
			</Employee>
			<Employee>
				<Name>Jeff Jones</Name>
				<Title>CFO</Title>
			</Employee>
		</Employees>
	</Member>
	<Member>
		<cst_key>8ffe1bb1-6b39-417b-ad08-167542419601</cst_key>
		<Name>Avectra</Name>
		<Employees>
			<Employee>
				<Name>Horace Smith</Name>
				<Title>Director</Title>
			</Employee>
		</Employees>
	</Member>
</Members>

In every other respect this option works essentially the same as option (c). It is not necessary to include the {XmlBuilderService} and {XmlBuilderMethod} metatags, but {XmlBuilderParams} metatags are supported if you need to pass parameters into the DynamicXmlBuilder.

Warning: In your SQL code, do not use the “<>” operator for “not equals” as it will cause XML parsing errors; instead use “!=” as shown below:

                {BeginXmlBuilderXml}<exhibitors>
  <exhibitor>
    <sql>
       SELECT DISTINCT exh_directory_name, exh_cst_key, exb_key
       FROM ex_exhibitor (nolock)
       JOIN ex_exhibitor_booth ON exh_key = hxb_exh_key 
         AND hxb_delete_flag != 1
       JOIN ac_invoice (nolock) ON hxb_inv_code = inv_code 
         AND inv_delete_flag != 1
       JOIN ex_show (nolock) ON exh_exb_key = exb_key
       WHERE 1=1 
       AND exb_evt_key = {evt_key}
       AND exh_cancel_date IS NULL
       AND exh_delete_flag != 1
       ORDER BY 1
    </sql>
  </exhibitor>
</exhibitors>
{EndXmlBuilderXml}
{BeginXmlBuilderParams}evt_key={evt_key}{EndXmlBuilderParams}

If desired, you may omit the node definition names in the {XmlBuilderXml} metatags if you have a single dimensional definition with only one SQL statement. This feature would not work in the first example above as we have a node for <Member> which has a sub-node of <Employees>. If the node definition names are omitted, then the XslGenerator will automatically name your nodes <root> and <detail>. For example:

                {BeginXmlBuilderXml}
  SELECT wps_title, wps_author, 
  convert(varchar(10), wps_post_date, 101) AS PostDate,
  wps_html_description 
  FROM md_web_posting (nolock)
  WHERE wps_key={wps_key}
{EndXmlBuilderXml}

For this XmlBuilderXml definition, the nodes will automatically be named <root> and <detail> as illustrated in this Xsl definition:

{BeginXsl}
<?xml  version="1.0"  encoding="ISO-8859-1"?>
<xsl:stylesheet  version="1.0"  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:output  method="html"  />
 
<xsl:template  match="/root">
  <xsl:apply-templates  select="detail"  />
</xsl:template>
 
<xsl:template  match="detail">
<TABLE  width="480"  border="0">
  <TBODY>
  <TR>
    <TD>
      <DIV  class="pageTitle"><xsl:value-of  select="wps_title"  /></DIV>
    </TD>
  </TR>
  <TR  class="bodyTXT">
    <TD>
      <div  class="tinyTXT"><xsl:value-of  select="PostDate"  /></div>
    </TD>
  </TR>
  <TR>
    <TD>
      <DIV  class="tinyTXT"><xsl:value-of  select="wps_author"  /></DIV>
    </TD>
  </TR>
  <TR>
    <TD>
       <DIV  class="bodyTXT"><xsl:value-of  select="wps_html_description"  disable-output-escaping="yes"/></DIV>
    </TD>
  </TR>
  </TBODY>
</TABLE>
</xsl:template>
</xsl:stylesheet>
{EndXsl}

The SQL statement also could have been coded this way and the page would operate in the exact same way:

                {BeginXmlBuilderXml}
  <root><detail><sql>
  SELECT wps_title, wps_author, 
  convert(varchar(10), wps_post_date, 101) AS PostDate,
  wps_html_description 
  FROM md_web_posting (nolock)
  WHERE wps_key={wps_key}
  </sql></detail></root>
{EndXmlBuilderXml}

Option (c) might be easier to work with in terms of visualizing the nodes, but option (d) can be convenient as all your code is in one place and it is easier to deploy between one site and another, as you will not need to deploy the web service/method metadata. You will only need to deploy the page detail.

In this image, we have names of people (in yellow) with each person’s designation(s) under the person. The corresponding SQL definitions are displayed on the right. The purple ovals depict how a parent node may pass its values down to its children node(s).

Step 3 - Configuring the XSL Source

The XSL definition may be typed directly into the web page detail definition or it may point to an XSL file on the web server.

Option a. XSL Definition in Page Detail

Enclose the XSL within {BeginXsl} and {EndXsl} metatags as shown:

{BeginPostUrl}http://www.wwltv.com/newskiosk/rss/localnews.xml{EndPostUrl}
{BeginCacheDurationMinutes}60{EndCacheDurationMinutes}
{BeginXsl}
<?xml  version="1.0"  encoding="UTF-8"  ?>
<xsl:stylesheet  version="1.0"  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
	<xsl:template  match="channel">
		<SPAN  class="FeedTitle">
			<DIV  class="bodyTXT">
				<B>FROM THE BIG EASY</B>
			</DIV>
		</SPAN>
		<DIV  class="box01"  style="width:260;padding:4px;">
			<span  class="tinyTXT">
				<xsl:value-of  select="pubDate"  />
			</span>
			<span  class="tinyTXT">
				<xsl:apply-templates  select="item"  />
			</span>
		</DIV>
	</xsl:template>
	<xsl:template  match="item">
		<DIV  style="line-height:16px;">
			<a  href="{link}">
				<xsl:value-of  select="title"  />
			</a>
		</DIV>
	</xsl:template>
</xsl:stylesheet>
{EndXsl}

Option b. Xsl Definition in File

To use an XSL file, enclose the file path and name within {BeginXslFileName} and {EndXslFileName} metatags as shown by this example:

{BeginXslFileName}style/xsl/abcde/chapter.xsl{EndXslFileName}

This file location in the example assumes the following folder structure on the web server, with a folder called abcde (where abcde is the client abbreviation) inside the xsl folder inside the style folder under the eweb folder. We recommend putting your files in a special directory with the client's abbreviation.

Ensure that the anonymous access user can access this folder.

Choosing between XSL definition in page detail or in File

Choose a file if you prefer to work that way, but only if you have easy file access to the web server. A file can also be preferable if you have multiple pages that use the same XSL stylesheet, so you can maintain this stylesheet in only one place (instead of having to make the same change in many page details).

Entering the XSL directly in the page detail can be more convenient for deploying pages, as you need worry only about the metadata for the pages and not about moving files from one site or server to another. Entering XSL in the page detail might also be preferable to maintaining and keeping track of many XSL files on the web server.

Step 4 – Adding Optional XSLT Style Sheet Parameters

If you wish to set XSLT Style Sheet Parameters to pass into your XSL stylesheet, you can do so by adding them between the {BeginXsltArguments}{EndXsltArguments} metatags.

First, in the content detail definition, pass in name/value pairs of parameters as shown below.

{BeginXsltArguments}recordsPerPage=5{EndXsltArguments}

If you have more than one set, then separate with a semicolon:

{BeginXsltArguments}recordsPerPage=5;chapterid={chp_code}{EndXsltArguments}

In the example above, you are passing in the value of {chp_code} into a XSLT parameter that you are calling chapterid. {chp_code} could be coming from a querystring parameter, for example.

You can use XSTL style sheet parameters to pass parsed values (such as {chp_code} in the example above) or other information into the XSL file.

Next, you need to initialize the XSLT parameter in your stylesheet with this line as a top level element near the top of the stylesheet:

                
                    <xsl:param  name="chapterid"  />
            

Then, wherever you want to output the parameter in your page, enter this:

                
                    <xsl:value-of  select="$chapterid"></xsl:value-of>
            

Here is an example of a complete XSL stylesheet that shows the XSLT parameter declaration and output on lines 3 and 9:

                

                    

                        

                            
                                <?xml  version="1.0"  encoding="ISO-8859-1"?>
                        
                    
                    

                        

                            
                                <xsl:stylesheet  version="1.0"  xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
                        
                    
                    

                        

                            
                                <xsl:param  name="chapterid"  />
                        
                    
                    

                        

                            
                                <xsl:param  name="pagerAlpha"  />
                        
                    
                    

                        

                            
                                <xsl:param  name="pagerResults"  />  
                    
                    

                        

                            
                                <xsl:output  method="html"  />
                        
                    
                    

                        
 
                    
                    

                        
  <xsl:template  match="/organizationresults">
                    
                    

                        
	<DIV  class="pageTitle">Chapter Information - <xsl:value-of  select="$chapterid"></xsl:value-of></DIV>
                    
                    

                        
	<xsl:apply-templates  select="organization"  />
                    
                    

                        
	<br>&#160;</br>
                    
                    

                        
    <DIV  class="tinyTXT"><xsl:value-of  select="$pagerResults"  disable-output-escaping="yes"></xsl:value-of></DIV>
                    
                    

                        
    <DIV  class="tinyTXT"><xsl:value-of  select="$pagerAlpha"  disable-output-escaping="yes"></xsl:value-of></DIV>
                    
                    

                        
  </xsl:template>
                    
                
            

Here's another sample that passes the value of a URL querystring parameter called sos_key into the XSL into a parameter called sosKey. Later, we list a number of records from an XML command (not shown) and want to highlight the "selected" record that matches the value of the URL querystring.

Here is the XSL Parameter initialization:

{BeginXsltArguments}sosKey={sos_key}{EndXsltArguments}

And the XSL declaration of the parameter in the 3rd line of the XSL stylesheet.:

                
                    <?xml  version="1.0"  encoding="UTF-8"    ?>
                
                
                    <xsl:stylesheet  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"  version="1.0">
                
                
                    <xsl:param  name="sosKey"  />
            

Here is a way you can test to see if the value of the parameter is equal to the value of a related field in the XML using xsl if. The assumption is that sos_key is contained in the SQL-XML result set, and $sosKey is the syntax to access the value of the XSL parameter:

                
                    <xsl:if  test="sos_key=$sosKey">Selected</xsl:if>
<xsl:if  test="sos_key!=$sosKey">Not Selected</xsl:if>

Sample XslGenerator Templates

If you have any good samples, please add them here with a link to a new page. To catalog these, name the page something like: XslGenerator:EventCalendar and for navigational ease please link back to this page. Contributors are encouraged to include a screen shot of the output, a description of the use case, and the text of the content detail as well as the text of the XSL if it is in a separate file. If the XML source is from a dynamic xml builder, it would be nice if you could copy-paste the SQL for reference. A good model to follow is XslGenerator:RegistrantList. Thanks.

• XslGenerator:RegistrantList - a list of registrants that can display in either list form or badge form, all using the same content detail, but with a dynamically selected XSL file name dependent on a URL querystring parameter. This was put into use on an Avectra website.
• XslGenerator:RSS1 - output a RSS feed.
• eWeb Find - Configure an eWeb Find.ascx page to drive results to an XslGenerator page that reads the search paramters from the find page and outputs the results. This is not as easy as a standard results page but it might be what you need in some advanced cases.
• XslGenerator:Exhibitor - This is a listing of Exhibitors with an Alpha Pager.
• XslGenerator:EventSessionSpeaker - Here is a template for an Event, displaying the Sessions and Tracks for a single event. Within each session, we output the speakers at that session.
• eWeb Search Results - a Toolkit Training exercise using XslGenerator and the Find.ascx control.
• XslGenerator:Event Calendar and Detail using FOR XML PATH - example of an EventCalendar and EventDetail using FOR XML PATH systax available in 2007.01 with SQL 2005.

Extensible Stylesheet Language Tips

See XSL language tips for various tips on using XSL in the XslGenerator.

XslGenerator Tips and Troubleshooting

Got any good troubleshooting tips? Please add them here. If this is a XSL tip, then post it in the Xsl Tip Page. If this section gets too long (we hope it does) then we may branch this out to its own page.

Detecting and Debugging XSL and XML Parsing Errors

Due to eWeb’s inclination to hide errors in the UI, detecting XML and XSL errors can be difficult. You must turn on debugging in your local environment by setting the debugMode property in /eweb/web.config to true as shown here:

                
                    <debugMode>
                true</debugMode>

Avoid doing this on a LIVE site as this setting may display a lot of errors you might not normally want to display. As an alternate, you can inspect the [fw_error_log] table to see your error:

                SELECT top 10 err_message, err_add_date 
FROM fw_error_log (nolock)
ORDER BY log_add_date DESC

Parsing Values

The XSL file is not parsed by netFORUM. Parsed values will not be evaluated in the XSL. XSL frequently uses curly braces, and running the value-parsing utility on the XSL would break in these scenarios. Therefore do not expect {cst_sort_name_dn} to parse in your XSL document! If you feel the need to do this, consider having other page details on the same form above the XlsGenerator page detail that parse and output these values. Or, pass in parsed vales with style sheet parameters.

Multiple XslGenerator Controls on the Same Page

At this time, there may be at most one XslGenerator control using pagers on a single page. If you have multiple XslGenerator lists, each with its own pager, then the page links cannot correctly figure out which page to go to and the pager will simply not operate correctly.

You may, however, have multiple XslGenerator controls on the same page as long as those sections do not use pagers, or if you use a pager on only one of the sections.

Viewing Raw XML

If you are trying to figure out what the raw XML looks like, then append the following to your browser’s URL querysting:

&showxml=yes

Resubmit your page and you will see the raw XML instead of the XML transformed through the XSL. This can be useful for troubleshooting a DynamicXmlBuilder or figuring out what (if anything) the web service is returning. Sometimes you are not really sure if the problem is with the XML data or your XSL, and looking at the raw XML might help you figure this out.

Unfortunately the result in your browser displays as a large block of HTML instead of cleanly structured XML. You can, however, easily view the XML in a browser by doing the following:

1. View the page source with right-mouse-click View Source or Edit View Source.
2. Looking at the HTML source, highlight everything between the beginning <?xml> tag and the closing element tag (whatever that might be) which will be near the bottom of the page.
3. With all the XML highlighted, copy this (Ctrl-C).
4. Open a new Notepad.
5. Paste (Ctrl-V) your clipboard into Notepad.
6. Save the Notepad file to your desktop with a XML file extension, such as test.xml.
7. Open the new file in a browser to view the raw XML. Open a new browser window first to prevent the file from opening in a browser window you are using.

To stop showing XML, backspace over the querystring parameter or make its value something other than yes.

&reg_evt_key turns into ®_evt_key

My workaround was to name the XSL parameter xref_evt_key and set the default value of the field to {xref_evt_key} on the receiving form.

This following method did not seem to work:

Change &reg_evt_key to &REg_evt_key and this will fool the parser into not turning it into the ® character that is used for registered trademarks. By making the letters "R" and "E" into uppercase, parsers will not try to change it the ® character. If you make all three "REG" letters uppercase, then it might transform it to the ® character.

HTML Adds Line Breaks and Tabs

Q. Do you know if there is a way to preserve the formatting of the XSL/HTML template? The application is reformatting the code in correctly tabbed output. Unfortunately, browsers recognize line breaks within certain tags as white space (gaps between images).

A. If you have an output method in your XSL file like this <xsl:output method="html" />, then try removing it and see if this solves the problem.

Turning Off Tags in Content Definition

If you want to switch a tag on and off, you can just type a "x" in front of tag such as {xBeginCacheDurationMintues}30{EndCacheDurationMinutes} and then turn it back on by removing the x. You can also type comments for your own reference in the content detail content area. The XslGenerator won't care:

Yahoo web service:
{BeginPostUrl}http://www.somewhere.com{EndPostUrl}...

Values are Not Getting Parsed

Q. I have some parameters like this:

{BeginXmlBuilderParams}CustomerKey={CustomerKey}{EndXmlBuilderParams}

but netFORUM does not properly parse CustomerKey; it is empty. Why is this not working?

A. Make sure that you have entered a Form in the Page Detail. Variables can only be parsed if you have a Form.

Q. I am trying to parse values within an Object on a page detail, but it's not parsing. Why?

A. If you are trying to parse a value contained on an Object on the page, you must include that value within the {BeginXmlBuilderParams}{EndXmlBuilderParams} metatags.

For example, suppose you have a page based on the Invoice object and you are trying to parse inv_cur_key in the WHERE clause of a SQL command. You must include it here:

{BeginXmlBuilderParams}inv_cur_key={inv_cur_key};CustomerKey={CustomerKey}{EndXmlBuilderParams}

Once you have included this in the {BeginXmlBuilderParams}{EndXmlBuilderParams} metatags, then it is available for parsing within your SQL command, for example:

                ...
                
                OR prc_cur_key=isnull({inv_cur_key},prc_cur_key)))
...

Note: it appears that system options will be parsed even if they are not included in the {BeginXmlBuilderParams}{EndXmlBuilderParams} metatags.

SQL Errors with certain characters

Warning: In your SQL code, do not use the “<>” operator for “not equals” as it will cause XML parsing errors; instead use “!=”. Greater than and less than use ampersand gt; and ampersand lt;

Reordering Results with Different Sort Order

The XslGenerator does not have a built-in way to click on a column header to reorder results.

If you want to provide a user with the ability to reorder results, you'll need to do the following:

1. Add a parameter to your SQL command or SP that specifies the sort order and apply this to the ORDER BY statement in your SQL.
2. Add a clickable link (or some other means) to allow the user to choose a sort order and specify that sort order in a querystring parameter. This will repost the page.
3. Modify the XslGenerator code to read the sort order choice from the querystring parameter described in the step above. Order the results based on the user's choice by applying the user's ordering choice in the SQL (as described above).
4. If using the Using the Alpha Pager feature, then you'll need to make sure you specify the sorting column in the {BeginPagerPropertiesAlphaElement} and {EndPagerPropertiesAlphaElement} metatags.

Alternate: it might be possible to reorder results on the client side by using javascript and XSL sorting commands, but Avectra has not tried this. The benefit of doing this would be that you do not need to repost the page.

Parameter Values Not Parsing on Find Control

Q. I have a Page Detail with a Find.ascx control and another Page Detail with XslGenerator. The XslGenerator has parameters that are supposed to take the values entered into the search fields on the Find control, but they're not parsing. Why not?

A. If you have parameter values that are not parsing on a Find.ascx control, then first look at the Page Detail on which you have the XslGenerator. Make sure that the Object of the Page Detail's Form can parse any fields that are on the search form on the Find control. In order for the Object to be able to parse the values, the values must be contained in a Data Object of the Object. Otherwise, the Object will not be able to parse the entries on the search form created by the Find control.

Setting Up Next/Previous Paging in Search Results

If your results will contain a lot of records, you may want to enable the user to page through the results using a numeric or alpha pager. See XslGenerator Pager for more information.

Using XslGenerator to Output Search Results

See eWeb Find for a case study.

In the same way that a List content detail can display search results driven by a search form on a page using the Find.ascx control, so can a content detail driven by XslGenerator.

Unlike a List, however, in which the search column values entered by the user are automatically added to a dynamically-generated WHERE clause in a SQL Select query, you must be sure to include every search control within your {BeginPostData} or {BeginXmlBuilderParams} metatags.

In your XslGenerator web page detail, be sure to choose the same Form as the Form in the related Find content detail to ensure the control values can be properly parsed.

Caching XML

If the Xml Data Source is from the DynamicXmlBuilder or from a web service, you may choose to configure the XslGenerator definition to save the XML file on the web server for faster access. You can set a refresh rate so that the data will be regenerated on an interval of every 10 minutes, 60 minutes, 24 hours, or whatever setting is appropriate. If your XML source is an RSS feed, then you must do this as a matter of etiquette -- it is bad form to continuously load an RSS feed.

Setting this property will make pages load faster, reduce network traffic and tax the SQL Server less, but at the cost of serving real-time data.

To do this, add this line to your content, where the number between the tags is the number of minutes you want to cache the content:

{BeginCacheDurationMinutes}60{EndCacheDurationMinutes}

See XslGenerator Cache for more information.

Summary of XslGenerator Tags

XML Tags

XML Tag	Used to Specify
{BeginPostUrl}{EndPostUrl}	The URL of the web service
{BeginPostData}{EndPostData}	Querystring values that will be passed to site of the {BeginPostUrl}. May be omitted or may be simply added to the {BeginPostUrl}. Works in tandem with {BeginPostUrl}
{BeginXmlFileName}{EndXmlFileName}	The path and file name of a static XML file (overridden by {BeginPostData})
{BeginXmlBuilderService} {EndXmlBuilderService}	Web Service Name of a netFORUM DynamicXmlBuilder (overridden by {BeginPostData} and {BeginPostUrl} if either is specified)
{BeginXmlBuilderMethod} {EndXmlBuilderMethod}	Name of the web service method of a netFORUM DynamicXmlBuilder. Works in tandem with {BeginXmlBuilderService}
{BeginXmlBuilderParams} {EndXmlBuilderParams}	Name and Value pairs of Parameters to be passed to method in {BeginXmlBuilderMethod}. May be omitted if there are no parameters.
{BeginXmlBuilderXml}{EndXmlBuilderXml}	Enter an DynamicXmlBuilder definition directly in web content detail.
{BeginPagerProperties} {EndPagerProperties}	Used to construct a pager and to set the number of records per page.
{BeginPagerPropertiesNode} {EndPagerPropertiesNode}	Used for advanced pagers. Instructs which node will be paged through.
{BeginPagerPropertiesAlphaElement} {EndPagerPropertiesAlphaElement}	Used to set up alpha paging. Determines which presorted Xml Element will drive alpha paging.
{BeginCacheDurationMinutes} {EndCacheDurationMinutes}	The number of minutes to cache or store an Xml data source file before generating a new one from the DynamicXmlBuilder or web service.

XSL Tags

XSL Tag	Used to Specify
{BeginXsl}{EndXsl}	The XSL document typed directly into the content detail.
{BeginXslFileName}{EndXslFileName}	The path and file name of a static XSL file (overridden by {BeginXsl})
{BeginXsltArguments}{EndXsltArguments}	Name and Value pairs of XSLT style sheet parameters. Optional.

Overriding the XslGenerator Control

.NET web developer may build a custom control that inherits from the XslGenerator control. See main article for more.

Limitations

Q. I understand that I can pass XlstArgument parameters to the XslGenerator. Can I add XsltArgument extensions as well?

A. We have not tested this yet.

Q. I want to call a web service that requires authentication. Can I do this with XslGenerator?

A. Baseline, no. But you can develop a .NET override of the control to do so. See XslGenerator Override. This is not documented at this time.

Q. I have multiple XslGenerator controls on the same page, and the pagers do not work.

A. This is a known limitation. See Troubleshooting section.

Q. Can the XslGenerator generate or publish a RSS news feed?

A. No. XslGenerator can consume and output a RSS feed, but it cannot publish one. See RSS Publish for netFORUM's RSS publishing tool.

• The original 2006.02 build had a bug related to the migration from .NET 1.1 to .NET 2.0 that caused the XslGenerator not to work. This is fixed in the first service pack for this build, 2006.02.02. You will encounter this only on the original release of this build.