type:
integration
system:
Craft CMS
name:
Craft CMS + FoxyCart
description:
Notes for integrating FoxyCart and Craft CMS
tag:
cms
date:
2014-06-20

CraftCMS

Craft is a great CMS, really well built, very power and extensible, but still nice and simple to use. FoxyCart is built to integrate and Craft is built to be integrated with - sounds like a great match!

Before getting started

These instructions assume you already have Craft installed somewhere. If you haven't already - jump over to the Craft documentation to run through the installation process, and reference it for any queries you may have about specific Craft functionality. Their documentation is great! There is also a great community support system available at http://craftcms.stackexchange.com if you have any questions about Craft.

Integrate FoxyCart Functionality

In order for FoxyCart to use the modal window and maintain sessions across the different domains, you need to add a few lines of includes to your websites head section. To get the correct FoxyCart include files for your store, navigate to the “Sample Code” section of the FoxyCart administration and copy them from there.

The easiest way to do that is to edit the _layout.html file in /craft/templates/, as that way it will also cascade on to any other templates that extend from it. If you're creating other parent template files, you'll need to include it there as well. Simply open that file and paste in the three lines of code found in the “Sample Code” section, right above the closing </head> tag.

Now, at this point you actually have a working FoxyCart integration. All you need to do now is just insert add to cart links and forms on any page. If you're running a simple site, you could pretty easily insert add to cart links using the text editor available for each page. You could also add in forms using the HTML editor - although that may get a little tedious to do.

Craft FoxyCart plugin

A plugin for Craft has been created that assists with some of the more advanced features of FoxyCart to make it easier to create a tighter integration between Craft and FoxyCart.

To install the plugin, head over to the Github repository and follow the instructions there.

Creating products within Craft

Craft has some great functionality built-in that allows you to create custom page structures in the way of “sections”, which you could use to create your own little product system. That would allow you to manage products from within the interface, rather than creating links or forms manually.

Create fields

Firstly navigate to “Settings > Fields”, and create a new group of fields for 'Products'. Within it, create the following fields:

Name: Name
Handle: product_name
Field Type: Plain Text

Name: Price
Handle: price
Field Type: Number
Decimal Points: 2

Those two fields are the only required pieces of information you need for a product to be valid with FoxyCart. There are some other default product attributes that come with FoxyCart that you can see here, but then you can also create any other sort of custom fields you want. For example, say you were wanting to include a product code, make use of FoxyCart's categories to apply different settings to products, include an image, and include a dropdown for colour options, that might look like this:

Name: Code
Handle: code
Field Type: Plain text

Name: Category
Handle: foxycart_category
Field Type: FoxyCart Category
Note: This field automatically fetches your stores categories, and caches the results for 10 minutes.

Name: Image
Handle: image
Field Type: Assets
Restrict allowed?: Image
Limit: 1
Note: You will need to configure an asset source if you haven't already, and you can do that under “Settings > Assets”.

Name: Colour
Handle: colour
Field Type: Table
Table Columns:

  • Column Heading: Label
  • Handle: label
  • Type: Single-line Text
  • Column Heading: Value
  • Handle: value
  • Type: Single-line Text
  • Column Heading: Default?
  • Handle: default
  • Type: Checkbox
  • Width: 45

Create section

Now navigate to 'Settings > Sections', and create a new section. Give it a name of “Product”, handle of “products” and a section type of “Channel”. Also set the Entry URL Format to “store/{slug}” and the Entry Template to “store/_product”.

Once that is created, click on the 'Edit entry type' that appears next to it's listing in the “Sections” page and then the “Product” option that appears. Uncheck the “Show title fields” checkbox and enter “{heading}” in the Title Format text box that appears. Down the bottom, create two tabs in the “Design your field layout” section. Name the first tab 'Default' and place in there the “Heading” and “Body” fields. Then name the second tab “Product” and add in any product fields you created in the previous step - making the “Heading”, “Name”, “Price” and “Code” fields required by clicking on the cog icon next to their labels.

Save those changes.

Set up templates

With the admin structure all good to go, now we have to get the templates set up. Open up /craft/templates and create a folder called store, and two files within it: index.html and _product.html.

index.html

{% extends "_layout" %}
{% set title = "Store" %}
 
{% block content %}
    <h1>Store</h1>
 
    {% for entry in craft.entries.section('products').find() %}
        <article>
            {% set image = entry.image.first() %}
            {% if image %}
                <img src="{{ image.url }}" alt="{{ entry.title }}" />
            {% endif %}
            <h3><a href="{{ entry.url }}">{{ entry.title }}</a></h3>
            <p>${{ entry.price }}</p>
            <p><a href="{{ entry.url }}">View product</a></p>
        </article>
    {% endfor %}
{% endblock %}

_product.html

{% extends "_layout" %}
 
{% block content %}
    {% set image = entry.image.first() %}
 
    <article>
        <h2>{{ entry.title }}</h2>
        <h3>${{ entry.price }}</h3>
        {% if image %}
            <img src="{{ image.url }}" alt="{{ entry.title }}" />
        {% endif %}
        {{ entry.body }}
        <form action="https://{{ craft.foxyCart.storedomain }}/cart" method="post" accept-charset="utf-8">
            <input type="hidden" name="name" value="{{ entry.product_name }}" />
            <input type="hidden" name="price" value="{{ entry.price }}" />
            <input type="hidden" name="code" value="{{ entry.code }}" />
            <input type="hidden" name="category" value="{{ entry.foxycart_category }}" />
            {% if image %}
                <input type="hidden" name="image" value="{{ image.url }}" />
            {% endif %}
            <label for="quantity">Quantity</label>
            <input type="number" id="quantity" name="quantity" value="1" />
            {% if entry.colour | length %}
                <label for="colour">Colour</label>
                <select name="colour" id="colour">
                    {% for row in entry.colour %}
                        <option value="{{ row.value }}" {% if row.default %}selected{% endif %}>{{ row.label }}</option>
                    {% endfor %}
                </select>
            {% endif %}
            <input type="submit" value="Add to cart" class="submit" />
        </form>
    </article>
{% endblock %}

Add some products!

Now with all of that done, you can jump back into the administration, and within the “Entries” section, add some products to the store section and test it all out!

Minicart display

What about letting people see how many items they have in their cart? Easy. Simply open up the _layout.html file again, and paste in the following code wherever you'd like it displayed - probably within the header somewhere (replacing the store URL with your correct store domain):

<a href="https://{{ craft.foxyCart.storedomain }}/cart?cart=view" id="fc_minicart">
	<span class="fc_quantity">0</span> <span class="fc_singular">item</span><span id="fc_plural">items</span> | $<span class="fc_total_price">0.00</span>
</a>

You may have to apply some custom styles to get it to position exactly how you want - but the javascript you added in the first step will take care of filling out the information as required. See this page for more details on how the minicart works.

Simple as that!

Getting FoxyCart integrated into Craft CMS is as simple as that - and thanks to the flexibility and power of Craft, you can very quickly and easily set up products that match exactly the structure your products need. You can also display them however you need, with complete control over the templates for Craft, as well as the templates for your FoxyCart store.

Obviously you'll need to apply some styling love to the templates - this should at least give you a great starting point to getting a FoxyCart powered store into your Craft website.

Other Plugin Features

Link/Form Validation

If you'd like to make use of our link and form validation to prevent possible tampering, you simply need to wrap your links and forms, or the whole page, within {% hmac %} and {% endhmac %} tags. Note that you also need to enable this option on the 'advanced' settings page of your store's FoxyCart administration. Taking the _product.html template from before:

{% extends "_layout" %}
 
{% block content %}
    {% set image = entry.image.first() %}
 
    <article>
        <h2>{{ entry.title }}</h2>
        <h3>${{ entry.price }}</h3>
        {% if image %}
            <img src="{{ image.url }}" alt="{{ entry.title }}" />
        {% endif %}
        {{ entry.body }}
        {% hmac %}
        <form action="https://{{ craft.foxyCart.storedomain }}/cart" method="post" accept-charset="utf-8">
            <input type="hidden" name="name" value="{{ entry.product_name }}" />
            <input type="hidden" name="price" value="{{ entry.price }}" />
            <input type="hidden" name="code" value="{{ entry.code }}" />
            <input type="hidden" name="category" value="{{ entry.foxycart_category }}" />
            {% if image %}
                <input type="hidden" name="image" value="{{ image.url }}" />
            {% endif %}
            <label for="quantity">Quantity</label>
            <input type="number" id="quantity" name="quantity" value="1" />
            {% if entry.colour | length %}
                <label for="colour">Colour</label>
                <select name="colour" id="colour">
                    {% for row in entry.colour %}
                        <option value="{{ row.value }}" {% if row.default %}selected{% endif %}>{{ row.label }}</option>
                    {% endfor %}
                </select>
            {% endif %}
            <input type="submit" value="Add to cart" class="submit" />
        </form>
        {% endhmac %}
    </article>
{% endblock %}

Webhooks

Navigate to the FoxyCart Craft plugin's settings page and copy the webhooks action URL from the lower section of the page, and set that within the 'advanced' settings section of your store's FoxyCart administration.

If you need to perform custom actions with that data (for example, you may need to subscribe a customer to a mailing list), you can make use of the foxyCart.onProcessWebhook event. The event contains two parameters, xml which contains the decrypted XML from the webhook payload and type which will either be transaction or subscription dependant on the type of webhook that has been triggered. If you don't have an existing custom plugin for your custom Craft code, we recommend utilising the Business Logic plugin.

craft()->on('foxyCart.onProcessWebhook', function(Event $event) {
    $xml = $event->params['xml']; // The decrypted XML payload
    $feedType = $event->params['type']; // "transaction" or "subscription"
 
    // .. your code
});

For an example of the payload you'll receive, you can review those on their respective wiki pages - transaction datafeed and subscription datafeed.

Single Sign-On

SSO functionality requires a Craft Pro subscription

To activate SSO for your Craft website, first jump into the Craft plugin's settings page and copy the SSO action URL and paste it into the 'advanced' settings section of your store's FoxyCart administration. Within the Craft plugin's settings page, you will then need to enable SSO, and optionally require customers login on your own website first (you'll need to create the login interface for that) and also what user group they will be added to by default. Finally, synchronising users with your Craft website requires that you allow public registrations within settings > users > settings

Taking this further

While this integration covers a lot of ground getting FoxyCart integrated into a Craft website, it can certainly be taken even further. If you'd like to add additional features and functionality into the FoxyCart plugin for Craft, feel free to submit a pull request.

Site Tools