====== Template Sets ======

FoxyCart's template sets introduces the ability to group different settings together into a container which you can switch between based on the requirements for your store. Initially this is restricted to just the language and locale for your store - but we'll be expanding on it moving forward to incorporate more aspects of a FoxyCart store.

Right now, the template sets feature adds native [[v:2.0:i18n|multilingual]] and [[v:2.0:multicurrency|multicurrency]] functionality to FoxyCart stores. They can be managed from the "Template Sets" section of your store's FoxyCart administration, found under the "Templates" column of the navigation.

Some common configurations that template sets allow for:

  * [[v:2.0:i18n|Multiple languages]] for a single store - with a template set for each different language
  * Supporting [[v:2.0:multicurrency|multiple currencies]], adding a template set per currency you need
  * A combination of multiple languages and currencies - a template set per combination
  * Customising language strings for different needs - extra template sets for the same language, but customising specific strings in certain template sets
  * Unique payment gateway configurations for each template set, using the [[v:2.0:payment_sets|payment sets]] functionality

===== Adding a Template Set =====

You can add a new template set by navigating to the "Template Sets" section and selecting "Add a new Template Set" in the "Select a template set" select option.

  ; Template set code
  : This is the actual code sent as the ''template_set'' parameter to the cart.
  ; Description
  : A descriptive name for this template set that will help you determine what it will be used for.
  ; Language
  : This is the language file for this template set which will be used for all dialogs and messages seen by your store customers. You can customize all of these values on the "Language" section of your store's administration. If you would like to see more default supported languages, [[http://www.foxycart.com/contact|please let us know]].
  ; Locale
  : This is the locale for this template set. This setting will determine how FoxyCart formats your currency display and date/time format.
  ; Payment set
  : This setting determines which [[v:2.0:payment_sets|payment set]] to use to determine the payment options available on the checkout when this template set is active.


Your store will always have a default template set which can not be removed, and it's code and description is read-only. This template set forms the default language and locale that your store will have if no specific custom template set has been specified for the cart session. The store locale from the "settings" section of the administration is the same setting as the locale for the default template set as well - changing one will also change the other.

===== Applying a template set =====

A template set can be applied to a cart in a number of ways - but at it's root, it's simply specified using the ''template_set'' parameter in a cart request, passing in the code of the template set you're wanting to apply.

If a template set is applied which changes the locale of the current cart session, any existing products will be removed. Products added within the same request will be added normally.

==== Within an add to cart ====

The ''template_set'' attribute is session-wide, and can be applied simply with your existing add to carts:

<code html>
<a href="https://YOURSTORE.foxycart.com/cart?name=My+Product&price=20&code=sku123&template_set=fr">Add My Product</a>

<form action="https://YOURSTORE.foxycart.com/cart" method="post">
    <input type="hidden" name="name" value="My Product" />
    <input type="hidden" name="price" value="20" />
    <input type="hidden" name="code" value="sku123" />
    <input type="hidden" name="template_set" value="fr" />
    <input type="submit" value="Add My Product" class="submit" />
</form>
</code>

==== As part of a language/currency selector ====

Commonly, when working with [[v:2.0:i18n|multilingual]] or [[v:2.0:multicurrency|mulitcurrency]] stores - you'll have some form of language or currency selection for customers on your website. This could be simply add to cart requests like above:

<code html><p class="foxy_lang">Select a language: <a href="https://YOURSTORE.foxycart.com/cart?template_set=en">English</a> | <a href="https://YOURSTORE.foxycart.com/cart?template_set=fr">French</a> | <a href="https://YOURSTORE.foxycart.com/cart?template_set=de">German</a></p>
</code>

With using straight HTML like that - the links will trigger the cart to show. If you want to perform the template set change in the background, you can perform a [[v:2.0:json|JSONP]] cart request in the background based on that selection to switch the cart's template set for the customers session. Include this code on your website with your existing javascript (for example, right before the closing ''</body>'' tag:

<code javascript>
<script>
$(document).ready(function() {
    $(".foxy_lang").on("click", "a", function(e) {
        FC.client.request($(this).attr("href")).done(function() {
            // Show a visual response that it's updated
        });
        return false;
    });
});
</script>
</code>

==== On page load (if it's not already set) ====

If you have separate websites, where each site matches a different template set, you can also use javascript to dynamically set the respective template set on page load. This removes the need for the customer to select the language, and just automatically sets it if it's not already set. You would include this code as part of your website template with your other javascript, right before the closing ''</body>'' tag:

<code javascript>
<script>
var FC = FC || {};
FC.onLoad = function() {
    FC.client.on("ready.done", function() {
        var template_set = "my-template-set";

        var existing_template_set = (FC.json.template_set == "") ? "DEFAULT" : FC.json.template_set;
        if (existing_template_set != template_set) {
            FC.client.request('https://' + FC.settings.storedomain + '/cart?template_set=' + template_set);
        }
    });
};
</script>
</code>

Within that code you will need to update the ''my-template-set'' string to match the template set code that you want that particular page to use.
===== Determining the current template set =====

The cart's current template set is available within the cart JSON object, as ''FC.json.template_set'' in javascript, and ''%%{{%% template_set %%}}%%'' in Twig.