The urls root tag contains the same number of entrypoint tags as entrypoints available in your application.

Each of these tags has a name attribute specifying the name of the entry point (without the .php extension), or, precisely, its relative path to the basePath indicated into the main configuration. And you could set eventually a default attribute specifying if this entry point is the default one for the actual type of request.

An entrypoint tag should also have a type attribute which indicates the type of the entry point : classic, xmlrpc, soap etc. If this attribute is not present, the default value is classic.

For compatibility reasons with older version of jelix, you can use other name for entrypoint elements. Their exact name gives the type of request they are affected to :

• classicentrypoint for classical request,
• xmlrpcentrypoint for xmlrpc
• etc...

However this kind of names are now deprecated.

Each entry point defines one or more possible url forms, knowing that those that are not defined will be accepted on an entry point defined as the default one.

Specify a complete url form ¶

   <url pathinfo="/foo/bar" module="hello" action="world" />

   <url pathinfo="/articles/:chapter/:id_art" module="cms" action="show" />

   <url pathinfo="/articles/:chapter/:id_art" module="cms" action="show">
      <param name="chapter" type="string" />
      <param name="id_art" regexp="\d+" />
   </url>

    <param name="type" regexp="(?:0|1|2){1}" />

   <url pathinfo="/:category/:product" module="shop" action="view">
      <param name="product"  regexp="\d{2}" />
      <static name="details" value="0" />
   </url>
   <url pathinfo="/:category/:product/details" module="shop" action="view">
      <param name="product"  regexp="\d{2}" />
      <static name="details" value="1" />
   </url>

   <url pathinfo="/articles/en/:page" module="cms" action="page:view">
      <param name="page"/>
      <static name="lang" value="en_US" />
   </url>
   <url pathinfo="/articles/fr/:page" module="cms" action="page:view">
      <param name="page"/>
      <static name="lang" value="fr_FR" />
   </url>

jUrl::get('cms~page:view', array('page'=>'foo', 'lang'=>jApp::config()->locale));
// or
jUrl::get('cms~page:view', array('page'=>'foo', 'lang'=>"en_US"));

<a href="{jurl 'cms~page:view', array('page'=>'foo', 'lang'=>$j_locale}">my link</a>
<a href="{jurl 'cms~page:view', array('page'=>'foo', 'lang'=>'fr_FR'}">my link</a>

with static parameters ¶

   <url pathinfo="/articles/english/:page" module="cms" action="page:view">
      <param name="page"/>
      <static name="lang" value="en_US" type="locale"/>
   </url>
   <url pathinfo="/articles/francais/:page" module="cms" action="page:view">
      <param name="page"/>
      <static name="lang" value="fr_FR" type="locale" />
   </url>

    <static name="lang" value="fr" type="lang" />

With dynamic parameters ¶

   <param name="lg" type="lang"/>
   <!-- or -->
   <param name="lg" type="locale"/>

   <url pathinfo="/articles/en/:page" module="cms" action="page:view">
      <param name="page"/>
      <static name="lang" value="en_US" />
   </url>
   <url pathinfo="/articles/fr/:page" module="cms" action="page:view">
      <param name="page"/>
      <static name="lang" value="fr_FR" />
   </url>

   <url pathinfo="/articles/:lang/:page" module="cms" action="page:view">
      <param name="page"/>
      <param name="lang" type="lang" />
   </url>

We saw how to use a system to analyse the content of the pathinfo. However, sometimes it is not enough, and we need a more complex parsing. For example, parts of a pathinfo can be some data stored in a database, and we need to search in the database this parts to get some ids or whatever..

So in some case, we want to create our own parser, called an "handler" (an other solution is to create a new url engine but it is more complicated).

To create an handler, you create a specific class:

class myHandlerUrlsHandler implements jIUrlSignificantHandler {

    function parse($url){
        
        if(preg_match("/^\/(.*)$/",$url->pathInfo,$match)){
            $urlact = new jUrlAction($url->params);
            $urlact->setParam('page',jUrl::unescape($match[1]));
            return $urlact;
        }else
            return false;
    }

    function create($urlact, $url){

        $p=jUrl::escape($url->getParam('page'));

        $url->pathInfo = "/$f";
        $url->delParam('page');
    }
}

The class name should end by "UrlsHandler", and the name of the handler is the prefix (here "myHandler"). Then the class should be stored in the classes/ directory of a module. The file should be named like prefix.urlhandler.php. In our example, it should be myHandler.urlhandler.php.

The method parse() should parse the url given as argument (a jUrl object). If your handler recognize the url, it should return a jUrlAction object, else it should return false.

The method create() is called each time the application ask the url corresponding to an action. This method receive a jUrlAction object and a jUrl object. $urlaction contains the parameters of the action. This parameters are already stored in the $url object. Then you should modify the $url object in order to generate the corresponding true url. So in fact, you should generate the pathinfo, and/or delete some parameters...

Note that you can use jUrl::escape() and jUrl::unescape(), to cleanup strings (by removing some special characters for example).

Then, in the urls.xml file, you have to specify the handler:

   <classicentrypoint name="wiki">
       <url handler="myHandler" module="unittest" action="url4" />
    </classicentrypoint>

Of course, the handler can be stored in any module:

   <classicentrypoint name="wiki">
       <url handler="othermodule~myHandler" module="unittest" action="url4" />
    </classicentrypoint>

Let's imagine that we have a url of the following pattern, /article/54-title, and this displays the article number 54 with a view action associated for example:

   <url pathinfo="/article/:id_art-:title" module="cms" action="view" />

We want to able to indicate other actions in some case without changing the url, with an action parameter:

• /article/54-title?action=edit
• /article/54-title?action=delete

Notice: we could also do /article/54-title/edit or /article/54-title/delete, with thus several <url> tags, which would avoid what follows. But this would not be very good when the url is called by a form for example.

To specify the authorized alternative actions, we add an actionoverride attribute, containing the list of the actions separated by a space or a comma:

   <url pathinfo="/article/:id_art-:title" module="cms" action="view" actionoverride="edit,delete" />

You not always want to indicate a significant url for the actions of particular module. However, you have created an entry point dedicated to this module. All these actions will pass through this entry point. You just then have to do it like this:

    <classicentrypoint name="news">
        <url module="news" />
    </classicentrypoint>

You can specify several module like that on a same entry point.

For some actions, you could want to access them through an https access. So you should add a https attribute (with "true" as a value) on the <url> elements you want. If you want to specify https on all actions of an entrypoint, then you can put the https attribute on the entrypoint element instead of each url element.

You can define URLs in separate files, in each module, and then declare those files into the main urls.xml file. It avoid to have a big main urls.xml file, and more important, to avoid to declare or rewrite all url of a module in this file, when you install a module made by someone.

To do it, you shoud create a file, urls.xml (or with an other name), in the directory of the module. This file should have a suburls element as root element, instead of urls, and have all needed url element to declare all urls mapped to each action of the module. You should not use entrypoint elements of course. Here is the urls.xml file of the jauth module:

<?xml version="1.0" encoding="utf-8"?>
<suburls xmlns="http://jelix.org/ns/suburls/1.0">
    <url pathinfo="/dologin" action="login:in" />
    <url pathinfo="/dologout" action="login:out" />
    <url pathinfo="/login" action="login:form"/>
</suburls>

And in the main urls.xml file, in one of your entrypoint element, you indicate:

  <entrypoint name="index">
    ...
     <url pathinfo="/auth" module="jauth" include="urls.xml" />
  </entrypoint>

It means: urls declared in the urls.xml file of the module jauth should be included, and should be prefixed by the given pathinfo "/auth/". So the url of the "jauth~login:in" action will be "/auth/dologin".

You notice that URLS defined in a module file are not "full" URL. It allow the developer to choose the first part of URLs, and it avoid to have conflict with other URLS declared in other modules.

In module files, you can declare URL with a static pathinfo, with a pathinfo with parameters, with an handler, with static values. However you have to declare an url for all actions. And you cannot of course use the module attribute.

You have also to create a url file for each type of entry point, if needed.

Perhaps you would prefer that the parsing of the urls will be done by the web server, by using for example the rewrite mod in Apache.

Full use of mod_rewrite ¶

 [urlengine]
  ..
  enableParser = off

Just remove the entry point ¶

   http://monsite.com/news/2007-02-08-il-neige-a-lille.html

   http://monsite.com/index.php/news/2007-02-08-il-neige-a-lille.html

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ index.php/$1 [L,QSA]
</IfModule>

    RewriteRule ^(.*)$ index.php?jpathinfo=/$1 [L,QSA]

 [urlengine]
 ...
 pathInfoInQueryParameter = jpathinfo