====== jUrl, the automatic URL engine of Jelix. ======

//(supported version of Jelix 1.3.x)//

this article will talk about 2 points of the URL engine

  - writting URL "à la jelix" 
  - the URL engines of Jelix

===== 1 - Introduction =====

Classically, to add a link in an HTML page, we just put the URL manually as follow :
<code>
<a href="/my/path/to/my/internal/link" title="my uggly link">My Nice Site</a>
</code>

But, if you install this application in an environment where the path is different, one the click of this link will lead to a 404 error page

===== 2 - writting URL "à la jelix" =====

==== the simplest ====


To avoid the previous issue,  __jUrl__ does its job, to a very simple way, as follow :
<code>
<a href="{jurl 'news~default:index',array('parm1'=>'value1')}" title="My beautiful link">My Nice Site</a>
</code>

Where : 
  - ''{jurl ...} '' is the template plugin that will build the URL for you
  - __news__ is the __module__ name, 
  - __default__ is the name of my __controller__, 
  - and  __index__ is my __method__.

This will build an URL http://localhost/index.php?module=news&action=default:index&parm1=value1

==== the prettiest ====

But of course, there is another way to have URLs cleaner and shortest  than that.


You can use jUrl directlty in your controller and assign the result to the template 

A concret case of this usage through a controller, could be for a form which always uses the same fields to create and edit a news, but the action itself will be different.

Let's have a look to the following example which illustrates how to assign the result of jUrl to a template

==== the controller ====

<code php>
function index() {
    $rep = $this->getResponse('html');
    $myUrl = jUrl::get('module~controller:action',
                    array('parm1'=>'what-an-amazing-engine'));
    $rep->body->assign('myurl', $myUrl);
    return $rep;
}
</code>

==== the template ====

<code>
<a href="{$myurl}">My Beautiful Site</a>
</code>


===== 3 - URL engines of  Jelix =====

Now another aspect of the URL engines of Jelix is its type, which can be :

  - basic_significant 
  - significant 

The type of engine __''basic_significant''__ produces URLs à la "Cake PHP" example : 

http://localhost/index.php/news/default/index?parm1=value1

which can be "translated" by  :

http://localhost/index.php/module/controller/method?parm1=value1 

The second URL Engine is the type __''significant''__ which procudes the following URL :

http://localhost/news/what-an-amazing-engine

this result is how much lighter and shorter to find/memorize the news  "what-an-amazing-engine" ;)

This engine uses a file named urls.xml, which can tell Jelix "this url is this module and the controller"

Thus for the URL http://localhost/news/what-an-amazing-engine, the urls.xml file could look like this :
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<urls xmlns="http://jelix.org/ns/urls/1.0">  
    <classicentrypoint name="index" default="true" noentrypoint="true">
        <url pathinfo="/news/:parm1" module="news" action="default:index">
           <param name="parm1" type="string"/>
        </url>
    </classicentrypoint>
</urls>
</code>

===== 4 - Conclusion =====  
  * URLs Generator allows precisely __ never have anything hardcoded __ and __ not freezing __ the choice of the URL engine
  * the engine __''basic_significant''__ represents a good ratio btw elapsed time / quality of the generated URLs.    
  * the engine __''significant''__ is a little trickier to manage because we have to write every URL, with a risk to see some of them totally  inoperative

with jelix, **jUrl** is the essential tool for porting its applications in heterogeneous environments and a very flexible implementation.

[[http://docs.jelix.org/en/manual-1.3/urls|read more about jURL]]