Merge branch '3363043-update-3.x-cheat' into '3.x'

Draft: Issue #3363043: Update 3.x cheat sheet with details from 2.x cheat sheet See merge request project/twig_tweak!33
2 years ago · 4a84d58a19
1 changed files with 74 additions and 11 deletions
--- a/docs/cheat-sheet.md
+++ b/docs/cheat-sheet.md
@ -1,20 +1,35 @@
 # Cheat sheet

 ## Drupal View
+Render a view. See [Twig Tweak and Views](./views.md) page for more information.
+### Accepted parameters
+<dl>
+  <dt><code>$name</code></dt>
+  <dd><em>String - Required</em> - The name of the view to embed.</dd>
+  <dt><code>$display_id</code></dt>
+  <dd><em>String - Optional</em> - The display id to embed. Default is <code>default</code>.</dd>
+  <dt><code>$...</code></dt>
+  <dd><em>Mixed - Optional</em> - Any additional parameters will be passed as arguments.</dd>
+</dl>
+
 ```twig
 {{ drupal_view('who_s_new', 'block_1') }}
 ```
-Specify additional parameters which map to contextual filters you have configured in your view:
+Specify additional parameters which map to contextual filters you have
+configured in your view:
 ```twig
 {{ drupal_view('who_s_new', 'block_1', arg_1, arg_2, arg_3) }}
 ```

 ## Drupal View Result
+Get the result of a view.
 ```twig
 {{ drupal_view_result('who_s_new', 'block_1') }}
 ```

 ## Drupal Block
+Used to render a block.
+
 In order to figure out the plugin IDs list them using block plugin manager.
 With Drush, it can be done like follows:
 ```shell
@ -31,9 +46,12 @@ drush ev "print_r(array_keys(\Drupal::service('plugin.manager.block')->getDefini
 {{ drupal_block('system_branding_block', wrapper=false) }}
 ```

-See [rendering blocks with Twig Tweak](blocks.md#block-plugin) for details.
+See [rendering blocks with Twig Tweak](blocks.md#block-plugin) for more details
+and examples.

 ## Drupal Region
+Used to render contents of a region from the default or any other specified
+theme.
 ```twig
 {# Print 'sidebar_first' region of the default site theme. #}
 {{ drupal_region('sidebar_first') }}
@ -43,6 +61,7 @@ See [rendering blocks with Twig Tweak](blocks.md#block-plugin) for details.
 ```

 ## Drupal Entity
+Used to render an entity. Returns `NULL` if the entity doesn't exist.
 ```twig
 {# Print a content block which ID is 1. #}
 {{ drupal_entity('block_content', 1) }}
@ -56,6 +75,7 @@ See [rendering blocks with Twig Tweak](blocks.md#block-plugin) for details.
 ```

 ## Drupal Entity Form
+Gets the built and processed entity form for the given entity type.
 ```twig
 {# Print edit form for node 1. #}
 {{ drupal_entity_form('node', 1) }}
@ -68,6 +88,8 @@ See [rendering blocks with Twig Tweak](blocks.md#block-plugin) for details.
 ```

 ## Drupal Field
+Returns the render array for a single entity field, or `NULL` if the field value
+doesn't exist.
 ```twig
 {# Render field_image from node 1 in view_mode "full" (default). #}
 {{ drupal_field('field_image', 'node', 1) }}
@ -87,6 +109,7 @@ options, which is documented here: https://api.drupal.org/api/drupal/core!lib!Dr
 ```

 ## Drupal Menu
+Returns a render array for the specified menu.
 ```twig
 {# Print the top level of 'main' menu. #}
 {{ drupal_menu('main') }}
@ -96,11 +119,13 @@ options, which is documented here: https://api.drupal.org/api/drupal/core!lib!Dr
 ```

 ## Drupal Form
+Returns a render array to represent the form.
 ```twig
 {{ drupal_form('Drupal\\search\\Form\\SearchBlockForm') }}
 ```

 ## Drupal Image
+Used to build the image.
 ```twig
 {# Render image specified by file ID. #}
 {{ drupal_image(123) }}
@ -119,16 +144,20 @@ options, which is documented here: https://api.drupal.org/api/drupal/core!lib!Dr
 ```

 ## Drupal Token
+Replaces a given token with appropriate value.
 ```twig
 {{ drupal_token('site:name') }}
 ```

 ## Drupal Config
+Retrieves data from a given configuration object.
 ```twig
 {{ drupal_config('system.site', 'name') }}
 ```

 ## Drupal Dump
+Dumps information about variables. Alias `dd()` could be used instead of
+`drupal_dump()`. You need to install <a href="https://symfony.com/doc/current/components/var_dumper.html">Symfony VarDumper</a> component.
 ```twig
 {# Basic usage. #}
 {{ drupal_dump(var) }}
@ -141,12 +170,15 @@ options, which is documented here: https://api.drupal.org/api/drupal/core!lib!Dr
 ```

 ## Drupal Title
+Returns a title for the current route.
 ```twig
 {# The title is cached per URL. #}
 {{ drupal_title() }}
 ```

 ## Drupal URL
+Generates and returns a URL object from an internal path or `NULL` if URL is not
+accessible to the user.
 ```twig
 {# Basic usage. #}
 {{ drupal_url('node/1') }}
@ -156,6 +188,8 @@ options, which is documented here: https://api.drupal.org/api/drupal/core!lib!Dr
 ```

 ## Drupal Link
+Generates and returns a link object from an internal path or `NULL` if URL is
+not accessible to the user.
 ```twig
 {# It supports the same options as drupal_url(), plus attributes. #}
 {{ drupal_link('View'|t, 'node/1', {attributes: {target: '_blank'}}) }}
@ -165,22 +199,26 @@ options, which is documented here: https://api.drupal.org/api/drupal/core!lib!Dr
 ```

 ## Drupal Messages
+Displays status messages.
 ```twig
 {{ drupal_messages() }}
 ```

 ## Drupal Breadcrumb
+Builds the breadcrumb.
 ```twig
 {{ drupal_breadcrumb() }}
 ```

 ## Drupal Breakpoint
+Emits a breakpoint to the debug client.
 ```twig
 {# Make Xdebug break on the specific line in the compiled Twig template. #}
 {{ drupal_breakpoint() }}
 ```

 ## Contextual Links
+Returns a renderable array representing contextual links.
 ```twig
 {# Basic usage. #}
 <div class="contextual-region">
@ -195,6 +233,8 @@ options, which is documented here: https://api.drupal.org/api/drupal/core!lib!Dr
 ```

 ## Token Replace
+Replaces all tokens in a given string with appropriate values and returns the
+HTML.
 ```twig
 {# Basic usage. #}
 {{ '<h1>[site:name]</h1><div>[site:slogan]</div>'|token_replace }}
@ -207,6 +247,8 @@ options, which is documented here: https://api.drupal.org/api/drupal/core!lib!Dr
 ```

 ## Preg Replace
+Performs a regular expression search and replace. For simple string
+interpolation consider using built-in replace or format Twig filters.
 ```twig
 {{ 'Drupal - community plumbing!'|preg_replace('/(Drupal)/', '<b>$1</b>') }}
 ```
@ -214,6 +256,10 @@ For simple string interpolation consider using built-in `replace` or `format`
 Twig filters.

 ## Image Style
+Returns the URL of this image derivative for an original image path or URI. The
+returned value is the absolute URL where a style image can be downloaded, so
+it's suitable for use in an `<img>` tag. Requesting the URL will cause the image
+to be created.
 ```twig
 {# Basic usage #}
 {{ 'public://images/ocean.jpg'|image_style('thumbnail') }}
@ -228,11 +274,15 @@ Twig filters.
 images when used in an `<img/>` tag.

 ## Transliterate
+Transliterates text from Unicode to US-ASCII. Returns a string with non-US-ASCII
+characters transliterated to US-ASCII characters, and unknown characters
+replaced with `$unknown_character`.
 ```twig
 {{ 'Привет!'|transliterate }}
 ```

 ## Check Markup
+Runs all the enabled filters on a piece of text.
 ```twig
 {{ '<b>bold</b> <strong>strong</strong>'|check_markup('restricted_html') }}
 ```
@ -244,6 +294,7 @@ Generates a string representation for the given byte count.
 ```

 ## Truncate
+Truncates a UTF-8-encoded string safely to a number of characters.
 ```twig
 {# Truncates a UTF-8-encoded string safely to 10 characters. #}
 {{ 'Some long text'|truncate(10) }}
@ -253,8 +304,9 @@ Generates a string representation for the given byte count.
 ```

 ## View
+Returns a render array for entity, field list or field item.
 ```twig
-{# Do not put this into node.html.twig template to avoid recursion. #}
+{# Do not put these node entity examples into node.html.twig template to avoid recursion. #}
 {{ node|view }}
 {{ node|view('teaser') }}

@ -265,7 +317,8 @@ Generates a string representation for the given byte count.
 ```

 ## With
-This is an opposite of core `without` filter.
+This filter is an opposite of core `without` filter: Adds new element to the
+array and returns the modified array.
 ```twig
 {# Set top-level value. #}
 {{ content.field_image|with('#title', 'Photo'|t) }}
@ -275,6 +328,7 @@ This is an opposite of core `without` filter.
 ```

 ## Children
+Filters out the children of a render array, optionally sorted by weight.
 ```twig
 <ul>
  {% for tag in content.field_tags|children %}
@ -284,9 +338,9 @@ This is an opposite of core `without` filter.
 ```

 ## File URI
-When field item list is passed, the URI will be extracted from the first item.
-In order to get URI of specific item specify its delta explicitly using array
-notation.
+When a field item list is passed, the URI will be extracted from the first item.
+In order to get the URI of a specific item, specify its delta explicitly using
+array notation.
 ```twig
 {{ node.field_image|file_uri }}
 {{ node.field_image[0]|file_uri }}
@ -298,8 +352,17 @@ it will return the URL to the resource, similar to the `file_url` filter.
 {{ node.field_media|file_uri }}
 ```

+Useful to apply the `image_style` filter to Media fields. (Remember to check
+whether a URI is actually returned.)
+```twig
+{% set media_uri = node.field_media|file_uri %}
+{% if media_uri is not null %}
+  {{ media_uri|image_style('thumbnail') }}
+{% endif %}
+```
+
 ## File URL
-For string arguments it works similar to core `file_url()` Twig function.
+For string arguments it works similar to core [`file_url()`](https://www.drupal.org/docs/theming-drupal/twig-in-drupal/functions-in-twig-templates#s-file-urluri) Twig function.
 ```twig
 {{ 'public://sea.jpg'|file_url }}
 ```
@ -309,9 +372,9 @@ In order to generate absolute URL set "relative" parameter to `false`.
 {{ 'public://sea.jpg'|file_url(false) }}
 ```

-When field item list is passed, the URL will be extracted from the first item.
-In order to get URL of specific item specify its delta explicitly using array
-notation.
+When a field item list is passed, the URL will be extracted from the first item.
+In order to get the URL of a specific item, specify its delta explicitly using
+array notation.
 ```twig
 {{ node.field_image|file_url }}
 {{ node.field_image[0]|file_url }}