URL construction

Applications often need to generate links to the URL's corresponding to controllers and actions. For example, a listing of all support tickets would need to generate a link to a URL similar to

  http://www.mycompany.com/support/ticket/display/123

These URL's could be generated by hard coding the entire URL except the ticket id. However, this is not desirable for several reasons. For example, if the application is relocated to reside at a different toplevel location, all such links have to modified. Similarly, if the route maps change, then all such links have to be made consistent.

Instead, links should be dynamically generated at runtime based on where the application resides. Rather than forcing the application to individually retrieve the various URL components and build it piecemeal, Woof! provides URL and link generation commands that make this simple to do. For example, the page template for the above link may have the fragment

<a href='[my url_for -action edit -parameters [params get]]'>Edit</a>

This would result in a link being inserted into the generated page that would point to the URL

  http://www.mycompany.com/support/ticket/edit/123

If at some point the application was moved to customers, the generated link would correctly point to

  http://www.mycompany.com/customers/ticket/edit/123

without any code having to be modified.

The url_for method

The url_for method constructs a URL based on the supplied criteria and using defaults based on the current controller context. For example, when the abovementioned URL is being processed by the Ticket controller (including any template processing), the controller context includes the host specification http://www.mycompany.com, the application root /support, the module, non-existent in this case, the controller ticket and action display.

Under this context, the method will return the following values:

my url_for -fullyqualify true -parameters {id 456}
  → http://www.mycompany.com/customers/ticket/display/456

Only the parameter 123 is changed to 456 while everything else is unchanged as it is taken from the current controller context.

If the -fullyqualify option was not specified,

my url_for -parameters {id 456}
  → 456

a URL, relative to the one specified by the client to access the current controller context, is returned. When resolved by the client, note this will resolve to the same URL as the fully qualified one above.

You can specify a different action within the same controller,

my url_for -fullyqualify true -action edit -parameters {id 123}
  → http://www.mycompany.com/customers/ticket/edit/123
my url_for -action edit -parameters {id 123}
  → ../edit/123

or to an action within a different controller (assumes routes have been appropriately defined)

my url_for -fullyqualify true -controller customer -parameters {name Acme}
  → http://www.mycompany.com/support/customer/index/Acme
my url_for -controller customer -parameters {name Acme}
  → ../../index/Acme

Note in this last example that even though we did not specify the -action option, the action method in the URL was changed to index. This is because url_for assumes that if you change the controller without specifying the action, the default action for the controller is to be used rather than the current action.

url_for has several additional options. See its reference documentation for more information. Several additional utility commands are layered on top of url_for. They are described elsewhere in this guide.