Items

In the context of e-commerce, items are products that that can be added to a shopping cart and be acquired by the customer. They typically have properties, such as a price, availability, etc.

The plugin ffItem offers typical properties and methods for e-commerce items.

Usage

It's good practice to create a prefixed class for your project

file classes/nsItem.php

class nsItem extends ffItem{
    // project-specific overwrites and functionality
}

You can turn any ffNode into an item by instantiating it with the current node:

File presenter/nsItemPresenter.php

$item = ffItem::getInstance($this->me); // returns nsItem object

The attributes of the item are stored in the node's metadata

file content/items/shirts/tshirt/.metadata.ff

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<folder>
    <item>
        <attribute id="Price">
            <value>10</value>
        </attribute>
    </item>
</folder>

Item variants

ffItem provides logic and tools to handle item variants.

In our fashion store, variants could be defined by two attributes, "Size" and "Color". Each of those attributes can have defined values:

Size: S, M, L, XL
Color: Red, Green, Blue

This means, that in total there are 12 possible variants of an item:

Size-S-Color-Red
Size-S-Color-Green
Size-S-Color-Blue
Size-M-Color-Red
Size-M-Color-Green
Size-M-Color-Blue
Size-L-Color-Red
Size-L-Color-Green
Size-L-Color-Blue
Size-XL-Color-Red
Size-XL-Color-Green
Size-XL-Color-Blue

In our store in ff, every variant of an item will be represented as a child node of what we call the "base item".

Project
|
+-- content
|   |
|   +-- items
|       |
|       +-- shirts
|           |
|           +-- tshirt // the base item
|               |
|               +-- Size-S-Color-Green
|               |
|               +-- Size-S-Color-Blue
|               |
|               +-- Size-M-Color-Red

defining variants

To make use of item variants, first the possible attributes need to be defined.

The attribute definition of variants is located in the metadata of one of the item's ancestor nodes. Based on the logic of the store, you can choose, where the definition is located.

In our shirt example, they could be located in the items/shirts node. This will allow all nodes below shirts to access the defined variant attributes.

It could also be located in the items node. This will allow all nodes below items to access the defined variant attributes.

file content/items/shirts/.metadata.ff

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<folder>
    <items>
        <values id="Size">
            <value>S</value>
            <value>M</value>
            <value>L</value>
            <value>XL</value>
        </values>
        <values id="Color">
            <value>Red</value>
            <value>Green</value>
            <value>Blue</value>
        </values>
    </items>
</folder>

Each node stores its attributes in its own metadata

file content/items/shirts/tshirt/.metadata.ff

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<folder>
    <item>
        <attribute id="Availability">
            <value>100</value>
        </attribute>
        <attribute id="Price">
            <value>10</value>
        </attribute>
        <attribute id="Size">
            <value>S</value>
        </attribute>
        <attribute id="Color">
            <value>Red</value>
        </attribute>
    </item>
</folder>

file content/items/shirts/tshirt/Size-S-Color-Green/.metadata.ff

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<folder>
    <item>
        <attribute id="Availability">
            <value>87</value>
        </attribute>
        <attribute id="Size">
            <value>S</value>
        </attribute>
        <attribute id="Color">
            <value>Green</value>
        </attribute>
    </item>
</folder>

Accessing attributes

Build a ffItem object from any node within the t-shirt node to access the attributes and their values.

Example: current path points to items,shirts,t-shirt,Size-S-Color-Green:

File presenter/item.php

$item = ffItem::getInstance($this->me);
// returns nsItem object
// N.B. this will return a nsItem only if you have created a nsItem class)

$item->getAttribute('Color');
// returns "Green"

$item->getAttribute('Availability');
// returns "87"

$item->getAttribute('Price');
// returns "10"
// N.B. This value is inherited from the base item

$item->hasVariants();
// returns true

$item->isVariantsBase();
// returns false

$item->getVariantsBase();
// returns the ffNode instance of items,shirts,t-shirt

$item->getMyVariantData();
// returns ["Size" => "S", "Color" => "Green"]

$item->getCustomAttributes() // method will probably be renamed
// returns ["Size", "Color"]

$item->getVariantAttributeSets()
// returns ["Size" => ["S", "M", "L", "XL"], "Color" => ["Red", "Green", "Blue"]]

$item->getNode();
// returns the ffNode of items,shirts,t-shirt,Size-S-Color-Green

Attribute inheritance

The inheritance mechanism of ffItem will make sure, that variants will always fall back to their base item's attributes if they are not explicitly defined in the variant node.

Any child node of items,shirts,t-shirt will return 10 for the price attribute by default.

Building a variant selector

Prices

ffItem provides out-of-the-box logic for various common price related topics, such as:

item price
multiple equal item price (if multiples of the same item are acquired)
sale price
shipping price per item
shipping price per item and destination
VAT per item (WIP!)
VAT per item and destination (WIP!)

12 April 2024