Mod_Layout FAQ

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?

LayoutDefaultHandlers

LayoutDisplayOriginal

LayoutIgnoreURI

LayoutIgnoreHeaderURI

LayoutIgnoreFooterURI

LayoutMergeErrorIgnore

LayoutIgnoreTagHeader

LayoutIgnoreTagFooter

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?

server-parsed

text/html

text/plain

perl-script

cgi-script

application/x-http-cgi

application/x-httpd-php

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:

LAYOUT_SCRIPT_NAME

LAYOUT_PATH_INFO

LAYOUT_QUERY_STRING

LAYOUT_LAST_MODIFIED

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? Ok, your best bet is to have documents with them ignored at the moment. To do this use LayoutIgnoreTag and specify the tag "<form>".

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

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.

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

    <Directory /u/Students/uniqname>
        LayoutFooter "Copyright Foobar, 2000"
    </Directory>

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

    <Directory /u/Students/uniqname>
        LayoutMerge On
        LayoutHeader "<IMG SRC="/site_logo.gif" ALT="Foobar incorporated">
        LayoutFooter /footer.php
    </Directory>

HTML only example

This will tack a simple Copyright on to the bottom of all of your pages

    <Directory /u/Students/uniqname>
        LayoutFooter "Copyright Foobar, 2000"
        Layout "<-- copyright -->" "Copyright Foobar, 2000"
        LayoutDefaultHandler OFF
        LayoutHandler text/html
    </Directory>

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.

    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>