Documentation You are here: start » v » 2.0 » templates » intermediate-automagicache

Table of Contents

Intermediate Template Customisation

Using your own design with AutoMagiCache

Working with FoxyCart Templates

A great way to keep a customer's trust in your brand is to maintain your own branding across the whole checkout flow. While the ability to include your logo in our default templates is a great first step, keeping a common visual style can be even better. Thankfully, embedding the cart, checkout and receipt into your own templates is quick and easy to do.

Step 1: Ready your template

You'll probably already have your own site designed that you're integrating FoxyCart into - but it may make sense to prepare a specific version of your page template just for the FoxyCart templates. By doing this, you can remove any assets that you use on your main site that aren't actually needed on your template. Common things that aren't generally needed are javascript libraries and feature specific stylesheets that won't be active on the FoxyCart checkout flow at all. By removing those, you bring the size of the page down, which makes loading the page for your customer even quicker.

We also recommend removing any unnecessary distractions and elements that might cause a customer to leave the checkout flow. For example, banners, signup forms and advertisements can be removed to keep the customers focus on completing their purchase. Otherwise it just provides more opportunities for customers to potentially abandon their purchase to complete a different task such as sign up for your newsletter.

You'll need three different templates - cart, checkout and receipt - so create three different copies of your template for that. Within the template, you should have the main section of the markup where the FoxyCart template will reside empty and ready for the FoxyCart code.

Step 2: Include the FoxyCart code

Styles

Within the <head> section of each template, include the following stylesheet to incorporate our default styles: 

{% for css_file_href in config.css_files %}
    <link href="{{ css_file_href }}" rel="stylesheet" media="all">
{% endfor %}

You don't need to change the href value there - that is a tag that our templating language will replace with the correct URL when it is rendered to the customer.

You'll also need to add an ID of fc to the parent element that you're inserting the FoxyCart template code inside of - so that these styles can be applied. We recommend applying this ID to a div that surrounds the checkout template code you'll paste in the next step, but you can alternatively apply it to the body tag or even the html tag. For example: 

<div id="fc">
<!-- Insert FoxyCart template logic here -->
</div>

Template

Within the main section of your template, paste the following code for the relevant template. Note that each of these three templates should be distinct files on your server, not all within one template.

Cart

{% set cart_is_fullpage = true %}
<div class="fc-context--cart-fullpage" data-fc-container="cart">
    {% embed 'cart.inc.twig' %}
    {% endembed %}
</div>

Also for the full page cart, you need to add this as an attribute of the body tag: 

data-fc-context='{"cart_is_fullpage":true}'

Checkout

{% include 'svg.inc.twig' %}
 
 {% import "utils.inc.twig" as utils %}
 {% embed 'checkout.inc.twig' %}
 {% endembed %}

Receipt

{% include 'svg.inc.twig' %}
 
 {% import "utils.inc.twig" as utils %}
 {% embed 'receipt.inc.twig' %}
 {% endembed %}

Emails

If you're wanting to customise the emails - we suggest jumping into your store's administration, and on the “emails” template page, select “custom” for the respective template and copy out the code contained within. This code will be the default template - and you'll need to edit this code to make any changes to how it's output.

Include Custom Code Placeholders

A great feature in 2.0 is allowing you to include custom code into your pages from within the administration. If you're rolling your own custom templates, it will probably make sense to include that custom aspects directly within your templates, but if you want to maintain the option, you need to include two extra lines in each of your templates.

Note that if you add custom code to your store's configuration page - you will need to complete this step in your custom templates.

Within the <head> section of your page, add this line: 

<!-- FC script insertion -->{{ fc_header_content|raw }}<!-- /FC script insertion -->

Right above the closing </body> tag of your page, add this line: 

<!-- FC footer script insertion -->{% include template_from_string(fc_footer_content) %}<!-- /FC footer scripts -->

Optional - Internet Explorer 8 & 9 support

If you would like to support IE 8 & 9 users, you'll also need to include some additional code in your templates:

Before any stylesheets, include the following code: 

<!--[if lt IE 9 ]>
    <script type="text/javascript">
        var IEElms = ['article', 'aside', 'header', 'main', 'nav', 'section'];
        for (var i = 0; i < IEElms.length; i++) {
            document.createElement(IEElms[i]);
        };
    </script>
    <script src="//{{ config.store_domain }}/static/scripts/respond/respond.1.4.2.js" charset="utf-8"></script>
<![endif]-->

Step 3: Upload your templates

In order for FoxyCart to securely cache your templates, they need to be publicly accessible online. Generally you'll be uploading it to where you upload your website as well. Just make sure they're accessible without needing to enter a password to view, and the URL doesn't redirect or change while the page loads - a direct URL to access them.

Step 4: AutoMagiCache!

Now the easy part! Jump into the FoxyCart administration and navigate to the template page you're looking to cache. Within the text input for “Remote template URL” enter the URL for the template you just uploaded online and press “Cache”. The system will then perform a process which we call “AutoMagiCache” in which it will save your template on our servers, and securely cache any assets such as images so that we can securely serve them to your customers. Once completed successfully, the page will update with your cached template visible in a text area — simply click “Save” to apply the new template and you're done!

The templates and, more importantly, their associated images and CSS should stay on your server at the specified URLs even after you've cached them. Otherwise the new servers that go online in our CDN would have nothing to cache and your templates would look broken.

Step 5: Styling

At this point, the FoxyCart templates will include your site design - but depending on your set up, you may then need to apply some specific CSS styling to bring our templates fully inline with your own page styling. We have utilised what's called the BEM naming method for the classes across the templates - which while does result in lengthy classes, it makes it easy to see where a given class would apply. It also means with how they're applied to the markup, you can apply custom styling using just one or two classes instead of having to stack ID's, classes and element names together to get what you want.

You can customize your styling in the TEMPLATES configuration settings by checking the Add custom header and footer code to your templates and inserting your styles in the custom header: text box like this: 

<style>
#fc .fc-form-control {
    background: #cc33cc;
}
</style>

This changes the background of entry boxes to magenta.

To see what classes you need to use, we recommend making use of an inspection tool - which most modern browsers will have built in. By using their inspection tools, you can select a given element on the page and the tool will show you the markup that outputs that element and you'll then be able to see the classes that apply to it.

For information on the different browser development tools - see the following:

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: 

https://YOURDOMAIN.foxycart.com/cache.php?url=http://example.com/path/to/image.gif

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.

Going Further

If you want to go even further with your customisations, such as making changes to the markup of the raw templates themselves, take a look at the Advanced Template Customisations section.

Common issues

"Error: Unclosed Comment Tag"

If you receive this error when caching your template, it's more than likely related to the inclusion of modernizer.js within your template. Modernizer includes a specific set of characters in their minified code that is interpreted by the template language as an open comment - specifically {#. As there isn't a matching closing tag of #}, this error is triggered.

To fix this error, you simply need to wrap the Modernizer asset in raw tags. That would look like this in your template: 

{% raw %}
<script src="../path/to/modernizer.js">
{% endraw %}

AutoMagiCache Technical Details

What It Does

  1. Pulls in target URL.
  2. Strips any <base> tags.
  3. “Convenience replacements”, currently converting “http” to “https” links for:
    • Google Analytics
  4. Imports non-secure external CSS
    • Rewrites all image paths (*.jpg, *.jpeg, *.png, *.gif) to use FoxyCart image caching.
    • Sticks it inline, inside CDATA comments.
  5. 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.
  6. Rewrites all <img> paths to use FoxyCart image caching.
  7. Rewrites all <a> paths to point to the correct locations.
  8. Rewrites all <form> actions to point to correct locations.

What Is Supported?

  • Most everything not listed below.

Important Notes

  • IE Conditional Stylesheets. Javascript is inserted automatically after the last detected stylesheet. This normally works, but if your last stylesheet is inside an IE conditional comment (like <!–[if lt IE 9 ]>), the javascript will be inserted into that comment. To fix this, put {{ fc_header_content|raw }} where you want the FoxyCart javascript to be inserted.
  • 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, 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, let us know.
  • **jQuery should not be included. The checkout will import its own jQuery.

Notes on Fonts

If you're wanting to include custom fonts within your templates, Google Fonts and Typekit work great for this because they can be referenced via https. If you're loading fonts manually though, and not using a service like this, as our caching system doesn't currently support caching font files, they won't work on your template.

In order to have them work, there are two approaches you can take. Firstly, if you have an SSL certificate for your own website, you can link to the font files using an absolute URL beginning with https. The secure templates for your store will then be able to load the font files directly from your server securely as well.

If you don't have an SSL certificate for your own site, and you really need a custom font, it will have to be embedded manually in the page. FontSquirrel can help with this (ref). Upload the fonts there, and select “Expert” mode. Within the configuration options that appear, on the line for “CSS”, check the “Base64 Encode” checkbox, and then click to complete the process at the bottom. From the resulting files that you download, you should be able to look in the CSS file it provides, and within that will be the styles that have the font files included directly within the CSS. If you use that on your cart/checkout/receipt templates instead of referencing the font URL on your own server - then they can be securely used on those pages. Just to clarify, you can continue referencing the fonts directly on your server for your own site, it's just for the FoxyCart cart, checkout and receipt templates you'd need to switch to the inline Base64 encoded versions.

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 {% raw %} and {% endraw %} around your javascript includes or you can simply edit the file in particular to change {# to { # and {{ to { {

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: 

<!--
Some text & more
-->

This issue may be related to your doctype, so if you encounter this please 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: 

<!--[if IE 6]>
<style type="text/css>
/* IE specific css */
</style>
<![endif]-->
<style type="text/css>
/* Blank style */
</style>

Page Tools

Site Tools