Mod_Layout FAQ.
General Questions
Appendix A. Layout Examples
General Questions
So what is Mod Layout?
Mod_Layout wraps a page. Ok, so what does that mean? It means that it can place
information at both the beginning and the end of a document (or before or after a tag).
Using the Layout directive you can actually insert layouts anywhere in a document dynamically.
This allows you to create a single look and feel throughout a website without using
server side includes to "automagically" add content in either of these two locations.
You can use it to add standard disclaimers to all of the pages on a server or to place
banner adds on the top of all pages (I know, banner adds, ick...). I have even
seen people use headers and footers to wrap the entire content of a given site (they
place the original content in a table and then place additional material all around
the content). With Mod_Layout's ability to work with pretty much any type of
original content (whether produced by text, CGI, Java, PHP or Perl) it is perfect for
development houses that use different technologies or who don't control all of the
different types of content that may go on their site.
There are many possibilities.
Where do I get it from?
You can get it from here.
What sort of license does it have?
You are pretty much free to use it as you please. The LICENSE is BSD (basically the same as Apache's).
How can I make suggestions for it?
Send email to brian@tangent.org.
How can I report a bug?
Fill out the form here.
Is there a mailing list?
Yes!. Two mailing lists have been created. One is announce-mod_layout@tangent.org which is only used for sending out announcements about new versions of the software. The other is mod_layout@tangent.org which is for general discussion of the software and its uses. Send mail to minordomo@tangent.org with a subject of "subscribe announce-mod_layout" or "subscribe mod_layout" to subscribe to either of the mailing lists.
How do I get started using it?
First you need to decide what sort of layout you need. Do you just need a Footer? If that is the
case you can just add LayoutFooter directives as needed. Now, if you want something a bit more complicated,
like a single look and feel throughout your site, then you need to decide if you want to use merge or not.
What merge does is insert footers and headers before and after tags found in the output of the original
document. By default it will use <body> tags. This can be a be very handy since as long as your
HTML is valid, you can create documents on the fly that have propper HTML.
If you want to include in
your headers and footers all of the propper HTML (and have your original documents just to be snippets of
HTML) you can run without merge (on the same token, if you don't care about valid HTML since browsers
seem to get it "right" you can do this too).
Is there anyplace I can see it at work?
I use it at http://tangent.org/ Comments should be on, so you can see how the different headers and footers are used to make the site (yeah, and it proves that while I can write code, I stink at HTML). In the Appendix of this Faq you will find the HTTP directives I use to create the site
How do I install it?
Look at the file called INSTALL that comes with your copy of mod_layout
What are the directives?
I have my own type that I have defined with AddHandler, how can I wrap that?
Use LayoutHandler. An example would be:
LayoutHandler type/subtype
Hey, I don't want to wrap CGI's, just HTML, how do I do that?
Use the following directives:
LayoutDefaultHandlers Off
LayoutHandler text/html.
What handlers does LayoutDefaultHandlers do?
I will probably add more in the future. Email me if you have one that you would like to see added in by default.
What environmental variables does ModLayout add?
Four environmental variables are currently added to environmental namespace for Layout and Header files. They are:
They represent the parsed information that made up the original request. You can set the look of LAYOUT_LAST_MODIFIED by using the LayoutTimeFormat directive).
How do I pick different headers and footers for different pages dynamically?
Write a cgi/servlet/PHP script and use the LAYOUT_SCRIPT_NAME environmental variable to determine what content you wish to display.
What about frames?
I personally hate them.
You want to know more?
Hey, what about using this with a proxy server?
As of version 0.9 I began to test support for the proxy module. Currently I have only tested ProxyPass and it seems to work (any feedback would be appreciated). In cases where a flash file is used as an Index file (or any filetype which is not wrappable) the page that is returned will be broken. Also, anything that ProxyPass cannot support, Mod_Layout will support.
Can I have just the footer and header display and skip the original content?
Yes. The most common reason to do this is if you are handling frames (and if you are doing frames don't forget to make the header dynamic and smart enough not to wrap itself). You can turn off the original content by using "LayoutDisplayOriginal Off".
Is it possible to specify text/* in for a LayoutHandler?
Yes, all handlers use fnmatch regular expressions. Look at your system's main pages to determine syntax. BTW If you specify something like "*/*", yes you will wrap everything, but this includes images (which will show up corrupted).
What about directories?
Ok, so you tried adding:
LayoutHandler text/directory
and it didn't work right?
At least for Solaris and Linux (that is the only place I have
tested this on), the following should work:
LayoutHandler httpd/unix-directory
Can I have it ignore certain files?
Yes!. You can speficy URI that are to be ignored by using the LayoutIgnoreURI directive. It handles regular expressions.
But can I have only certain files not display headers (or footers)
Yes!. You can speficy URI that are to be ignored for headers by using the LayoutIgnoreHeaderURI directive. A similair directive, LayoutIgnoreFooterURI exists for footers. Both handle regular expressions.
How do I modify outbound HTTP headers?
LayoutHTTPOverrideHeader and LayoutHTTPOverrideURI can be used to have mod_layout ignore producing headers for scripts. Keep in mind though if you are using merge and you have headers, that those headers will be what will produce HTTP headers.
How do I make this work with PHP?
It has worked out of the box with php (AKA no needing to add handlers) since version 2.11.5
So what is up with custom error documents?
As of version 2.11.5 this all works like you think it should.
What am I to do if I get 405's with SSI documents?
The answer is that you have LayoutPostAsync enabled. Right now there is no fix for this. The SSI module rejects attempts on SSI's when it thinks the request was a POST. This will be fixed eventually
Can I use mod_layout directives in .htaccess files?
If you enable .htaccess files, mod_layout will work in them.
What is this merge thing??
Merge is a really cool feature that was added as of version 2.8. What it does is insert your headers and footers inside of the original content. By default it inserts the headers after the <BODY*> tag and the footers before the </BODY> tag. You can modify which tags are used. If you are looking to do correctly formatting HTML, this is for you.
Why are cookies not working, and php scripts with Location are failing?
This was all fixed in version 2.11.4 so it is no longer an issue.
So, mod_layout is dinking up my plain text documents, what can I do?
You need to install a tex->html handler. You could use mod_text2html.
Woops, mod_layout is displaying my php/perl script as code, its not executing it, what happened?
You did something like this: LayoutHeader /usr/local/apache/htdocs/footer.pl instead of LayoutHeader /footer.pl. You need to reference from a document root (or scriptalias root).
What is the future?
This is really just the first component of what will be an entire web publishing system. I have a few others that I have written over the years that I am currently trying to clean up enough to give away. We shall see how ambitious I get :)
Appendix A. Layout Examples
Simple Copyright Example
This will tack a simple Copyright on to the bottom of all of your pages
<VirtualHost www.foo.com:80>
LayoutFooter "Copyright Foobar, 2000"
</VirtualHost>
Header and Footer example.
This Site uses merge to insert a banner and dynamic footer.
This will tack a simple Copyright on to the bottom of all of your pages
<VirtualHost www.foo.com:80>
LayoutMerge On
LayoutHeader "<IMG SRC="/site_logo.gif" ALT="Foobar incorporated">
LayoutFooter /footer.php
</VirtualHost>
HTML only example
This will tack a simple Copyright on to the bottom of all of your pages
<VirtualHost www.foo.com:80>
LayoutFooter "Copyright Foobar, 2000"
Layout "<-- copyright -->" "Copyright Foobar, 2000"
LayoutDefaultHandler OFF
LayoutHandler text/html
</VirtualHost>
Hosting Service.
This is a typical way hosting services use mod_layout. You will notice how the header and fotter are kept in a scriptalias directory where the user can not get at them.
httpd.conf
----------
ScriptAlias /cgi-bin/ "/usr/local/apache/cgi-bin/"
LayoutHeader /cgi-bin/header.pl
LayoutFooter /cgi-bin/header.php
<VirtualHost example.com>
...
</VirtualHost>
<VirtualHost 2example.com>
...
</VirtualHost>
Advanced site.
This example is from tangent.org. Notice how it uses different headers and footers for different subdirecties. Note that all content ending with rss are ignored. Also note that user's home directories will not be wrapped in this example. Comments are enabled so you can see where different content begins and ends.
<VirtualHost 205.153.154.37:80>
######
###### www.tangent.org
######
ServerName www.tangent.org
ServerAlias shiitake.tangent.org shiitake.tangent.org tangent.org portabello portabello.tangent.org www
UseCanonicalName On
ErrorDocument 404 /404.pl
RandomQuote On
RandomQuoteFile /usr/local/apache/conf/quotes
DocumentRoot /usr/local/apache/htdocs-Tangent
UserDir public_html
CustomLog /usr/local/apache/logs/www_tangent_org.access combined
ErrorLog /usr/local/apache/logs/www_tangent_org.error
LayoutComment On
LayoutIgnoreURI *.rss
<Directory /usr/local/apache/htdocs-Tangent/>
LayoutHeader /usr/local/apache/htdocs-Tangent/header.html
LayoutFooter /footer.pl
LayoutHandler httpd/unix-directory
LayoutMerge On
</Directory>
<Directory /usr/local/apache/htdocs-Tangent/mod_layout/>
LayoutHeader /mod_layout/header.html
</Directory>
<Directory /usr/local/apache/htdocs-Tangent/mod_repository/>
LayoutHeader /mod_repository/header.html
</Directory>
<Directory /usr/local/apache/htdocs-Tangent/mod_random/>
LayoutHeader /mod_random/header.html
</Directory>
<Directory /usr/local/apache/htdocs-Tangent/mod_cgi_debug/>
LayoutHeader /mod_cgi_debug/header.html
</Directory>
<Directory /usr/local/apache/htdocs-Tangent/mod_relocate/>
LayoutHeader /mod_relocate/header.html
</Directory>
<Directory /usr/local/apache/htdocs-Tangent/mod_filter/>
LayoutHeader /mod_filter/header.html
</Directory>
<Directory /usr/local/apache/htdocs-Tangent/DBIx-Password/>
LayoutHeader /DBIx-Password/header.html
</Directory>
</VirtualHost>