diff --git a/composer.json b/composer.json index 5d31150..c79384c 100644 --- a/composer.json +++ b/composer.json @@ -13,6 +13,6 @@ "drupal/core": "^8.7" }, "suggest": { - "symfony/var-dumper": "better dump() function for debugging Twig variables" + "symfony/var-dumper": "Better dump() function for debugging Twig variables" } } diff --git a/src/TwigExtension.php b/src/TwigExtension.php index a2d931d..7f11d68 100644 --- a/src/TwigExtension.php +++ b/src/TwigExtension.php @@ -28,7 +28,7 @@ use Symfony\Cmf\Component\Routing\RouteObjectInterface; /** * Twig extension with some useful functions and filters. * - * Dependency injection is not used for performance reason. + * Dependencies are not injected for performance reason. */ class TwigExtension extends \Twig_Extension { @@ -36,8 +36,8 @@ class TwigExtension extends \Twig_Extension { * {@inheritdoc} */ public function getFunctions() { - $all_options = ['needs_environment' => TRUE, 'needs_context' => TRUE]; $context_options = ['needs_context' => TRUE]; + $all_options = ['needs_environment' => TRUE, 'needs_context' => TRUE]; return [ new \Twig_SimpleFunction('drupal_view', 'views_embed_view'), new \Twig_SimpleFunction('drupal_view_result', 'views_get_view_result'), @@ -95,12 +95,32 @@ class TwigExtension extends \Twig_Extension { /** * Builds the render array for a block. * + * In order to list all registered plugin IDs fetch them with block plugin + * manager. With Drush it can be done like follows: + * @code + * drush ev "print_r(array_keys(\Drupal::service('plugin.manager.block')->getDefinitions()));" + * @endcode + * + * Examples: + * @code + * # Print block using default configuration. + * {{ drupal_block('system_branding_block') }} + * + * # Print block using custom configuration. + * {{ drupal_block('system_branding_block', {label: 'Branding', use_site_name: false}) + * + * # Bypass block.html.twig theming. + * {{ drupal_block('system_branding_block', wrapper=false) }} + * @endcode + * + * @see https://www.drupal.org/node/2964457#block-plugin + * * @param mixed $id * The string of block plugin to render. * @param array $configuration - * (Optional) Pass on any configuration to the plugin block. + * (optional) Pass on any configuration to the plugin block. * @param bool $wrapper - * (Optional) Whether or not use block template for rendering. + * (optional) Whether or not use block template for rendering. * * @return null|array * A render array for the block or NULL if the block cannot be rendered. @@ -162,10 +182,19 @@ class TwigExtension extends \Twig_Extension { /** * Builds the render array of a given region. * + * Examples: + * @code + * # Print 'Sidebar First' region of the default site theme. + * {{ drupal_region('sidebar_first') }} + * + * # Print 'Sidebar First' region of Bartik theme. + * {{ drupal_region('sidebar_first', 'bartik') }} + * @endcode + * * @param string $region * The region to build. * @param string $theme - * (Optional) The name of the theme to load the region. If it is not + * (optional) The name of the theme to load the region. If it is not * provided then default theme will be used. * * @return array @@ -205,19 +234,35 @@ class TwigExtension extends \Twig_Extension { } /** - * Returns the render array for an entity. + * Returns the render array to represent and entity. + * + * Examples: + * @code + * # Print a content block which ID is 1. + * {{ drupal_entity('block_content', 1) }} + * + * # Print a user which ID is fetched from URL (i.e. /user/1). + * {{ drupal_entity('user') }} + * + * # Print a node's teaser. + * {{ drupal_entity('node', 123, 'teaser') }} + * + * # Print Branding block which was previously disabled on + * # admin/structure/block page. + * {{ drupal_entity('block', 'bartik_branding', check_access=false) }} + * @endcode * * @param string $entity_type * The entity type. * @param mixed $id - * The ID of the entity to build. + * (optional) The ID of the entity to build. * @param string $view_mode * (optional) The view mode that should be used to render the entity. * @param string $langcode * (optional) For which language the entity should be rendered, defaults to * the current content language. * @param bool $check_access - * (Optional) Indicates that access check is required. + * (optional) Indicates that access check is required. * * @return null|array * A render array for the entity or NULL if the entity does not exist. @@ -236,6 +281,18 @@ class TwigExtension extends \Twig_Extension { /** * Gets the built and processed entity form for the given entity type. * + * Examples: + * @code + * # Print edit form for node 1. + * {{ drupal_entity_form('node', 1) }} + * + * # Print add form for Article content type. + * {{ drupal_entity_form('node', values={type: 'article'}) }} + * + * # Print user register form. + * {{ drupal_entity_form('user', NULL, 'register', check_access=false) }} + * @endcode + * * @param string $entity_type * The entity type. * @param mixed $id @@ -246,7 +303,7 @@ class TwigExtension extends \Twig_Extension { * @param array $values * (optional) An array of values to set, keyed by property name. * @param bool $check_access - * (Optional) Indicates that access check is required. + * (optional) Indicates that access check is required. * * @return array * The processed form for the given entity type and form mode. @@ -269,6 +326,14 @@ class TwigExtension extends \Twig_Extension { /** * Returns the render array for a single entity field. * + * This works very much like drupal_entity() except it prints only one + * specific field. + * + * Example: + * @code + * {{ drupal_field('field_image', 'node', 1) }} + * @endcode + * * @param string $field_name * The field name. * @param string $entity_type @@ -280,7 +345,7 @@ class TwigExtension extends \Twig_Extension { * @param string $langcode * (optional) Language code to load translation. * @param bool $check_access - * (Optional) Indicates that access check is required. + * (optional) Indicates that access check is required. * * @return null|array * A render array for the field or NULL if the value does not exist. @@ -302,6 +367,11 @@ class TwigExtension extends \Twig_Extension { /** * Returns the render array for Drupal menu. * + * Example: + * @code + * {{ drupal_menu('main') }} + * @endcode + * * @param string $menu_name * The name of the menu. * @param int $level @@ -346,6 +416,11 @@ class TwigExtension extends \Twig_Extension { /** * Builds and processes a form for a given form ID. * + * Example: + * @code + * {{ drupal_form('Drupal\\search\\Form\\SearchBlockForm') }} + * @endcode + * * @param string $form_id * The form ID. * @param ... @@ -355,23 +430,41 @@ class TwigExtension extends \Twig_Extension { * A render array to represent the form. */ public function drupalForm($form_id) { - $form_builder = \Drupal::formBuilder(); - return call_user_func_array([$form_builder, 'getForm'], func_get_args()); + $callback = [\Drupal::formBuilder(), 'getForm']; + return call_user_func_array($callback, func_get_args()); } /** * Builds an image. * + * Examples: + * @code + * # Render image specified by file ID. + * {{ drupal_image(123) }} + * + * # Render image specified by file UUID. + * {{ drupal_image('9bb27144-e6b2-4847-bd24-adcc59613ec0') }} + * + * # Render image specified by file URI. + * {{ drupal_image('public://ocean.jpg') }} + * + * # Render image using 'thumbnail' image style and custom attributes. + * {{ drupal_image('public://ocean.jpg', 'thumbnail', {alt: 'The alternative text'|t, title: 'The title text'|t}) }} + * + * # Render responsive image. + * {{ drupal_image('public://ocean.jpg', 'wide', responsive=true) }} + * @endcode + * * @param mixed $property * A property to identify the image. * @param string $style - * (Optional) Image style. + * (optional) Image style. * @param array $attributes - * (Optional) Image attributes. + * (optional) Image attributes. * @param bool $responsive - * (Optional) Indicates that the provided image style is responsive. + * (optional) Indicates that the provided image style is responsive. * @param bool $check_access - * (Optional) Indicates that access check is required. + * (optional) Indicates that access check is required. * * @return array|null * A render array to represent the image. @@ -429,6 +522,11 @@ class TwigExtension extends \Twig_Extension { /** * Replaces a given tokens with appropriate value. * + * Example: + * @code + * {{ drupal_token('site:name') }} + * @endcode + * * @param string $token * A replaceable token. * @param array $data @@ -451,7 +549,12 @@ class TwigExtension extends \Twig_Extension { } /** - * Gets data from this configuration. + * Retrieves data from a given configuration object. + * + * Example: + * @code + * {{ drupal_config('system.site', 'name') }} + * @endcode * * @param string $name * The name of the configuration object to construct. @@ -468,10 +571,22 @@ class TwigExtension extends \Twig_Extension { /** * Dumps information about variables. * + * Examples: + * @code + * # Basic usage. + * {{ drupal_dump(var) }} + * + * # Same as above but shorter. + * {{ dd(var) }} + * + * # Dump all available variables for the current template. + * {{ dd() }} + * @endcode + * * @param array $context * Variables from the Twig template. * @param mixed $variable - * (Optional) The variable to dump. + * (optional) The variable to dump. */ public function drupalDump(array $context, $variable = NULL) { $var_dumper = '\Symfony\Component\VarDumper\VarDumper'; @@ -502,12 +617,21 @@ class TwigExtension extends \Twig_Extension { /** * Generates a URL from an internal path. * + * Examples: + * @code + * # Basic usage. + * {{ drupal_url('node/1) }} + * + * # Complex URL. + * {{ drupal_url('node/1', {query: {foo: 'bar'}, fragment: 'example', absolute: true}) }} + * @endcode + * * @param string $user_input * User input for a link or path. * @param array $options * (optional) An array of options. * @param bool $check_access - * (Optional) Indicates that access check is required. + * (optional) Indicates that access check is required. * * @return \Drupal\Core\Url * A new Url object based on user input. @@ -533,6 +657,15 @@ class TwigExtension extends \Twig_Extension { /** * Generates a link from an internal path. * + * Examples: + * @code + * # It supports the same options as drupal_url(), plus attributes. + * {{ drupal_link('View'|t, 'node/1', {attributes: {target: '_blank'}}) }} + * + * # This link will only be shown for privileged users. + * {{ drupal_link('Example'|t, '/admin', check_access=true) }} + * @endcode + * * @param string $text * The text to be used for the link. * @param string $user_input @@ -540,7 +673,7 @@ class TwigExtension extends \Twig_Extension { * @param array $options * (optional) An array of options. * @param bool $check_access - * (Optional) Indicates that access check is required. + * (optional) Indicates that access check is required. * * @return \Drupal\Core\Link * A new Link object. @@ -596,6 +729,18 @@ class TwigExtension extends \Twig_Extension { /** * Replaces all tokens in a given string with appropriate values. * + * Example: + * @code + * # Basic usage. + * {{ '