diff --git a/cppcms/url_mapper.h b/cppcms/url_mapper.h index 5c34748..82dd12e 100644 --- a/cppcms/url_mapper.h +++ b/cppcms/url_mapper.h @@ -31,7 +31,106 @@ namespace cppcms { class application; /// - /// \brief class for mapping URLs - oposite of dispatch + /// \brief 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: + /// + /// - site + /// - news + /// - article + /// - category + /// - forums + /// - topics + /// - threads + /// - users + /// - management + /// - registration + /// - profile + /// + /// 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: + /// + /// - "/" - the default site page + /// - "/news" - the default news page + /// - "/news/article" - the default article page + /// - "/news/category/by_date" - the categories pages sorted by data + /// - "/news/category/by_interest" - the categories pages sorted by interest + /// - "/news/category" - the default category pages + /// + /// 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: + /// + /// \code + /// 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_); + /// ... + /// \endcode + /// + /// 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: + /// + /// \code + /// add(news_, + /// "news","/news{1}", + /// "/news((/.*)?)",1); + /// \endcode + /// + /// Which effectively the same as: + /// + /// \code + /// add(news_); + /// mapper().mount("news","/news{1}",news_); + /// dispatcher().mount("/news((/.*)?)",news_,1); + /// \endcode + /// + /// Such system allows using "url" tag in templates system easily as" + /// + /// \code + /// " >... + /// \endcode + /// + /// 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: + /// + /// - "/news/article" or "/news/article/" - the default URL + /// - "/news/article/preview" - preview unpublished article URL. + /// + /// They can be defined in article class as following: + /// + /// \code + /// 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); + /// } + /// \endcode + /// /// class CPPCMS_API url_mapper : public booster::noncopyable { public: @@ -40,35 +139,101 @@ namespace cppcms { ~url_mapper(); /// \endcond + /// + /// Get the root of the application - the string that + /// is added to the any URL patter like "/forum" or + /// "http://my.site.com" + /// std::string root(); + /// + /// Set the root of the application - the string that + /// is added to the any URL patter like "/forum" or + /// "http://my.site.com" + /// void root(std::string const &r); + /// + /// Provide a mapping between special \a key and a \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 4 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 keys with values "..", ".", "" are prohibited + /// as they have special meanings + /// void assign(std::string const &key,std::string const &url); + /// + /// Map the default key for the application, \a url has same rules as for assign(key,url) but + /// they rather refer to default application's URL when it is used in hierarchy. + /// void assign(std::string const &url); + /// + /// Set special value for a key that would be used + /// in URL mapping, for example set_value("lang","en") + /// void set_value(std::string const &key,std::string const &value); + /// + /// Clear the special value - reset to empty + /// void clear_value(std::string const &key); - + + /// + /// Write the URL to output stream \a out for the URL \a path with 0 parameters + /// void map( std::ostream &out, - std::string const &key); + std::string const &path); + /// + /// Write the URL to output stream \a out for the URL \a path with 1 parameters + /// void map( std::ostream &out, - std::string const &key, + std::string const &path, filters::streamable const &p1); + /// + /// Write the URL to output stream \a out for the URL \a path with 2 parameters + /// void map( std::ostream &out, - std::string const &key, + std::string const &path, filters::streamable const &p1, filters::streamable const &p2); + /// + /// Write the URL to output stream \a out for the URL \a path with 3 parameters + /// void map( std::ostream &out, - std::string const &key, + std::string const &path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3); + /// + /// Write the URL to output stream \a out for the URL \a path with 4 parameters + /// void map( std::ostream &out, - std::string const &key, + std::string const &path, filters::streamable const &p1, filters::streamable const &p2, filters::streamable const &p3, @@ -78,7 +243,7 @@ namespace cppcms { /// Mount sub application \a app using name \a name to a \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 subapplication + /// which would be substituted with the mapping of the URL of sub-application /// instead of using "root" patch /// void mount(std::string const &name,std::string const &url,application &app); @@ -88,11 +253,11 @@ namespace cppcms { url_mapper &child(std::string const &name); /// - /// Get a parent mapper, if not exists throws + /// Get a parent mapper, if not exists throws cppcms_error /// url_mapper &parent(); /// - /// Get a topmost mapper + /// Get a topmost mapper, if have no parents returns reference to \c this. /// url_mapper &topmost();