www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Utility/LinkGeneratorInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Utility;
   4
   5 use Drupal\Core\Link;
   6 use Drupal\Core\Url;
   7
   8 /**
   9  * Defines an interface for generating links from route names and parameters.
  10  */
  11 interface LinkGeneratorInterface {
  12
  13   /**
  14    * Renders a link to a URL.
  15    *
  16    * Examples:
  17    * @code
  18    * $link_generator = \Drupal::service('link_generator');
  19    * $installer_url = \Drupal\Core\Url::fromUri('base://core/install.php');
  20    * $installer_link = $link_generator->generate($text, $installer_url);
  21    * $external_url = \Drupal\Core\Url::fromUri('http://example.com', ['query' => ['foo' => 'bar']]);
  22    * $external_link = $link_generator->generate($text, $external_url);
  23    * $internal_url = \Drupal\Core\Url::fromRoute('system.admin');
  24    * $internal_link = $link_generator->generate($text, $internal_url);
  25    * @endcode
  26    * However, for links enclosed in translatable text you should use t() and
  27    * embed the HTML anchor tag directly in the translated string. For example:
  28    * @code
  29    * $text = t('Visit the <a href=":url">content types</a> page', array(':url' => \Drupal::url('entity.node_type.collection')));
  30    * @endcode
  31    * This keeps the context of the link title ('settings' in the example) for
  32    * translators.
  33    *
  34    * @param string|array|\Drupal\Component\Render\MarkupInterface $text
  35    *   The link text for the anchor tag as a translated string or render array.
  36    *   Strings will be sanitized automatically. If you need to output HTML in
  37    *   the link text, use a render array or an already sanitized string such as
  38    *   the output of \Drupal\Component\Utility\Xss::filter() or
  39    *   \Drupal\Component\Utility\SafeMarkup::format().
  40    * @param \Drupal\Core\Url $url
  41    *   The URL object used for the link. Amongst its options, the following may
  42    *   be set to affect the generated link:
  43    *   - attributes: An associative array of HTML attributes to apply to the
  44    *     anchor tag. If element 'class' is included, it must be an array; 'title'
  45    *     must be a string; other elements are more flexible, as they just need
  46    *     to work as an argument for the constructor of the class
  47    *     Drupal\Core\Template\Attribute($options['attributes']).
  48    *   - language: An optional language object. If the path being linked to is
  49    *     internal to the site, $options['language'] is used to determine whether
  50    *     the link is "active", or pointing to the current page (the language as
  51    *     well as the path must match).
  52    *   - 'set_active_class': Whether this method should compare the $route_name,
  53    *     $parameters, language and query options to the current URL to determine
  54    *     whether the link is "active". Defaults to FALSE. If TRUE, an "active"
  55    *     class will be applied to the link. It is important to use this
  56    *     sparingly since it is usually unnecessary and requires extra
  57    *     processing.
  58    *
  59    * @return \Drupal\Core\GeneratedLink
  60    *   A GeneratedLink object containing a link to the given route and
  61    *   parameters and bubbleable metadata.
  62    *
  63    * @throws \Symfony\Component\Routing\Exception\RouteNotFoundException
  64    *   Thrown when the named route doesn't exist.
  65    * @throws \Symfony\Component\Routing\Exception\MissingMandatoryParametersException
  66    *   Thrown when some parameters are missing that are mandatory for the route.
  67    * @throws \Symfony\Component\Routing\Exception\InvalidParameterException
  68    *   Thrown when a parameter value for a placeholder is not correct because it
  69    *   does not match the requirement.
  70    *
  71    * @internal
  72    *   Should not be used in user code. Use \Drupal\Core\Link instead.
  73    */
  74   public function generate($text, Url $url);
  75
  76   /**
  77    * Renders a link from a link object.
  78    *
  79    * @param \Drupal\Core\Link $link
  80    *   A link object to convert to a string.
  81    *
  82    * @return \Drupal\Core\GeneratedLink
  83    *   A GeneratedLink object containing a link to the given route and
  84    *   parameters and bubbleable metadata.
  85    *
  86    * @internal
  87    *   Should not be used in user code.
  88    *   Use \Drupal\Core\Link instead.
  89    */
  90   public function generateFromLink(Link $link);
  91
  92 }