.. include:: _include.rst .. highlight:: bbcode .. _shortcodes_asa2_smart_collection: ################################# [asa2_smart_collection] ################################# .. include:: _include_local_toc.rst ************ Introduction ************ The shortcode ``[asa2_smart_collection /]`` gives you the ability to **access the products** stored in your :ref:`repo` 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**: |productabbr| 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 *********** .. code:: [asa2_smart_collection s="LEGO" tplid="16" limit="5" /] .. _shortcodes_asa2_smart_collection_options: ******* 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. .. code:: [asa2_smart_collection s="LEGO" associate_id_set="my-i18n-ids" /] cat ~~~~~~ A comma separated list of :ref:`repo` **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. .. code:: [asa2_smart_collection s="LEGO" cat="13,34,56" /] The best place to find the product category IDs is on page "ASA2 Products / Categories": .. image:: _static/repo_cat_ids.gif :height: 207px :width: 500px :scale: 100% :alt: Product categories IDs cat__in ~~~~~~~ A comma separated list of :ref:`repo` **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. .. code:: [asa2_smart_collection s="LEGO" cat__in="13,34,56" /] cat__not_in ~~~~~~~~~~~ A comma separated list of :ref:`repo` **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. .. code:: [asa2_smart_collection s="LEGO" cat="13" cat__not_in="34,56" /] cat_slug ~~~~~~~~ A comma separated list of :ref:`repo` **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". .. code:: [asa2_smart_collection s="LEGO" cat_slug="starwars,minifigure" /] cat_slug__in ~~~~~~~~~~~~ A comma separated list of :ref:`repo` **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". .. code:: [asa2_smart_collection s="LEGO" cat_slug__in="starwars,minifigure,vehicle" /] cat_slug__not_in ~~~~~~~~~~~~~~~~ A comma separated list of :ref:`repo` **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". .. code:: [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 :ref:`repo` item. To learn how to use WP Custom Fields with :ref:`repo` items, see :ref:`repo_adv_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. .. code:: [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. .. code:: [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" (>). .. code:: [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 :ref:`repo` items from that country store. This example will only show products from the "US" Amazon store. .. code:: [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. .. code:: [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 .. code:: [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 .. code:: [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 .. code:: [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 :ref:`i18n`. Options: - "true" / "1": Only show products that **are prepared** for internationalization - "false" / "0": Only show products that **are not prepared** for internationalization .. code:: // 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 .. code:: [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 .. code:: [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 .. code:: [asa2_smart_collection cat_slug="starwars" is_available_used="true" /] is_prime ~~~~~~~~ Use the ``is_prime`` option to filter for :ref:`repo` products **available via Amazon Prime**. To receive only products available via Prime, use ``is_prime="1"``: .. code:: [asa2_smart_collection s="LEGO" is_prime="1" /] Or the opposite, to get only products **not available via Prime**, use ``is_prime="0"``: .. code:: [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". .. code:: [asa2_smart_collection s="LEGO" tplid="16" limit="5" /] main_price_gt ~~~~~~~~~~~~~ Use the option ``main_price_gt`` to only get :ref:`repo` 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: .. code:: [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 :ref:`repo` items from the category "starwars" with a main price less than 50: .. code:: [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 :ref:`repo` 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. .. code:: [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 :ref:`options_templates_mobile` has to be activated before this will work. .. code:: [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. .. code:: [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) .. code:: [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". .. code:: [asa2_smart_collection s="LEGO" tplid="16" limit="5" orderby="title" order="desc" /] rating_gt ~~~~~~~~~ Use the ``rating_gt`` option to only get :ref:`repo` items with a **rating greater than** the given number. For example, only load items from the category "starwars" with a rating greater than 4: .. code:: [asa2_smart_collection cat_slug="starwars" rating_gt="4" /] You can also use a decimal place, like: .. code:: [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 :ref:`repo` items from the category "starwars" with a rating less than 3.5: .. code:: [asa2_smart_collection cat_slug="starwars" rating_gt="3.5" /] rating_between ~~~~~~~~~~~~~~ You can also define a range in between the rating of a :ref:`repo` 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: .. code:: [asa2_smart_collection cat_slug="starwars" rating_gt="3.5,4" /] s ~ A search string. You can use it to filter :ref:`repo` items by their title. This example will generate a smart collection of products including "LEGO" in their title: .. code:: [asa2_smart_collection s="LEGO" /] sales_rank_gt ~~~~~~~~~~~~~ Use the option ``sales_rank_gt`` to only get :ref:`repo` items having a sales rank greater than a given number. For example, only load :ref:`repo` items from the category "starwars" with a sales rank greater than 100: .. code:: [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 :ref:`repo` items from the category "starwars" with a sales rank less than 50: .. code:: [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 :ref:`repo` 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. .. code:: [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 :ref:`shops`. .. code:: [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. .. code:: [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 :ref:`repo` **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. .. code:: [asa2_smart_collection s="LEGO" tag="sale,green" /] tag_id ~~~~~~ A comma separated list of :ref:`repo` **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: .. code:: [asa2_smart_collection s="LEGO" tag_id="15,46" /] The best place to find the product tags IDs is on page "ASA2 Products / Tags": .. image:: _static/repo_tag_ids.gif :height: 207px :width: 500px :scale: 100% :alt: product tag IDs tag__in ~~~~~~~ A comma separated list of :ref:`repo` **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. .. code:: [asa2_smart_collection s="LEGO" tag__in="15,46" /] tag__not_in ~~~~~~~~~~~ A comma separated list of :ref:`repo` **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. .. code:: [asa2_smart_collection s="LEGO" tag="sale" tag__not_in="15,46" /] tag_slug__in ~~~~~~~~~~~~ A comma separated list of :ref:`repo` **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". .. code:: [asa2_smart_collection s="LEGO" tag_slug__in="spaceship,sale,yellow" /] tag_slug__not_in ~~~~~~~~~~~~~~~~ A comma separated list of :ref:`repo` **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". .. code:: [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. .. code:: [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. .. code:: [asa2_smart_collection s="LEGO" tplid="16" /] .. image:: _static/templates_col_id.jpg :height: 267px :width: 527px :scale: 100% :alt: Templates table column ID tracking_id ~~~~~~~~~~~ You can also set a custom Associate ID in the asa2_smart_collection options. .. code:: [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. .. code:: [asa2_smart_collection s="LEGO" my_custom_text="Banana!" /] # use placeholder {{ my_custom_text }} in your template