[asa2_smart_collection]¶

Introduction ¶

The shortcode [asa2_smart_collection /] gives you the ability to access the products stored in your Products section. It has the power to create dynamic queries based on a set of options. Each product in the result will be rendered with the template of your choice.

The supported options are documented on this page.

Note

Expert knowledge: ASA2 uses a WP_Query object to perform the query on the products. The arguments for the query are populated with the options of the shortcode.

Basic usage ¶

[asa2_smart_collection s="LEGO" tplid="16" limit="5" /]

Options ¶

associate_id_set ¶

Defines which Associate ID set to use. The Associate ID of a product’s country code will be used if it was found in the set.

Note

Option tracking_id is dominant, meaning that if you set tracking_id, this ID will be used and associate_id_set will be ignored.

[asa2_smart_collection s="LEGO" associate_id_set="my-i18n-ids" /]

cat ¶

A comma separated list of Products category IDs. It filters the smart collection result to only contain products attached to ALL of the categories in the list.

Example: The result of this smart collection will only contain products which are attached to the categories with the ids 13, 34 AND 56.

[asa2_smart_collection s="LEGO" cat="13,34,56" /]

The best place to find the product category IDs is on page “ASA2 Products / Categories”:

cat__in ¶

A comma separated list of Products category IDs. It filters the smart collection result to only contain products attached to at least ONE of the category IDs in the list.

Example: The result of this smart collection will only contain products which are attached to either one of the categories 13, 34 OR 56.

[asa2_smart_collection s="LEGO" cat__in="13,34,56" /]

cat__not_in ¶

A comma separated list of Products category IDs. It excludes products from the smart collection which are attached to ONE of the categories in the list.

Example: The result of this smart collection will only contain products which are attached to the category id 13 and NOT attached to the categories 34 OR 56.

[asa2_smart_collection s="LEGO" cat="13" cat__not_in="34,56" /]

cat_slug ¶

A comma separated list of Products category SLUGs. It filters the smart collection result to only contain products attached to ALL the categories in the list.

Example: The result of this smart collection will only contain products which are attached to both categories “starwars” AND “minifigure”.

[asa2_smart_collection s="LEGO" cat_slug="starwars,minifigure" /]

cat_slug__in ¶

A comma separated list of Products category SLUGSs. It filters the smart collection result to only contain products attached to ONE of the category slugs in the list.

Example: The result of this smart collection will only contain products which are attached to either one of the categories “starwars”, “minifigure” OR “vehicle”.

[asa2_smart_collection s="LEGO" cat_slug__in="starwars,minifigure,vehicle" /]

cat_slug__not_in ¶

A comma separated list of Products category SLUGs. It excludes products from the smart collection which are attached to ONE of the categories in the list.

Example: The result of this smart collection will only contain products which are attached to the category slug “starwars” and not attached to “minifigure” AND “vehicle”.

[asa2_smart_collection s="LEGO" cat_slug="starwars" cat_slug__not_in="minifigure,vehicle" /]

cf (Custom Fields)¶

The cf option allows you to filter the smart collection result by WordPress Custom Fields associated with a Products item. To learn how to use WP Custom Fields with Products items, see Custom Fields.

The definition of a Custom Field (CF) criteria consists of at least three segments separated by the character “~”.

Note

Single CF criteria:

cf=”cf_name~cf_operator~cf_value”

Multiple CF criteria:

cf=”cf_name~cf_operator~cf_value&&cf_name~cf_operator~cf_value&&…”

The first segment stands for the CF name as it is stored in the database.
The second segment stands for the comparison operator.
The third segment stands for the value.
The fourth segment is optional stands for the CF type.

Here is an example that filters articles that have the CF “color” value “green”. It uses “=” as operator.

[asa2_smart_collection cf="color~=~green" /]

To specify multiple values to be used as an array, separate the values with commas. The next example shows how and uses “IN” as operator.

[asa2_smart_collection cf="color~IN~green,red,blue" /]

You can combine multiple CF filter criteria. They must be separated by “&&”.

This example adds a second criteria that filters for “my_ratings” having a value greater than 3. It uses the operator “gt” which stands for “greater than” (>).

[asa2_smart_collection cf="color~IN~green,red,blue&&my_rating~gt~3" /]

Supported operators¶

This is a list of the supported comparison operators (second segment):

‘=’, ‘!=’, ‘gt’ (>), ‘gte’ (>=), ‘lt’ (<), ‘lte’ (<=), ‘LIKE’, ‘NOT LIKE’, ‘IN’, ‘NOT IN’, ‘BETWEEN’, ‘NOT BETWEEN’, ‘NOT EXISTS’, ‘REGEXP’, ‘NOT REGEXP’, ‘RLIKE’

Supported CF types¶

This is a list of the supported Custom Field types (optional fourth segment):

‘NUMERIC’, ‘BINARY’, ‘CHAR’, ‘DATE’, ‘DATETIME’, ‘DECIMAL’, ‘SIGNED’, ‘TIME’, ‘UNSIGNED’

country_code ¶

Use a valid Amazon country code to retrieve only Products items from that country store.

This example will only show products from the “US” Amazon store.

[asa2_smart_collection s="LEGO" country_code="US" /]

disabled ¶

If you want to hide a smart collection temporarily but not to delete the whole shortcode, you can use option disabled. If it is set to 1, the shortcode will not be rendered.

[asa2_smart_collection s="LEGO" disabled="1" /]

has_small_image_url ¶

Use the option has_small_image_url to only get products having or not having a small image URL.

Options:

“true” / “1”: Only show products with a small image URL
“false” / “0”: Only show products without a small image URL

[asa2_smart_collection cat_slug="starwars" has_small_image_url="true" /]

has_medium_image_url ¶

Use the option has_medium_image_url to only get products having or not having a medium image URL.

Options:

“true” / “1”: Only show products with a medium image URL
“false” / “0”: Only show products without a medium image URL

[asa2_smart_collection cat_slug="starwars" has_medium_image_url="true" /]

has_large_image_url ¶

Use the option has_large_image_url to only get products having or not having a large image URL.

Options:

“true” / “1”: Only show products with a large image URL
“false” / “0”: Only show products without a large image URL

[asa2_smart_collection cat_slug="starwars" has_large_image_url="true" /]

i18n ¶

Use the option i18n to filter for products that are prepared for internationalization. For more details about ASA2’s i18n functionality read chapter Internationalization (i18n).

Options:

“true” / “1”: Only show products that are prepared for internationalization
“false” / “0”: Only show products that are not prepared for internationalization

// will show up to 10 i18n prepared items:
[asa2_smart_collection i18n="1" limit="10" /]

// will exclude i18n prepared products:
[asa2_smart_collection i18n="false" limit="10" /]

is_available_main ¶

Use the option is_available_main to filter for products that have a main price available.

Options:

“true” / “1”: Only show products that have a main price
“false” / “0”: Only show products that do not have a main price

[asa2_smart_collection cat_slug="starwars" is_available_main="true" /]

is_available_new ¶

Use the option is_available_new to filter for products the have offers for new items.

Options:

“true” / “1”: Only show products that have offers for new items
“false” / “0”: Only show products that do not have offers for new items

[asa2_smart_collection cat_slug="starwars" is_available_new="true" /]

is_available_used ¶

Use the option is_available_used to filter for products the have offers for used items.

Options:

“true” / “1”: Only show products that have offers for used items
“false” / “0”: Only show products that do not have offers for used items

[asa2_smart_collection cat_slug="starwars" is_available_used="true" /]

is_prime ¶

Use the is_prime option to filter for Products products available via Amazon Prime.

To receive only products available via Prime, use is_prime="1":

[asa2_smart_collection s="LEGO" is_prime="1" /]

Or the opposite, to get only products not available via Prime, use is_prime="0":

[asa2_smart_collection s="LEGO" is_prime="0" /]

limit ¶

To limit the result of a smart collection, use the limit option. By default the limit is set to 10. To reset the limit, set it to 0.

The following example will generate a list of 5 products matching the search string “LEGO”.

[asa2_smart_collection s="LEGO" tplid="16" limit="5" /]

main_price_gt ¶

Use the option main_price_gt to only get Products items having a main price greater than a given number.

For example, only load items from the category “starwars” with a main price greater than 100:

[asa2_smart_collection cat_slug="starwars" main_price_gt="100" /]

main_price_lt ¶

If you want to load only products with a main price less than a given number, use the main_price_lt option.

This example will only load Products items from the category “starwars” with a main price less than 50:

[asa2_smart_collection cat_slug="starwars" main_price_lt="50" /]

main_price_between ¶

You can also define a range in between the main price of a Products item should be, by using the option main_price_between.

For example, only load items from the category “starwars” with a main price between 50 and 100.

[asa2_smart_collection cat_slug="starwars" main_price_between="50,100"]

mobile_tpl ¶

With option mobile_tpl you can define a template which will be used on mobile devices (Smartphones). Note that option Mobile templates has to be activated before this will work.

[asa2_smart_collection cat_slug="starwars" mobile_tpl="my_template_for_smartphones" /]

no_cache ¶

The no_cache option will prevent the smart collection result from being loaded from template cache. This is useful if you want to test template updates in the frontend. In production you should use it with care.

[asa2_smart_collection s="LEGO" tplid="16" no_cache="1" /]

orderby ¶

If you want to order the smart collection items, use the orderby option.

Options are:

main_price (product main price)

rand (random order)

rating (customer reviews)

sales_rank (product sales rank)

timestamp (when added to collection)

title (product title)

cf_* (custom field)

[asa2_smart_collection s="LEGO" tplid="16" limit="5" orderby="title" /]

// if you want to order by a custom field named "custom_rating"
[asa2_smart_collection cat="4" limit="0" orderby="cf_custom_rating" order="desc" /]

// if you want to order by a custom field named "ranking"
[asa2_smart_collection cat="4" limit="0" orderby="cf_ranking" order="desc" /]

order ¶

The order direction.

Options are:

asc (ascending)

desc (descending)

Default is “asc”.

[asa2_smart_collection s="LEGO" tplid="16" limit="5" orderby="title" order="desc" /]

rating_gt ¶

Use the rating_gt option to only get Products items with a rating greater than the given number.

For example, only load items from the category “starwars” with a rating greater than 4:

[asa2_smart_collection cat_slug="starwars" rating_gt="4" /]

You can also use a decimal place, like:

[asa2_smart_collection cat_slug="starwars" rating_gt="4.4" /]

rating_lt ¶

If you want to load only products with a rating less than a given number, use the rating_lt option.

This example will only load Products items from the category “starwars” with a rating less than 3.5:

[asa2_smart_collection cat_slug="starwars" rating_gt="3.5" /]

rating_between ¶

You can also define a range in between the rating of a Products item should be, by using the option rating_between.

For example, only load items from the category “starwars” with a rating between 3.5 and 4:

[asa2_smart_collection cat_slug="starwars" rating_gt="3.5,4" /]

s ¶

A search string. You can use it to filter Products items by their title.

This example will generate a smart collection of products including “LEGO” in their title:

[asa2_smart_collection s="LEGO" /]

sales_rank_gt ¶

Use the option sales_rank_gt to only get Products items having a sales rank greater than a given number.

For example, only load Products items from the category “starwars” with a sales rank greater than 100:

[asa2_smart_collection cat_slug="starwars" sales_rank_gt="100" /]

sales_rank_lt ¶

If you want to load only products with a sales rank less than a given number, use the sales_rank_lt option.

This example will only load Products items from the category “starwars” with a sales rank less than 50:

[asa2_smart_collection cat_slug="starwars" sales_rank_lt="50" /]

sales_rank_between ¶

You can also define a range in between the sales rank of a Products item should be, by using the option sales_rank_between.

For example, only load items from the category “starwars” with a sales rank between 50 and 100.

[asa2_smart_collection cat_slug="starwars" sales_rank_between="50,100" /]

shop_id ¶

With the option “shop_id” it is possible to display only products of one or more Shops.

[asa2_smart_collection limit="3" shop_id="42,100" /]

short_url ¶

Use the option short_url to transform the Amazon page URL into a shorter format.

[asa2_smart_collection s="LEGO" short_url="1" /]

// results in links like: http://www.amazon.de/exec/obidos/ASIN/B0094J2BZ0/tracking-id

tag ¶

A comma separated list of Products tag SLUGs. It filters the smart collection result to only contain products tagged with ALL the tag slugs in the list.

Example: The result of this smart collection will only contain products which are attached to the tags “Sale” AND “Green” defined by their slugs.

[asa2_smart_collection s="LEGO" tag="sale,green" /]

tag_id ¶

A comma separated list of Products tag IDs. It filters the smart collection result to only contain products attached to ALL the tag IDs in the list.

This example will show only those products attached to tag ID 15 AND 46:

[asa2_smart_collection s="LEGO" tag_id="15,46" /]

The best place to find the product tags IDs is on page “ASA2 Products / Tags”:

tag__in ¶

A comma separated list of Products tag IDs. It filters the smart collection result to only contain products attached to at least ONE of the tag IDs in the list.

Example: The result of this smart collection will only contain products which are attached to either one of the categories 13, 34 OR 56.

[asa2_smart_collection s="LEGO" tag__in="15,46" /]

tag__not_in ¶

A comma separated list of Products tag IDs. It excludes products from the smart collection which are attached to ONE of the categories in the list.

Example: The result of this smart collection will only contain products tagged with “sale” and NOT attached to the tag IDs 15 OR 46.

[asa2_smart_collection s="LEGO" tag="sale" tag__not_in="15,46" /]

tag_slug__in ¶

A comma separated list of Products tag SLUGSs. It filters the smart collection result to only contain products attached to at least ONE of the tag slugs in the list.

Example: The result of this smart collection will only contain products which are attached to either one of the tag slugs “spaceship”, “sale” OR “yellow”.

[asa2_smart_collection s="LEGO" tag_slug__in="spaceship,sale,yellow" /]

tag_slug__not_in ¶

A comma separated list of Products tag SLUGs. It excludes products from the smart collection which are attached to at least ONE of the tag slugs in the list.

Example: The result of this smart collection will only contain products which are tagged with “spaceship” and are not tagged with “sale” AND “yellow”.

[asa2_smart_collection s="LEGO" tag_slug="spaceship" tag_slug__not_in="sale,yellow" /]

tpl ¶

If you do not want to use the default template to render the smart collection items, you can define a custom template by its name using the tpl option.

[asa2_smart_collection s="LEGO" tpl="my_awsome_template" /]

tplid ¶

If you want to define a template by its ID, use the tplid option. You can find the ID in the first column of the template table. Using the template ID allows you to change the template’s name afterwards.

[asa2_smart_collection s="LEGO" tplid="16" /]

tracking_id ¶

You can also set a custom Associate ID in the asa2_smart_collection options.

[asa2_smart_collection s="LEGO" tracking_id="other-id" /]

Custom Values Placeholders ¶

Additionally to the shortcode options, you can also define custom values to use as placeholders in templates.

It is very easy. Just define a unique shortcode option with a value and use the exact same option name as placeholder in a template.

[asa2_smart_collection s="LEGO" my_custom_text="Banana!" /]

# use placeholder {{ my_custom_text }} in your template