| XML Package Overview & Operation
XML packages let developers extend the functionality of AspDotNetStorefront without necessarily having to know ASP.NET and/or recompile the storefront.
One example would be the XML packages we use for our shopping site feeds, like Google Product Search, TheFind, Shopzilla, etc. If a developer wanted to add support for a new feed to the application, he would not have to recompile the storefront. He would simply write a new XML package that generates the shopping comparison site feed data and add this XML package to the admin console. This allows developers to add features easily without rebuilding the core source or waiting for the feature to be added to the core application.
XML packages also provide a 'middle tier', separating business logic (code) from presentation layer (html), and allowing the XML package to bring those two areas together without mixing HTML into your code objects.
AspDotNetStorefront uses XML packages to render most category, manufacturer, department, and product pages. This allows you to change page layouts in the storefront just by writing a new XML package, or modifying an existing one.
AspDotNetStorefront also uses XML packages for all customer notifications, including receipts, order shipping notifications, distributor drop ship notifications, etc making it easy to completely customize these messages.
A knowledge of XML, XSL, XSLT, and SQL is required to fully utilize XML packages.
XML packages have two purposes:
- Internal Packages: Used internally by AspDotNetStorefront to provide access to nested entities like categories, sections, libraries and object structures in the database. The storefront will NOT function if these XML packages are removed.
- Display Rendering Packages: These XML packages are created by third party developers to generate custom page HTML outputs for entity and/or object pages. An example is to create a custom category page display format for the storefront.
What is an XML Package?
 An XML package is pretty simple. It takes an input data set, SQL statement, or Web service call and combines the data with automatically generated system and customer run-time environmental data (e.g. query string params, form params, cookies, etc), to produce an output document. The output document can be almost any format, but the most common are: XML for structured data or HTML for web page display content.
XML packages are named with the .web.config extension (e.g. MyXmlPackage1.web.config).
The steps an XML package works is as follows:
- Package is instantiated by Name (the filename, e.g. MyXmlPackage1.web.config)
- Package reads .xml.config file
- Code adds additional run-time parameters to the XML package
- Code adds additional system defined parameters to the XML package
- Datasets are built from the SQL statements
- Datasets are converted into XmlDocument
- XmlDocument is XslTransformed into final XML or HTML. You can even have multiple transforms in one XML package
- Caller of package will typically then process any AspDotNetStorefront specific tokens in the output (if HTML) and render it on the page
XML packages are defined by the XSLT language. The technologies of: XML, XSL, SQL, HTML, XHTML, etc are all leveraged to write effective XML packages. There are many tutorials and good books on those technologies, so they are not discussed here, except where any unusual exceptions or requirements are imposed by the storefront.
Please remember that XML packages are XHTML compliant.
Internal XML Packages
When used internally as a helper object, the XML package typically produces an in-memory XmlDocument object, as a result of input SQL statements, and various customer, system, and user defined parameters. Examples of these internal packages can be found by looking at files such as:
- /XmlPackages/CategoryMgr.xml.config
- /XmlPackages/ManufacturerMgr.xml.config
- etc...
Display Rendering XML Packages
When used by developers or customers, this type of XML package outputs HTML to be rendered within a store page, typically rendering within the skin in the contents area. This is important to allow developers to add custom page formats for their clients. For example, a particular client may want a custom category page. Adding one is as simple as creating a new XML package (or just modifying an existing one), uploading it to the site, and then setting the category to use that package through the admin console.
Installing XML Packages
XML packages are installed by placing them in XML packages folder in the web site or in /admin/XmlPackages. XML package requirements may differ if they are used on the store site vs. the admin site. XML packages can also be stored by skin in skins/skin_1/XmlPackages, because different skin layouts may require different manifestations of the package. When your XML package is ready for use, just FTP the file into that directory. Then you can assign that XML package to any entity or product in the storefront using the Admin site.
Invoking XML Packages By Themselves
XML packages can also be executed on demand, using the engine.aspx page on your site. This page can be invoked at site.com/engine.aspx?xmlpackage=xmlpackagename or with the shortcut site.com/e-xmlpackagename.aspx.
This new engine page now allows you to do things using dynamic data to add totally new pages in your store. For example, suppose you want to have a page which lists the top 5 most heavily discounted products in your db, or a page which lists the most 25 recently added products in the store. You can easily write an XML package to do either, and with both packages you have full control over the data that is being used to generate the page and the display format used to render the page results. All this is possible by writing .xslt files with the necessary XML package instructions. No change to the asp.net storefront code is required. To deploy a new XML package page to your site, all you have to do is FTP the XML package file to the /XmlPackages directory of your web server and invoke it.
Full real-time Debugging & Breakpoints in XML Packages
You can set the Xml.DumpTransform AppConfig to true, and the XML package engine will write intermediate .xml files into the /images directory. The xml files will be appropriately named based on the name of the XML package, and also intermediate stage files will be written out.
To debug your xsl transforms, you can use your favorite Xsl debugger tool or Visual Studio.net directly.
Example XML Package
The following XML package shows an example of how to display a category (entity) page in grid icon layout, and shows how easy it would be to alter this layout, as the XML package separates structure (html) from content (database information).
For more information, see our XML Package Specification document in the manual |