Issue #2347831 by xjm, effulgentsia: Fix documentation for \Drupal::url(), \Drupal::l(), etc. (and fix the change record).
Alex Pott
parent
002ae719c9
commit
64de978a08
|
|
@ -748,7 +748,7 @@ function drupal_http_header_attributes(array $attributes = array()) {
|
|||
* @see _url()
|
||||
* @see system_page_build()
|
||||
* @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.0.
|
||||
* Use \Drupal::linkGenerator()->generate($url) where $url is an instance of
|
||||
* Use \Drupal::l($text, $url) where $url is an instance of
|
||||
* \Drupal\Core\Url. To build a \Drupal\Core\Url object for internal paths
|
||||
* served by Drupal controllers use \Drupal\Core\Url::fromRoute(). For
|
||||
* external paths or non-controller or sub-domain URIs such as
|
||||
|
|
@ -758,11 +758,11 @@ function drupal_http_header_attributes(array $attributes = array()) {
|
|||
* be prepended with base://. For example:
|
||||
* @code
|
||||
* $installer_url = \Drupal\Core\Url::fromUri('base://core/install.php')->toString();
|
||||
* $installer_link = \Drupal::linkGenerator()->generate($installer_url);
|
||||
* $installer_link = \Drupal::l($text, $installer_url);
|
||||
* $external_url = \Drupal\Core\Url::fromUri('http://example.com', ['query' => ['foo' => 'bar']])->toString();
|
||||
* $external_link = \Drupal::linkGenerator()->generate($external_url);
|
||||
* $external_link = \Drupal::l($text, $external_url);
|
||||
* $internal_url = \Drupal\Core\Url::fromRoute('system.admin')->toString();
|
||||
* $internal_link = \Drupal::linkGenerator()->generate($internal_url);
|
||||
* $internal_link = \Drupal::l($text, $internal_url);
|
||||
* @endcode
|
||||
*/
|
||||
function _l($text, $path, array $options = array()) {
|
||||
|
|
|
|||
|
|
@ -460,47 +460,18 @@ class Drupal {
|
|||
}
|
||||
|
||||
/**
|
||||
* Generates a URL or path for a specific route based on the given parameters.
|
||||
* Generates a URL string for a specific route based on the given parameters.
|
||||
*
|
||||
* Parameters that reference placeholders in the route pattern will be
|
||||
* substituted for them in the pattern. Extra params are added as query
|
||||
* strings to the URL.
|
||||
* This method is a convenience wrapper for generating URL strings for URLs
|
||||
* that have Drupal routes (that is, most pages generated by Drupal) using
|
||||
* the \Drupal\Core\Url object. See \Drupal\Core\Url::fromRoute() for
|
||||
* detailed documentation. For non-routed local URIs relative to
|
||||
* the base path (like robots.txt) use Url::fromUri()->toString() with the
|
||||
* base:// scheme.
|
||||
*
|
||||
* @param string $route_name
|
||||
* The name of the route
|
||||
* @param array $route_parameters
|
||||
* An associative array of parameter names and values.
|
||||
* @param array $options
|
||||
* (optional) An associative array of additional options, with the following
|
||||
* elements:
|
||||
* - 'query': An array of query key/value-pairs (without any URL-encoding)
|
||||
* to append to the URL. Merged with the parameters array.
|
||||
* - 'fragment': A fragment identifier (named anchor) to append to the URL.
|
||||
* Do not include the leading '#' character.
|
||||
* - 'absolute': Defaults to FALSE. Whether to force the output to be an
|
||||
* absolute link (beginning with http:). Useful for links that will be
|
||||
* displayed outside the site, such as in an RSS feed.
|
||||
* - 'language': An optional language object used to look up the alias
|
||||
* for the URL. If $options['language'] is omitted, the language will be
|
||||
* obtained from
|
||||
* \Drupal::languageManager()->getCurrentLanguage(LanguageInterface::TYPE_URL).
|
||||
* - 'https': Whether this URL should point to a secure location. If not
|
||||
* defined, the current scheme is used, so the user stays on HTTP or HTTPS
|
||||
* respectively. if mixed mode sessions are permitted, TRUE enforces HTTPS
|
||||
* and FALSE enforces HTTP.
|
||||
*
|
||||
* @return string
|
||||
* The generated URL for the given route.
|
||||
*
|
||||
* @throws \Symfony\Component\Routing\Exception\RouteNotFoundException
|
||||
* Thrown when the named route doesn't exist.
|
||||
* @throws \Symfony\Component\Routing\Exception\MissingMandatoryParametersException
|
||||
* Thrown when some parameters are missing that are mandatory for the route.
|
||||
* @throws \Symfony\Component\Routing\Exception\InvalidParameterException
|
||||
* Thrown when a parameter value for a placeholder is not correct because it
|
||||
* does not match the requirement.
|
||||
*
|
||||
* @see \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute()
|
||||
* @see \Drupal\Core\Url
|
||||
* @see \Drupal\Core\Url::fromRoute()
|
||||
* @see \Drupal\Core\Url::fromUri()
|
||||
*/
|
||||
public static function url($route_name, $route_parameters = array(), $options = array()) {
|
||||
return static::$container->get('url_generator')->generateFromRoute($route_name, $route_parameters, $options);
|
||||
|
|
@ -516,58 +487,14 @@ class Drupal {
|
|||
}
|
||||
|
||||
/**
|
||||
* Renders a link to a route given a route name and its parameters.
|
||||
* Renders a link with a given link text and Url object.
|
||||
*
|
||||
* This function correctly handles aliased paths and sanitizing text, so all
|
||||
* internal links output by modules should be generated by this function if
|
||||
* possible.
|
||||
* This method is a convenience wrapper for the link generator service's
|
||||
* generate() method. For detailed documentation, see
|
||||
* \Drupal\Core\Routing\LinkGeneratorInterface::generate().
|
||||
*
|
||||
* However, for links enclosed in translatable text you should use t() and
|
||||
* embed the HTML anchor tag directly in the translated string. For example:
|
||||
* @code
|
||||
* t('Visit the <a href="@url">content types</a> page', array('@url' => \Drupal::url('node.overview_types')));
|
||||
* @endcode
|
||||
* This keeps the context of the link title ('settings' in the example) for
|
||||
* translators.
|
||||
*
|
||||
* @param string|array $text
|
||||
* The link text for the anchor tag as a translated string or render array.
|
||||
* @param \Drupal\Core\Url $url
|
||||
* The URL object used for the link. Amongst its options, the following may
|
||||
* be set to affect the generated link:
|
||||
* - 'query': An array of query key/value-pairs (without any URL-encoding) to
|
||||
* append to the URL.
|
||||
* - absolute: Whether to force the output to be an absolute link (beginning
|
||||
* with http:). Useful for links that will be displayed outside the site,
|
||||
* such as in an RSS feed. Defaults to FALSE.
|
||||
* - attributes: An associative array of HTML attributes to apply to the
|
||||
* anchor tag. If element 'class' is included, it must be an array; 'title'
|
||||
* must be a string; other elements are more flexible, as they just need
|
||||
* to work as an argument for the constructor of the class
|
||||
* Drupal\Core\Template\Attribute($options['attributes']).
|
||||
* - html: Whether $text is HTML or just plain-text. For
|
||||
* example, to make an image tag into a link, this must be set to TRUE, or
|
||||
* you will see the escaped HTML image tag. $text is not sanitized if
|
||||
* 'html' is TRUE. The calling function must ensure that $text is already
|
||||
* safe. Defaults to FALSE.
|
||||
* - language: An optional language object. If the path being linked to is
|
||||
* internal to the site, $options['language'] is used to determine whether
|
||||
* the link is "active", or pointing to the current page (the language as
|
||||
* well as the path must match).
|
||||
*
|
||||
* @return string
|
||||
* An HTML string containing a link to the given route and parameters.
|
||||
*
|
||||
* @throws \Symfony\Component\Routing\Exception\RouteNotFoundException
|
||||
* Thrown when the named route doesn't exist.
|
||||
* @throws \Symfony\Component\Routing\Exception\MissingMandatoryParametersException
|
||||
* Thrown when some parameters are missing that are mandatory for the route.
|
||||
* @throws \Symfony\Component\Routing\Exception\InvalidParameterException
|
||||
* Thrown when a parameter value for a placeholder is not correct because it
|
||||
* does not match the requirement.
|
||||
*
|
||||
* @see \Drupal\Core\Routing\UrlGeneratorInterface::generateFromRoute()
|
||||
* @see \Drupal\Core\Utility\LinkGeneratorInterface::generate()
|
||||
* @see \Drupal\Core\Url
|
||||
*/
|
||||
public static function l($text, Url $url) {
|
||||
return static::$container->get('link_generator')->generate($text, $url);
|
||||
|
|
|
|||
|
|
@ -77,8 +77,15 @@ interface UrlGeneratorInterface extends VersatileGeneratorInterface {
|
|||
*
|
||||
* @throws \Drupal\Core\Routing\GeneratorNotInitializedException.
|
||||
*
|
||||
* @deprecated in Drupal 8.x-dev, will be removed before Drupal 8.0.
|
||||
* System paths should not be used - use route names and parameters.
|
||||
* @deprecated in Drupal 8.0.x-dev and will be removed before Drupal 8.0.0.
|
||||
* To generate URLs for Drupal routes (that is, most pages generated by
|
||||
* Drupal), see UrlGeneratorInterface::generateFromRoute() instead. For
|
||||
* non-routed local URIs relative to the base path (like robots.txt) see
|
||||
* \Drupal\Core\Utility\UnroutedUrlAssembler.
|
||||
*
|
||||
* @see static::generateFromRoute()
|
||||
* @see \Drupal\Core\Utility\UnroutedUrlAssembler
|
||||
* @see \Drupal\Core\Url
|
||||
*/
|
||||
public function generateFromPath($path = NULL, $options = array());
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue