diff --git a/content/collections/docs/antlers-legacy.md b/content/collections/docs/antlers-legacy.md deleted file mode 100644 index f5b3982d5..000000000 --- a/content/collections/docs/antlers-legacy.md +++ /dev/null @@ -1,426 +0,0 @@ ---- -id: dcf80ee6-209e-45aa-af42-46bbe01996e2 -blueprint: page -title: 'Antlers Templates (Legacy Regex)' -intro: |- - Antlers is a simple and powerful templating engine provided with Statamic. It can fetch and filter content, display and modify data, tap into core features like user authentication and search, and handle complex logic. - :::warning This parser has been retired - We have a [brand new, completely rewritten Antlers Parser](/antlers) jam packed with new features, performance improvements, and bug fixes. Make sure to use it if you're on Statamic 3.3 or higher. - ::: -template: page -nav_title: 'Antlers Templates (Legacy)' ---- -## Overview - -Antlers view files are often called templates. Any files in your `resources/views` directory using an `.antlers.html` file extension will be parsed with the Antlers engine. - -:::tip -The `.antlers.html` extension is important. Without it, your template will be rendered as **unparsed, static HTML**. -::: - -## Antlers Syntax - -Antlers adds capabilities on top of HTML through the use of curly brace expressions. Those curly braces – often called double mustaches or squiggly gigglies – look a whole lot like _antlers_ to us, hence the name. - -```antlers -{{ hello_world }} -``` - -Before getting into listing all the things that happen _inside_ an Antlers expression, lets take a moment to establish the rules for properly formatting one. - -### Formatting Rules - -1. Each set of curly braces **must** stay together always, like Kenan & Kel or Wayne & Garth. -2. Expressions are **case sensitive**. -3. Hyphens and underscores are **not** interchangeable. -4. Whitespace between the curly braces and inner text is **recommended**, but optional. -5. You **can** break up an expression onto multiple lines. - -Consistency is important. We recommend using single spaces between braces, lowercase variable names, and underscores as word separators. Picking your style and stick to it. Future you will thank you, but don't expect a postcard. - -``` antlers -This is great! -{{ perfectenschlag }} - -This is allowed. -{{squished}} - -This can make sense when you have lots of parameters. -{{ - testimonials - limit="5" - order="username" -}} - -This is terrible in every possible way. -{{play-sad_Trombone }} -``` - -## Displaying Data - -You can display data passed into your Antlers views by wrapping the variable in double curly braces. For example, given the following data: - -``` yaml ---- -title: DJ Jazzy Jeff & The Fresh Prince -songs: - - Boom! Shake the Room - - Summertime - - Just Cruisin' ---- -``` - -You can display the contents of the `title` variable like this: - -``` antlers -
Time to {{ songs:0 }} cuz we're {{ songs:2 }}.
-``` - -``` html -Time to Boom! Shake the Room cuz we're Just Crusin'.
-``` - -### Dictionaries -Dictionaries are represented in YAML by nested key:value pairs, _inside_ another variable name. These are sometimes called element maps, or associative arrays. - -``` yaml -mailing_address: - address: 123 Foo Ave - city: Barville - province: West Exampleton - country: Docsylvania -``` - -#### Accessing Data -You can access the keys inside the dictionary by "gluing" the parent/child keys together you want to traverse through, much like breadcrumbs. - -``` antlers -I live in {{ mailing_address:city }}. -``` - -### Multi-Dimensional Arrays -More complex data is stored in objects or arrays inside arrays. This is usually called a multi-dimensional array. - -``` yaml -skaters: - - - name: Tony Hawk - style: Vert - - - name: Rodney Mullen - style: Street -``` - -If you know the names of the variables inside the array, you can loop through the items and access their variables. - -``` antlers -{{ skaters }} -{{ style }}
-Vert
-Street
-There is a song!
-{{ elseif songs > 100 }} -There are lots of songs!
-{{ elseif songs }} -There are songs. -{{ else }} -
There are no songs.
-{{ /if }} -``` - - -Antlers variables are null by default. Keep your logic statements simple and skip checking for existence altogether.- -### Shorthand Conditions (Ternary) {#ternary} - -Basic ternary operators will let you write a simple if/else statement all in one line. - -``` -// Basic: verbose -This item is {{ if is_sold }}sold{{ else }}available{{ /if }}. - -// Ternary: nice and short -This item is {{ is_sold ? "sold" : "available" }}. -``` - -Learn more about [ternary operators][ternary] in PHP. - -### Modifiers Inside Conditions - -If you want to manipulate a variable with [modifiers](/modifiers) before evaluating a condition, wrap the expression in (parenthesis). - -``` -{{ if (number_of_bedrooms | count) > 10 }} -
Who are you, Dwayne Johnson?
-{{ /if }} -``` - -### Variable Fallbacks (Null Coalescence) {#null-coalescence} - -When all you need to do is display a variable and set a fallback when it’s null, use the null coalescence operator (`??`). - -``` -{{ meta_title ?? title ?? "No Title Set" }} -``` - -### Conditional Variable Fallbacks - -What if you want to combine an `is set` check with a ternary operator? No problem. - -``` -// Short and sweet -{{ show_title ?= title }} - -// Longer and bitterer -{{ if show_title }}{{ title }}{{ /if }} -``` - -### Using Tags in Conditions - -Yes, you can even use tags in conditions. When working with [tags][tags] instead of variables, you **must** wrap the tag in a pair of additional single braces to tell the parser to run that logic first. - -``` -{{ if {session:some_var} == "Statamic is rad!" }} - ... -{{ /if }} -``` - -## Code Comments {#comments} - -Antlers also allows you to define comments in your views. However, unlike HTML comments, Antlers are not included in the rendered HTML. You can use these comments to "turn off" chunks of code, document your work, or leave notes for yourself and other developers. - -``` -{{# Remember to replace the lorem ipsum this time. #}} -``` - -## Tags - -[Tags][tags] are the primary method for implementing most of Statamic's dynamic features, like search, forms, nav building, pagination, collection listing, filtering, image resizing, and so on. - -Tags often look quite similar to variables, so it pays to learn the list of available [Tags][tags] so you don't mix them up or create conflicts. - -### Variables Inside Tag Parameters - -There are two ways to use variables _inside_ a Tag's parameters. - -You can use **dynamic binding** to pass the value of a variable via its name. - -``` -{{ nav :from="segment_1" }} -``` - -Alternatively, you can use **string interpolation** and reference any variables with _single braces_. This method lets you concatenate a string giving you the ability assemble arguments out of various parts. Like Frankenstein's monster. - -``` -{{ nav from="{segment_1}/{segment_2}" }} -``` - -### Modifiers Inside Parameters - -If using a variable inside of a Tag is nice, using a variable with a modifier inside of a Tag is better. Or more complicated. Either way, it works exactly as you’d expect with one small caveat: When using a modifier inside of a Tag, no whitespace is allowed between variables, pipes, and modifiers. Collapse that stuff. - -``` -// Totally fine. -{{ partially:broken src="{featured_image|url}" }} - -// Totally not. -{{ partially:broken src="{ featured_image | url }" }} -``` - -## Prevent Parsing - -You may find you need to prevent Antlers statements from being parsed. This is common if you're using a JavaScript library like [Vue.js][vue], or perhaps you want to display code examples (like we do in these docs). In either case, you have a few options. - -First, you may use an `@` symbol to tell Antlers to leave it alone like a jellyfish on the beach. The `@` symbol will be stripped out automatically leaving nothing but your expression behind. - -``` -Hey, look at that @{{ noun }}! -``` - -### The `noparse` Tag - -Use this method if you need to prevent entire code blocks from being parsed. - -``` -{{ noparse }} - Welcome to {{ fast_food_chain }}, - home of the {{ fast_food_chain_specialty_item }}, - can I take your order? -{{ /noparse }} -``` - -## Using Antlers in Content - -By default, Antlers expressions and tags are **not** parsed inside your content. This is for performance and security reasons. - -For example, a guest author with limited access to the control panel could conceivably write some template code to fetch and display published/private content from a collection they don't have access to. - -If this isn't a concern of yours, you can enable Antlers parsing on a per-field basis by setting `antlers: true` in your blueprint. - -## Using PHP in Antlers - -PHP is disabled by default, but if you change your view's file extension from `.antlers.html` to `.antlers.php`, you can write all the PHP you want in that template. - -## IDEs & Syntax Highlighters - -Syntax highlighting packages are available for most of the popular IDEs. Make life sweeter, like they do with tea in the south. - -- [Antlers Toolbox for VS Code](https://antlers.dev/) -- [Antlers Language Support for PHP Storm](https://plugins.jetbrains.com/plugin/19203-antlers-language-support) -- [Antlers for Atom](https://github.com/addisonhall/language-antlers) -- [Antlers for Sublime](https://github.com/addisonhall/antlers-statamic-sublime-syntax) - - -[ternary]: https://www.php.net/manual/en/language.operators.comparison.php#language.operators.comparison.ternary -[vue]: https://vuejs.org -[modifiers]: /modifiers -[tags]: /tags \ No newline at end of file diff --git a/content/collections/docs/antlers.md b/content/collections/docs/antlers.md index 1329bb34b..00c7c61bb 100644 --- a/content/collections/docs/antlers.md +++ b/content/collections/docs/antlers.md @@ -4,9 +4,6 @@ blueprint: page title: 'Antlers Templates' intro: |- Antlers is a simple and powerful templating engine provided with Statamic. It can fetch and filter content, display, modify, and set variables, tap into core features like user authentication and search, and handle complex logic. Coming from Laravel and want to stick to Blade? [We got you covered](/blade). - :::tip Hot Tip - For sites running Statamic 3.2 and older you'll need to use the [legacy Antlers parser](/antlers-legacy). For all other projects, keep reading. You're in the right place. - ::: template: page --- ## Overview @@ -32,13 +29,22 @@ This is a very simple Antlers tag: ### Configuring -You can configure advanced settings (or switch to the [legacy Antlers parser](/antlers-legacy)) in `config/statamic/antlers.php`. The `runtime` version is the fresh new default parser as of Statamic 3.4, as documented on this very page. +You can configure advanced settings, like guarded variables, tags & modifiers in `config/statamic/antlers.php`. ```php // config/statamic/antlers.php return [ - 'version' => 'runtime', - // ... + 'guardedVariables' => [ + 'config.app.key', + ], + + 'guardedTags' => [ + // + ], + + 'guardedModifiers' => [ + // + ], ]; ``` @@ -375,10 +381,6 @@ There are more than 150 built-in [modifiers](/reference/modifiers) that can do a You can even create [Macros](/modifiers/macro) to combine sets of often used modifiers into one, new reusable one. -#### Legacy Syntax - -The New Antlers Parser still supports what we're now calling the "[Legacy Syntax](/antlers-legacy#stringshorthand-style)" styles, and will continue to do so until Statamic 4.0. - ### Creating Variables You can now set variables by using the assignment operator, `=`.