====== Intermediate Template Customisation ====== ===== Using your own design with AutoMagiCache ===== **Working with FoxyCart Templates** * [[v:2.0:templates|Basic Customizations]]\\ Utilising the new configuration option for common changes * [[v:2.0:templates:intermediate-automagicache|Intermediate Customizations]]\\ Incorporating your own designs in the FoxyCart templates * [[v:2.0:templates:advanced|Advanced Customizations]]\\ Altering the raw templates * [[v:2.0:templates:primer|FoxyCart Templates and Caching Primer]] * [[v:2.0:templates:view_data|Template View Data]]\\ Cheatsheet for the variables accessible on the 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 '''' section of each template, include the following stylesheet to incorporate our default styles:

{% for css_file_href in config.css_files %}
    
{% 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:

==== 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 %}

    {% embed 'cart.inc.twig' %}
    {% endembed %}

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 '''' section of your page, add this line: {{ fc_header_content|raw }} Right above the closing '''' tag of your page, add this line: {% include template_from_string(fc_footer_content) %} ==== 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:

===== 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:

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: * [[https://developer.chrome.com/devtools|Chrome]] * [[https://developer.apple.com/safari/tools/|Safari]] * [[https://developer.mozilla.org/en-US/docs/Tools/Page_Inspector|Firefox]] * [[http://msdn.microsoft.com/library/ie/bg182326(v=vs.85)|Internet Explorer]] * [[https://getfirebug.com/|Firebug (Plugin available for browsers)]] ===== 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 [[v:2.0:templates:advanced|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 %}