appmods.yaws

<erl>


box(Str) ->
    {'div',[{class,"box"}],
     {pre,[], yaws_api:htmlize(Str)}}.

tbox(T) ->
    box(lists:flatten(io_lib:format("~p",[T]))).


ssi(File) ->
    {'div',[{class,"box"}],
     {pre,[],
      {ssi, File,[],[]}}}.


out(A) -> 
    [{ssi, "TAB.inc", "%%",[{"appmods", "choosen"}]},
     {ehtml,
      {'div', [{id, "entry"}],

      [{h1, [], "Appmods (Application modules)"},
       
       {p, [],
        ["Appmods are a way to let the application programmer take control over the URL path.  Or put in another way, to let the application programmer fake real paths in URLs where in reality an Erlang modules is executing. Possibly an example make this easy to understand. Say we have the folowing url"]},

       box("http://yaws.hyber.org/pathelem/foo/bar/x.pdf"),
       
       {p,[],["With the above url, the webserver would try to deliver the file \"/pathelem/foo/bar/x.pdf\" relative to the docroot. However if we had specified \"pathelem\" as an appmod, the server would stop processing the url after seeing the \"pathelem\" part of the URL. Say we had the following in our yaws.conf configuration file"]},

       
       box("
<server tita>
        port = 8001
        listen = 0.0.0.0
        docroot = /home/klacke/yaws/yaws/scripts/../www
        appmods = <pathelem, myappmod>
</server>"),



       
       {p,[],
        ["Then the webserver would invoke ",
         {tt,[], "myappmod:out(A)"},
         " instead of trying to deliver the actual file. When shipping such an ",
         {a, [{href, "/pathelem/foo/bar/x.pdf"}], "Url"}, 
         " there are 2 fields in the #arg record which are especially interesting. If we have the following code in \"myappmod.erl\":"]},

       ssi("code/myappmod.erl"),

       {p,[],"The #arg field called \"appmoddata\" contains the remainder of the path following the encountered appmod and the field \"appmod_prepath\" contains the part of the URL path leading upto the appmod."},


       {p,[],
        "Thus the following url"},
       box("http://yaws.hyber.org/zap/pathelem/foo/bar/x.pdf?a=b"),
       {p,[],
        "Produces the following output:"},
       box("
A#arg.appmoddata = \"/foo/bar/x.pdf\"
A#arg.appmod_prepath = \"/zap/\"
A#arg.querydata = \"a=b\""),
       
       {br,[],[]},

       {p, [],
        "Appmods would typically be used by webapplications that want to provide the illusion of proper paths to the browser. "},

       {p, [], "A special case of an appmod that is particularly interesting is the '/' appmod. This used when we want application code to handle all requests. This is common with web frameworks such as Nitrogen."},
       
       box("
<server tita>
        port = 8001
        listen = 0.0.0.0
        docroot = /home/klacke/yaws/yaws/scripts/../www
        appmods = </, myappmod>
</server>"),

       {p, [], "The above configuration snippet is an example of a slash appmod. One complication with the slash appmod is that usually we have a set of folders containing static data, images and java script, and we want yaws to just deliver those files without intervention from the slash appmod. This can be achieved by excluding a set of directories."},
 

       box("
<server tita>
        port = 8001
        listen = 0.0.0.0
        docroot = /home/klacke/yaws/yaws/scripts/../www
        appmods = </, myappmod exclude_paths icons js top/static>
</server>"),

       {p, [], "The above configuration will invoke the 'myappmod' erlang module on everything except any file found in directories, 'icons', 'js' and 'top/static' relative to the docroot"}


       ]
       }},
       {ssi, "END2",[],[]}
       ].



</erl>