CartRegister Control Documentation

CartRegister Control for StoreFront 7
by Structured Solutions

The CartRegister Control is an alternative cart control for StoreFront 7.0. This control displays a list of items in the cart in a format similar to a register tape. It can be used anywhere the built-in CartList Control can be used.

Features

Compact "Register tape" list of items linked to Product pages
Personalized Header
- Any text or image is linked to the Checkout page
- Include any Customer field in the text for a personalized header when the customer is signed in
Customizable Toolbar
- Any text or image is linked to the Shopping Cart page to create a View Cart button
- Any text or image is linked to a Javascript Expand and Shrink function that will alternately show and hide the items in the cart
- Include any Cart field in the summary text displayed when items are hidden
Customizable Footer
- Include any Cart field in the total line
Each section can be turned off individually if you want to integrate this cart with your own control
Every option is available using standard HTML syntax, no ASP.NET programming required
Javascript and cookies must be enabled for the shrink/expand function to work properly (Javascript and cookies are also required for StoreFront to work correctly)

Installation Instructions

Run the installer to extract all the files for CartRegister Control to a directory on your local computer. The directory will have 4 subdirectories called bin, controls, documentation and images.
Copy the files from the bin directory to the bin directory of your website.
Copy the files from the controls directory to the controls directory of your website.
Copy SSCartRegister.js to the root and ssl directories of your store.
Optional: Copy the sample images from the images directory to the images directory of your store. These are the same images seen in Examples 3-6 below.

Now add the CartRegister Control to a common control so that it appears on your website. For example, to add the CartRegister Control to the left column, follow these steps:

Add the following line to the top of LeftColumnNav.ascx.

<%@ Register TagPrefix="ss" TagName="CartRegister" Src="../Controls/CartRegister.ascx" %>

Add the following line to the body of LeftColumnNav.ascx where you want the CartRegister Control to appear.
```
<ss:CartRegister id="cart" runat="server" />
```

Control Documentation

See Example 1 below to see how the control looks by default. You can completely customize the look and feel of the CartRegister with just a few simple additions to the CartRegister tag. The CartRegister control is designed to make customization very easy by eliminating the need to edit complex ASP.NET controls or change the "codebehind" programming.

The table below lists all of the CartRegister attributes that can be added to the CartRegister tag. Multiple attributes can be used just like with regular HTML tags. Moreover, you do not need to recompile your store to see your changes. Just save your page or control file (aspx or ascx) and reload the page in your browser. This makes experimenting very easy. Several examples are shown in the next section.

CartRegister Control Attributes

Attribute	Description	Example
CssClass	The Cascading Style Sheet (CSS) class to use throughout this control. If no CssClass is specified, then CartRegister will explicitly inherit the class of the control that surrounds it. For example, if the CartRegister control is in an HTML table cell with a class of "RightColumn", then the CartRegister will also use a class of "RightColumn". This CSS class will propagate to each of the individual elements in CartRegister that do not have a class assigned. By default no class is assigned to any element. Default: The container class	<uc1:CartRegister CssClass="RightColumn" ...>
EmptyText	The text to display when no items are in the cart. This can be turned off by setting ShowEmpty="False". Default: "No Items"	<uc1:CartRegister EmptyText="Nada" ...>
ExpandImage	The relative path of an image file to display in the Shrink/Expand position of the toolbar. The path is relative to the page in which this control is included. If no path is entered, then the ExpandText is displayed. The image is linked to a routine that will display all the items in the cart. Default: nothing	<uc1:CartRegister ExpandImage="images/expand.gif" ...>
ExpandText	The text to display in the Shrink/Expand position of the toolbar if no ExpandImage is specified. If ExpandImage is specified, this text will be used as the alternate text for the image. The text is linked to a routine that will display all the items in the cart. Default: "Expand"	<uc1:CartRegister ExpandText="Show Items" ...>
FooterStyle	CSS inline style overrides for the footer portion of the control. Default: blank	<uc1:CartRegister FooterStyle="text-align: right" ...>
FooterText	The text to display in the footer portion of the CartRegister. You can include any Cart field in the text and it will be formatted as currency. To include a Cart field, enclose it in square brackets "[ ]". Default: "Total: [SubTotal]"	<uc1:CartRegister FooterText="Sub Total: [Sub Total]" ...>
HeaderImage	The relative path of an image file to display in the header portion of the control. The path is relative to the page in which this control is included. If no path is entered, then the HeaderSignedInText and HeaderSIgnedOutText are displayed. The image is linked to the Checkout page. Default: blank	<uc1:CartRegister HeaderImage="images/cartcheckout.gif" ...>
HeaderSignedInText	The text to be displayed as a header when the customer is signed in. If a HeaderImage is specified, then this text will be used as the alternate text for the image. The header text is linked to the Checkout page. You can include any Customer field in the text. To include a Customer field, enclose it in square brackets "[ ]". Default: "[CustFirstName]'s Cart"	<uc1:CartRegister HeaderSignedInText="[CustFirstName] [CustLastName]'s Cart" ...>
HeaderSIgnedOutText	The text to be displayed as a header when the customer is signed out. If a HeaderImage is specified, then this text will be used as the alternate text for the image. The header text is linked to the Checkout page. Default: "My Cart"	<uc1:CartRegister HeaderSignedOutText="Checkout" ...>
HeaderStyle	CSS inline style overrides for the header portion of the control. Default: blank	<uc1:CartRegister HeaderStyle="text-align: center; font-weight: bold" ...>
HeaderToolTip	Pop-up text to display if the header is a text link. Default: "Checkout"	<uc1:CartRegister HeaderToolTip="This way out" ...>
HeaderUrl	The url to be linked with the CartRegister header. If you use a relative url it will have the site url appended to the beginning. Default: shoppingcart.aspx	<uc1:CartRegister HeaderUrl="mailto:amiller@sfaddons.com" ...>
ItemStyle	CSS inline style overrides for the items listed in the body of the control. Default: blank	<uc1:CartRegister ItemStyle="text-align: left" ...>
ItemWrap	A Boolean value (True or False) which determines whether the item name should be allowed to wrap onto multiple lines. Default: True	<uc1:CartRegister ItemWrap="False" ...>
LineColor	Specifies the color of the lines that separates the header and footer from the "register tape" portion of the control. Any valid html color is allowed. Default: Black	<uc1:CartRegister LineColor="White" ...>
MultipleItemsText	The summary text displayed in the body of the control when the Cart is shrunk and ShowSummary is True and there is more than 1 item in the cart. You can include any Cart field in the text. To include a Cart field, enclose it in square brackets "[ ]". Default: "[ItemCount] Items"	<uc1:CartRegister MultipleItemsText="[Count] pieces" ...>
ShowEmpty	A Boolean value (True or False) which determines if the EmptyText message is displayed when there are no items in the cart. Default: True	<uc1:CartRegister ShowEmpty="False" ...>
ShowFooter	A Boolean value (True or False) which determines if the FooterText is displayed. Default: True	<uc1:CartRegister ShowFooter="False" ...>
ShowHeader	A Boolean value (True or False) which determines if the Header is displayed. Default: True	<uc1:CartRegister ShowHeader="False" ...>
ShowLines	A Boolean value (True or False) which determines if the separator lines are displayed. Default: True	<uc1:CartRegister ShowLines="False" ...>
ShowLinks	A Boolean value (True or False) which determines if the product name is linked to the detail page for the product. Default: True	<uc1:CartRegister ShowLinks="False" ...>
ShowPlurals	A Boolean value (True or False) which determines if plural product names are used when the quantity is greater than 1. If True and no plural name is defined, the singular will be used. Default: True	<uc1:CartRegister ShowPlurals="False" ...>
ShowSummary	A Boolean value (True or False) which determines if MultipleItemsText or SingleItemText are displayed when the cart is shrunk. Default: True	<uc1:CartRegister ShowSummary="False" ...>
ShowToolbar	A Boolean value (True or False) which determines if the Toolbar is displayed. Default: True	<uc1:CartRegister ShowToolbar="False" ...>
ShowToolTips	A Boolean value (True of False) which determines if product pop-up descriptions are displayed. Default: True	<uc1:CartRegister ShowToolTips="False" ...>
ShrinkImage	The relative path of an image file to display in the Shrink/Expand position of the toolbar. The path is relative to the page in which this control is included. If no path is entered, then the ShrinkText is displayed. The image is linked to a routine that will hide the items in the cart. Default: nothing	<uc1:CartRegister ShrinkImage="images/shrink.gif" ...>
ShrinkText	The text to display in the Shrink/Expand position of the toolbar if no ShrinkImage is specified. If ShrinkImage is specified, this text will be used as the alternate text for the image. The text is linked to a routine that will hide the items in the cart. Default: "Shrink"	<uc1:CartRegister ShrinkText="Hide" ...>
SingleItemText	The summary text displayed in the body of the control when the Cart is shrunk and ShowSummary is True and there is exactly 1 item in the cart. You can include any Cart field in the text. To include a Cart field, enclose it in square brackets "[ ]". Default: "[ItemCount] Item"	<uc1:CartRegister SingleItemText="One Item" ...>
ToolbarStyle	CSS inline style overrides for the toolbar portion of the control. Default: blank	<uc1:CartRegister ToolbarStyle="text-align: center; font-weight: bold" ...>
ViewCart Image	The relative path of an image file to display in the View Cart position of the toolbar. The path is relative to the page in which this control is included. If no path is entered, then the ViewCartText is displayed. The image is linked to the Shopping Cart page. Default: nothing	<uc1:CartRegister ViewCartImage="images/viewcart.gif" ...>
ViewCart Text	The text to display in the View Cart position of the toolbar if no ViewCartImage is specified. If ViewCartImage is specified, this text will be used as the alternate text for the image. The text is linked to the Shopping Cart page. Default: "View Cart"	<uc1:CartRegister ViewCartText="Show Cart" ...>
Width	Specifies the width of the CartRegister control. Any valid HTML width is allowed. Default: Not specified	<uc1:CartRegister Width="100%" ...>

Cart Fields

These Cart fields can be referenced in the FooterText, SingleItemText and MultipleItemsText attributes. To reference a field, enclose it in square brackets "[ ]". For example, "Subtotal: [SubTotal]". Most of these fields will not have useful information until you start checking out. Similarly, it would not make sense to use a Text field in the FooterText since it will be formatted as currency.

Field Name	Type
BackOrderMessage	Text
BackOrderTotalAmt	Number
CODTotal	Number
Count	Number
CountryTax	Number
DiscountTotal	Number
GiftCertificateTotal	Number

Field Name	Type
GrandTotal	Number
HandlingTotal	Number
ItemCount	Number
LocalTax	Number
MerchandiseTotal	Number
OandaISO	Text
OandaRate	Number

Field Name	Type
OrderTotal	Number
ShipmentsTotal	Number
ShippingTotal	Number
StateTax	Number
SubHandlingTotal	Number
SubTotal	Number
TotalBilledAmt	Number

Customer Fields

These Customer fields can be referenced in the HeaderSignedInText attributes to provide a personalized message to customers when they are signed on. For example, if you specify HeaderSignedInText="[CustFirstName]'s Cart" and Joe Arbogast is signed in, then the Header text will read "Joe's Cart".

Field Name	Type
CustFirstName	Text
CustIsSubscribed	True/False
CustLastName	Text
CustPassWord	Text
Email	Text
OandaISO	Text
OandaRate	Number

Editing the CartRegister Control

Although you can change a great deal of the look and feel of CartRegister control using tag attributes, you may find that you want to change more. In that case, you will need to edit the CartRegister control source (CartRegister.ascx). These tips and guidelines are meant to help you change the control without breaking it:

Do not delete any tag from CartRegister.ascx that has an "ID" (e.g. <asp:Label id="test"...>).
There are 4 sections to the control: Header, Toolbar, Body, and Footer. Each section has a corresponding <asp:TableRow>, such as <asp:TableRow id="HeaderRow"...> for the Header. To hide a section, you can use the appropriate ShowXXX attribute described above, or add the attribute/value Visible="False" to the corresponding table row. For example, to hide the header you can either specify <uc1:CartRegister ShowHeader="False"> where you use the CartRegister control, or change CartRegister.ascx so to read <asp:TableRow id="HeaderRow" Visible="False">.
If you enter header or footer text in CartRegister.ascx, it will take precedence over text you enter on HeaderSignedInText, HeaderSignedOutText, or FooterText.. That is, you will see the text you entered in the control source. You will not see the conflicting text you entered in the tag.
If you enter a value for CssClass for an element in the control source, it will take precedence over the CSS class that you specify on the tag or inherit from the surrounding control.
Most odd display differences between browsers can be traced to putting a class parameter onto the wrong element in the control. It is probably safer to specify the CssClass on the CartRegister tag and let the program logic take care of propagating it correctly.
Do not change an element type in the control source (i.e. from a table cell to a label). If you want to integrate your own element to replace the one that is there, you should hide the entire section and then create your own version of that section.

Examples

All of the following examples were taken from a standard StoreFront 6.1 installation using the default "Coffee" design scheme. The CartRegister control was inserted below the Simple Search control in the default RightColumnNav.ascx file using the tag shown. Any changes to the CartRegister html are shown in the CartRegister.ascx column. Each one builds on the previous. Changes from one to the next are highlighted in bold.

Sample Display	CartRegister Tag (in RightColumnNav.ascx)	CartRegister Source Changes (in CartRegister.ascx)
Example 1: This example shows the default appearance of the CartRegister Control. This is what you will see after you install CartRegister if you make no other changes.
	`<uc1:CartRegister id="CartRegister1" runat="server"></uc1:CartRegister>`	No changes
Example 2: Custom styles are used to center the header and make the text bold, and align the footer to the right. Notice that the customer has signed in, so their first name now appears in the header.
	`<uc1:CartRegister id="CartRegister1" runat="server" HeaderStyle="text-align:center; font-weight:bold" FooterStyle="text-align:right"></uc1:CartRegister>`	No changes
Example 3: Convert the header and toolbar to use graphic images. The sample images are 50 and 100 pixels wide so the cart width is set to match and centered in the column.
	`<center> <uc1:CartRegister id="CartRegister1" runat="server" HeaderStyle="text-align:center; font-weight:bold" FooterStyle="text-align:right" HeaderImage="images/cartcheck.gif" ViewCartImage="images/viewcart.gif" ExpandImage="images/expand.gif" ShrinkImage="images/shrink.gif" Width="100"></uc1:CartRegister> </center>`	No changes
Example 4: Same as above but the items are hidden because the Shrink button was pressed.
	No changes	No changes
Example 5: Now the summary line is hidden and the line color is changed to match the button borders.
	`<center> <uc1:CartRegister id="CartRegister1" runat="server" HeaderStyle="text-align:center; font-weight:bold" FooterStyle="text-align:right" HeaderImage="images/cartcheck.gif" ViewCartImage="images/viewcart.gif" ExpandImage="images/expand.gif" ShrinkImage="images/shrink.gif" Width="110" LineColor="#929081" ShowSummary="False"></uc1:CartRegister> </center>`	No changes
Example 6: This last example shows that you can also make changes to the source template for the control. In this case, the footer is changed to bold white.
	No changes	`<asp:TableCell id="FooterCell" Runat="server" wrap="False" Width="100%" Font-Bold="True" ForeColor="#ffffff"></asp:TableCell>`