docs: update explanation about route_to() and url_to()

Author: kenjis

user_guide_src/source/general/common_functions.rst

@@ -333,10 +333,16 @@ Miscellaneous Functions
 
     .. note:: This function requires the controller/method to have a route defined in **app/Config/routes.php**.
 
-    Generates a URI path (route) for you based on either a named route alias,
+    Generates a route for you based on either a named route alias,
     or a controller::method combination. Will take parameters into effect, if provided.
 
-    For full details, see the :ref:`reverse-routing` and :ref:`using-named-routes`.
+    .. literalinclude:: common_functions/009.php
+
+    .. literalinclude:: common_functions/010.php
+
+    .. note:: ``route_to()`` returns a route, not a full URI path for your site.
+        If your **baseURL** contains sub folders, the return value is not the same
+        as the URI to link. In that case, just use :php:func:`url_to` instead.
 
 .. php:function:: service($name[, ...$params])
 

user_guide_src/source/general/common_functions/009.php

@@ -0,0 +1,12 @@
+<?php
+
+// The route is defined as:
+$routes->get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2');
+
+?>
+
+<?php
+
+// Generate the route with user ID 15, gallery 12:
+route_to('Galleries::showUserGallery', 15, 12);
+// Result: '/users/15/gallery/12'

user_guide_src/source/general/common_functions/010.php

@@ -0,0 +1,12 @@
+<?php
+
+// The route is defined as:
+$routes->get('users/(:num)/gallery(:any)', 'Galleries::showUserGallery/$1/$2', ['as' => 'user_gallery']);
+
+?>
+
+<?php
+
+// Generate the route with user ID 15, gallery 12:
+route_to('user_gallery', 15, 12);
+// Result: '/users/15/gallery/12'

user_guide_src/source/helpers/url_helper.rst

@@ -365,6 +365,8 @@ The following functions are available:
     This is useful because you can still change your routes after putting links
     into your views.
 
+    For full details, see the :ref:`reverse-routing` and :ref:`using-named-routes`.
+
 .. php:function:: url_is($path)
 
     :param string $path: The path to check the current URI path against.

user_guide_src/source/incoming/routing.rst

@@ -278,18 +278,13 @@ Reverse routing allows you to define the controller and method, as well as any p
 to, and have the router lookup the current route to it. This allows route definitions to change without you having
 to update your application code. This is typically used within views to create links.
 
-For example, if you have a route to a photo gallery that you want to link to, you can use the ``route_to()`` helper
-function to get the URI path (route) that should be used. The first parameter is the fully qualified Controller and method,
+For example, if you have a route to a photo gallery that you want to link to, you can use the ``url_to()`` helper
+function to get the route that should be used. The first parameter is the fully qualified Controller and method,
 separated by a double colon (``::``), much like you would use when writing the initial route itself. Any parameters that
 should be passed to the route are passed in next:
 
 .. literalinclude:: routing/029.php
 
-.. note:: ``route_to()`` returns a URI path for the route, not a full URI path
-    for your site. If your **baseURL** contains sub folders, the return value is
-    not the same as the URI to link. In that case, you need to use :php:func:`site_url`
-    like ``site_url(route_to(...))``, or just use :php:func:`url_to` instead.
-
 .. _using-named-routes:
 
 Using Named Routes
@@ -304,11 +299,6 @@ with the name of the route:
 
 This has the added benefit of making the views more readable, too.
 
-.. note:: ``route_to()`` returns a URI path for the route, not a full URI path
-    for your site. If your **baseURL** contains sub folders, the return value is
-    not the same as the URI to link. In that case, you need to use :php:func:`site_url`
-    like ``site_url(route_to(...))``, or just use :php:func:`url_to` instead.
-
 Routes with any HTTP verbs
 ==========================
 

user_guide_src/source/incoming/routing/029.php

@@ -5,6 +5,6 @@
 
 ?>
 
-<!-- Generate the URI path (route) to link to user ID 15, gallery 12: -->
-<a href="<?= route_to('Galleries::showUserGallery', 15, 12) ?>">View Gallery</a>
-<!-- Result: '/users/15/gallery/12' -->
+<!-- Generate the URI to link to user ID 15, gallery 12: -->
+<a href="<?= url_to('Galleries::showUserGallery', 15, 12) ?>">View Gallery</a>
+<!-- Result: 'http://example.com/users/15/gallery/12' -->

user_guide_src/source/incoming/routing/030.php

@@ -5,6 +5,6 @@
 
 ?>
 
-<!-- Generate the URI path (route) to link to user ID 15, gallery 12: -->
-<a href="<?= route_to('user_gallery', 15, 12) ?>">View Gallery</a>
-<!-- Result: '/users/15/gallery/12' -->
+<!-- Generate the URI to link to user ID 15, gallery 12: -->
+<a href="<?= url_to('user_gallery', 15, 12) ?>">View Gallery</a>
+<!-- Result: 'http://example.com//users/15/gallery/12' -->