documentation/manual/es/module_specs/Zend_Controller-Router-Route.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2     <!-- EN-Revision: 17592 -->
   3     <!-- Reviewed: no -->
   4 <sect3 id="zend.controller.router.routes.standard">
   5     <title>Zend_Controller_Router_Route</title>
   6
   7     <para>
   8         <classname>Zend_Controller_Router_Route</classname>
   9         es la ruta standard
  10         del framework. Combina la facilidad de uso con la flexibilidad para la
  11         definición de rutas. Cada ruta consiste fundamentalmente en el mapeo de
  12         la
  13         <acronym>URL</acronym>
  14         (de partes estáticas y dinámicas (variables))
  15         y puede ser iniciada con valores
  16         predeterminados así como con requisitos
  17         variables.
  18     </para>
  19
  20     <para>
  21         Imaginemos que nuestra aplicación ficticia necesitará algunas páginas
  22         informativas sobre los
  23         autores del contenido. Queremos ser capaces de
  24         apuntar nuestro navegador web a
  25         <filename>http://domain.com/author/martel</filename>
  26         para ver la
  27         información sobre este muchacho "martel". La ruta para esa funcionalidad
  28         podría
  29         parecerse a:
  30     </para>
  31
  32     <programlisting language="php"><![CDATA[
  33 $route = new Zend_Controller_Router_Route(
  34     'author/:username',
  35     array(
  36         'controller' => 'profile',
  37         'action'     => 'userinfo'
  38     )
  39 );
  40
  41 $router->addRoute('user', $route);
  42 ]]></programlisting>
  43
  44     <para>
  45         El primer parámetro en el constructor
  46         <classname>Zend_Controller_Router_Route</classname>
  47         es una
  48         definición de ruta que será acompañada de una
  49         <acronym>URL</acronym>
  50         .
  51         Las definiciones de ruta consisten en partes estáticas y dinámicas
  52         separadas por el caracter
  53         barra ('/'). Las partes estáticas son simples
  54         textos:
  55         <command>author</command>
  56         . Las partes dinámicas, llamadas
  57         variables, se marcan anteponiendo dos puntos (:) al nombre
  58         de la
  59         variable
  60         <command>:username</command>
  61         .
  62     </para>
  63
  64     <note>
  65         <title>Uso de Caracteres</title>
  66         <para>
  67             La implementación actual le permite utilizar cualquier carácter
  68             (salvo una barra) como un
  69             identificador de variable, pero se
  70             recomienda encarecidamente que se utilicen sólo
  71             caracteres que sean
  72             válidos para identificadores de variables
  73             <acronym>PHP</acronym>
  74             . En
  75             implementaciones futuras se podría alterar este comportamiento,
  76             resultando en
  77             probables fallos escondidos en su código.
  78         </para>
  79     </note>
  80
  81     <para>
  82         Este ejemplo de ruta debería ser coincidente cuando apunta su
  83         navegador a
  84         <filename>http://domain.com/author/martel</filename>
  85         , en
  86         cuyo caso todas sus variables se inyectan al objeto
  87         <classname>Zend_Controller_Request</classname>
  88         y quedando accesibles
  89         en
  90         <classname>ProfileController</classname>
  91         . Las variables devueltas
  92         por este ejemplo pueden ser representadas como el siguiente array
  93         de
  94         pares clave/valor:
  95     </para>
  96
  97     <programlisting language="php"><![CDATA[
  98 $values = array(
  99     'username'   => 'martel',
 100     'controller' => 'profile',
 101     'action'     => 'userinfo'
 102 );
 103 ]]></programlisting>
 104
 105     <para>
 106         Después,
 107         <classname>Zend_Controller_Dispatcher_Standard</classname>
 108         debe invocar al método
 109         <methodname>userinfoAction()</methodname>
 110         de su
 111         clase
 112         <classname>ProfileController</classname>
 113         (en el módulo por
 114         defecto) basado en estos valores. Allí se podrán acceder a todas las
 115         variables mediante los métodos
 116         <methodname>Zend_Controller_Action::_getParam()</methodname>
 117         o
 118         <methodname>Zend_Controller_Request::getParam()</methodname>
 119         :
 120     </para>
 121
 122     <programlisting language="php"><![CDATA[
 123 public function userinfoAction()
 124 {
 125     $request = $this->getRequest();
 126     $username = $request->getParam('username');
 127
 128     $username = $this->_getParam('username');
 129 }
 130 ]]></programlisting>
 131
 132     <para>
 133         La definición de ruta puede contener uno o más caracteres especiales
 134         - un comodín -
 135         representado por el símbolo '*'. Se utiliza para reunir
 136         parámetros al igual que el valor de
 137         ruta por defecto del Módulo (var =>
 138         pares de valores definidos en la
 139         <acronym>URI</acronym>
 140         ). La siguiente
 141         ruta imita más o menos el comportamiento de la ruta del Módulo:
 142     </para>
 143
 144     <programlisting language="php"><![CDATA[
 145 $route = new Zend_Controller_Router_Route(
 146     ':module/:controller/:action/*',
 147     array('module' => 'default')
 148 );
 149 $router->addRoute('default', $route);
 150 ]]></programlisting>
 151
 152     <sect4 id="zend.controller.router.routes.standard.variable-defaults">
 153         <title>Variables por Defecto</title>
 154
 155         <para>
 156             Cada variable en la ruta puede tener una valor por defecto y para
 157             esto es que se usa el
 158             segundo parámetro del constructor
 159             <classname>Zend_Controller_Router_Route</classname>
 160             . Este
 161             parámetro es un array con claves representando los nombres de
 162             variables y con
 163             valores como los deseados por defecto:
 164         </para>
 165
 166         <programlisting language="php"><![CDATA[
 167 $route = new Zend_Controller_Router_Route(
 168     'archive/:year',
 169     array('year' => 2006)
 170 );
 171 $router->addRoute('archive', $route);
 172 ]]></programlisting>
 173
 174         <para>
 175             La ruta de arriba comparará
 176             <acronym>URL</acronym>
 177             s como
 178             <filename>http://domain.com/archive/2005</filename>
 179             y
 180             <filename>http://example.com/archive</filename>
 181             . En este último
 182             caso la variable year(año) tendrá un valor inicial predeterminado de
 183             2006.
 184         </para>
 185
 186         <para>
 187             Este ejemplo resultará en inyectar una variable año al objeto
 188             solicitud. Ya que no hay
 189             información de enrutamiento presente (no se
 190             define ningún controlador ni parámetros de
 191             acción), la solicitud
 192             será enviada al controlador y al método de acción por defecto (que
 193             a
 194             la vez ambos están definidos en
 195             <classname>Zend_Controller_Dispatcher_Abstract</classname>
 196             ).
 197             Para hacerlos más utilizables, tiene que proporcionar un controlador
 198             válido y una
 199             acción válida como la ruta por defecto:
 200         </para>
 201
 202         <programlisting language="php"><![CDATA[
 203 $route = new Zend_Controller_Router_Route(
 204     'archive/:year',
 205     array(
 206         'year'       => 2006,
 207         'controller' => 'archive',
 208         'action'     => 'show'
 209     )
 210 );
 211 $router->addRoute('archive', $route);
 212 ]]></programlisting>
 213
 214         <para>
 215             Entonces, esta ruta resultará en el dispatch al método
 216             <methodname>showAction()</methodname>
 217             de la clase
 218             <classname>ArchiveController</classname>
 219             .
 220         </para>
 221
 222     </sect4>
 223
 224     <sect4 id="zend.controller.router.routes.standard.variable-requirements">
 225         <title>Requerimientos para Variables</title>
 226
 227         <para>
 228             Podemos agregar un tercer parámetro al constructor
 229             <classname>Zend_Controller_Router_Route</classname>
 230             donde
 231             podemos establecer los requisitos para las variables. Estas son
 232             definidas como
 233             partes de una expresión regular:
 234         </para>
 235
 236         <programlisting language="php"><![CDATA[
 237 $route = new Zend_Controller_Router_Route(
 238     'archive/:year',
 239     array(
 240         'year'       => 2006,
 241         'controller' => 'archive',
 242         'action'     => 'show'
 243     ),
 244     array('year' => '\d+')
 245 );
 246 $router->addRoute('archive', $route);
 247 ]]></programlisting>
 248
 249         <para>
 250             Con una ruta definida como la de arriba, el router comparará solo
 251             cuando la variable año
 252             contenga datos numéricos, eg.
 253             <filename>http://domain.com/archive/2345</filename>
 254             . Una
 255             <acronym>URL</acronym>
 256             como
 257             <filename>http://example.com/archive/test</filename>
 258             no se
 259             comparará y en su lugar el control se pasará a la próxima ruta en la
 260             cadena.
 261         </para>
 262     </sect4>
 263
 264     <sect4 id="zend.controller.router.routes.standard.translated-segments">
 265         <title>Segmentos Traducidos</title>
 266
 267         <para>
 268             El standard de ruta brinda apoyo a la traducción de segmentos.
 269             Para utilizar esta
 270             característica, tiene que definir por lo menos un
 271             traductor (una instancia de
 272             <classname>Zend_Translate</classname>
 273             )
 274             mediante una de las siguientes formas:
 275         </para>
 276
 277         <itemizedlist>
 278             <listitem>
 279                 <para>
 280                     Ponerlo en el registro con la clave
 281                     <classname>Zend_Translate</classname>
 282                     .
 283                 </para>
 284             </listitem>
 285             <listitem>
 286                 <para>
 287                     Setearlo mediante el método estático
 288                     <methodname>Zend_Controller_Router_Route::setDefaultTranslator()</methodname>
 289                     .
 290                 </para>
 291             </listitem>
 292             <listitem>
 293                 <para>Pasarlo como cuarto parámetro al constructor.</para>
 294             </listitem>
 295         </itemizedlist>
 296
 297         <para>
 298             Por defecto, se utilizará el "locale" especificado en la
 299             instancia
 300             <classname>Zend_Translate</classname>
 301             . Para anularlo, debe
 302             setearlo (como una instancia de
 303             <classname>Zend_Locale</classname>
 304             o
 305             un string local) de una de las siguientes maneras:
 306         </para>
 307
 308         <itemizedlist>
 309             <listitem>
 310                 <para>
 311                     Ponerlo en el registro con la clave
 312                     <classname>Zend_Locale</classname>
 313                     .
 314                 </para>
 315             </listitem>
 316             <listitem>
 317                 <para>
 318                     Setearlo mediante el método estático
 319                     <methodname>Zend_Controller_Router_Route::setDefaultLocale()</methodname>
 320                     .
 321                 </para>
 322             </listitem>
 323             <listitem>
 324                 <para>Pasarlo como cuarto parámetro al constructor.</para>
 325             </listitem>
 326             <listitem>
 327                 <para>
 328                     Pasarlo como parámetro
 329                     <command>@locale</command>
 330                     al método de ensamblaje.
 331                 </para>
 332             </listitem>
 333         </itemizedlist>
 334
 335         <para>
 336             Los segmentos traducidos se dividen en dos partes. Los segmentos
 337             fijos están precedidos
 338             por un único signo
 339             <emphasis>@</emphasis>
 340             , y serán traducidos al "locale" actual
 341             para el ensamblaje y se revierten al ID del
 342             mensaje cuando se acepte
 343             nuevamente. Los segmentos dinámicos tienen el prefijo
 344             <command>:@</command>
 345             . Para el ensamblaje, el parámetro
 346             dado será traducido y se insertará en la posición del
 347             parámetro.
 348             Cuando se acepte, el parámetro traducido de la URL volverá al ID del
 349             mensaje
 350             nuevamente.
 351         </para>
 352
 353         <note>
 354             <title>IDs de Mensajes y Archivos de Lenguajes Separados</title>
 355             <para>
 356                 Ocasionalmente un ID de mensaje que quiere usar en una de sus
 357                 rutas ya se utiliza en
 358                 un view script o en otro lugar. Para
 359                 tener pleno control sobre
 360                 <acronym>URL</acronym>
 361                 s seguras, debe
 362                 usar un archivo de idioma separado para los mensajes utilizados
 363                 en la
 364                 ruta.
 365             </para>
 366         </note>
 367
 368         <para>La siguiente es la forma más sencilla para preparar el itinerario
 369             normal para el uso de
 370             la traducción del segmento:</para>
 371
 372         <programlisting language="php"><![CDATA[
 373 // Prepare el traductor
 374 $translator = new Zend_Translate('array', array(), 'en');
 375 $translator->addTranslation(array('archive' => 'archiv',
 376                                   'year'    => 'jahr',
 377                                   'month'   => 'monat',
 378                                   'index'   => 'uebersicht'),
 379                             'de');
 380
 381 // Establecer el "locale" actual para el traductor
 382 $translator->setLocale('en');
 383
 384 // Establecerlo como traductor por defecto para las rutas
 385 Zend_Controller_Router_Route::setDefaultTranslator($translator);
 386 ]]></programlisting>
 387
 388         <para>Este ejemplo demuestra el uso de segmentos estáticos:</para>
 389
 390         <programlisting language="php"><![CDATA[
 391 // Crear la ruta
 392 $route = new Zend_Controller_Router_Route(
 393     '@archive',
 394     array(
 395         'controller' => 'archive',
 396         'action'     => 'index'
 397     )
 398 );
 399 $router->addRoute('archive', $route);
 400
 401 // Ensamblar la URL en el locale actual por defecto: archive
 402 $route->assemble(array());
 403
 404 // Ensamblar la URL en alemán: archiv
 405 $route->assemble(array());
 406 ]]></programlisting>
 407
 408         <para>Puede usar segmentos dinámicos para crear veriones traducidas
 409             como del tipo
 410             módulo-ruta:</para>
 411
 412         <programlisting language="php"><![CDATA[
 413 // Crear la ruta
 414 $route = new Zend_Controller_Router_Route(
 415     ':@controller/:@action/*',
 416     array(
 417         'controller' => 'index',
 418         'action'     => 'index'
 419     )
 420 );
 421 $router->addRoute('archive', $route);
 422
 423 // Ensamblar la URL en el "locale" por defecto: archive/index/foo/bar
 424 $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
 425
 426 // Ensamblar la URL en alemán: archiv/uebersicht/foo/bar
 427 $route->assemble(array('controller' => 'archive', 'foo' => 'bar'));
 428 ]]></programlisting>
 429
 430         <para>También puede mezclar segmentos estáticos y dinámicos:</para>
 431
 432         <programlisting language="php"><![CDATA[
 433 // Crear la ruta
 434 $route = new Zend_Controller_Router_Route(
 435     '@archive/:@mode/:value',
 436     array(
 437         'mode'       => 'year'
 438         'value'      => 2005,
 439         'controller' => 'archive',
 440         'action'     => 'show'
 441     ),
 442     array('mode'  => '(month|year)'
 443           'value' => '\d+')
 444 );
 445 $router->addRoute('archive', $route);
 446
 447 // Ensamblar la URL en el "locale" por defecto: archive/month/5
 448 $route->assemble(array('mode' => 'month', 'value' => '5'));
 449
 450 // Ensamblar la URL en alemán: archiv/monat/5
 451 $route->assemble(array('mode' => 'month', 'value' => '5', '@locale' => 'de'));
 452 ]]></programlisting>
 453     </sect4>
 454 </sect3>