CppCMS
Public Member Functions
cppcms::url_mapper Class Reference

class for mapping URLs - the opposite of dispatch More...

#include <cppcms/url_mapper.h>

Inheritance diagram for cppcms::url_mapper:
booster::noncopyable

List of all members.

Public Member Functions

std::string root ()
void root (std::string const &r)
void assign (std::string const &key, std::string const &url)
void assign (std::string const &url)
void set_value (std::string const &key, std::string const &value)
void clear_value (std::string const &key)
void map (std::ostream &out, char const *path)
void map (std::ostream &out, char const *path, filters::streamable const &p1)
void map (std::ostream &out, char const *path, filters::streamable const &p1, filters::streamable const &p2)
void map (std::ostream &out, char const *path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3)
void map (std::ostream &out, char const *path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3, filters::streamable const &p4)
void map (std::ostream &out, char const *path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3, filters::streamable const &p4, filters::streamable const &p5)
void map (std::ostream &out, char const *path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3, filters::streamable const &p4, filters::streamable const &p5, filters::streamable const &p6)
void map (std::ostream &out, std::string const &path)
void map (std::ostream &out, std::string const &path, filters::streamable const &p1)
void map (std::ostream &out, std::string const &path, filters::streamable const &p1, filters::streamable const &p2)
void map (std::ostream &out, std::string const &path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3)
void map (std::ostream &out, std::string const &path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3, filters::streamable const &p4)
void map (std::ostream &out, std::string const &path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3, filters::streamable const &p4, filters::streamable const &p5)
void map (std::ostream &out, std::string const &path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3, filters::streamable const &p4, filters::streamable const &p5, filters::streamable const &p6)
void mount (std::string const &name, std::string const &url, application &app)
url_mapperchild (std::string const &name)
url_mapperparent ()
url_mappertopmost ()

Detailed Description

class for mapping URLs - the opposite of dispatch

This class is useful for mapping between different page identifications that represent different classes/view and the URL.

The URL mapping is done in hierarchy of applications where each application has its own name and they bundler into single hierarchy. Each application in hierarchy can be referred by its key and location. It may have different "urls" for mapping different values.

For example, we develop a content management system with following tools:

Each node above is represented my cppcms::application and its children mounted to it. In order to access each URL we use "file system" like convention:

And so on.

Each application can be referred by its full path from root or by its relative path, so if we for example in article sub-application and we want to refer to "category" URL we would use something like map(out(),"../category/by_interest",category_id);

In order to all this process work, each application should mount its children by some name, like:

     site::site(cppcms::service &s) : 
           cppcms::application(s),
           news_(s),
           forums_(s),
           users_(s)
     {
         add(news_);
         mapper().mount("news","/news{1}",news_);
         add(forums_);
         mapper().mount("forums","/forums{1}",forums_);
         ...

You can also use cppcms::application::add and cppcms::application::attach that allows to provide mapping for url_dispatcher and url_mapper in a single command like:

    add(news_,
        "news","/news{1}",
        "/news((/.*)?)",1);

Which effectively the same as:

    add(news_);
    mapper().mount("news","/news{1}",news_);
    dispatcher().mount("/news((/.*)?)",news_,1);

Such system allows using "url" tag in templates system easily as"

   <a href="<% url "/news/article" using article id %>" >...</a>

Each mounted application may a default URL (something like index.html) which is mapped when mounted application is referred. So for example there are may be following URLs:

They can be defined in article class as following:

  article::article(cppcms::service &s) : cppcms::application(s)
  {
     mapper().assign("/{1}"); // the default URL
     dispatcher().assign("/(\\d+)",&article::display,this,1);
     mapper().assign("preview","/{1}/preview"); // the preview URL
     dispatcher().assign("/(\\d+)/preview",&article::preview,this,1);
  }

Additional supported feature is "named" parameters which are usually set to some default value using set_value, they are defined by special keywords between instead of numbers.

For example assign("article", "/article/{lang}/{1}") were "lang" is special value for language defined by set_value("lang","en"), so mapping map(out(),"article",10) would create a URL "/article/en/10"

Sometimes it is useful to change such values there are two ways to do it:


Member Function Documentation

void cppcms::url_mapper::assign ( std::string const &  key,
std::string const &  url 
)

Provide a mapping between special key and a url pattern.

URL patter is a string that includes mapped patters between "{" and "}" brackets. For example "/page/{1}" where "{1}" is being substituted by the first parameter in map functions.

The ids can be numbers - 1 to 6 and special keys that can be changed in the run time using set_value functions. For example:

"/wiki/{lang}/page/{1}"

Where "lang" can be defined by "set_value". For example.

For the url above with "lang" set to "en" and first parameter "cppcms" the string would be "/wiki/en/page/cppcms"

Note the keys may be overloaded by number of parameters as for example:

  • assign("page","/wiki/{1}/page/{2}");
  • assign("page","/wiki/{lang}/page/{1}");
  • assign("page","/wiki/{lang}/page/main");

Then map(output,"page") - would create "/wiki/en/page/main", map(output,"page",134) would create "/wiki/en/page/132" and map(output,"page","ru","cppcms") would create "/wiki/ru/page/cppcms"

Note: They keys containing "/", "," or ";" and keys with values "..", ".", "" are prohibited as they have special meanings

void cppcms::url_mapper::assign ( std::string const &  url)

Map the default key for the application, url has same rules as for assign(key,url) but they rather refer to default application's URL when it is used in hierarchy.

url_mapper& cppcms::url_mapper::child ( std::string const &  name)

Get a mapper of mounted application by its name

void cppcms::url_mapper::clear_value ( std::string const &  key)

Clear the special value - reset to empty

Note: this value is cleared globally for all applications hierarchy and not only for this specific application

void cppcms::url_mapper::map ( std::ostream &  out,
char const *  path 
)

Write the URL to output stream out for the URL path with 0 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
char const *  path,
filters::streamable const &  p1 
)

Write the URL to output stream out for the URL path with 1 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
char const *  path,
filters::streamable const &  p1,
filters::streamable const &  p2 
)

Write the URL to output stream out for the URL path with 2 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
char const *  path,
filters::streamable const &  p1,
filters::streamable const &  p2,
filters::streamable const &  p3 
)

Write the URL to output stream out for the URL path with 3 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
char const *  path,
filters::streamable const &  p1,
filters::streamable const &  p2,
filters::streamable const &  p3,
filters::streamable const &  p4 
)

Write the URL to output stream out for the URL path with 4 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
char const *  path,
filters::streamable const &  p1,
filters::streamable const &  p2,
filters::streamable const &  p3,
filters::streamable const &  p4,
filters::streamable const &  p5 
)

Write the URL to output stream out for the URL path with 5 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
char const *  path,
filters::streamable const &  p1,
filters::streamable const &  p2,
filters::streamable const &  p3,
filters::streamable const &  p4,
filters::streamable const &  p5,
filters::streamable const &  p6 
)

Write the URL to output stream out for the URL path with 6 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
std::string const &  path 
)

Write the URL to output stream out for the URL path with 0 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
std::string const &  path,
filters::streamable const &  p1 
)

Write the URL to output stream out for the URL path with 1 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
std::string const &  path,
filters::streamable const &  p1,
filters::streamable const &  p2 
)

Write the URL to output stream out for the URL path with 2 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
std::string const &  path,
filters::streamable const &  p1,
filters::streamable const &  p2,
filters::streamable const &  p3 
)

Write the URL to output stream out for the URL path with 3 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
std::string const &  path,
filters::streamable const &  p1,
filters::streamable const &  p2,
filters::streamable const &  p3,
filters::streamable const &  p4 
)

Write the URL to output stream out for the URL path with 4 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
std::string const &  path,
filters::streamable const &  p1,
filters::streamable const &  p2,
filters::streamable const &  p3,
filters::streamable const &  p4,
filters::streamable const &  p5 
)

Write the URL to output stream out for the URL path with 5 parameters

void cppcms::url_mapper::map ( std::ostream &  out,
std::string const &  path,
filters::streamable const &  p1,
filters::streamable const &  p2,
filters::streamable const &  p3,
filters::streamable const &  p4,
filters::streamable const &  p5,
filters::streamable const &  p6 
)

Write the URL to output stream out for the URL path with 6 parameters

void cppcms::url_mapper::mount ( std::string const &  name,
std::string const &  url,
application app 
)

Mount sub application app using name name to url.

The URL format as in assign but it requires a single parameter {1} which would be substituted with the mapping of the URL of sub-application instead of using "root" patch

Get a parent mapper, if not exists throws cppcms_error

std::string cppcms::url_mapper::root ( )

Get the root of the application - the string that is added to the any URL patter like "/forum" or "http://my.site.com"

void cppcms::url_mapper::root ( std::string const &  r)

Set the root of the application - the string that is added to the any URL patter like "/forum" or "http://my.site.com"

void cppcms::url_mapper::set_value ( std::string const &  key,
std::string const &  value 
)

Set special value for a key that would be used in URL mapping, for example set_value("lang","en")

Note: this value is defined globally for all applications hierarchy and not only for this specific application

Get a topmost mapper, if have no parents returns reference to this.


The documentation for this class was generated from the following file: