| Both sides previous revisionPrevious revisionNext revision | Previous revision |
| v:2.0:templates:advanced [2017/02/02 05:13] – [Allowed Twig Tags and Functionality] adam | v:2.0:templates:advanced [2023/05/25 12:21] (current) – adam |
|---|
| |
| ===== Getting even more advanced with Twig ===== | ===== Getting even more advanced with Twig ===== |
| If you'd like to customize your templates beyond what you can do with HTML, CSS, and JavaScript, FoxyCart allows you to use the [[http://twig.sensiolabs.org/|Twig template language]] as well. Twig is flexible template language that's either near identical or relatively similar to a variety of other template languages. This functionality is very advanced, and most users should be able to achieve very very seamless visual integrations without this. If you have super specific needs, however, you can dig into Twig. | If you'd like to customize your templates beyond what you can do with HTML, CSS, and JavaScript, FoxyCart allows you to use the [[https://twig.symfony.com|Twig template language]] as well. Twig is flexible template language that's either near identical or relatively similar to a variety of other template languages. This functionality is very advanced, and most users should be able to achieve very seamless visual integrations without this. If you have super specific needs, however, you can dig into Twig. |
| |
| ===== Templates and Caching: How it all works ===== | ===== Templates and Caching: How it all works ===== |
| |
| * We use [[http://twig.sensiolabs.org/|Twig]] as a template language, and we use [[https://github.com/justjohn/twig.js/wiki|Twig.js]] as well. Doing this allows us (and you) to use the same templates for clientside and serverside rendering. | * We use [[https://twig.symfony.com|Twig]] as a template language, and we use [[https://github.com/justjohn/twig.js/wiki|Twig.js]] as well. Doing this allows us (and you) to use the same templates for clientside and serverside rendering. |
| * We use the [[http://bem.info/method/definitions/|BEM methodology]] for CSS naming. | * We use the [[http://bem.info/method/definitions/|BEM methodology]] for CSS naming. |
| * All template variables used exist in the ''FC.json'' object. You'll see references to variables in the template files. That's where they live, but there are helper methods to work with that data. | * All template variables used exist in the ''FC.json'' object. You'll see references to variables in the template files. That's where they live, but there are helper methods to work with that data. |
| * We have a system we call AutoMagiCache, which scrapes a template file on your site and will cache it (and all assets) securely on our systems, so you don't need SSL on your own server to reference assets (images, css, js). [[v:2.0:templates:intermediate-automagicache|Details on working with AutoMagiCache here]]. | * We have a system we call AutoMagiCache, which scrapes a template file on your site and will cache it (and all assets) securely on our systems, so you don't need SSL on your own server to reference assets (images, css, js). [[v:2.0:templates:intermediate-automagicache|Details on working with AutoMagiCache here]]. |
| * We're currently using Twitter Bootstrap 3 as a base for our default theme, but we're using SASS ''@extend'' functionality so you won't see any Bootstrap classnames. | * We're currently using Twitter Bootstrap 3 as a base for our default theme, but we're using SASS ''@extend'' functionality so you won't see any Bootstrap classnames. |
| * Doing advanced customizations can get involved, but there are "easier" and "more difficult" ways to accomplish things within our templating approach. When in doubt, please //please// just reach out. We're happy to help. | * Doing advanced customizations can get involved, but there are "easier" and "more difficult" ways to accomplish things within our templating approach. When in doubt please, //please// just reach out. We're happy to help. |
| |
| Additionally, in previous versions of FoxyCart there was no clear separations of concerns between content (HTML), presentation (CSS), and dynamic behavior (Javascript). With v2.0 we're doing our best to help each aspect be a separate concern, so that you can override or customize the specific aspects your customers need without worrying about breaking things. | Additionally, in previous versions of FoxyCart there was no clear separation of concerns between content (HTML), presentation (CSS), and dynamic behavior (Javascript). With v2.0 we're doing our best to help each aspect be a separate concern, so that you can override or customize the specific aspects your customers need without worrying about breaking things. |
| |
| ==== Recommended Reading ==== | ==== Recommended Reading ==== |
| Before you proceed any further, we recommend looking over our [[v:2.0:templates:primer|Templates and Caching Primer]] page to get an understanding of the different pieces involved. Some parts may be already familiar to you - but having a grasp of the different pieces of the puzzle will make working deep within our templates all the more easier. | Before you proceed any further, we recommend looking over our [[v:2.0:templates:primer|Templates and Caching Primer]] page to get an understanding of the different pieces involved. Some parts may be already familiar to you - but having a grasp of the different pieces of the puzzle will make working deep within our templates all the more easier. |
| |
| We also strongly recommend taking a look at the Twig overview documentation over at their site at [[http://twig.sensiolabs.org/doc/templates.html]]. Understanding the basics of Twig will help you to be able to read our templates. | We also strongly recommend taking a look at the Twig overview documentation over at their site at [[https://twig.symfony.com/doc/2.x/templates.html]]. Understanding the basics of Twig will help you to be able to read our templates. |
| |
| Below, you'll find our best attempt at explaining each aspect of our templates and how you can override, hook into, or remove the aspects that you're interested in. If you have questions, post on our [[http://forum.foxycart.com|forum]] and let us know what is confusing, or email support if you have a suggestion on how this documentation can be more helpful. | Below, you'll find our best attempt at explaining each aspect of our templates and how you can override, hook into, or remove the aspects that you're interested in. If you have questions, please don't hesitate to [[https://foxy.io/contact|contact our support]]. |
| |
| |
| ==== Partial Include Templates ==== | ==== Partial Include Templates ==== |
| |
| Within the page templates, are one or more partial includes that output different sections of the respective templates. Partial's can also be stacked - a given partial may include one or more other partials within itself if required. The different partials may seem confusing at first - but we've broken the templates up into modular reusable pieces. As a quick overview of the different partials includes we have, look over the following cascading lists of our partial's as they're included. | Within the page templates, are one or more partial includes that output different sections of the respective templates. Partials can also be stacked - a given partial may include one or more other partials within itself if required. The different partials may seem confusing at first - but we've broken the templates up into modular reusable pieces. As a quick overview of the different partials includes we have, look over the following cascading lists of our partials as they're included. |
| |
| * ''cart.inc.twig'' | * ''cart.inc.twig'' |
| ==== Outputting Partial Includes ==== | ==== Outputting Partial Includes ==== |
| |
| A page template on it's own is just a normal page. If you want to include FoxyCart functionality within it, you'l need to output one or more partial includes within the template. You can output a Twig include file in one of two ways, ''include'' and ''use''. Which you use will depend on what you're wanting to do. | A page template on it's own is just a normal page. If you want to include FoxyCart functionality within it, you'll need to output one or more partial includes within the template. You can output a Twig include file in one of two ways, ''include'' and ''use''. Which you use will depend on what you're wanting to do. |
| |
| === Include - directly output the include into the page === | === Include - directly output the include into the page === |
| |
| If you use ''include'', that will take the whole contents of that file, and output it at that spot in the template. This is perfect if you're just wanting to output the default approach to that section, but you're wanting to include it somewhere specific. [[http://twig.sensiolabs.org/doc/tags/include.html|View include in the Twig documentation]]. | If you use ''include'', that will take the whole contents of that file, and output it at that spot in the template. This is perfect if you're just wanting to output the default approach to that section, but you're wanting to include it somewhere specific. [[https://twig.symfony.com/doc/2.x/tags/include.html|View include in the Twig documentation]]. |
| |
| Example: | Example: |
| === Embed - output the include on the page, but allowing for overriding blocks within it === | === Embed - output the include on the page, but allowing for overriding blocks within it === |
| |
| Loading an include using ''embed'' behaves similar to ''include'' above in that it will output the whole contents of the file into the page. Within the ''embed'' tags though, you can also define ''block'' tags for blocks that exist within that included file, and overwrite them. Any code not contained with a pre-existing block, or any custom blocks, will be ignored. [[http://twig.sensiolabs.org/doc/tags/embed.html|View embed in the Twig documentation]]. | Loading an include using ''embed'' behaves similar to ''include'' above in that it will output the whole contents of the file into the page. Within the ''embed'' tags though, you can also define ''block'' tags for blocks that exist within that included file, and overwrite them. Any code not contained with a pre-existing block, or any custom blocks, will be ignored. [[https://twig.symfony.com/doc/2.x/tags/embed.html|View embed in the Twig documentation]]. |
| |
| Example: | Example: |
| === Use - load the blocks contained within ready for placement and modifying === | === Use - load the blocks contained within ready for placement and modifying === |
| |
| Referencing an include using ''use'', with just that tag in isolation will output nothing into the page. What it will do is gather all the blocks within that include and load them into memory for you to manually include as desired. Anything not contained inside blocks will be ignored. [[http://twig.sensiolabs.org/doc/tags/use.html|View use in the Twig documentation]]. | Referencing an include using ''use'', with just that tag in isolation will output nothing into the page. What it will do is gather all the blocks within that include and load them into memory for you to manually include as desired. Anything not contained inside blocks will be ignored. [[https://twig.symfony.com/doc/2.x/tags/use.html|View use in the Twig documentation]]. |
| |
| Example: | Example: |
| ==== Blocks ==== | ==== Blocks ==== |
| |
| Within the partial templates, we make use of [[#|Twig's block functionality]] to wrap certain chunks of our code into a named block. For an example, let's say you have a partial include called ''widgets.inc.twig'' with blocks that look like this: | Within the partial templates, we make use of [[https://twig.symfony.com/doc/2.x/tags/block.html|Twig's block functionality]] to wrap certain chunks of our code into a named block. For an example, let's say you have a partial include called ''widgets.inc.twig'' with blocks that look like this: |
| |
| <code html>{% block block_a %} | <code html>{% block block_a %} |
| {% endblock block_b %}</code> | {% endblock block_b %}</code> |
| |
| As you can see, there is two blocks within that markup enclosing two headers. If you wanted to just include that whole partial in your page template, you would just use the ''include'' approach to do that. What if you wanted to include that partial, but make some changes to one of the blocks? That's where ''use'' comes into play - allowing you to reference whole blocks with a single tag. | As you can see, there are two blocks within that markup enclosing two headers. If you wanted to just include that whole partial in your page template, you would just use the ''include'' approach to do that. What if you wanted to include that partial, but make some changes to one of the blocks? That's where ''use'' comes into play - allowing you to reference whole blocks with a single tag. |
| |
| === Editing blocks with ''embed'' === | === Editing blocks with ''embed'' === |
| <h2>{{ widget_subtitle }}</h2> | <h2>{{ widget_subtitle }}</h2> |
| <p>{{ widget_date }}</p></code> | <p>{{ widget_date }}</p></code> |
| | |
| | <WRAP center round info 90%> |
| | If you're wanting to make changes to how the cart template is displayed on the checkout or receipt - you should make changes directly to the "cart include" template. We don't currently support using an ''embed'' tag of the ''cart.inc.twig'' template within the checkout or receipt ''embed'' calls. |
| | </WRAP> |
| |
| ==== Allowed Twig Tags and Functionality ==== | ==== Allowed Twig Tags and Functionality ==== |
| At present, the only allowed functionality for Twig is as follows: | At present, the only allowed functionality for Twig is as follows: |
| |
| * Tags: [[http://twig.sensiolabs.org/doc/2.x/tags/block.html|block]], [[http://twig.sensiolabs.org/doc/2.x/tags/embed.html|embed]], [[http://twig.sensiolabs.org/doc/2.x/tags/if.html|if]], [[http://twig.sensiolabs.org/doc/2.x/tags/import.html|import]], [[http://twig.sensiolabs.org/doc/2.x/tags/include.html|include]], [[http://twig.sensiolabs.org/doc/2.x/tags/for.html|for]], [[http://twig.sensiolabs.org/doc/2.x/tags/macro.html|macro]], [[http://twig.sensiolabs.org/doc/2.x/tags/set.html|set]] | * Tags: [[https://twig.symfony.com/doc/2.x/tags/block.html|block]], [[https://twig.symfony.com/doc/2.x/tags/embed.html|embed]], [[https://twig.symfony.com/doc/2.x/tags/if.html|if]], [[https://twig.symfony.com/doc/2.x/tags/import.html|import]], [[https://twig.symfony.com/doc/2.x/tags/include.html|include]], [[https://twig.symfony.com/doc/2.x/tags/for.html|for]], [[https://twig.symfony.com/doc/2.x/tags/macro.html|macro]], [[https://twig.symfony.com/doc/2.x/tags/set.html|set]] |
| * Filters: [[http://twig.sensiolabs.org/doc/2.x/filters/abs.html|abs]], [[http://twig.sensiolabs.org/doc/2.x/filters/date.html|date]], [[http://twig.sensiolabs.org/doc/2.x/filters/date_modify.html|date_modify]], [[http://twig.sensiolabs.org/doc/2.x/filters/default.html|default]], [[http://twig.sensiolabs.org/doc/2.x/filters/escape.html|escape]], [[http://twig.sensiolabs.org/doc/2.x/filters/first.html|first]], [[http://twig.sensiolabs.org/doc/2.x/filters/json_encode.html|json_encode]], [[http://twig.sensiolabs.org/doc/2.x/filters/keys.html|keys]], [[http://twig.sensiolabs.org/doc/2.x/filters/last.html|last]], [[http://twig.sensiolabs.org/doc/2.x/filters/length.html|length]], [[http://twig.sensiolabs.org/doc/2.x/filters/lower.html|lower]], [[http://twig.sensiolabs.org/doc/2.x/filters/merge.html|merge]], [[http://twig.sensiolabs.org/doc/2.x/filters/nl2br.html|nl2br]], [[http://twig.sensiolabs.org/doc/2.x/filters/number_format.html|number_format]], [[http://twig.sensiolabs.org/doc/2.x/filters/round.html|round]], [[http://twig.sensiolabs.org/doc/2.x/filters/slice.html|slice]], [[http://twig.sensiolabs.org/doc/2.x/filters/split.html|split]], [[http://twig.sensiolabs.org/doc/2.x/filters/raw.html|raw]], [[http://twig.sensiolabs.org/doc/2.x/filters/replace.html|replace]], [[http://twig.sensiolabs.org/doc/2.x/filters/reverse.html|reverse]], [[http://twig.sensiolabs.org/doc/2.x/filters/title.html|title]], [[http://twig.sensiolabs.org/doc/2.x/filters/trim.html|trim]], [[http://twig.sensiolabs.org/doc/2.x/filters/upper.html|upper]], [[http://twig.sensiolabs.org/doc/2.x/filters/url_encode.html|url_encode]] | * Filters: [[https://twig.symfony.com/doc/2.x/filters/abs.html|abs]], [[https://twig.symfony.com/doc/2.x/filters/capitalize.html|capitalize]], [[https://twig.symfony.com/doc/2.x/filters/date.html|date]], [[https://twig.symfony.com/doc/2.x/filters/date_modify.html|date_modify]], [[https://twig.symfony.com/doc/2.x/filters/default.html|default]], [[https://twig.symfony.com/doc/2.x/filters/escape.html|escape]], [[https://twig.symfony.com/doc/2.x/filters/first.html|first]], [[https://twig.symfony.com/doc/2.x/filters/join.html|join]], [[https://twig.symfony.com/doc/2.x/filters/json_encode.html|json_encode]], [[https://twig.symfony.com/doc/2.x/filters/keys.html|keys]], [[https://twig.symfony.com/doc/2.x/filters/last.html|last]], [[https://twig.symfony.com/doc/2.x/filters/length.html|length]], [[https://twig.symfony.com/doc/2.x/filters/lower.html|lower]], [[https://twig.symfony.com/doc/2.x/filters/merge.html|merge]], [[https://twig.symfony.com/doc/2.x/filters/nl2br.html|nl2br]], [[https://twig.symfony.com/doc/2.x/filters/number_format.html|number_format]], [[https://twig.symfony.com/doc/2.x/filters/round.html|round]], [[https://twig.symfony.com/doc/2.x/filters/slice.html|slice]], [[https://twig.symfony.com/doc/2.x/filters/split.html|split]], [[https://twig.symfony.com/doc/2.x/filters/raw.html|raw]], [[https://twig.symfony.com/doc/2.x/filters/replace.html|replace]], [[https://twig.symfony.com/doc/2.x/filters/reverse.html|reverse]], [[https://twig.symfony.com/doc/2.x/filters/title.html|title]], [[https://twig.symfony.com/doc/2.x/filters/trim.html|trim]], [[https://twig.symfony.com/doc/2.x/filters/upper.html|upper]], [[https://twig.symfony.com/doc/2.x/filters/url_encode.html|url_encode]] |
| * Functions: [[http://twig.sensiolabs.org/doc/2.x/functions/block.html|block]], [[http://twig.sensiolabs.org/doc/2.x/functions/date.html|date]], [[http://twig.sensiolabs.org/doc/2.x/functions/random.html|random]], [[http://twig.sensiolabs.org/doc/2.x/functions/template_from_string.html|template_from_string]], [[http://twig.sensiolabs.org/doc/2.x/functions/min.html|min]], [[http://twig.sensiolabs.org/doc/2.x/functions/max.html|max]] | * Functions: [[https://twig.symfony.com/doc/2.x/functions/block.html|block]], [[https://twig.symfony.com/doc/2.x/functions/date.html|date]], [[https://twig.symfony.com/doc/2.x/functions/random.html|random]], [[https://twig.symfony.com/doc/2.x/functions/template_from_string.html|template_from_string]], [[https://twig.symfony.com/doc/2.x/functions/min.html|min]], [[https://twig.symfony.com/doc/2.x/functions/max.html|max]] |
| |
| Need a tag, filter or function not listed here? Simply [[http://www.foxycart.com/contact|get in touch]] and we can look at adding it. | Need a tag, filter or function not listed here? Simply [[http://www.foxycart.com/contact|get in touch]] and we can look at adding it. |
| : **Example:** ''%%{{ getPostalCodeLabel(address.country) }}%%'' | : **Example:** ''%%{{ getPostalCodeLabel(address.country) }}%%'' |
| ; ''generate_sso_token'' | ; ''generate_sso_token'' |
| : **Description:** Used to generate a SSO token useful for quick purchases from the receipt or reverse SSO logins, [[v:2.0:sso#reverse_ssologging_a_customer_into_your_own_site_from_foxycart|as documented here]]. | : **Description:** Used to generate a SSO token useful for quick purchases from the receipt or reverse SSO logins, [[v:2.0:sso#example_2automatically_logging_the_user_in_on_your_website|as documented here]]. |
| | : **Example:** ''%%{{ generate_sso_token(timestamp) }}%%'' |
| : **Notes:** Only generated server-side, won't run with client-side Twig.js | : **Notes:** Only generated server-side, won't run with client-side Twig.js |
| |
| ===== Accessing FoxyCart's Templates ===== | ===== Accessing FoxyCart's Templates ===== |
| |
| All of our page and partial templates are available from our [[https://github.com/FoxyCart/2.0-templates|2.0 templates Github Repository]]. You can simply use repository to view the different templates and copy out the templates that you need. If you're familiar with Git though, you can also fork our repository and apply any changes to the templates as needed - and when we apply any updates you can merge those new commits into your edited templates to keep your custom templates up to date. | All of our page and partial templates are available from our [[https://github.com/FoxyCart/2.0-templates|2.0 templates Github Repository]]. You can simply use the repository to view the different templates and copy out the templates that you need. If you're familiar with Git though, you can also fork our repository and apply any changes to the templates as needed - and when we apply any updates you can merge those new commits into your edited templates to keep your custom templates up to date. |
| |
| <wrap tip>If you're customising any of the partial includes, you can be updated of changes to the templates in a few ways. Firstly, you can "star" or "watch" the repository to receive notifications through Github. You can also view a [[https://github.com/FoxyCart/2.0-templates/commits/master.atom|RSS feed of all commits to the repository]] in a RSS viewing tool.</wrap> | <wrap tip>If you're customising any of the partial includes, you can be updated of changes to the templates in a few ways. Firstly, you can "star" or "watch" the repository to receive notifications through Github. You can also view a [[https://github.com/FoxyCart/2.0-templates/commits/master.atom|RSS feed of all commits to the repository]] in a RSS viewing tool.</wrap> |
