{"_id":"58112e73ded0340f0085d06b","__v":0,"category":{"_id":"58112e72ded0340f0085d02c","project":"551e85be610f400d00837db7","__v":0,"version":"58112e71ded0340f0085d02a","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-04-07T18:58:09.521Z","from_sync":false,"order":2,"slug":"theme-logic","title":"Theme Logic & Components"},"project":"551e85be610f400d00837db7","user":"551e85707ca3030d00be0c07","parentDoc":null,"version":{"_id":"58112e71ded0340f0085d02a","project":"551e85be610f400d00837db7","__v":4,"createdAt":"2016-10-26T22:30:09.862Z","releaseDate":"2016-10-26T22:30:09.862Z","categories":["58112e72ded0340f0085d02b","58112e72ded0340f0085d02c","58112e72ded0340f0085d02d","58112e72ded0340f0085d02e","58112e72ded0340f0085d02f","58112e72ded0340f0085d030","58112e72ded0340f0085d031","58112e72ded0340f0085d032","58112e72ded0340f0085d033","58112e72ded0340f0085d034","581137cc604d3c230048b7e4","58dc367221742d0f00a73f98","590768e54669da0f00db5c0b"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"new designer","version_clean":"2.0.0","version":"2.0"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-04-07T21:49:25.059Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Filters are basic methods for modifying strings, numbers, variables, and objects. Using a filter is as simple as adding ``| filter_name`` after whatever you want to filter\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- product.name = \\\"great subscription box\\\" -->\\n{{ product.name | title }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n\n**Output**:\n\n```\nGreat Subscription Box\n```\n\nThe ``title`` filter is a [Jinja built-in filter](http://jinja.pocoo.org/docs/dev/templates/#title)\n\nThemes have access to all the [Jinja2 built-in filters](http://jinja.pocoo.org/docs/dev/templates/#list-of-builtin-filters), plus some Cratejoy defined filters, described below.\n\n# FORMATTING\n\n## currency\nThe ``currency`` filter formats a currency according to your store’s configured currency. It defaults to 2 decimal places, but you can also specify different values.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- price = 500 -->\\n{{ price | currency }}\\n{{ price | currency(0) }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n$5.00\n$5\n```\n\n## tojson\n\nWe also expose a ``tojson`` filter, which converts an object into JSON. If used inside a script tag, disable escaping with jinja2’s ‘safe’ filter.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- store.name = \\\"My Store\\\"  -->  \\n<script type=\\\"text/javascript\\\">\\n    runExampleCode({{ store.name | tojson | safe }});\\n</script>\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<script type=\"text/javascript\">\n    runExampleCode(\"My Store\");\n</script>\n```\n\n# TAGS\n\nTag filters create HTML tags from Jinja variables.\n\n## img_tag\n\nCreates an ``<img>`` tag from a URL\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{ 'images/man_with_hat.jpg' | asset_url | img_tag(\\\"A dapper gentleman wearing a top hat\\\", \\\"thumbnail\\\") }}\\n{{ 'images/man_with_hat.jpg' | asset_url | img_tag }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<img src=\"//cdn.cratejoy.com/storename/designname/images/man_with_hat.jpg\" alt=\"A dapper gentleman wearing a top hat\" class=\"thumbnail\" />\n<img src=\"//cdn.cratejoy.com/storename/designname/images/man_with_hat.jpg\" />\n```\n\n## icon_tag\n\nCreates an icon ``<link>`` from a URL\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{ 'images/favicon.ico' | asset_url | icon_tag }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<link href=\"//cdn.cratejoy.com/storename/designname/images/favicon.ico\" rel=\"icon\" type=\"image/x-icon\">\n```\n\n## stylesheet_tag\n\nCreates a stylesheet ``<link>`` from a URL\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{ 'css/style.css' | asset_url | stylesheet_tag }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<link rel=\"stylesheet\" href=\"//cdn.cratejoy.com/storename/designname/css/style.css\" type=\"text/css\" />\n```\n\n## javascript_tag\n\nCreates a javascript ``<script>`` tag from a URL\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{ 'js/store.js' | asset_url | javascript_tag }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<script type=\"text/javascript\" src=\"//cdn.cratejoy.com/storename/designname/js/store.js\"></script>\n```\n\n# URL\n\nURL filters help create URLs to files in your store's themes. It is important to use URL filters or you may be referencing your files in a way which bypasses our content distribution network and slows down your storefront's loading for customers.\n\n## asset_url\nReturns a URL from a file asset which is part of a design\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<a href=\\\"{{ 'images/big.jpg' | asset_url }}\\\">Big Image</a>\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<a href=\"//cdn.cratejoy.com/storename/designname/images/big.jpg\">Big Image</a>\n```\n\n## global_asset_url\n\nReturns a URL from a file asset which is part of the Cratejoy provided platform\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{{ 'css/store.css' | global_asset_url | stylesheet_tag }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<link rel=\"stylesheet\" href=\"//cdn.cratejoy.com/css/store.css\" type=\"text/css\" />\n```\n\n\n## product\nReturn a product object for a given product id.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{% set product = 12345678 | get_product %}\\n{{ product.name }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\nMy Little Box\n```\n    \n## product_subscribe_url\nReturns the URL that corresponds to a product subscription choice, for example a variant or a term\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<a class=\\\"btn btn-default\\\" href=\\\"{{ product | product_subscribe_url(chosen_values,\\\"large-box\\\") }}\\\">Select Large Box</a>\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<a class=\"btn btn-default\" href=\"//teststore.cratejoy.com/subscribe/1111_My+Box/1111_large-box\">Select Large Box</a>\n```\n\n## product_ecom_url\nReturns the URL that corresponds to an e-commerce product\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<a href=\\\"{{ product | product_ecom_url }}\\\">{{ product.name | safe}}</a>\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<a href=\"//teststore.cratejoy.com/shop/product/1111_Dapper+Hat\">Dapper Hat</a>\n```\n\n## cratejoy_domain\n\nReturns a store’s cratejoy domain\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<a href=\\\"https://{{ store | cratejoy_domain }}/subscribe/\\\">Subscribe Now!</a>\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<a href=\"https://teststore.cratejoy.com/subscribe/\">Subscribe Now!</a>\n```\n\n## custom_domain\n\nReturns a store’s custom domain\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<a href=\\\"https://{{ store | custom_domain }}/subscribe/\\\">Subscribe Now!</a>\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<a href=\"https://teststore.com/subscribe/\">Subscribe Now!</a>\n```\n\n# UTILITY\n\nThese filters are time saver functions.\n\n## get_price_or_price_range\n\nReturns a price or min-max price range for a product and optional variants. Since products can have a range of prices based on variant choices and term options, this method is a convenient way of seamlessly handling a single price or price range without any template side logic.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<span class=\\\"price\\\">{{ product | get_price_or_price_range }}</span>\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\nIf the product has multiple pre-payment terms it may return a range like this:\n\n```\n<span class=\"price\"><p>$10-$25</p></span>\n```\n\nIf the product has just a single pre-payment term (such as month to month) it would return a single price:\n\n```\n<span class=\"price\"><p>$25</p></span>\n```\n\nVariant values may also be specified\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- value is the variant value we're getting the price for -->\\n<span class=\\\"price\\\">{{ product | get_price_or_price_range(value.variant_type, values = chosen_values + [value]) }}</span>\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n## append_kvp\n\nReturns a URL with a Key-Value pair appended to it. Used to select variants in subscribe flow\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- base_url = \\\"http://teststore.cratejoy.com/subscribe/\\\" -->\\n<a href=\\\"{{ base_url | append_kvp('box-size', 'small') }}\\\">Select Small Box</a>\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\n<a href=\"http://teststore.cratejoy.com/subscribe/box-size_small\">Select Small Box</a>\n```\n\n## category\n\nReturns products matching passed in taxonomies.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!--\\nstore.ecom_products contains\\nname - taxonomies\\n\\\"Bird Necklacke\\\" - ['birds']\\n\\\"Pith Helmet\\\" - ['helmets']\\n\\\"Snow Shoes\\\" - ['shoes', 'snow']\\n\\\"Hawk Headdress\\\" - ['helmets', 'birds']\\n-->\\n{% for p in store.ecom_products | category('birds', 'helmets') %}\\n    {{ p.name }}\\n{% endfor %}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\nBird Necklace\nPith Helmet\nHawk Headdress\n```\n\n## meta_value\n\nReturns the meta field value for the passed in key\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- If your subscription had a meta field key value pair {\\\"flavor_preference\\\": \\\"Savory\\\"}-->\\nYour Flavor Preference: {{ subscription | meta_value(\\\"flavor_preference\\\") }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\nYour Flavor Preference: Savory\n```\n\n## get_meta_dict\n\nReturns a dictionary of all meta fields attached to the filtered object\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!-- If your subscription had a meta field key value pair {\\\"flavor_preference\\\": \\\"Savory\\\", \\\"send_day\\\":\\\"Friday\\\"}-->\\n{% set meta = subscription|get_meta_dict %}\\nYour Flavor Preference: {{ meta.flavor_preference }}\\nYour Send Day: {{ meta.send_day }}\",\n      \"language\": \"jinja2\"\n    }\n  ]\n}\n[/block]\n**Output:**\n\n```\nYour Flavor Preference: Savory\nYour Send Day: Friday\n```","excerpt":"","slug":"filters","type":"basic","title":"Filters"}
Filters are basic methods for modifying strings, numbers, variables, and objects. Using a filter is as simple as adding ``| filter_name`` after whatever you want to filter [block:code] { "codes": [ { "code": "<!-- product.name = \"great subscription box\" -->\n{{ product.name | title }}", "language": "jinja2" } ] } [/block] **Output**: ``` Great Subscription Box ``` The ``title`` filter is a [Jinja built-in filter](http://jinja.pocoo.org/docs/dev/templates/#title) Themes have access to all the [Jinja2 built-in filters](http://jinja.pocoo.org/docs/dev/templates/#list-of-builtin-filters), plus some Cratejoy defined filters, described below. # FORMATTING ## currency The ``currency`` filter formats a currency according to your store’s configured currency. It defaults to 2 decimal places, but you can also specify different values. [block:code] { "codes": [ { "code": "<!-- price = 500 -->\n{{ price | currency }}\n{{ price | currency(0) }}", "language": "jinja2" } ] } [/block] **Output:** ``` $5.00 $5 ``` ## tojson We also expose a ``tojson`` filter, which converts an object into JSON. If used inside a script tag, disable escaping with jinja2’s ‘safe’ filter. [block:code] { "codes": [ { "code": "<!-- store.name = \"My Store\" --> \n<script type=\"text/javascript\">\n runExampleCode({{ store.name | tojson | safe }});\n</script>", "language": "jinja2" } ] } [/block] **Output:** ``` <script type="text/javascript"> runExampleCode("My Store"); </script> ``` # TAGS Tag filters create HTML tags from Jinja variables. ## img_tag Creates an ``<img>`` tag from a URL [block:code] { "codes": [ { "code": "{{ 'images/man_with_hat.jpg' | asset_url | img_tag(\"A dapper gentleman wearing a top hat\", \"thumbnail\") }}\n{{ 'images/man_with_hat.jpg' | asset_url | img_tag }}", "language": "jinja2" } ] } [/block] **Output:** ``` <img src="//cdn.cratejoy.com/storename/designname/images/man_with_hat.jpg" alt="A dapper gentleman wearing a top hat" class="thumbnail" /> <img src="//cdn.cratejoy.com/storename/designname/images/man_with_hat.jpg" /> ``` ## icon_tag Creates an icon ``<link>`` from a URL [block:code] { "codes": [ { "code": "{{ 'images/favicon.ico' | asset_url | icon_tag }}", "language": "jinja2" } ] } [/block] **Output:** ``` <link href="//cdn.cratejoy.com/storename/designname/images/favicon.ico" rel="icon" type="image/x-icon"> ``` ## stylesheet_tag Creates a stylesheet ``<link>`` from a URL [block:code] { "codes": [ { "code": "{{ 'css/style.css' | asset_url | stylesheet_tag }}", "language": "jinja2" } ] } [/block] **Output:** ``` <link rel="stylesheet" href="//cdn.cratejoy.com/storename/designname/css/style.css" type="text/css" /> ``` ## javascript_tag Creates a javascript ``<script>`` tag from a URL [block:code] { "codes": [ { "code": "{{ 'js/store.js' | asset_url | javascript_tag }}", "language": "jinja2" } ] } [/block] **Output:** ``` <script type="text/javascript" src="//cdn.cratejoy.com/storename/designname/js/store.js"></script> ``` # URL URL filters help create URLs to files in your store's themes. It is important to use URL filters or you may be referencing your files in a way which bypasses our content distribution network and slows down your storefront's loading for customers. ## asset_url Returns a URL from a file asset which is part of a design [block:code] { "codes": [ { "code": "<a href=\"{{ 'images/big.jpg' | asset_url }}\">Big Image</a>", "language": "jinja2" } ] } [/block] **Output:** ``` <a href="//cdn.cratejoy.com/storename/designname/images/big.jpg">Big Image</a> ``` ## global_asset_url Returns a URL from a file asset which is part of the Cratejoy provided platform [block:code] { "codes": [ { "code": "{{ 'css/store.css' | global_asset_url | stylesheet_tag }}", "language": "jinja2" } ] } [/block] **Output:** ``` <link rel="stylesheet" href="//cdn.cratejoy.com/css/store.css" type="text/css" /> ``` ## product Return a product object for a given product id. [block:code] { "codes": [ { "code": "{% set product = 12345678 | get_product %}\n{{ product.name }}", "language": "jinja2" } ] } [/block] **Output:** ``` My Little Box ``` ## product_subscribe_url Returns the URL that corresponds to a product subscription choice, for example a variant or a term [block:code] { "codes": [ { "code": "<a class=\"btn btn-default\" href=\"{{ product | product_subscribe_url(chosen_values,\"large-box\") }}\">Select Large Box</a>", "language": "jinja2" } ] } [/block] **Output:** ``` <a class="btn btn-default" href="//teststore.cratejoy.com/subscribe/1111_My+Box/1111_large-box">Select Large Box</a> ``` ## product_ecom_url Returns the URL that corresponds to an e-commerce product [block:code] { "codes": [ { "code": "<a href=\"{{ product | product_ecom_url }}\">{{ product.name | safe}}</a>", "language": "jinja2" } ] } [/block] **Output:** ``` <a href="//teststore.cratejoy.com/shop/product/1111_Dapper+Hat">Dapper Hat</a> ``` ## cratejoy_domain Returns a store’s cratejoy domain [block:code] { "codes": [ { "code": "<a href=\"https://{{ store | cratejoy_domain }}/subscribe/\">Subscribe Now!</a>", "language": "jinja2" } ] } [/block] **Output:** ``` <a href="https://teststore.cratejoy.com/subscribe/">Subscribe Now!</a> ``` ## custom_domain Returns a store’s custom domain [block:code] { "codes": [ { "code": "<a href=\"https://{{ store | custom_domain }}/subscribe/\">Subscribe Now!</a>", "language": "jinja2" } ] } [/block] **Output:** ``` <a href="https://teststore.com/subscribe/">Subscribe Now!</a> ``` # UTILITY These filters are time saver functions. ## get_price_or_price_range Returns a price or min-max price range for a product and optional variants. Since products can have a range of prices based on variant choices and term options, this method is a convenient way of seamlessly handling a single price or price range without any template side logic. [block:code] { "codes": [ { "code": "<span class=\"price\">{{ product | get_price_or_price_range }}</span>", "language": "jinja2" } ] } [/block] **Output:** If the product has multiple pre-payment terms it may return a range like this: ``` <span class="price"><p>$10-$25</p></span> ``` If the product has just a single pre-payment term (such as month to month) it would return a single price: ``` <span class="price"><p>$25</p></span> ``` Variant values may also be specified [block:code] { "codes": [ { "code": "<!-- value is the variant value we're getting the price for -->\n<span class=\"price\">{{ product | get_price_or_price_range(value.variant_type, values = chosen_values + [value]) }}</span>", "language": "jinja2" } ] } [/block] ## append_kvp Returns a URL with a Key-Value pair appended to it. Used to select variants in subscribe flow [block:code] { "codes": [ { "code": "<!-- base_url = \"http://teststore.cratejoy.com/subscribe/\" -->\n<a href=\"{{ base_url | append_kvp('box-size', 'small') }}\">Select Small Box</a>", "language": "jinja2" } ] } [/block] **Output:** ``` <a href="http://teststore.cratejoy.com/subscribe/box-size_small">Select Small Box</a> ``` ## category Returns products matching passed in taxonomies. [block:code] { "codes": [ { "code": "<!--\nstore.ecom_products contains\nname - taxonomies\n\"Bird Necklacke\" - ['birds']\n\"Pith Helmet\" - ['helmets']\n\"Snow Shoes\" - ['shoes', 'snow']\n\"Hawk Headdress\" - ['helmets', 'birds']\n-->\n{% for p in store.ecom_products | category('birds', 'helmets') %}\n {{ p.name }}\n{% endfor %}", "language": "jinja2" } ] } [/block] **Output:** ``` Bird Necklace Pith Helmet Hawk Headdress ``` ## meta_value Returns the meta field value for the passed in key [block:code] { "codes": [ { "code": "<!-- If your subscription had a meta field key value pair {\"flavor_preference\": \"Savory\"}-->\nYour Flavor Preference: {{ subscription | meta_value(\"flavor_preference\") }}", "language": "jinja2" } ] } [/block] **Output:** ``` Your Flavor Preference: Savory ``` ## get_meta_dict Returns a dictionary of all meta fields attached to the filtered object [block:code] { "codes": [ { "code": "<!-- If your subscription had a meta field key value pair {\"flavor_preference\": \"Savory\", \"send_day\":\"Friday\"}-->\n{% set meta = subscription|get_meta_dict %}\nYour Flavor Preference: {{ meta.flavor_preference }}\nYour Send Day: {{ meta.send_day }}", "language": "jinja2" } ] } [/block] **Output:** ``` Your Flavor Preference: Savory Your Send Day: Friday ```