Looking for the v10 manual? Visit our new user's guide!
Search Descriptions Version
This article applies to: Developer Resources

Guide to Front End Development in AspDotNetStorefront

In AspDotNetStorefront, there are three different types of front end pages.

  1. "Topics" for content pages managed through the admin console.
  2. "Xml Packages" for site nagivation, entity pages(like categories), and product pages.
  3. Active Server Pages (.aspx) for web forms pages like account and checkout.

Regardless of the type of page, the content is output through the content placeholder in the Master Template for the Skin that you have assigned to your store.

App_Templates & The Master Template

In the App_Templates directory for the skin you are applying to your store (like App_Templates/Skin_1), you will find:

  1. An "XmlPackages" Folder. This contains XML Packages specific to the Skin. An XML Package in this folder with the same name as an XML Package in the Root XML Packages folder will override the root one.
  2. Some unused master templates: empty.master, empty3.master and expressTemplate.master. These are here for backwards compatability.
  3. Some .css files: phonestyle.css, receipt.css and receiptstyle.css. These CSS files are placed here in order to prevent them being pulled into the master template (you can read about that in the "App_Themes" explanation).
  4. The Master Template for the Skin.

The Master Template

The Master Template file provides a centralization to the common functionality of your pages. You can control the layout of your site in one place.

  1. In Visual Studio, in your Solution Explorer, drop open the web directory. This should look like "http://localhost/AspDotNetStorefrontMultistore" or something similar.
  2. Navigate to App_Templates, Skin_1, and open "template.master"

If you're thinking "hey, this looks like an HTML file" that's because eventually, after the server gets done with it, it will be.

  1. The very first thing you'll see is a Master Template Declaration.
  2. Next you'll see a bunch of "Register TaxPrefix=...." These are including references to controls that are used on the Master Template.
  3. You'll then see a DOCTYPE. If you want to know more about DOCTYPEs, you can read about it here.
  4. You'll see some meta tages and a title tag. Don't mess with these, because you don't need to! You can configure Meta Data for SEO in your Admin Console.
  5. Next you should see the very first XML Package control on the page, a special goodie that can be used for header scripts that need dynamic data.
  6. Now, you are in the BODY of the HTML. This is where the site layout happens. You'll see a div element for the header, and for the top navigation, breadcrumbs, the content, vertical navigation and footer.
  7. In addition to XML Package controls, you'll see Topic Controls on the Page. We will cover both of those later, but you can think of Topic Controls as content placeholders that you can put anywhere on the Master Template, and change the content from the Admin Console without having to modify code.
  8. Now, look for the server tag that looks like this: <asp:ContentPlaceHolder ID="PageContent" runat="server"> </asp:ContentPlaceHolder>. This where the content for every unique page gets rendered.

The App_Themes/Skins Directory and the Skin's CSS Files

After witnessing what goes on inside the "App_Templates" directory, you might have a hunch what takes place in the "App_Themes" directory. If you guessed "Theming" you are totally correct.

In Visual Studio, in the Solution Explorer, navigate to "App_Themes" and "Skin_1." Open base.css (In versions prior to 9.4.1, this stylesheet won't exist, and all styles will be in the style.css file). This is the base stylesheet for global styles that are needed regardless of the skin's theme. This contains structure for things like the shopping cart page.

In Visual Studio, in the Solution Explorer, navigate to "App_Themes" and "Skin_1." Open style.css. This is the stylesheet for the skin's theme. If links on the site are aquamarine, it's because there is a style for it in this file.

*Any* CSS file in this directory (with a .css extension) will automatically pulled into the Master Template and be included on EVERY PAGE in your site. This means, you don't have to add a reference to new stylesheets you create. Also, you need to be careful of how you manage stylesheets in this directory. If you think you're going to back up a stylesheet by naming it style_OLD.css, you will end up with style_OLD.css pulled into your site.

If you'd like to learn more about CSS, there are tons of tutorials out there on the internet. You can read about Cascading Style Sheets here.

Topics: Content Pages and Content Placeholders

Topics can be found in the Admin Console under Content-->Manage Topics

Topics can be used for two things:

  1. Pages that you can link to, and manage the content of through the Admin Console.
  2. Content Placeholders that you can place in your code and manage the content through the Admin Console.

For a handy version of your topic that doesn't contain the Master Template content (great for lightboxes or popups) put a 2 after the t in the t-topicname.aspx. This will look like http://localhost/AspDotNetStorefrontMultiStore9/t2-topicname.aspx.

XML Packages

XML Packages give you control of your dymanic content and how it will display. Not only can you query for the data that you want to use for dymanic display, but you can use XSLT to manipulate and transform that data. You can even use XSLT to perform logic on HTML elements and attributes to display, to include CSS classes.

If you know basic SQL, HTML & XSLT you are three quarters on the way to being a full fledged XML Package Ninja. If not – you’ll want to research all three of those technologies (Microsoft SQL, HTML, & XSLT). There are some great resources out there on the web for XSLT: https://www.google.com/#q=XSLT+tutorial+training&safe=active

The Package Declaration:

Three handy feature’s in the Package Declaration:

  1. 1. The Debug Option:  Set this value to true and the package will output 4 debug windows onto your page.  The 1st window outputs the contents of your xml package, the 2nd the XML being transformed, the 3rd will output any sql queries including the runtime parameters, and the 4th simply outputs the html of the page.  The XML debug window is the one you will use the most.
  2. 2.  Entity Helpers:  If you haven’t had a chance to look at Entity Helpers yet – you’ll want to.  If your XML Package is 100% custom and doesn’t reference EntityHelpers anywhere in the file – set this to false.  There is a slight performance hit and you don’t want this running unnecessarily, especially if your XML Package is hanging out on the Master Template and running every page load.  On Entity & Product Pages however, you will want this.  You get an XML tree of your site’s published Entities, to include their Name, Description & other handy info.
  3. 3.  Allow Engine:  Set this to true to run your XML Package as a stand-alone page.  Syntax: if your package name is packagename.xml.config, then e-packagename.aspx will render your page in the site’s content area, and x-packagename.aspx will give you the page free of the template. “x-” is great for modal or lightbox popups.

SQL Queries & Web Queries:

In SQL Queries, you define the node names that will render in the XML that is being transformed.  name= defines the parent node and rowElementName= defines the node name of each row that will render as a child node.

Like so:

In Web Queries, the Response XML from a RESTful Web Service URL Defines the Node names.

The “WebQuery” Node will be the parent node of the Response:

Package Transform:

This is where we transform the XML returned from our queries. Everything inside the Package Transform is traditional XSLT.

Stylesheet Declaration:

This is where we provide the stylesheet information. If we have namespaces to deal with, we add them here. You automatically “get” the aspnsf namespace – complete with access to the XSLTExtensionBase methods. (This is how we get price, image, ML support, Appconfigs & String Resources right in the package)

Global Parameters:

These parameters are declared before any of our templates and can be accessed globally within any template in the package. Remember, XSLT is a declarative language so once the parameter gets it’s value, you cannot change it later in the code.


The root template in an XML Package is matched on “/”. This will run one time – so put all of your “one time” HTML in this template.

<xsl:apply-templates /> will run a template match for every node in the node set. So if I’m on a product listings page for a category, and have a query for 20 products with a node for each Product in my XML – this template will fire once for each one of the 20 products. So if your writing HTML for this page you would want to put your “wrapper” div in the root (/) template surrounding the apply-templates call and your repeatable divs in the Product template.

<xsl:call-template /> is a bit different. This doesn’t match on a node set but only runs once for each time you call it (by name).

So, to apply a template for a node-set, like Products, you define your template as <xsl:template match="Product"></xsl:template> and apply that template with the XPATH to your node set <xsl:apply-templates select="/root/Products/Product" />. To call a template by name, that does not match a node set, you define your template as <xsl:template name="SubEntity"></xsl:template> and call that template by it's name <xsl:call-template name="SubEntity" />

Active Server Pages (.aspx), Controls (.ascx), and their Code-Behinds

In the root of your website you'll see a large amount of .aspx files, and their c# or vb codehinds (.aspx.cs or .aspx.vb). You will also see a "controls" folder, containing user control (.ascx). These pages are used throughout the site for forms pages like shopping cart, account, creating an account, and signing in. If you aren't familiar with ASP .NET Web Forms, you can read about it here.

Like Source Code, these pages are subject to feature changes and improvements, that if you were to modify them it will take you off what is called "The Upgrade Path." You are on the upgrade path if you only modify the Skins (The App_Templates and App_Themes folders). If you aren't on "the upgrade path," that doesn't necessarily mean you can't upgrade. In fact, many merchants will have business requirements that call for a change to some of the account or checkout forms. That just means that an upgrade isn't a quick update of your core code and an update script to your database. It will require a developer to merge the customizations in everytime. This is common practice. The point is, the less changes you make to the source code and active server pages, the less cost there will be for an upgrade to the latest version.