Shortlist

Quickstart

Getting started with Shortlist is as simple as 3 easy steps. Follow these steps if you're just getting started with Shortlist on Craft, and then you can expand on the concepts and features from there.

The Basic 3 things every Shortlist implemention needs are the following :

1. Add a way for users to add and remove items
2. Add a way for users to view their current lists
3. Add a way for users to create new lists, and other utility functions

1. Add a way for users to add and remove items

The most basic concept in Shortlist is items.

An item can be any element within Craft. That means you can use Shortlist with entries, users, assets, categories, and everything else that's an element. This includes completely custom third party ElementTypes. Spiffy.

Note: We'll use entries in all these examples just for simplicity, but the same things will work with any element type

Lets start with a loop of entries using the standard Craft tags :

{% for entry in craft.entries.section('news') %}
    <h2>{{ entry.title }}</h2>
{% endfor %}

Which returns something like :

<h2>Entry One</h2>
<h2>Entry Two</h2>
<h2>Entry Three</h2>

Now, add tags to both check the state of the current item, and give add/remove functions as appropriate. This uses the shortlist.item tag, it's really simple :

{% for entry in craft.entries.section('news') %}
    {% set item = craft.shortlist.item(entry.id) %}
    <h2>{{ entry.title }}</h2>

    {% if item.inList %}
        {!-- This item is already in the default list, show a remove button --}
        <a href="{{ item.removeActionUrl }}">Remove from List</a>
    {% else %}
        {!-- Not currently in the default list, show an add button --}
        <a href="{{ item.addActionUrl }}">Add to List</a>
    {% endif %}
{% endfor %}

Which ends up something like this :

<h2>Entry One</h2>
<a href="action/..">Add to List</a>


<h2>Entry Two</h2>
<a href="action/..">Remove from List</a>

<h2>Entry Three</h2>
<a href="action/..">Add to List</a>

Simple right?

This setup just shows the details from the user's current default list. If they have multiple lists, we want to give them details about those other lists too. That's just as simple :

{% for entry in craft.entries.section('news') %}
    {% set item = craft.shortlist.item(entry.id) %}
    <h2>{{ entry.title }}</h2>

    {% if item.inList %}
        {!-- This item is already in the default list, show a remove button --}
        <a href="{{ item.removeActionUrl }}">Remove from List</a>
    {% else %}
        {!-- Not currently in the default list, show an add button --}
        <a href="{{ item.addActionUrl }}">Add to List</a>
    {% endif %}

    {!-- Show details about the other lists for the user --}
    {!-- First test if they have other lists --}
    {% if item.otherLists is not empty %}
        <h3>Other Lists</h3>
        {% for otherList in item.otherLists %}

        {!-- Test if this item is in this list and display buttons as appropriate
        {% if otherList.inList %}
            <a href="{{ otherList.removeActionUrl }}">Remove from {{ otherList.title }}</a>
        {% else %}
            <a href="{{ otherList.addActionUrl }}">Add to {{ otherList.title }}</a>
        {% endif %}

        {% endfor %}
    {% endif %}
{% endfor %}

Which will return something like :

<h2>Entry One</h2>
<a href="action/..">Add to List</a>
    <h3>Other Lists</h3>
    <a href="action/..">Add to My Favourites</a>
    <a href="action/..">Remove from To Buy List</a>


<h2>Entry Two</h2>
<a href="action/..">Remove from List</a>
    <h3>Other Lists</h3>
    <a href="action/..">Add to My Favourites</a>
    <a href="action/..">Add to To Buy List</a>

<h2>Entry Three</h2>
<a href="action/..">Add to List</a>
    <h3>Other Lists</h3>
    <a href="action/..">Remove from My Favourites</a>
    <a href="action/..">Remove from To Buy List</a>

Boom. Next we need to look at lists.

Note: This is just the most basic implemenation of items with Shortlist. There's lots more possible - checkout the full documentation for details

---

2. Add a way for users to view their current lists

Now that we've covered items, we should look at the second core concept in Shortlist - lists.

Lists as just as simple as items. They're simply a list of items. (Pretty imaginative huh?)

First let's setup a way to view the current user's lists. We get a user's list the shortlist.lists method. Like so :

{% set lists = craft.shortlist.lists %}

Simple right? That lists variable is an array of the lists for the current user. (Be they a logged in member or guest). You'd loop over this array as any other array, just be aware - this may be empty if the user has no lists currently.

Now we have their lists, we also have access to the items in those lists, which is a sub-array within each list. Again - be aware that each list could be empty. Let's loop through them and output them on the page :

{% if shortlistLists is empty %}
You have no lists at the moment.
{% else %}
    {% for list in lists %}
    <h3>{{ list.title }}</h3>

    {% if list.items is empty %}
    No items in this list
    {% else %}
    <ul>
        {% for item in list.items %}
            <li>{{ item.title }} (<a href="{{ item.removeActionUrl }}">Remove</a>)</li>
        {% endfor %}
    </ul>
    {% endif %}
    {% endfor %}
{% endif %}

Note: The list.items here is simply an array of the same Shortlist_ItemModel type as we used in the first step, so all the same concepts and features work here too.

With all this in place, you'll end up with something similar to the following outputted :

<h3>Wishlist</h3>
<ul>
    <li>First Item (<a href="action/..">Remove</a>)</li>
    <li>Second Item (<a href="action/..">Remove</a>)</li>
    <li>Third Item (<a href="action/..">Remove</a>)</li>
</ul>

<h3>My Favs</h3>
<ul>
    <li>Blue Bag (<a href="action/..">Remove</a>)</li>
    <li>Red Bag (<a href="action/..">Remove</a>)</li>
</ul>

<h3>My Saved Items</h3>
No items in this list

That's as simple as it gets right?

The only other key thing to get a grasp of is default lists.

Each user will have a single default list. This is the list that is set to their default, and, unless otherwise specified, will be the list shown and acted on by the list, add, remove functions.

You can get the current default state for each list with a simple {{ list.default }} variable. Also, we can let a user change their default list simply too. While we're at it, lets give them a way to Delete and Clear specific lists too.

{% if shortlistLists is empty %}
You have no lists at the moment.
{% else %}
    {% for list in lists %}
    <h3>{{ list.title }}</h3>

    <a href="{{ list.delete }}">Delete List</a>

    {% if list.default %}
        <em>Default List</em>
    {% else %}
        <a href="{{ list.makeDefaultActionUrl }}">Make Default</a>
    {% endif %}

    {% if list.items is not empty %}
        <a href="{{ list.clearActionUrl }}">Clear List</a>
    {% endif %}


    {% if list.items is empty %}
        No items in this list
    {% else %}
        <ul>
        {% for item in list.items %}
            <li>{{ item.title }} (<a href="{{ item.removeActionUrl }}">Remove</a>)</li>
        {% endfor %}
        </ul>
    {% endif %}
    {% endfor %}
{% endif %}

Which would return similar to :

<h3>Wishlist</h3>
<a href="action/..">Delete List</a>
<em>Default List</em>
<a href="action/..">Clear List</a>

<ul>
    <li>First Item (<a href="action/..">Remove</a>)</li>
    <li>Second Item (<a href="action/..">Remove</a>)</li>
    <li>Third Item (<a href="action/..">Remove</a>)</li>
</ul>

<h3>My Favs</h3>
<a href="action/..">Delete List</a>
<a href="action/..">Make Default</em>
<a href="action/..">Clear List</a>

<ul>
    <li>Blue Bag (<a href="action/..">Remove</a>)</li>
    <li>Red Bag (<a href="action/..">Remove</a>)</li>
</ul>

<h3>My Saved Items</h3>
<a href="action/..">Delete List</a>
<a href="action/..">Make Default</em>

No items in this list

And that's all there is too it. Next up, we've got a few utility functions we can add.

Note: These examples cover the basic setup, but there's lots more you can do with Lists. Check the full documentation for details

---

3. Add a way for users to create new lists, and other utility functions

Now we've covered lists and items we've got a few other quick things to drop in to make the setup complete.

Simply - we want to give users a way to create new lists directly, and optionally a way to clear all and delete all their lists in a single action (pretty useful for testing too).

Note: For security the Delete All and Clear All functions require a POST action.

<h2>List Options</h2>
<a href="{{ shortlist.newListActionUrl }}">+ Create New List</a>


<h4>List Utilities</h4>
<form method="post" action="">
    <input type="hidden" name="action" value="shortlist/list/deleteAll" />
    <input type="submit" value="Delete All Lists" />
</form>
<form method="post" action="">
    <input type="hidden" name="action" value="shortlist/list/clearAll" />
    <input type="submit" value="Clear All Lists" />
</form>

And that'll return something very similar to :

<h2>List Options</h2>
<a href="action/..">+ Create New List</a>

<h4>List Utilities</h4>
<form method="post" action="">
    <input type="hidden" name="action" value="shortlist/list/deleteAll" />
    <input type="submit" value="Delete All Lists" />
</form>
<form method="post" action="">
    <input type="hidden" name="action" value="shortlist/list/clearAll" />
    <input type="submit" value="Clear All Lists" />
</form>

And you're all done.

Note: These basic examples are included in the plugin download for you to get started straight away.