Documentation

Getting Started

As a prerequisite, Magic Data and eCommerce must already be installed before you install Magic Data Commerce.

Whilst not required by the installation process, you should also install Magic Data Symbols. In addition to the general symbols provided, the list processing symbols APPLY_EACH and FILTER_LIST will come in very useful when you want to work with product sets, carts or orders.

You will also need a further addon to process Magic Data tokens within non-eCommerce blocks. The easiest option here is Magic Data Templates, but you could also use a Magic Data enabled theme such as Magic Yogurt, the event driven Magic Data On Block Load processor, or many of the addons that come Magic Data enabled such as Pro Blog.

Before using Magic Data from the front end of your site, go to Dashboard > Magic Data > Symbols to the Magic Data - Symbols page.

Here you can browse the symbols available and familiarise yourself with some of the capabilities they provide.

Also on this page is the Symbol evaluation tester. You will find this invaluable when writing tokens. You can just enter the symbols of your token here and try them out, with a complete diagnostic on the various stages of evaluation. It can also be a very helpful tool for developers writing new tokens in php.

All the examples here assume the standard eCommerce sample content. You will need to generalise these examples to the content of your eCommerce project. You will also want to have some orders in various states of approval and some products in your cart while working through the exercises.

Showing product information

A couple of simple expressions to get you started.

Enter:

SET "Marvin Mandarin" CONTEXT Product AS_PRODUCT PRODUCT_PRICE

The expression evaluates to:

25

This could be better, so append the symbol FORMAT_PRICE:

SET "Marvin Mandarin" CONTEXT Product AS_PRODUCT PRODUCT_PRICE FORMAT_PRICE

Now it evaluates to:

$25.00

You will probably want to show a bit more information. Perhaps combining the above with the product name and quantity in stock. Remember that you can always put multiple tokens within the text of a regular block, so you don't have to do everything within Magic Data.

Using with page attributes

A good application of Magic Data is to do stuff with page attributes. For example, you could add a text attribute "Promotion" to a page and enter the text "Marvin Mandarin" to that attribute.

Now you can do:

CID ATTRIBUTE Promotion CONTEXT Product AS_PRODUCT PRODUCT_NAME

To get the name of the promoted product from a page attribute and then:

CID ATTRIBUTE Promotion CONTEXT Product AS_PRODUCT PRODUCT_SPECIAL_PRICE FORMAT_PRICE

To get the special offer price from eCommerce.

Within a content block you could then write:

Today's special promotion is [% ….. %] at a price of just [% .…. %].

With our above two tokens inserted where we have [% ... %].

Ideally, you don't just want the product, but a link to the product page. That requires a small change to the first expression:

CID ATTRIBUTE Promotion CONTEXT Product AS_PRODUCT PRODUCT_PAGE_LINK

Now, you have a snippet of text and a couple of Magic Data symbols you can insert into a page and it will show a link and price to whatever product you give in the Promotion attribute. When you want to change the promotion, you only have to change the attribute, not the content of the page, and the page will adapt.

You could also add product image thumbnails, using the symbol PRODUCT_THUMBNAIL.

Taking it further

Lets look at another way of creating this, using memories. It may look more complex now, but it will come in useful later. Think of Magic Data memories like you would using the memories on a pocket calculator. They enable us to break a sequence of symbols up into parts, saving the result of each part, then assemble the result from those remembered parts.

( CID ATTRIBUTE Promotion CONTEXT Product AS_PRODUCT PRODUCT_PAGE_LINK SAVE m1 )
( CID ATTRIBUTE Promotion CONTEXT Product AS_PRODUCT PRODUCT_PRICE FORMAT_PRICE SAVE m2 )
SET "Today's special promotion is {{m1}} at a price of just {{m2}}" FORMAT

This uses Magic Data's FORMAT symbol to pull a previously saved value. We have now put all of our text into a single Magic Data token, so we could add the special promotion text into any content by simply wrapping the whole of the above in [% ….. %]

It may seem an unnecessary complexity, but now we can use the whole lot within a list or make it conditional on a user being logged in:

UID IF
( SET "By registering as a user you can benefit from many special promotions." )
(
( CID ATTRIBUTE Promotion CONTEXT Product AS_PRODUCT PRODUCT_PAGE_LINK SAVE m1 )
( CID ATTRIBUTE Promotion CONTEXT Product AS_PRODUCT PRODUCT_PRICE FORMAT_PRICE SAVE m2 )
SET "Today's special promotion for registered users is {{m1}} at a price of just {{m2}}" FORMAT
)

Here, the IF symbol will return one of the two following expressions depending on UID. UID is null/false if no user is logged in. Note that parenthesis " ( " will only be treated as a magic data symbol if it is surrounded by white space.

To put these symbol expressions as tokens within a regular content block you will need to remove all the new lines or they will get mauled. Or you could put the token within an HTML block and keep the white space.

[% UID IF ( SET "By registering as a user you can benefit from many special offers." ) ( ( CID ATTRIBUTE Promotion CONTEXT Product AS_PRODUCT PRODUCT_PAGE_LINK SAVE m1 ) ( CID ATTRIBUTE Promotion CONTEXT Product AS_PRODUCT PRODUCT_PRICE FORMAT_PRICE SAVE m2 ) SET "Today's special promotion is {{m1}} at a price of just {{m2}}" FORMAT ) %]

Introducing Lists

Now lest look at lists within Magic Data Commerce. There are several kinds of lists we can process. Lists of products in product sets, the content of a shopping cart or the content of an order.

On my test site, I have just placed an order.

LIST_ORDERS LIST_ORDER

Will list all orders for the current user (me) and, by default, return the most recent order. You can also index into a list using the INDEX symbol It will then list the products in that order.

["5","1","6"]

A list of product numbers is not much use, so lets translate that into product names and add some formatting to it:

LIST_ORDERS LIST_ORDER APPLY_EACH PRODUCT_PAGE_LINK END_APPLY_EACH IMPLODE_NICELY

Evaluating gives links to:

Rick Ruddy, Marvin Mandarin and His & Hers Mandarins

You will find APPLY_EACH / END_APPLY_EACH regularly useful for applying the same processing to each element of a list. As they are regular Magic Data symbols, I wont go into fine detail here.

The no-order case

What happens if someone doesn't have an order? LIST_ORDERS will return null. Everything that follows can be skipped by inserting END_ON_NULL to end a subexpression.

LIST_ORDERS END_ON_NULL LIST_ORDER APPLY_EACH PRODUCT_PAGE_LINK END_APPLY_EACH IMPLODE_NICELY

Most recent order

We can combine this with our previous example to provide a customer with a reminder of their most recent order:

LIST_ORDERS END_ON_NULL LIST_ORDER APPLY_EACH SAVE m1
( m1 RETRIEVE PRODUCT_PAGE_LINK SAVE m2 )
( m1 RETRIEVE PRODUCT_PRICE FORMAT_PRICE SAVE m3 )
( "{{m2}} : {{m3}}" FORMAT )
END_APPLY_EACH IMPLODE_NICELY

Here we apply a sequence to all items in the order. First we save the product to m1, then retrieve the product so we can get a product link and a price for it, saving each, then format those results, and finally turn it into a nicely formatted list.

For my recent order, I get:

Rick Ruddy : $18.00, Marvin Mandarin : $25.00 and His & Hers Mandarins : $155.00

To use this, you may want to combine it with the IF example so as to provide a different output if the user has not previously placed an order and to add some text along the lines of "Products in your most recent order [% ….. %]".

Another trick is to combine this with assigning users to groups on purchase. That way, you can use blocks shown by permissions to thos who have or have not purchased from your site.

Personalised order status

By now the possibilities should be bubbling in your mind. Here is a much more complicated symbol expression that will greet users with a personalised message about their order status:

( UID USERNAME SAVE m1 )
( ( LIST_ORDERS END_ON_NULL LIST_ORDER APPLY_EACH PRODUCT_PAGE_LINK END_APPLY_EACH IMPLODE_NICELY ) SAVE m2 )
LIST_ORDERS ORDER_STATUS SWITCH "Pending|Payment Incomplete|Authorized|Shipped|Complete|Cancelled"
( 'Hello {{m1}}, your order for {{m2}} is pending and will be authorized as soon as we receive payment.' FORMAT )
( 'Hello {{m1}}. Unfortunately payment for your order for {{m2}} has not completed, please contact us to resolve this.' FORMAT )
( 'Hello {{m1}}, {{m2}} are quacking with excitement that you have chosen them and will be speeding on their way to you as soon as they have packed their bags.' FORMAT )
( 'Hello {{m1}}, {{m2}} are now on their way and these cute little ducks will soon be with you.' FORMAT )
( 'Hello {{m1}}, we are sure you are enjoying the company of {{m2}} and we look forward to supplying many more cute little friends for them.' FORMAT )
( 'Hello {{m1}}, {{m2}} are heartbroken that your order for them has been cancelled. Think of those cute little ducks you are missing out on!' FORMAT )
OR
"Welcome to the home of the cutest ducks on the Internet. Here you can find all the ducks you ever wanted."

The new concepts here are SWITCH, where subsequent processing switches dependant on order status, and OR, where rather than using an IF within the processing I just catch those without an order at the end. Place that on your home page and returning users get an immediate personalised update of their order status. Those without orders are simply reminded how cute the ducks are!

There are so many ways to combine symbols that its really up to you to have ideas, experiment and see what you can do. You have a powerful toolbox for extending your eCommerce site. Its up to your imagination what you build with it.

There is a growing support section with tutorials for Magic Data on my c5magic site.

Symbols

The list of symbols available from Magic Data and Magic Data Commerce is constantly growing and other addons are integrating the magic. The list of commerce symbolse here is correct at the time of release 1.0.

See Available Symbols on my c5magic site for a mostly up-to-date list.

Magic Data powered discount and shipping types

Magic Data Commerce provides magic data powered discount types for discounts and surcharges and a magic data powered shipping type.

All work in the same way. You enter a magic data expression and that will be evaluated to provide an amount.

The shipping type includes some further provisions:

  1. If the expression evaluates to 'unavailable', shipping will be unavailable.
  2. Any text the expression saves to the memory 'ShippingName' will be returned to eCommerce as the shipping name.

 

 

Dont forget to regularly check out the growing support section for Magic Data on my c5magic site.