Documentation You are here: start » v » 2.0 » templates_backup

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

v:2.0:templates_backup [2017/04/26 07:02] (current)
Line 1: Line 1:
 +====== Templates, Caching, and Template Customization with HTML + CSS ======
  
 +===== Quick and Easy Customizations =====
 +==== Get Your Logo In There! ====
 +You can set your store logo in the Settings tab of your FoxyCart Store'​s Admin. There, you can add the url for your store'​s logo to the "logo url" field. We'll cache your logo to ensure it's served securely, so don't worry about your own SSL.
 +
 +If you don't already have a copy of your logo someplace online, an alternate option is to add the logo to a Dropbox folder and [[https://​www.dropbox.com/​help/​167|use the share link to paste into the FoxyCart admin]]. That's an easy and free way to get your logo hosted someplace that we can pull from.
 +
 +==== Other Common Customizations ====
 +FoxyCart supports many common template customizations from the Template Configuration page in the admin. You can configure:
 +  * Guest checkout settings (forcing guest, forcing account, allowing both but defaulting to one or the other).
 +  * Terms of Service (TOS) checkbox and link.
 +  * Newsletter opt-in checkbox.
 +  * Some color settings to control the visual on the cart, checkout and receipt.
 +  * Product option hiding. (Hide weight, code, category, or all options.)
 +  * Credit card logos. (If you don't accept AmEx, uncheck that box. Note that this only changes the display, not what your payment gateway actually accepts.)
 +  * Credit card security code requirements. (Required, optional, etc.)
 +  * Checkout fields required and displayed. (Don't collect the address info if you aren't shipping. Require a phone field. Etc.)
 +  * Custom content (HTML, JS) injection, for custom styles or tracking code.
 +  * Debugging messaging.
 +  * Receipt over SSL or not.
 +  * Shipping and billing country/​region whitelisting/​blacklisting. If you only want to accept customers or to ship to certain countries, you can do that here.
 +
 +==== Minor Styling Customizations ====
 +Using the custom code template setting, it's now possible to add CSS and javascript to your templates //without needing to modify the templates themselves//​. If you just want to change the background, some colors or styling, or anything else you accomplish with CSS only, we strongly recommend taking this approach. If you want to really customize, read on!
 +
 +
 +
 +
 +===== Advanced and Thorough Customizations =====
 +==== What Are Templates and Why Do You Care? ====
 +Nearly every piece of HTML that FoxyCart presents to your customers is configurable in a template for your store. There are individual templates for:
 +  * [[.:​cart|The Cart]]
 +  * [[.:​checkout|The Checkout]]
 +  * [[.:​receipt|The Receipt]]
 +  * [[.:​emails|Email Receipts]] in plain text and HTML, for the store-wide as well as category-specific varieties.
 +
 +While you can certainly use the [[#​default_template_styles|default templates]],​ we will see just how easy it is to use your own site's design for your FoxyCart templates.
 +
 +<wrap tip>We recommend sticking with the default templates unless you //really// want to make significant changes.</​wrap>​ In the future, we plan on rolling out improvements to increase the conversion rate automatically to users on the default templates (which we'll notify about in advance, in case you're worried). Also, unlike in v1.1 and prior, you can now make many common changes to the templates without any customization.
 +
 +
 +==== An Overview of FoxyCart'​s Template Customization & Caching ====
 +<wrap tip>This section is for people with intermediate to advanced CSS, HTML, and JS abilities. We're happy to help you if you get stuck, but if it's your first rodeo, this stuff might be a bit head-spinning :​)</​wrap>​
 +
 +We'll go into detail below, but it's useful to understand the high-level approach we've taken to templating.
 +  * We use [[http://​twig.sensiolabs.org/​|Twig]] as a template language, and we use [[https://​github.com/​justjohn/​twig.js/​wiki|Twig.js]] as well. Doing this allows us (and you) to use the same templates for clientside and serverside rendering.
 +  * We use the [[http://​bem.info/​method/​definitions/​|BEM methodology]] for CSS naming.
 +  * All template variables used exist in the ''​FC.json''​ object. You'll see references to variables in the template files. That's where they live, but there are helper methods to work with that data.
 +  * We have a system we call AutoMagiCache,​ which scrapes a template file on your site and will cache it (and all assets) securely on our systems, so you don't need SSL on your own server to reference assets (images, css, js).
 +  * We're currently using Twitter Bootstrap 3 as a base for our default theme, but we're using SASS ''​@extend''​ functionality so you won't see any Bootstrap classnames.
 +  * Doing advanced customizations can get involved, but there are "​easier"​ and "more difficult"​ ways to accomplish things within our templating approach. When in doubt, please //please// just reach out. We're happy to help.
 +
 +Additionally,​ in previous versions of FoxyCart there was no clear separations of concerns between content (HTML), presentation (CSS), and dynamic behavior (Javascript). With v2.0 we're doing our best to help each aspect be a separate concern, so that you can override or customize the specific aspects your customers need without worrying about breaking things.
 +
 +Below, you'll find our best attempt at explaining each aspect of our templates and how you can override, hook into, or remove the aspects that you're interested in. If you have questions, post on our [[http://​forum.foxycart.com|forum]] and let us know what is confusing, or email support if you have a suggestion on how this documentation can be more helpful.
 +
 +=== Introduction to Templating ===
 +<wrap tip>If you've used a template language before, you can probably skip this section. If you haven'​t,​ it's probably useful to go through this section to understand how and why templating works the way it does.</​wrap>​
 +
 +FoxyCart 2.0 takes advantage of Twig javascript templates to allow you the freedom to customize all aspects of the eCommerce experience. Templates allow you to quickly and fairly easily add dynamic aspects to your HTML pages. Here's a quick example of how templates will make your life easier. With a simple HTML page, you'd have this:
 +
 +<code html>
 +<h1 class="​product-title">​Product 1</​h1>​
 +<p class="​description">​Description about Product 1</p>
 +<p class="​cost">​Cost:​ $25</​p>​
 +<a href="#"​ class="​add-link">​Add to Cart</​a>​
 +</​code>​
 +
 +The classes make it really easy to style the presentation of the different elements with CSS, but CSS and HTML alone do not allow you to change dynamically update the contents of the HTML. That's why web developers use Javascript, to add interactivity to the sites they design. Commonly this is done with jQuery, so let's examine how that might work. Perhaps you want a product that has two options, and the second option adds 10% to the cost. First, you'd start with your HTML:
 +
 +<code html>
 +<h1 class="​product-title">​Product 1</​h1>​
 +<p class="​description">​Description about Product 1</p>
 +<ul class="​options">​
 +  <li class="​option1"><​input type="​radio"​ value="​default">​Default</​input></​li>​
 +  <li class="​option2"><​input type="​radio"​ value="​premium">​Premium</​input></​li>​
 +</ul>
 +<p class="​cost">​Cost:​ $<span class="​number">​25</​span></​p>​
 +<a href="#"​ class="​add-link">​Add to Cart</​a>​
 +</​code>​
 +
 +Then you'd add the javascript to watch the radio buttons:
 +
 +<code javascript>​
 +$( document ).ready( function () {
 +  $('​.options'​).click( function () {
 +    var option2 = $('​.option2:​checked'​).length;​
 +    if (option2 > 0) {
 +      $('​.number'​).text('​35'​);​
 +     } else {
 +      $('​.number'​).text('​25'​);​
 +  });
 +});
 +</​code>​
 +
 +That's potentially ok for one or two products, but it doesn'​t scale well. That's why smarter engineers than us have created worked on building Javascript templates that help abstract some of this work. The basic concept is you take some JSON data, insert it into a Javascript template, and then insert the combined output into the client document. It works like this. First, you create a template. In this example we're using Twig syntax:
 +
 +<code html>
 +<h1 class="​product-title">​{{ title }}</​h1>​
 +<p class="​description">​{{ description }}</​p>​
 +<ul class="​options">​
 +  {% for option in options %}
 +  <​li><​input type="​radio"​ value="​{{ name }}">​{{ name }}</​input></​li>​
 +  {% endfor %}
 +</ul>
 +<p class="​cost">​Cost:​ ${{ cost }}</​p>​
 +<a href="#"​ class="​add-link">​Add to Cart</​a>​
 +</​code>​
 +
 +Now, we can just render the template by providing some JSON data that matches the variables:
 +
 +<code javascript>​
 +
 +var templateData = {
 +  title: "A product",​
 +  description:​ "This is a product description",​
 +  options: {[
 +    option1: {
 +      cost: 25,
 +      name: "​Default"​
 +    },
 +    option2: {    ​
 +      cost: 35,
 +      name: "​Premium
 +    }
 +  ]}
 +}
 +</​code>​
 +
 +No longer do we need to write custom Javascript for each product option. Now we can just let the template rendering engine handle it. The default HTML output of this code looks like this: 
 +
 +<code html>
 +<h1 class="​product-title">​A product</​h1>​
 +<p class="​description">​This is a product description</​p>​
 +<ul class="​options">​
 +  <​li><​input type="​radio"​ value="​default">​default</​input></​li>​
 +  <​li><​input type="​radio"​ value="​premium">​premium</​input></​li>​
 +</ul>
 +<p class="​cost">​Cost:​ $25</​p>​
 +<a href="#"​ class="​add-link">​Add to Cart</​a>​
 +</​code>​
 +
 +Now all we have to do is listen for a click, and then rerender the template with the current context. This makes it much easier to scale our code - now we can have as many options as we need. We could also pass in products as data and add new products easily, which it turns out is exactly what happens in FoxyCart templates.
 +
 +
 +
 +
 +==== Class, ID, and Data Conventions ====
 +
 +  * ''​.fc-*''​ classes are for styling purposes only. They aren't required for functionality. (See more in the BEM section immediately below.)
 +  * ''#​fc-*''​ IDs are for styling purposes. ''#​fc-''​ IDs are used sparingly, and mostly for namespacing CSS. (See more in the BEM section immediately below.) Our recommendation is to **not use these IDs for javascript selectors**. Use the ''​data-fc-*''​ attribute(s) instead and stick with our conventions.
 +  * ''​data-fc-*''​ attributes are for functional purposes and template rendering.
 +  * ''​input''​ elements (and ''​select''​ and other form elements) have some caveats:
 +    * Their ''​name''​ attributes have underscores. These can't be changed without breaking serverside functionality,​ so don't change them in template customizations.
 +    * Per HTML requirements,​ ''​label''​ elements operate based on the ''​id''​ attribute of the related input. For ease of implementation and because ''​name''​ and ''​id''​ values almost always match in most HTML, the ''​id''​ values for form inputs also have underscores,​ and are not prefixed with ''​fc-''​.
 +    * Inputs should be selected (in javascript) using the ''​name''​ and ''​value''​ (if necessary) selectors, not the ''​id''​ attribute. Yes, theoretically IDs would be faster, but selector speed isn't really a concern at this point with modern browsers.
 +
 +=== CSS Class and ID Naming Principles with BEM ===
 +To help make the base FoxyCart theme easily modifiable, we've adopted the [[http://​bem.info/​method/​definitions/​|BEM methodology]] for element naming. BEM stands for Block, Element, Modifier and it introduces a funky identifier scheme that we've tried to apply consistently in our templates.
 +
 +[[http://​csswizardry.com/​2013/​01/​mindbemding-getting-your-head-round-bem-syntax/​|This article]] will give you an extensive background on the BEM philosophy we used. Basically, Blocks are defined as distinct elements of a template, Elements are the individual HTML elements that make up the Block, and modifiers are variations of the Elements. They are represented like so:
 +<​code>​block--element__modifier</​code>​
 +And they can be strung together:
 +<​code>​block--block--element__modifier</​code>​
 +
 +FoxyCart templates now have as much separation of concerns as possible, which means all classes are only used for presentation styling and have no impact on actual functionality. The goal with BEM styling is that all elements can be custom styled with a the ''#​fc''​ namespace selector plus at most two class names. Custom CSS can be added to the Admin, or you can hook into the BEM naming to easily apply your own styles.
 +
 +<wrap todo>
 +TODO: Create class name skeleton lists for reference.
 +</​wrap>​
 +
 +=== Specific IDs and Data Attributes ===
 +  * ''#​fc'':​ This is used to namespace CSS for default themes. For the main default theme to function properly but not to interact with a user's own CSS, this keeps the default FoxyCart CSS separate. It may be on the ''​html''​ element (for the fullpage cart, checkout, and receipt templates) or on a ''​div''​ container when rendered on client sites.
 +  * ''​data-fc-container="​cart"'':​ The cart will be rendered (via Twig.js) inside of this element.
 +  * ''​data-fc-container-for="​..."'':​
 +  * ''​data-fc-messaging-for="​..."'':​
 +  * ''​data-fc-error-for="​..."'':​
 +  * ''​data-fc-id="​..."'':​ For tagging specific DOM elements you want to access via code.
 +  * ''​data-fc-container-id="​..."'':​ When a ''​data-fc-id''​ element takes an action on the DOM (for example, when a coupon code is removed, quantity is changed, or an item is removed from the cart), the corresponding element will be acted upon.
 +
 +=== Frameworks & Extending ===
 +
 +FoxyCart 2.0 has an underlying foundation of Bootstrap - but you can't tell by looking at the HTML. Our Bootstrap CSS is custom compiled with an ''​ #fc ''​ namespace and then applied to the DOM via Sass's ''​ @extend ''​ functionality. [[http://​css-tricks.com/​the-extend-concept/​|CSS Tricks covers the basics of Extending in this article]]. In the FoxyCart Sass, we provide a partial called ''​ _fc-to-bootstrap.scss ''​ that maps Bootstrap classes on to the correlating FoxyCart classes. If you are building off of the default responsive theme for your customization,​ it would behoove you to look in that file to see grid classes applied to elements for responsiveness.
 +
 +<wrap info>
 +This dependency should not be considered permanent. Future updates to FoxyCart may remove Bootstrap for lighter CSS, thus the reason it is not exposed in templates.
 +</​wrap>​
 +
 +
 +
 +
 +==== Errors ====
 +A big part of an online checkout is error handling. We have some conventions and helper functions if you'd like to customize error handling.
 +
 +=== Required Fields & Inline Errors ===
 +Required fields will generate an error if a user tabs off of them. Our goal in FoxyCart 2.0 has been to create a default client-side validation system that unobtrusively alerts users to problems with the form, while also giving you as much room to customize as possible. With that in mind inline errors now have three parts: ​
 +  - Field highlighting
 +  - Error bar updating
 +  - Error event firing
 +
 +Each of these parts are designed to be independent so you can utilize just one or both in whichever way works best for you. Below you'll find in depth explorations of each step.
 +
 +=== 1. Field Highlighting ===
 +The specific field will be highlighted by adding a class to the element, which allows CSS styling to highlight the field. FoxyCart gives you flexibility in customizing both the error class applied, and which element it is applied to through the use of data attributes. The **error class** is defined with the ''​data-fc-error-class''​ attribute.
 +
 +If you are adding the error class to an element other than the input (such as a parent element), then you need to include a ''​data-fc-error-for''​ attribute on that element, with the value being the ''​name''​ of the input. So for the shipping first name field, the parent <div> has both attributes, looking like this:: ''​data-fc-error-class="​invalid"''​ ''​data-fc-error-for="​shipping-last-name"''​. In case of an error on the field, the class ''​invalid''​ will be added to the <​div>,​ and once the error is resolved, the class will be removed.
 +
 +''​data-fc-error-class''​ is **required** if you wish to utilize the FoxyCart inline-error functionality. If no class is found, a fallback method of rerendering the block will be triggered. For the default templates, the fallback method will evaluate the twig context, find the error, and apply the styling to the field. This rerendering is expensive from a browser perspective,​ so we attempt to avoid it whenever possible.
 +
 +The ''​data-fc-error-for''​ is not required on the input itself - you can just add the ''​data-fc-error-class''​ attribute alone and FoxyCart will apply it to the input when an error occurs. ​
 +
 +Error classes are cleared in the same way they are added: FoxyCart checks the input to see if it has a ''​data-fc-error-class''​ attribute and removes the defined class from the input, if present, and then checks for a ''​data-fc-error-for="​FIELD_NAME"''​ and if one is found, removes the ''​data-fc-error-class''​ defined on the element, if present.
 +
 +The ''​data-fc-error-class''​ typically just takes a single class name as a string, but an additional "​success"​ class can be added after a comma, like this:
 +
 +<code html>
 +<div class="​alert alert-danger"​
 +    data-fc-error-for="​cc_cvv2"​
 +    data-fc-error-class="​show,​hidden"></​div>​
 +</​code>​
 +This will not only add the ''​show''​ class on error, but it will also //remove// the ''​hidden''​ class as well. When the error is cleared, it will toggle ''​show''​ off and toggle ''​hidden''​ on.
 +
 +=== 2. Error bar updating ===
 +
 +Once the field markup has been updated, FoxyCart updates the notifier bar at the top of the page to alert the user that a field has an error on it. This only occurs if the notifier bar is present. The markup for the bar is very simple, here's what it looks like in the default checkout template:
 +
 +<code html>
 +<section data-fc-error-notifier>​
 +  <h3 data-fc-notifier-text></​h3>​
 +</​section>​
 +</​code>​
 +
 +The ''​data-fc-error-notifier''​ attribute needs no value. Adding it to an element tells FoxyCart that all error messages should be added to this element. The ''​data-fc-notifier-text''​ attribute is optional, by default the message will be appended as a ''<​p>''​ element, if you wish to use a different text element, use the ''​data-fc-notifier-text''​ attribute. ​
 +
 +When a message is sent to the notifier bar, it checks the length of FC.JSON.messages.errors,​ and if there are errors present, the bar updates the count and adds the classes "alert alert-danger."​ All appearance and animations are handled with CSS and can be defined/​overridden in your custom style sheets.
 +
 +<wrap todo>​Class that is appended to be active user-definable.</​wrap>​
 +
 +=== 3. Error Event Firing ===
 +
 +The last step in error handling is firing a jQuery event that you can listen for to add your own customizations. ''​notificationUpdate''​ is fired on the ''<​body>''​ tag every time a message is sent or removed from FC.JSON.messages.errors. Listening for this event allows you to design custom ways of alerting the user that there are errors on the form, such as [[https://​github.com/​stanlemon/​jGrowl|jGrowl]] or something custom.
 +
 +**Hard errors** <wrap todo>​more info coming soon</​wrap>​
 +
 +
 +
 +==== Twig Templates & Conventions ====
 +All our templates are available (and automatically kept up-to-date) at GitHub: https://​github.com/​FoxyCart/​2.0-templates
 +You'll notice some conventions in those templates, and you'll need to be aware of those as you do your own customization.
 +
 +  * The Twig block names from the default templates must remain in place even with if you rewrite the template entirely.
 +  * The **checkout template** must include a block named ''​checkout'',​ and the ''​endblock''​ tag must also include the name. So <code twig>{% block checkout %}
 +{# stuff goes here #}
 +{% endblock checkout %}</​code>​ If you haven'​t done any customizations inside the ''​checkout''​ block (like if you're using ''​%%{{ block("​checkout"​) }}%%''​),​ this is already present. Unless you're doing major customizations,​ you won't have to worry about this.
 +  * Twig filenames are ''​partial.context.inc.twig'',​ like ''​address.checkout.inc.twig''​. The ''​context''​ piece is optional.
 +
 +
 +
 +
 +===== Making It Easy: AutoMagiCache =====
 +
 +TODO: add detailed walkthrough for 2.0 customization path.
 +
 +===== Caching Assets Manually =====
 +If for some reason you don't want to use AutoMagiCache to do things automatically,​ you can securely cache your ''​http''​ images on our server (''​https''​) by calling them like this:
 +<code html>
 +https://​YOURDOMAIN.foxycart.com/​cache.php?​url=http://​example.com/​path/​to/​image.gif
 +</​code>​
 +Please note that this will //only// work on your cart, checkout, and receipt pages. Again, this is done automatically if you cache your template using AutoMagiCache,​ so you only need to do this if you're not caching your template.
 +
 +
 +
 +
 +===== Getting Even More Advanced with Twig =====
 +
 +If you'd like to customize your templates beyond what you can do with HTML, CSS, and JavaScript, FoxyCart allows you to use the [[http://​twig.sensiolabs.org/​|Twig template language]] as well. Twig is flexible template language that's either near identical or relatively similar to a variety of other template languages. This functionality is very advanced, and most users should be able to achieve very very seamless visual integrations without this. If you have super specific needs, however, you can dig into Twig.
 +
 +==== Where Twig Is Used in FoxyCart ====
 +Twig is used in all FoxyCart templates:
 +  * The cart in all forms (HTML cart on the cart page, on the checkout and receipt, and on both HTML and plain text emails)
 +  * The checkout
 +  * The receipt
 +  * The email receipts (both HTML and plain text)
 +
 +==== Using Twig with FoxyCart ====
 +=== Understanding Twig ===
 +The first step is to review the [[http://​twig.sensiolabs.org/​doc/​templates.html|Twig for Template Designers]] at the official Twig site.
 +
 +=== Twig + FoxyCart ===
 +By default, you won't see any Twig syntax if you select the normal templates to start from. If you'd like to see the details of what's going on you can select the "​Twig"​ templates (with the radio buttons) for the template you're modifying. That will show you a bit more of Twig, like this (for the checkout):
 +
 +<code html>
 +    {% include '​svg.inc.twig'​ %}
 +
 +    {% import "​utils.inc.twig"​ as utils %}
 +    {% use '​checkout.inc.twig'​ %}
 +    {{ block('​checkout'​) }}
 +{# etc... #}
 +</​code>​
 +That might look complicated,​ but the basic idea is that each of the ''​%%{{ block('​foo'​) }}%%''​ tags loads a ''​block''​ from the ''​checkout.inc.twig''​ template, which is loaded via the ''​use''​ command. This view gives you the ability to move elements around pretty easily without needing to get //super// involved with giant chunks of HTML. It also allows you to override just specific portions of the HTML without needing to edit the entire massive template. (It's also really helpful for understanding the different elements and logic, even if you do end up using one of the full templates below.)
 +
 +If, however, you do want more control, you don't have to use the ''​block''​ and ''​use''​ method, and you can instead just start with the underlying default template and customize from there. You can fork the Github repo here: https://​github.com/​FoxyCart/​2.0-templates and include them directly in your website application. This will allow you to easily merge in any changes we make into your customizations,​ especially as you upgrade from one version to another.
 +
 +If you use any of the above linked files as a starting point, you can insert that raw Twig+HTML directly into your FoxyCart template (either directly in the admin or in your own templates for use with AutoMagiCache).
 +
 +=== Customizing the Cart ===
 +It's important to understand that there are two "​cart"​ templates. There'​s the "​full"​ cart template, which is what displays if you pull up ''​your_store.foxycart.com/​cart'',​ used for full-page cart displays as well as the iframe in the default Colorbox cart. But there'​s also the cart that's displayed on the checkout, the receipt, and the email receipts. The "​full"​ cart uses the "cart include"​ cart, just as the other templates do. So if you want to make a change to the cart system-wide (across the full cart, checkout, receipt, and email templates), you can edit the "cart include."​
 +
 +=== Allowed Twig Tags and Functionality ===
 +At present, the only allowed functionality for Twig is as follows:
 +
 +  * Tags: ''​if'',​ ''​for'',​ ''​include'',​ ''​macro'',​ ''​block'',​ ''​set'',​ ''​import''​
 +  * Filters: ''​abs'',​ ''​number_format'',​ ''​escape'',​ ''​raw'',​ ''​length'',​ ''​date_modify'',​ ''​replace'',​ ''​upper'',​ ''​lower'',​ ''​title'',​ ''​trim'',​ ''​date'',​ ''​url_encode'',​ ''​keys''​
 +  * Functions: ''​block'',​ ''​date'',​ ''​template_from_string''​
 +
 +===== Default Template Styles =====
 +As of v2.0, We've included a full responsive default theme which works on desktops, mobile devices and tables. We recommend using this team for the best customer checkout experience possible.
 +
 +===== AutoMagiCache Technical Details =====
 +==== What It Does ====
 +  - Pulls in target URL.
 +  - Strips any <​base>​ tags.
 +  - "​Convenience replacements",​ currently converting "​http"​ to "​https"​ links for:
 +    * Google Analytics
 +  - Imports non-secure external CSS
 +    * Rewrites all image paths (''​*.jpg'',​ ''​*.jpeg'',​ ''​*.png'',​ ''​*.gif''​) to use FoxyCart image caching.
 +    * Sticks it inline, inside CDATA comments.
 +  - Imports non-secure external JS
 +    * Replaces ''/​ /''​ with ''​\/​\/''​ when not preceded by a space or line break.
 +    * Replaces all ''</''​ with ''<​\/''​.
 +    * Sticks it inline, inside CDATA comments.
 +  - Rewrites all ''<​img>''​ paths to use FoxyCart image caching.
 +  - Rewrites all ''<​a>''​ paths to point to the correct locations.
 +  - Rewrites all ''<​form>''​ actions to point to correct locations.
 +
 +==== What Is Supported? ====
 +  * Most everything not listed below.
 +
 +==== Important Notes ====
 +  * **Linked Stylesheets if the ''​rel''​ attribute is after the ''​href''​ attribute.** This one is weird, and //​shouldn'​t//​ be a problem (the regex is perfect), but if you have ''<​link>''​ elements that aren't being cached, switch the order of the attributes and put the ''​rel="​stylesheet"''​ before the ''​href''​ attribute.
 +  * **Preventing Hotlinking?​** If you're running scripts to prevent hotlinking, that may interfere with the template caching. If images aren't showing up properly, turn off your hotlinking protection while you cache your templates.
 +  * **Attributes must be enclosed in single or double quotes** like ''​src="​foo/​bar"''​ or ''​src='​foo/​bar'''​.
 +  * **Your page must have a UTF-8 content type** so you may need to add this inside your document'​s head tag: ''<​meta http-equiv="​Content-Type"​ content="​text/​html;​ charset=utf-8"/>''​.
 +  * **Flash will not be cached**. Because it's near-impossible to "see inside"​ of a ''​swf''​ file, there'​s no good way to ensure that additional necessary files (like ''​xml'',​ ''​flv'',​ etc.) are cached along with the ''​swf''​ file itself.
 +  * **"​Upward relative paths"​** (stuff like ''​../​foo/​bar.ext''​) more than one level deep are not supported. ''​../​foo/​bar.ext''​ will work, but ''​../​../​foo/​bar.ext''​ will not. If you have a legitimate need for more than one level deep, [[http://​forum.foxycart.com|let us know]].
 +  * **''​@IMPORT''​ rules more than one level deep** are not supported. An import will work just fine, but an import inside an import won't be cached. If you have a legitimate need for more than one level deep, [[http://​forum.foxycart.com|let us know]].
 +  * **jQuery should not be included. The checkout will import its own jQuery.
 +  * **HTC files**. These //may// work if you're using a custom subdomain, but likely will not work if you're using a default ''​*.foxycart.com''​ subdomain.
 +
 +=== Notes on Fonts ===
 +Google fonts work great because they can be referenced via https. The cacher doesn'​t download font files, though, so if you really need a custom font, it will have to be embedded manually in the page. [[http://​www.fontsquirrel.com/​fontface/​generator|FontSquirrel]] can help with this. ([[http://​forum.foxycart.com/​discussion/​6564/​is-font-face-suppossed-to-work/​p1|ref]])
 +
 +=== Notes on JS Files ===
 +Twig has a hard time with some Javascript files (Modernizr in particular) because of some characters inside the parsed JS file that Twig reads as actual twig comments. To fix this, you can either put <​code>​{% raw %}</​code>​ and <​code>​{% endraw %}</​code>​ around your javascript includes or you can simply edit the file in particular to change <​code>​{#</​code>​ to <​code>​{ #</​code>​ and <​code>​{{</​code>​ to <​code>​{ {</​code>​
 +
 +=== Comments, Conditional Comments, and the Ampersand ("&"​) ===
 +For some reason, Firefox and Internet Explorer may have problems when you have the ampersand ("&"​) character inside of code comments:
 +<code html>
 +<!--
 +Some text & more
 +-->
 +</​code>​
 +This issue may be related to your doctype, so if you encounter this please [[http://​forum.foxycart.com/​|let us know]].
 +
 +If you utilise conditional style blocks to target just a particular browser (like Internet Explorer), AutoMagiCache will currently trip over if that is the last style tag included in your ''<​head>''​ section. Simply including a style tag after it will correct this issue:
 +<code html>
 +<!--[if IE 6]>
 +<style type="​text/​css>​
 +/* IE specific css */
 +</​style>​
 +<​![endif]-->​
 +<style type="​text/​css>​
 +/* Blank style */
 +</​style>​
 +</​code>​
 +
 +
 +{{page>​v:​2.0:​cheat_sheet#​view_data}}

Site Tools