Both sides previous revisionPrevious revisionNext revision | Previous revision |
integration:craftcms [2014/06/30 05:34] – [Links and Forms] adam | integration:craftcms [2019/01/22 14:14] (current) – [Webhooks] adam |
---|
---- dataentry ---- | ---- dataentry ---- |
type : integration # do not change this line | type : integration # do not change this line |
systems : CraftCMS # the system(s) that the integration is for, separated with commas if more than one | systems : Craft CMS # the system(s) that the integration is for, separated with commas if more than one |
name : CraftCMS + FoxyCart # the name of the integration | name : Craft CMS + FoxyCart # the name of the integration |
description : Notes for integrating FoxyCart and Craft CMS # | description : Notes for integrating FoxyCart and Craft CMS |
tags : cms # tags, separated by commas. don't include the "system" here. | tags : cms # tags, separated by commas. don't include the "system" here. |
date_dt : 2014-06-20 # the date in YYYY-MM-DD format | date_dt : 2014-06-20 # the date in YYYY-MM-DD format |
developer_url : # if you'd like a link back to your site, stick it here | developer_url : # if you'd like a link back to your site, stick it here |
---- | ---- |
| |
| |
| |
[[http://buildwithcraft.com/|{{ :integration:craft_logo.png?nolink&150|}}]] | [[http://buildwithcraft.com/|{{ :integration:craft_logo.png?nolink&150|}}]] |
[[http://buildwithcraft.com/|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! | [[http://buildwithcraft.com/|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! |
| |
Until a more formal FoxyCart + Craft integration is created, this page will list some starting information about using FoxyCart with CraftCMS. | |
| |
===== Before getting started ===== | ===== Before getting started ===== |
| |
Now, at this point you actually have a working FoxyCart integration. All you need to do now is just insert [[http://wiki.foxycart.com/getting_started:adding_links_and_forms|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. | Now, at this point you actually have a working FoxyCart integration. All you need to do now is just insert [[http://wiki.foxycart.com/getting_started:adding_links_and_forms|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 [[https://github.com/FoxyCart/foxycart-craft|Github repository]] and follow the instructions there. |
| |
===== Creating products within Craft ===== | ===== Creating products within Craft ===== |
| |
| {{ :integration:craft_admin_full.jpg?nolink |}} |
| |
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. | 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 ==== | ==== Create fields ==== |
{{ :integration:craft_fields.jpg?400|}} | {{ :integration:craft_fields.jpg?400|}} |
**Decimal Points:** 2 | **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 [[http://wiki.foxycart.com/getting_started:adding_links_and_forms|see here]], but then you can also create any other sort of custom fields you want. For example, say you were making use of FoxyCart's categories to apply different settings to products, and also include an image, that might look like this: | 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 [[http://wiki.foxycart.com/getting_started:adding_links_and_forms|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\\ | **Name:** Category\\ |
**Handle:** ''foxycart_category''\\ | **Handle:** ''foxycart_category''\\ |
**Field Type:** Dropdown\\ | **Field Type:** FoxyCart Category\\ |
**Options:** \\ | **Note:** This field automatically fetches your stores categories, and caches the results for 10 minutes. |
* Default | DEFAULT | |
* Other Category | other-category-code | |
**Note:** This field would relate to the actual categories set up in your FoxyCart store. | |
| |
**Name:** Image\\ | **Name:** Image\\ |
**Note:** You will need to configure an asset source if you haven't already, and you can do that under "Settings > Assets". | **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 ==== | ==== Create section ==== |
{{ :integration:craft_field_layout.jpg?400|}} | {{ :integration:craft_field_layout2.jpg?400|}} |
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". | 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 "Name" and "Price" fields required by clicking on the cog icon next to their labels. | 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. | Save those changes. |
| |
{% block content %} | {% block content %} |
<h1>Store</h1> | <h1>Store</h1> |
| |
{% for entry in craft.entries.section('products').find() %} | {% for entry in craft.entries.section('products').find() %} |
<article> | <article> |
{% set image = entry.image.first() %} | {% set image = entry.image.first() %} |
{% if image %} | {% if image %} |
<img src="{{ image.url }}" alt="{{ entry.title }}" /> | <img src="{{ image.url }}" alt="{{ entry.title }}" /> |
{% endif %} | {% endif %} |
<h3><a href="{{ entry.url }}">{{ entry.title }}</a></h3> | <h3><a href="{{ entry.url }}">{{ entry.title }}</a></h3> |
<p>${{ entry.price }}</p> | <p>${{ entry.price }}</p> |
<p><a href="{{ entry.url }}">View product</a></p> | <p><a href="{{ entry.url }}">View product</a></p> |
</article> | </article> |
{% endfor %} | {% endfor %} |
{% endblock %} | {% endblock %} |
</code> | </code> |
| |
=== _product.html === | === _product.html === |
| |
Make sure you replace the store domain in the add to cart form in this code. | |
| |
<code html>{% extends "_layout" %} | <code html>{% extends "_layout" %} |
| |
{% block content %} | {% block content %} |
{% set image = entry.image.first() %} | {% set image = entry.image.first() %} |
| |
<article> | <article> |
<h2>{{ entry.title }}</h2> | <h2>{{ entry.title }}</h2> |
<h3>${{ entry.price }}</h3> | <h3>${{ entry.price }}</h3> |
{% if image %} | {% if image %} |
<img src="{{ image.url }}" alt="{{ entry.title }}" /> | <img src="{{ image.url }}" alt="{{ entry.title }}" /> |
{% endif %} | {% endif %} |
{{ entry.body }} | {{ entry.body }} |
| <form action="https://{{ craft.foxyCart.storedomain }}/cart" method="post" accept-charset="utf-8"> |
<form action="https://yourstore.foxycart.com/cart" method="post" accept-charset="utf-8"> | <input type="hidden" name="name" value="{{ entry.product_name }}" /> |
<input type="hidden" name="name" value="{{ entry.product_name }}" /> | <input type="hidden" name="price" value="{{ entry.price }}" /> |
<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 }}" /> | <input type="hidden" name="category" value="{{ entry.foxycart_category }}" /> |
{% if image %} | {% if image %} |
<input type="hidden" name="image" value="{{ image.url }}" /> | <input type="hidden" name="image" value="{{ image.url }}" /> |
{% endif %} | {% endif %} |
<label for="quantity">Quantity</label> | <label for="quantity">Quantity</label> |
<input type="number" id="quantity" name="quantity" value="1" /> | <input type="number" id="quantity" name="quantity" value="1" /> |
<input type="submit" value="Add to cart" class="submit" /> | {% if entry.colour | length %} |
</form> | <label for="colour">Colour</label> |
</article> | <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 %} | {% endblock %} |
</code> | </code> |
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): | 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): |
<code html> | <code html> |
<a href="https://yourdomain.foxycart.com/cart?cart=view" id="fc_minicart"> | <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> | <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> | </a> |
===== Simple as that! ===== | ===== Simple as that! ===== |
| |
{{ :integration:craft_site.jpg?400|}} | {{ :integration:craft_site2.jpg?400|}} |
Getting FoxyCart integrated into CraftCMS 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. | |
| 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. | 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 [[static:redirect:price_validation|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: |
| |
| <code 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 }} |
| {% 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 %} |
| </code> |
| |
| ==== 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 [[https://github.com/lindseydiloreto/craft-businesslogic|Business Logic plugin]]. |
| |
| <code php> |
| craft()->on('foxyCart.onProcessWebhook', function(Event $event) { |
| $xml = $event->params['xml']; // The decrypted XML payload |
| $feedType = $event->params['type']; // "transaction" or "subscription" |
| |
| // .. your code |
| }); |
| </code> |
| |
| For an example of the payload you'll receive, you can review those on their respective wiki pages - [[v:2.0:transaction_xml_datafeed|transaction datafeed]] and [[v:2.0:subscription_xml_datafeed|subscription datafeed]]. |
| ==== Single Sign-On ==== |
| |
| <WRAP center round info 90%> |
| SSO functionality requires a Craft Pro subscription |
| </WRAP> |
| |
| 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 ===== | ===== Taking this further ===== |
| |
Craft has some really great functionality that we haven't even touched on here that could make for a really tight integration with FoxyCart, and has the potential for a awesome plugin to be developed that would benefit both the FoxyCart and CraftCMS community. If that sounds like something you'd be interested in, [[http://www.foxycart.com/contact|get in touch with the team at FoxyCart]] and have a chat! | 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 [[https://github.com/FoxyCart/foxycart-craft|submit a pull request]]. |