Xaraya: using xarModURL to create links 09.14.2005

Article Summary

In Xaraya, hardcoded links are rarely a good choice for creating links to internal objects. The Xaraya function xarModURL() allows for the creation of dynamic links, which adjust as a site changes.

Navigational schemes for the majority of websites out there include some form menu that lists every section available to the user from the website. In most cases, these are internal links that lead to different content under the same domain.

With CMS software such as Xaraya, there are options to change URL formats at will, which in turn will cause all links on the website to change, including those in your navigation menu. This is bad news if you've decided to hard code the links in your navigation menu, because you'll then be forced to re-edit any templates that have those hardcoded links in them.

In order to prevent you from having to do such tedious work, Xaraya provides a utility function that creates links for you on-the-fly.

The Scenario

Let's say you plan on including the following sections in your navigation menu:

  • Home (link to the front page)
  • News (link to the News publication type)
  • Forum (link to the XarBB forum)

First Step

Links to each of these can be made very easily. The first step is to put the links in an unordered list:

<ul>
    <li>Home</li>
    <li>News</li>
    <li>Forum</li>
</ul>

You'll end up with something that looks similar to this:

  • Home
  • News
  • Forum

For those of you who are unfamiliar with web standards, this may look a bit odd to you. For a thorough explanation of why this is implemented as an unordered list, take a look at the article CSS Design: Taming Lists over at A List Apart.

Second Step

The second step is to place links inside of these lists:

<ul>
    <li><a href="#">Home</a></li>
    <li><a href="#">News</a></li>
    <li><a href="#">Forum</a></li>
</ul>

The result looks something like this:

Adding xarModURL

Now, we can add xarModURL():

<ul>
    <li><a href="#xarModURL()#">Home</a></li>
    <li><a href="#xarModURL('articles', 'user', 'view', array('ptid' => 1))#">News</a></li>
    <li><a href="#xarModURL('xarbb', 'user', 'main')#">Forum</a></li>
</ul>

In the first list item, we've made a call to xarModURL() with no parameters. Since there are no parameters, by default the link created by this call will lead to the front page of the website.

In the second list item, we've made a call to xarModURL with a number of parameters:

  • The first parameter 'articles' refers to the parent module of the intended destination (in all cases, the intended destination is a module function, which will be explained below).
  • The second parameter 'users' refers to the type of module function we're seeking. There are two module types in Xaraya, user and admin. User types are intended to be viewed by users, while admin types are intended to be viewed by site administrators.
  • The third parameter 'view' refers to the specific module function we want to perform. There are many different kinds of possible module functions (display, main, modifyconfig, new, etc.). However, in this case we want to use view because it's considered the top-level function for accessing all content in a publication type.
  • Finally, the fourth parameter array('ptid' => 1) is actually a parameter to the 'view' function that is specified immediately before it. Its purpose is to restrict the articles being viewed to those from the publication type with an ID of 1 (which in this hypothetical case is the News publication type). There are many other parameters that can be added here to specify more stringent requirements, such as sorting, date ranges, authors, etc. However, since we want to see all articles in the publication type, we'll just use 'ptid' as the single parameter here.

In the third list item:

  • The first parameter 'xarbb' refers to the XarBB module (Xaraya's message board module).
  • The second parameter 'user' refers to function type as explained above.
  • The third parameter 'main' refers to the Main function of the XarBB module. This is basically a reference to the top-level page of the XarBB module, where all the other user functions can be accessed.

Depending on how your installation is configured, the actual links could look like any of the following (roll your mouse over the links to see the URLs):

Short URLs enabled, index.php removed from URL path
Short URLs enabled, index.php retained in URL path
Short URLs disabled

Conclusion

No you've got a nice unordered list with links that are automagically tailored to your site's configuration — and if you decide to change this configuration in the future, all links you've created with xarModURL will automatically be updated. Now all that' sleft is to style your navigation menu to make it look like a navigation menu. The aforementioned Taming Lists article from A List Apart will be of great use in helping you make your lists pretty.

posted in Xaraya at 03:36AM on September 14, 2005.