Change log

Add To Favorites

The Favorites functionality allows logged-in users to save an item reference (from any module) to their account and render those items on a page for them to refer back to as needed.

You can use Favorites on any built-in system module (such as Blogs, Authors, Events, etc.), Custom Modules and eCommerce Catalogs/Products.

By default, the component renders an icon (a heart by default) forming the interface button for users to add (or remove) an item in their Favorites inventory.

Additionally, the component can output all the items data for listing the member's favorite items, via Liquid, with your own custom layouts.

{% component type: "favorites", source: "<Module name/ID>" %}

Parameters and Options

Parameter
Values
Required
Description
type
favorites

This is the name of the entity that needs to be used for the component retrieving function.

source
<Module name/ID>
The module’s entity/alias name or ID that the data is to be sourced from.
itemId
<ItemID>

The module item's ID. While not required for accessing the Favorite items data, this ID will be required when using this component to render the Favorite button interface for individual items.
includeItemData
false (default)
true

When false the items system properties are returned in the output data, along with the Favorites data. When true all of the items system and custom properties are returned in the output data, along with the Favorites data (as shown in the output examples below).
layout
<path/to/layout>

Path to file that will contain the Liquid layout content to be parsed.

If an empty string, nothing will be rendered.
If paramater is not included, the default virtual layout will be rendered (see below).

filterBy
id
parentid
name
weighting
url
urlslug
releasedate
expirydate
LastUpdatedDate
Author
ItemCategories
ItemTags
<CustomPropertyName>
...and any other top level properties available for the module

The name of the property to filter by. If empty or not present, no filtering will be used.

Remove spaces from custom property names here.

filterValue
<your value>

Your specific value to filter by, eg: name, id, number, date, etc.
Liquid variables can be used here also. If present but no value set, no items will be returned.
sortBy
id
parentid
name
weighting
url
urlslug
releasedate
expirydate
LastUpdatedDate
Author
ItemCategories
ItemTags
<CustomPropertyName>
...and any other top level properties available for the module

The name of the property to sort by. If empty or not present, alpha/numeric sorting will be used.

Remove spaces from custom property names here.

sortOrder
ASC (default)
DESC

ASC sorts the items in ascending order while DESC sorts in descending order (based on alpha/numeric or date sorting).
If empty or not present, alpha/numeric sorting will be used.
ignoreWeighting
false (default)
true

Enables/disables sorting items first by their weighting values. When false items will sort by their weighting values first, followed by any sortBy properties (or the default alpha/numeric sorting if sortBy is empty or not present). If true item weightings will be ignored and sorting will only be applied via sortBy or default sorting.
random
false (default)
true

Displays the available items in a random order.

If used in conjunction with sortBy, that sorting criteria will be applied to the randomly retrieved results. So, if retrieving all, or most, of the items they will not appear to be random since they will then be sorted back into a logical order. To overcome this, set the sortBy parameter to 'enabled' (or another unused property) as this will not provide any viable sorting criteria* and the items will not be sorted from their initial random order.
* Unless there are weighted items, which will always override the random option.

If this param's value is 'true' - pagination will not be shown.
limit
10 (default)
<integer>

The maximum number of items returned. If displayPagination is enabled this determines the maximum number of items per page.
enablePagination
true (default)
false

Enables/disables pagination for the component.

This is useful for avoiding pagniation affects for a specific component when multiple components of the same module are output on the same page and do use pagination.

object
item (default)
collection

Determines the method for Liquid rendering.
item returns each item iteratively, one after another, for output (generally, output to a container element with no need for looping through the data).
collection returns all items as one collection for output (your container element and looping logic would be handled in the Components Layout).
collectionVariable
<yourLiquidVariableName>

Assigns the data to a Liquid collection enabling further access to the data on the Page or Template using Liquid.

Your collectionVariable value must only contain English letters, numbers or underscores. Spaces or special characters are not supported.

<customParameter>
<your custom value>

You can add your own additional parameters (name/value pairs) to the Component tag. These will be passed to the Components Layout (and the collectionVariable if used) for use via Liquid.

Your <customParameter> name must only contain English letters, numbers or underscores. Spaces or special characters are not supported.

You can use HTML as the value here, just be sure to change any double quotes in your HTML to single quotes.

Also, see here for a tutorial on using Custom Paramters.

Liquid Output

The below example shows how the items and Favorites data is structured. The Liquid data output from this example would look like the following (for example, when using a collectionVariable to create the collection):

includeItemData: false

{
    "items": [
        {
            "FavoritesInfo": {
                "ItemId": 1234,
                "CreatedDateTime": "2021-01-29T22:54:57.623",
                "IsFavorite": true,
                "AddToFavoritesUrl": "/public/api/module-items/add-favorite/1234",
                "RemoveFromFavoritesUrl": "/public/api/module-items/delete-favorite/1234"
            },
            "FavoriteCreateDate": "2021-01-29T22:54:57.623",
            "IsFavorite": true
            "id": "1234",
            "name": "Item Name 1",
            ... all system properties for the item
        },
        {
            "FavoritesInfo": {
                "ItemId": 9876,
                "CreatedDateTime": "2021-01-29T21:34:22.132",
                "IsFavorite": true,
                "AddToFavoritesUrl": "/public/api/module-items/add-favorite/9876",
                "RemoveFromFavoritesUrl": "/public/api/module-items/delete-favorite/9876"
            },
            "FavoriteCreateDate": "2021-01-29T21:34:22.132",
            "IsFavorite": true
            "id": "9876",
            "name": "Item Name 2",
            ... all system properties for the item
        }
    ]
}

includeItemData: true

{
    "items": [
        {
            "FavoriteCreateDate": "2021-01-29T22:54:57.623",
            "IsFavorite": true
            "id": "1234",
            "name": "Item Name 1",
            ... all system and custom properties for the item
        },
        {
            "FavoriteCreateDate": "2021-01-29T21:34:22.132",
            "IsFavorite": true
            "id": "9876",
            "name": "Item Name 2",
            ... all system and custom properties for the item
        }
    ]
}

Virtual Layout

Rendering the Favorites button (which you can also generate the code for from the Components Manager > 'CRM' > "Add to Favorites Button"), if not using any layout or collection, the default virtual layout will output as a heart icon, acting as a interface button for toggling an item in or out of the member's Favorites:

{% component type: "favorites", source: "<Module name/ID>", itemId: "{{this.id}}" %}

<div class="cms_add_favorites {% if this.FavoritesInfo.IsFavorite %}added_to_favorites{% endif %}" data-favorites_holder>
	<span data-add_to_favorites_link="{{this.FavoritesInfo.AddToFavoritesUrl}}" data-remove_from_favorites_link="{{this.FavoritesInfo.RemoveFromFavoritesUrl}}" onclick="window.addToFavorites(this); return false;">
		<svg class="cms_add_favorites_trigger" xmlns="http://www.w3.org/2000/svg" height="16" viewBox="0 0 24 24" width="16"><path d="M0 0h24v24H0z" fill="none"/><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/></svg>
	</span>
	<script>
	  'use strict';window.addToFavorites=function(b){let c=b.closest("[data-favorites_holder]"),d=b.dataset.add_to_favorites_link,e=b.dataset.remove_from_favorites_link;c.classList.contains("added_to_favorites")?fetch(e+"?jsonResponse=true",{method:"GET"}).then(function(a){if(200===a.status)return!0;401===a.status?window.location=e:alert(a.json().Message)}).then(function(a){c.classList.remove("added_to_favorites")}):fetch(d+"?jsonResponse=true",{method:"GET"}).then(function(a){if(200===a.status)return!0;
      401===a.status?window.location=d:alert(a.json().Message)}).then(function(a){c.classList.add("added_to_favorites")})};
	</script>
</div>

Rendering the interface element:

To render the Favorited items for the member (which you can also generate the code for from the Components Manager > CRM > "Favorites List"), if using the provided system layout:

{% component type: "favorites", source: "<Module name/ID>", layout: "/cms-assets/layouts/favorites/list.layout" %}

<div class="cms_favorites">
    <h3 class="cms_favorites__title">
        <a href="{{this.url}}" class="cms_favorites__link">{{this.name}}</a> 
        <div class="cms_add_favorites {% if this.FavoritesInfo.IsFavorite %}added_to_favorites{% endif %}" data-favorites_holder>
            <span data-add_to_favorites_link="{{this.FavoritesInfo.AddToFavoritesUrl}}" data-remove_from_favorites_link="{{this.FavoritesInfo.RemoveFromFavoritesUrl}}" onclick="window.addToFavorites(this); return false;"><svg class="cms_add_favorites_trigger" xmlns="http://www.w3.org/2000/svg" height="16" viewBox="0 0 24 24" width="16"><path d="M0 0h24v24H0z" fill="none"/><path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"/></svg></span>
            <script>
              'use strict';window.addToFavorites=function(b){let c=b.closest("[data-favorites_holder]"),d=b.dataset.add_to_favorites_link,e=b.dataset.remove_from_favorites_link;c.classList.contains("added_to_favorites")?fetch(e+"?jsonResponse=true",{method:"GET"}).then(function(a){if(200===a.status)return!0;401===a.status?window.location=e:alert(a.json().Message)}).then(function(a){c.classList.remove("added_to_favorites")}):fetch(d+"?jsonResponse=true",{method:"GET"}).then(function(a){if(200===a.status)return!0;
              401===a.status?window.location=d:alert(a.json().Message)}).then(function(a){c.classList.add("added_to_favorites")})};
            </script>
        </div>
    </h3>
    <p class="cms_favorites__description">{{this.description | strip_html | truncatewords: 10}}</p>
</div>

Rendering the HTML markup:

Item Name 1

Truncated item description here...

Accessing the Data

JSON Output

You can output the full JSON for your component data by referencing the root Liquid object {{this}} in your module’s layouts, or directly on your page, if using the collectionVariable parameter in your component tag.

For example:

{% component type: ... collectionVariable: "myData" %}

You can then render the JSON like so:

{{myData}}

For more details on using this approach, see Part 2 of the free ‘Learning Liquid Course’.

Rendering Property Values

This data is accessible directly on the Page or Template via a Liquid Collection if collectionVariable was added to the Component.

An example using collectionVariable with value "favCollection" for favourited items from the Product module:

{% component type: "favorites", source: "Products", collectionVariable: "favCollection" %}

Using the following forloop directly on the page:

<ul>
    {% for favorite in favCollection.items %}
        <li>{{favorite['name']}}</li>
    {% endfor %}
</ul>

Renders all the item names in a list:

  • Item Name 1
  • Item Name 2

Accessing a specific item within the collection. In this case the second item (zero based index), which in our example would render the value Item Name 2

{{favCollection.items[1]['name']}}

Related Articles

  • Liquid Objects & Usage
    {{ member }} object
    This liquid object will output the Member's details of whom submitted a Form. You can...
  • Content Modules
    Secure Zones
    Secure Zones provide a way of creating restricted content on your website that only registered Secure Zone Members are able to access after successfully logging in.
  • Content Modules
    Comments
    Allow logged-in users to post comments and ratings against items and/or respond to other user’s comments.
  • Liquid Components
    member_update_form
    This component renders a contact update form for a specified CRM contact so that a CRM Admin role, who is logged in to the front-end, can update the specified contact’s CRM info or secure zone subscriptions.
  • Liquid Components
    commentThreads
    This component fetches a threaded list of Comments (and star ratings) assigned to a given module item along with the Comment submission form and author edit links for logged-in members.
  • Liquid Components
    comments
    This component fetches a single list of Comments (and star ratings) assigned to a given module item along with the Comment submission form and author edit links for logged-in members.
  • Liquid Components
    frontend_API

External Resources

There are currently no external resources available.

Please let us know if you have any other contributions or know of any helpful resources you'd like to see added here.

Questions?

We are always happy to help with any questions you may have.
Visit the Treepl Forum for community support and to search previously asked questions or send us a message at support@treepl.co and we will consult you as soon as possible.