CartThrob Wish List / Gift Registry Version 1.02

Adding
Viewing lists
Deleting
Searching
Adding items to cart

CartThrob Wish List addon adds the ability to create and edit product wish lists in ExpressionEngine, and add items in the wish list to your shopping cart. In addition to creating a wish list, wish lists can also be searched, shared, edited, and products in them can be added to the cart. Wish lists are stored as EE channel entries, so all of the power of entries can be harnessed with your wish lists.

CartThrob Wish List is an addon for CartThrob. Like other CartThrob addons, it must be uploaded and installed on your website, and CartThrob must be active for it to run. To use this addon, you will need to add additional template tags for adding, editing, and deleting wish lists. You can place the tags in any of your EE templates to suit your specific workflow. Sample template code can be found here in the documentation.

Note To create and edit a wish list, membership & login is required.

Features
Requirements
Installation
Upgrading
Sample User Flow
Tags
Adding and updating wish lists
Deleting a wishlist
Displaying wishlist contents
Search for a wish list
Add wish list items to the cart

Features

Wish lists are standard channel entries. Store any data you want with a wish list.
Works with CartThrob eCommerce system.
Products in lists can be added to cart.
Purchased and wanted quantities are adjusted when items are purchased.
Multiple wish lists can be created for each user
Like any other channel entry, you can set a user configurable status, for instance a "public" vs "private" option that would determine whether the given wish list is available to be searched and found by others. That way a person could use a wish list to collect their own personal shopping/ wish list and not for public purposes.

Requirements

ExpressionEngine 2.5+
CartThrob 2.2+
PHP 5.3+

Installation

Upload the /system/expressionengine/third_party/cartthrob_wish_list/ folder to /system/expressionengine/third_party/
Make sure Extensions are enabled on your system
Install the CartThrob Wish List module and extension (through EE's add-ons/modules panel)
Go to EE settings » addons » extensions » CartThrob Wish list and choose the "Example Template Installation". This will install all channel and templates needed.

You may want to review the wish list template group for examples on usage in your site templates.

Should you ever need to change the wish list channel or field once installed, you can do so through the settings.

Upgrading

Upload the /system/expressionengine/third_party/cartthrob_wish_list/ folder to /system/expressionengine/third_party/ Overwriting existing files.
Go to EE settings » addons » and click "Run Module Updates"

Sample User Flow

While you can use the wish list tags to build your ideal system, the following is a pretty common sample user flow:

User creates a wish list
User adds products to wish list
User views wish list, adds and edits items on the list
User shares link to wish list with friend
Friend views wish list
Friend adds configured items to the cart and purchases through standard checkout
User can choose to view items that have been purchased, and the purchased quantities

Tags and Custom Field Types

add_to_wish_list_form add items to a wish list
my_wish_lists view existing wish lists and their contents
wish_list_select outputs a select dropdown containing all wish lists for current user
wish_list_form create and edit wish lists
wish_list_items view all items in a given wish list
wish_list_total view the total combined amount of all of the items in a wish list
wish_list_remaining_total view the total amount of items in the wish list that have not yet been purchased.

Adding and updating wish lists

`add_to_wish_list_form`

This will allow your customer to add items to their wish list. It works in the same way as the CartThrob add_to_cart_form, using the same parameters, plus some new ones listed below.

A customer can configure a product like they normally would with CartThrob's add_to_cart_form, and add the exact configuration they prefer to their wish list.

Adding item option data is simple, like CartThrob’s add_to_cart_form, just add a new item_option:

<input type="hidden" name="item_options[my_option]" value="like this!" />

Parameters

`wish_list_entry_id`

To save data to a specific wish list, you must use add the wish lists entry_id or url_title in the add_to_wish_list_form. You can pass the entry_id using this parameter or input field

`wish_list_url_title`

To save data to a specific wish list, you must use add the wish lists entry_id or url_title in the add_to_wish_list_form. You can pass the url_title using this parameter or input field

`id`

Form ID

`name`

Form name

`onsubmit`

You can add javascript in this parameter that should be called before the form is submitted

`quantity`

The amount of this item that should be added to the cart

`return`

the templategroup/template that the user should be returned to when the form has been submitted. You can add ENTRY_ID to the end of this, and it will be dynamically replaced with the recently created wish list

Examples

This is an example of how to add items to a wish list

{exp:channel:entries channel="products"  limit=""  dynamic="no" show_future_entries="yes" }

    {exp:cartthrob_wish_list:add_to_wish_list_form entry_id="{entry_id}"}
        <label>Add to wish list</label>

        {!-- this outputs a select dropdown to choose which list the item should go in. --}
        {exp:cartthrob_wish_list:wish_list_select}<br><br>

        {title} {product_price}<br>
        {exp:cartthrob:item_options entry_id="{entry_id}""}
            {if dynamic}
                <label>{option_label}</label>
                    {input}
            {if:else}
                {if options_exist}
                    <label>{option_label}</label>
                    {select} 
                        <option {selected} value="{option_value}">
                            {option_name}{if option_price_numeric != 0} +{option_price}{/if}
                        </option>
                    {/select}
                    <br>
                {/if}
            {/if}
        {/exp:cartthrob:item_options}
        <input type="submit" name="Submit" /> 
        {/exp:cartthrob_wish_list:add_to_wish_list_form}

{/exp:channel:entries}

`wish_list_form`

The wish list form is used to update the contents of existing wish lists. If you are adding items to a wish list, use add_to_wish_list_form. This form looks similar to other cartthrob forms.

Parameters

In addition to the parameters listed here wish list also uses SafeCracker's parameters and variables.

`entry_id`

Entry_id of the wish list (if editing an entry). Only entry_id or url_title are required to edit an existing entry

`url_title`

Url_title of the wish list (if editing an entry)

`return`

return="wish_list/edit/ENTRY_ID"

Variables

There are no unique variables. Because wish list extends SafeCracker, you can output any field entry data from the wish list channel that you would like. For more details see the description of the wish_list_items field below. The wish_list_items field is used to capture, edit, and display wish list item data.

Form Fields

At a minimum, you should have the following input fields listed in the wish list form

<input type="text" name="wish_list_name" id="wish_list_name" value="{wish_list_name}" /> 
<input type="text" name="wish_list_date" id="wish_list_date" value="{wish_list_date}{if '{wish_list_date}' == ''}{current_time format="%Y-%m-%d %H:%i %A"}{/if}" />
<input type="text" name="wish_list_occasion" id="wish_list_occasion" value="{wish_list_occasion}" />

Deleting an entry

Because wish lists are EE entries, as a safety precaution they can not be deleted. To "delete" a wish list, you can set its status to "closed".

<input type="checkbox" name="status" value="closed" />Remove this wish list</label>

Example

This example shows the method to create a basic wish list.

{exp:cartthrob_wish_list:wish_list_form
    return="wishlist/wish_list_form"
    {!-- return="wishlist/edit/ENTRY_ID" this can be used to edit the newly created list--}
    }
    <fieldset>
        <label for="title">Wish List Name<span class="required">*</span></label>
        <input type="text" name="title" id="title" value="{title}" />
    </fieldset>
    <fieldset>
        <label for="wish_list_occasion">Occasion</label>
        <input type="text" name="wish_list_occasion" id="wish_list_occasion" value="{wish_list_occasion}" />
    </fieldset>
    <fieldset>
        <label for="wish_list_date">Date<span class="required">*</span></label>
        <input type="text" name="wish_list_date" id="wish_list_date" value="{if '{wish_list_date}' == ''}{current_time format="%Y-%m-%d %H:%i %A"}{if:else}{wish_list_date format="%Y-%m-%d %H:%i %A"}{/if}" />
    </fieldset>
    <fieldset>
        <label for="wish_list_name">Your Name<span class="required">*</span></label>
        <input type="text" name="wish_list_name" id="wish_list_name" value="{wish_list_name}" />
    </fieldset>
    <fieldset>
        <input type="submit" value="Submit" />
    </fieldset>
{/exp:cartthrob_wish_list:wish_list_form}

This example shows how to edit the contents of a wish list

{exp:cartthrob_wish_list:my_wish_lists}
    {if wish_list:no_results}
        You have no wish lists, would you like to <a href="{path=wish_list/new}">start one</a>?
    {/if}


    <h3>List: {title}</h3>
    {exp:cartthrob_wish_list:wish_list_form
        entry_id="{entry_id}"
        return="wishlist/wish_list_form"
        preserve_items="yes"
        }
        <fieldset>
            <label for="title">Wish List Name<span class="required">*</span></label>
            <input type="text" name="title" id="title" value="{title}" />
        </fieldset>
        <fieldset>
            <label for="wish_list_occasion">Occasion</label>
            <input type="text" name="wish_list_occasion" id="wish_list_occasion" value="{wish_list_occasion}" />
        </fieldset>
        <fieldset>
            <label for="wish_list_date">Date<span class="required">*</span></label>
            <input type="text" name="wish_list_date" id="wish_list_date" value="{if '{wish_list_date}' == ''}{current_time format="%Y-%m-%d %H:%i %A"}{if:else}{wish_list_date format="%Y-%m-%d %H:%i %A"}{/if}" />
        </fieldset>
        <fieldset>
            <label for="wish_list_name">Your Name<span class="required">*</span></label>
            <input type="text" name="wish_list_name" id="wish_list_name" value="{wish_list_name}" />
        </fieldset>
        <fieldset>
            <label for="wish_list_name">Delete this list?</label>
            <input type="checkbox" name="status" value="closed" />
        </fieldset>

        <fieldset>
        {exp:cartthrob_wish_list:wish_list_items entry_id="{entry_id}" variable_prefix="items:"}

                {!-- due to EE parsing issues, this probably won't work if it's nested within another tag that has a no_results option. sorry. Embed this entire tag if you really need no_results within another tag.  --}
                {if no_results}
                    No items are in this wish list
                {/if}

                {if items:count ==1}
                <h3>Items</h3>
                {/if}
                <div>
                    <strong>{items:title} {price}</strong><br>
                    <!-- NOTE because you can update multiple items at the same time, when updating items, make sure you add the {row_id} -->

                    <label><input type="checkbox" name="wish_list_items[{items:row_id}][delete]" value="1" />Remove this item?</label><br>
                    Quantity: <input type="text" name="wish_list_items[{items:row_id}][quantity]" value="{items:quantity}" size="5" /><br>
                    Note: <input type="text" name="wish_list_items[{items:row_id}][note]" value="{items:note}" size="20" /><br><br>
                    {!-- 
                    {items:item_options}
                        {option_value}<br>
                        {dynamic}<br>
                        {price}<br>
                        {option_label}<br>
                        {item_options_total_results}<br>
                        {item_options_count}<br>
                        {options_exist}<br>
                    {/items:item_options}
                    --}

                    {if items:count==items:total_results}
                        &nbsp;
                    {/if}
                </div>

        {/exp:cartthrob_wish_list:wish_list_items}

        </fieldset>
        <fieldset>
            <input type="submit" value="Submit" />
        </fieldset>
    {/exp:cartthrob_wish_list:wish_list_form}

{/exp:cartthrob_wish_list:my_wish_lists}

Information about wish lists

`my_wish_lists`

This tag will loop through wish lists created by the currently logged in member.

NOTE You can also use a standard weblog entries loop to show data about your wish lists.

Variables

`count`

Current loop count

`entry_id`

Entry of the current wish list

`total_results`

Total number of wish lists for this user

`switch`

You can use this (for instance) for zebra striping.

{switch="red|green"}

Conditonals

`{if no_results}`

Use this to conditionally show content if no wish lists have been created

{if no_results}
    You have no wish lists, would you like to <a href="{path=wish_list/new}">start one</a>?
{/if}

Examples

This example will output the name of all wish lists for the current user

{exp:cartthrob_wish_list:my_wish_lists}
    {if no_results}
        You have no wish lists, would you like to <a href="{path=wish_list/new}">start one</a>?
    {/if}
    <strong>{title} list</strong><br>
{/exp:cartthrob_wish_list:my_wish_lists}

`wish_list_items`

The wish_list_items tag outputs information about items added to the wish list.

Parameters

`entry_id`

To save data to a specific wish list, you must use add the wish lists entry_id or url_title in the add_to_wish_list_form. You can pass the entry_id using this parameter or input field

`variable_prefix`

You can assign a prefix that will be added to all variables. This may help you avoid variable name conflicts when using this tag within other tags that use the same variable names.

Variables

`note`

Information captured in the notes field

`purchased`

The total number of this item that have been purchased

`price`

The price of the item as it is configured

`entry_id`

The entry id of the item

`title`

The title of the item

`quantity`

The wanted quantity of the item

`row_id`

The current row_id of the item

`count`

The current loop count

`total_results`

The total number of items in this wish list

Variable Pairs

`item_options`

Lists all item options for a given item in the wish list

{items:item_options}
    {option_field} The short name of the item option field
    {option_label} The label for the selected option
    {option_value} The value of the selected option
    {dynamic} For use in a conditional to say if the option is related to a custom field, or if it's been dynamically added
    {price} The price of this option
    {item_options_total_results} Total number of options
    {item_options_count} The count of the current option
{/items:item_options}

Examples

This example lists all items within a wish list

{exp:cartthrob_wish_list:wish_list_items entry_id="{entry_id}" variable_prefix="items:"}

        <strong>{items:title}</strong> {items:price}

{/exp:cartthrob_wish_list:wish_list_items}

`wish_list_total`

Outputs the total cost for a given wish list including all purchased and non-purchased items

Parameters

`entry_id`

Specific wish list entry id

`url_title`

Specific url title. Either entry id or url title must be set

Examples

{exp:cartthrob_wish_list:wish_list_total entry_id="{entry_id}"}

`wish_list_remaining_total`

Outputs the total cost for a given wish list including all non-purchased items

Parameters

`entry_id`

Specific wish list entry id

`url_title`

Specific url title. Either entry id or url title must be set

Examples

{exp:cartthrob_wish_list:wish_list_remaining_total entry_id="{entry_id}"}

`wish_list_select`

This outputs a select dropdown containing all wish lists for the current logged in user

{exp:cartthrob_wish_list:wish_list_select}

Search for a wish list

You can use EEs standard search to find wish lists

{exp:search:simple_form channel="wish_list" result_page="wish_list/results" search_in="entries"}

    <p><label for="keywords">Search Registries:</label><br />
    <input type="text" name="keywords" id="keywords" value="" size="18" maxlength="100" /></p>
    <p><input type="submit" value="submit" class="submit" /></p>

{/exp:search:simple_form}

// results 

{exp:search:search_results}
    <li><a href="{path=wish_list/view/{entry_id}}">{title}</a></li>
{/exp:search:search_results}

Add wish list items to cart

To add wish list items to the cart, you use CartThrob's standard add_to_cart_form, and add the wish_list_entry_id and wish_list_row_id parameters to the add_to_cart_form tag. If these 2 parameters aren't added, the related wish list items won't be found, and the data added to the cart may not be correct. See the example below for more details.

Parameters

`wish_list_row_id`

The row_id of the item you want to add to the cart. This row ID will help the cart identify the unique item being added, in the case of multiple configurations of one specific item.

`wish_list_entry_id`

The entry_id of the wish list containing the item.

{exp:cartthrob_wish_list:my_wish_lists}
    {exp:cartthrob_wish_list:wish_list_items entry_id="{entry_id}" variable_prefix="items:"}
            {exp:cartthrob:add_to_cart_form 
                return=""
                wish_list_row_id="{items:row_id}"
                wish_list_entry_id = "{entry_id}"
                }

            <strong>{items:title}</strong> {items:price}
            <input type="submit" value="Add to Cart" />

            {/exp:cartthrob:add_to_cart_form}
    {/exp:cartthrob_wish_list:wish_list_items}
{/exp:cartthrob_wish_list:my_wish_lists}