====== Router ======

Router slúži na generovanie URI adries na základe dopredu nadefinovaných parametrov. 
Spätné zavolanie tejto URI vyvolá našu funkciu.
Parametre môžu byť verziované.

===== Definovanie ciest =====

Na definovanie ciest sa treba zaregistrovať na počúvanie broadcastu ''router/defineRoutes''.

<code php setListeners.php space=2>
$this->app->cc_setListener("router/defineRoutes", "bMyRouter/bDefineRoutes");
</code>


<code php bMyRouter.php space=2>
function bDefineRoutes(iBroadcastEvent $e)
{
  # Existujúce cesty (routy) sú zadefinované v $e->getRefData();
  $routes = &$e->getRefData();
  

  # Môja nová routa
  $routes["my_route1"] = array(
  
    # CoolName
    "coolName" => "cesta1",
    
    # callback - funkcia, ktorá sa zavolá, keď zavoláme vygenerovanú cestu
    "callback" => array(&$this, "myRouteCallback"),  
    
    # arguments - parametre
    "arguments" => array(  
    
      # "1" - verzia parametrov
      "1" => array(
        "meno",
        "vek",
      ),
    ),
  );
}


function myRouteCallback($settings = array(), $argumentsVersion = NULL)
{
  echo "<pre>Callback, argumentsVersion=$argumentsVersion\n";
  var_export($settings);
}
</code>


Použitie v reálnom kóde:
<code php test.php space=2>
$router = $this->app->initCoreModule("router");
echo $router->getRoute("my_route1", array(
  "meno" => "Jozef",
  "vek" => 24,
));
</code>



Použitie v Smarty šablóne:
<code smarty test.tpl space=2>
{getRoute routeIdf="my_route1" meno="Jozef" vek=24}
</code>

Výstup v obidvoch prípadoch bude:
<code>
http://studio2.local/r/cesta1/1/Jozef/24
</code>

Po zavolaní tejto URL adresy dostaneme v prehliadači výsledok:

<code>
Callback, argumentsVersion=1
array (
  'meno' => 'Jozef',
  'vek' => '24',
)
</code>
-----
==== coolName ====

Parameter ''coolName'' určuje, čo bude zobrazené vo výslednej URI adrese.
Môže byť ''string'' alebo ''array''.
Ak bude ''array'', potom môže obsahovať informáciu o kóde jazyka, pre ktorý je dané coolName určené.

<code php bMyRouter.php space=2>
$routes["my_route1"] = array(
  "coolName" => "cesta1",
  # ...
</code>
Skript bude reagovať na URL adresu
\\ ''http://studio2.local/r/cesta1/1/Jozef/24''


-----

<code php bMyRouter.php space=2>
$routes["my_route1"] = array(
  "coolName" => array(
    "cesta1",
    "moja-cesta1",
    "my-path1",
  ),
  # ...
</code>

Skript bude reagovať na URL adresy:
\\ ''http://studio2.local/r/cesta1/1/Jozef/24''
\\ ''http://studio2.local/r/moja-cesta1/1/Jozef/24''
\\ ''http://studio2.local/r/my-path1/1/Jozef/24''


-----


<code php bMyRouter.php space=2>
$routes["my_route1"] = array(
  "coolName" => array(
    "cesta1" => "sk",
    "moja-cesta1" => "sk",
    "my-path1" => "en",
  ),
  # ...
</code>

Skript bude reagovať na adresy ako v predchádzajúcom prípade. 
\\ Pri generovaní cesty pomocou ''getRoute()'' máme možnosť zvoliť, ktorý **coolName** sa použije na základe parametra ''langId''. 
Ak nebude parameter ''langId'' nastavený, SystemOmega sa bude snažiť použiť jazyk podľa aktuálne prihláseného užívateľa.

Príklad, v ktorom budeme preferovať anglický jazyk:
<code php test.php space=2>
$router = $this->app->initCoreModule("router");
echo $router->getRoute("my_route1", array(
  "meno" => "Jozef",
  "vek" => 24,
), 
array(
  "langId" => "en",
));
</code>

<code smarty test.tpl space=2>
{getRoute routeIdf="my_route1" routeLangId="en" meno="Jozef" vek=24}
</code>

Výstup v obidvoch prípadoch bude:
<code>
http://studio2.local/r/my-path1/1/Jozef/24
</code>

-----


==== arguments====

Parameter ''arguments'' určuje, aké parametre sa zakódujú do výslednej URL adresy.
Musí byť ''array'', ktorý bude obsahovať ďalší ''array''.
Prvý ''array'' musí obsahovať číselný kľúč, ktorý určuje verziu parametrov.
Verzia parametrov je nástroj, pomocou ktorého zaručujeme spätnú kompatibilita.
Ak dnes používame verziu parametrov **1**, ktorá obsahuje 2 parametre a o pol roka zavedieme verziu **2** s 3 parametrami, musíme zaručiť, aby odkazy vygenerované vo verzii **1** boli stále platné a funkčné.


<code php bMyRouter.php space=2>
$routes["my_route1"] = array(
  "arguments" => array(  
    "1" => array(
      "meno",
      "vek",
    ),
  ),
  # ...
</code>
<code php test.php space=2>
$router = $this->app->initCoreModule("router");
echo $router->getRoute("my_route1", array(
  "meno" => "Jozef",
  "vek" => 24,
));
</code>

Výsledok:
<code>
http://studio2.local/r/cesta1/2/Jozef/24
</code>


-----
Funkcia ''getRoute'' použije najvyššiu verziu parametrov.

<code php bMyRouter.php space=2>
$routes["my_route1"] = array(
  "arguments" => array(  
    "1" => array(
      "meno",
      "vek",
    ),
    "2" => array(
      "meno",
      "vek",
      "vyska",
    ),
  ),
  # ...
</code>

<code php test.php space=2>
$router = $this->app->initCoreModule("router");
echo $router->getRoute("my_route1", array(
  "meno" => "Jozef",
  "vek" => 24,
  "vyska" => 180,
));
</code>

Výsledok:
<code>
http://studio2.local/r/cesta1/2/Jozef/24/180
</code>

-----

Ak by sme nezadali parameter ''vyska'', aj tak by sa vygenerovala verzia **2** (násl. príklad).

<code php test.php space=2>
$router = $this->app->initCoreModule("router");
echo $router->getRoute("my_route1", array(
  "meno" => "Jozef",
  "vek" => 24,
));
</code>

Výsledok:
<code>
http://studio2.local/r/cesta1/2/Jozef/24/
</code>




-----

===== getRoute =====

<code php space=2>
	/**
	 *
	 * @param	string	$routeIdf
	 *    Identifikátor routy
	 *
	 * @param	array	$arguments
	 *    Parametre do routy
	 *
	 * @param	array	$settings
	 * @param	string	$settings["coolName"]=NULL
	 * @param	string	$settings["langId"]=NULL
	 * @param	string	$settings["separator"]="&amp;"
	 * @param	string	$settings["anchor"]=NULL
	 * @param	string	$settings["disableCoolUri"]=FALSE
	 *
	 * @return	string
	 */
	function getRoute($routeIdf, $routeArguments = array(), $settings = array());
</code>