EasyWish - Manage your whislist - Project file for Stakcs Pro and RapidWeaver

Documentation

Overview

On this page, you will find detailed documentation for each section and element of EasyWish, complete with guidelines on classes and identifiers. Do not be intimidated by the length of the content; setting up EasyWish is much simpler than it may seem at first glance. You will also find the Quick Setup section, which is a quick guide to the essential steps for getting started with EasyWish.

What is EasyWish

EasyWish is a versatile wishlist system, ideal for those who wish to save and manage their favorite items with ease. This tool integrates seamlessly with both dynamic and static content, offering extensive customization freedom through the use of adaptable templates. Discover how EasyWish can enhance user interaction with your content, increasing engagement and customer satisfaction.

Data Persistence

EasyWish utilizes browser Local Storage to ensure that your wishlist data remains saved even after closing the browser. This local storage method allows users to add items to their wishlist and find them intact upon their next site visit, without the need for login or registration. The selected items are stored directly on the user's device, providing a practical and fast solution for maintaining a personalized and readily accessible wish list.

Quick Setup

Setup Step by Step

To integrate EasyWish into your site, start by placing the Pen stacks EasyWish JS code and EasyWish on the desired page.
Proceed with data mapping in the Items Grid Area, adding the predefined EasyWish classes (learn more on Predefined Classes) to the elements you would like to include in the wishlist. All elements must reside within the Container stack with the class ew-item and data-ew-item-id="the-item-id" correctly set in Custom Attrs (learn more about what the 'the-item-id' is go to Items Grid Area).
Proceed to replicate the same assignments in the layout of the Item Template (learn more on Item Template) to ensure consistency with the data present in the Items Grid Area items. Accurate data mapping is crucial for the proper functioning of EasyWish and for optimal display of the articles in the wishlist.

Practical Example:

Suppose you need to configure the wishlist to display three item data types: image, name and category. Here is how to proceed:

Step 1

Items Grid Area: Data Mapping

By Items Grid Area, we mean the grid, on the page, of items that can be added to the wish list.

In the item of the Items Grid Area, proceed with data mapping by assigning the predefined classes (in this case, we will use ew-image for the item's image, ew-name for the item's name and ew-category for the item's category) to the respective elements (F6 stacks) of your item (or all items, in the case of static content).
Set up an Add-item button (so you can add an item to the wishlist) by inserting a Button stack in the element layout and assigning the class ew-add-item to it. This button will function as a toggle button to add/remove the item from the wishlist.
Ensure that all elements (F6 stacks) used as data for the wishlist reside within the Container stack with class ew-item and data-ew-item-id=“the-item-id” correctly set in Custom Attrs (learn more on Items Grid Area).

Step 2

Item Template: Data Mapping and Layout Customization

Within the EasyWish > Wishlist Pen stacks, choose the layout type for your wishlist by enabling only the corresponding Pen stack.
It is now necessary to replicate the data mapping set in Items Grid Area also within the Pen stack Item Template.
Then proceed to add within the template (i.e., within the Container stack with id="ew-item-template”) the necessary stacks to show the data you previously set in Items Grid Area. In this specific case, they could be one Picture stack for the image, and two Text type stacks for the textual contents of the name and category.
Assign these three stacks the respectively predefined classes ew-image, ew-name and ew-category also assigned in Items Grid Area.
If you see fit, you can customise the layout of the Item Template to your liking.

Step 3

Launch the preview

After correctly configuring the classes, start the RW preview and try adding an item to the wishlist to verify that everything has been set up correctly and that the data is displayed as desired in the wishlist.

Structure

Overview

For a better understanding, the structure of EasyWish is organized into Pen stacks based on the functionalities of the elements they contain.

EasyWish, on the page, is divided into three parts. The first two parts rich in content and a third part that is simpler, but nevertheless fundamental to the functioning of EasyWish.

Part 1 - Pen stack EasyWish JS code
Part 2 - Pen stack EasyWish
Part 3 - Some elements inside the Item Grid Area

Pen stack

What is it?

For the uninitiated, Pen stack is nothing more than a container of other stacks, and is very useful for organising the page in Edit mode when many stacks are present. Think of it as a folder in the Finder, and like folders you can nest them together to better organise the contents.

Example of a Pen stack with two stacks inside it.

Show/Hide the Pen content

In EasyWish, all Pen stacks are set with their contents hidden, to show their contents simply click on the icon in the top right-hand corner of the Stacks plugin toolbar, or with the keyboard shortcut Shift + H.

Enable/Disable the Pen stack

By default, the contents of Pen stacks are published when the page is published. But in its settings, by ticking the checkbox Do Not Publish Content? you can choose not to publish its content. Later on when we refer to enabling or disabling a Pen stack we refer to this very feature of publishing or not publishing its content.

Pen stack

1. EasyWish JavaScript code

This Pen stack contains the JavaScript code that powers EasyWish. It is essential on every page where EasyWish is used.

Important!

This code must not be modified under any circumstances, otherwise the entire operation of EasyWish will be compromised.

Pen stack

2. EasyWish

This Pen stack contains all the elements that make up the structure of EasyWish, and is in turn subdivided into:

Pen stack Toolbar
Pen stack Wishlist
Pen stack Alerts
Pen stack Styles - Email Content Settings
Pen stack Styles - Items Grid Area

Contents of the EasyWish Pen stack.

Important!

It is important not to remove the classes used by EasyWish from any EasyWish element, which are easily identified because they always start with ew- followed by the text indicating the function they perform (example: ew-remove-item is the class that allows the element to which it has been assigned to remove an item from the wishlist).

Pen stack

Toolbar

This Pen stack contains the elements and buttons, and their related styles, that manage the content of EasyWish. There are three simple pre-built layouts divided into Pen stacks; you just need to enable the Pen stack of the desired layout (and keep the other Pen stacks disabled).

Toolbar layouts.

Each Toolbar layout is composed of the following main elements:

Counter

It is the element that indicates the number of items present in the wishlist.
Used Stack: Text
Element Class: ew-counter
In EasyWish, the Text stack is used, but it also works with Header and Button stacks or any other stack that involves the insertion of text.
It is possible to have multiple instances of this element per page.

Show/Hide Button

It is the button that acts as a toggle to show and hide the wishlist.
Used Stack: Button
Element Class: ew-show-content
In EasyWish, the Button stack is used, but it could potentially work with any type of stack.
It can be placed at will anywhere on the page.
It is possible to have multiple instances of this element per page.

Clear All Button

Removes all items within the wishlist.
Used Stack: Button
Element Class: ew-remove-all-items
In EasyWish, the Button stack is used, but it could potentially work with any type of stack.
It is deactivated when the wishlist is empty, becomes active (the is-active class is assigned) when the wishlist contains at least one item.
It is possible to have only one instance of this element per page.

Share Button

Opens the mail client and populates the email content with all the data of the items contained in the wishlist.
Used Stack: Button
Element Class: ew-send-email
In EasyWish, the Button stack is used, but it could potentially work with any type of stack.
It is deactivated when the wishlist is empty, becomes active (the is-active class is assigned) when the wishlist contains at least one item.
It is possible to have only one instance of this element per page.

Tip

To set up the email content, see the section Styles - Email Content Settings

Pen stack

Wishlist

This Pen stack contains the actual elements of the wishlist. There are 4 pre-built layouts divided into Pen stacks, you just need to enable the Pen stack of the desired layout (and keep the other Pen stacks disabled).

Wislist layouts.

Each Wishlist layout is composed as follows:

Pen stack

Styles

This Pen stack contains the styles of the layout.

Pen stack

Item Template

The Item Template represents the layout of each single article within the wishlist of EasyWish. Thanks to the F6 stacks, it is possible to easily customize the layout of the Item Template, arranging the elements in total freedom according to your needs.

Item Template for Wishlist Grid Layout with the Container id="ew-item-template" stack highlighted

Data Mapping

Setting the data type of each element (F6 stack) within the template is extremely simple with EasyWish. Just assign one of the Predefined Classes for data mapping to the corresponding element (F6 stack) in the template.
It is essential that there is consistency between the data set in the Item Template layout and the data set in the items in the Items Grid Area. If a data is present only in one of the two places then that data will not be visible in the wishlist.

Important!

It is crucial to ensure that the layout of the Item Template is correctly contained within a Container stack with Custom Attrs id="ew-item-template”. This container acts as a base model for each article added to the wishlist: its content is cloned every time a product is inserted. This process ensures that all additions to the wishlist maintain a uniform structure and respect the design defined in the template. Ensure that the id is correct and unique to avoid conflicts in the DOM and ensure smooth and error-free operation of the wishlist system.

Pen stack

Wishlist Wrapper

Is the element with the class ew-wrapper which, by varying the height value, shows and hides the wishlist inside.

Tip

If you want the wishlist always visible, all you have to do is:

Select the Pens stacks Whislist and Empty List Message and drag them out of the ew-wrapper element.
Hide the Show/Hide Buton inside the Pen stack Toolbar.

The Wishlist Wrapper contains the following Pen stacks:

Contents of the Wishlist Wrapper Pen stack.

Pen stack

Wishlilst

This Pen stack contains the element ew-content, the actual container of the wishlist, inside which the cloned templates (populated with the item's data) are added when an item is added to the wishlist.
It is crucial to ensure that the ew-content element is present otherwise the wishlist will not be displayed.

Pen stack

Empty List Message

In this Pen stack you can set the text displayed when the wishlist is empty. Or you can completely customize the layout to your liking, the important thing is that it is contained within the element ew-empty-list.

Pen stack

Alerts

This Pen stack contains the elements for notification when an item is added or removed from the wishlist. There are 4 pre-built layouts divided into Pen stacks, you just need to enable the Pen stack of the desired layout (and keep the other Pen stacks disabled).

Alerts layouts.

Each Alert layout is composed as follows:

Contents of the Toast Bost - Top RIght Pen stack.

Pen stack

Styles

This Pen stack contains the styles of the alert, and it is here that you can customize the appearance of each alert to adapt them to the graphics of your website.

Time Setting

By setting the value of the variable --ew-alert-time in the CSS swatch named Time (you can find it in the Styles stack of each alert layout) you can set the total duration of the action of an alert. The default setting is 1500 milliseconds.

Pen stack

Add Item

This Pen stack contains the elements of the alert shown when an item is added to the wishlist.

Pen stack

Remove Item

This Pen stack contains the elements of the alert shown when an item is removed from the wishlist.

Pen stack

Remove All Items

This Pen stack contains the elements of the alert shown when all items are removed from the wishlist.

Pen stack

Styles - Email Content Settings

This Pen stack contains a CSS swatch that defines the variables used to customize the labels and contents of the articles inside the email generated when using the Share button.

CSS variables for setting the content of email.

Below is a table illustrating the correspondences between the data labels and the corresponding CSS variables:

Variable	Label
--ew-email-subject	The subject of the email.
--ew-email-intro	This is the introduction text placed before the item list.
--ew-email-name	The item name.
--ew-email-code	The item code.
--ew-email-category	The item category.
--ew-email-info	The item description.
--ew-email-extra-1	Label for the custom data #1.
--ew-email-extra-2	Label for the custom data #2.
--ew-email-extra-3	Label for the custom data #3.
--ew-email-price	The item price.
--ew-email-url	The item page url.

Pen stack

Styles - Items Grid Area

This Pen stack contains the styles for the elements of EasyWish located in the Items Grid Area. In particular, it includes the styles for the Add Item button, which allows users to add items to their wishlist. Customize the styles to better integrate the button with your site's design.

Pen stack

3. Items Grid Area

With Items Grid Area we mean the grid of items present on the page that can be added to the wishlist.

Item Setup

It is important that each item contains a Container stack as the parent of the elements whose data you want to add to the wishlist, and that it has the class ew-item with set in Custom Attrs data-ew-item-id=“the-item-id” where the value the-item-id must be a unique value.

Item setup within the Blog List stack with the Container ew-item stack highlighted.

Important!

If you are using EasyWish with TCMS Blog List then ‘the-item-id’ might correspond to {{permalink}} which uniquely identifies each item (in this case each blog post) and thus to the Container stack you can add the attribute data-ew-item-id=“{{permalink}}”

In conclusion, if your items are generated dynamically, you just need to set up a single Container stack with the attribute data-ew-item-id=“the-item-id” set.
Instead, if your items are static data, you will need to set up the Container stack for each item in your Items Grid Area making sure that each the-item-id set is unique and not repeated in other items.

Data Mapping

Configuring the data type of each element within the ew-item element is extremely simple with EasyWish. Just assign one of the Predefined Classes for data mapping to the element (F6 stack) corresponding to the data you want to add to the wishlist.

It is essential that there is consistency between the data set in the items in the Items Grid Area and the data set in the layout of Item Template. If a data is present only in one of the two places then that data will not be visible in the wishlist.

Classes

Predefinited Classes

Here is a list of predefined EasyWish classes you can use to assign up to 10 specific data types to elements within your wishlist template:

Class	Description	Data Type	Stack Used	Other info
ew-image	Used to include the image of the item in the wishlist.	Image	Picture	The ‘Alt Tag’ is automatically filled with the ew-name data.
ew-name	Used to include the name of the item in the wishlist.	Text	Text	It could potentially also work with other types of stacks where there is text to be inserted.
ew-code	Used to include the identification code of the item in the wishlist.	Text	Text	It could potentially also work with other types of stacks where there is text to be inserted.
ew-category	Used to include the category of the item in the wishlist.	Text	Text	It could potentially also work with other types of stacks where there is text to be inserted.
ew-info	Used to include the description of the item in the wishlist.	Text	Text	It could potentially also work with other types of stacks where there is text to be inserted.
ew-price	Used to include the price of the item in the wishlist.	Text	Text	It could potentially also work with other types of stacks where there is text to be inserted.
ew-url	Used to include a direct link to the product page in the wishlist.	Text	Button	It is assigned to a Button type stack as the EasyWish JavaScript code retrieves the ‘href’ value.
ew-extra-1	Used to include additional information about the item in the wishlist.	Text	Text	It could potentially also work with other types of stacks where there is text to be inserted.
ew-extra-2	Used to include additional information about the item in the wishlist.	Text	Text	It could potentially also work with other types of stacks where there is text to be inserted.
ew-extra-3	Used to include additional information about the item in the wishlist.	Text	Text	It could potentially also work with other types of stacks where there is text to be inserted.

These classes are assigned to the appropriate elements within your Item Template to ensure that the correct data is displayed in every component of the product in the wishlist.
Be sure to apply the same data type classes, as defined in the Item Template, also to the corresponding elements within each item in the Items Grid Area. The presence of a class in both contexts ensures that the corresponding data is visible and correctly displayed in your wishlist.

Tip

For example, if you want a button that shows the price and directs the user to the product page, you just need to associate the ew-price and ew-url classes with the Button stack.