=pod

=head1 NAME

WWW::Autosite::Manual - installation, usage, examples for autosite

=head1 OVERVIEW

The general reasoning behind autosite is that as a web guru, someone who wants you to make them a bio webpage, sends you bio.txt and maybe bio.jpg. You put them together to make bio.html. 
We refer to the raw content (bio.txt, and bio.jpg, here) as the 'content', and to the final product (bio.html) as sgc, or server generated content. Because that's what it should be. And if you implement this system, that's what it will be.

No more waiting on text files, image files, mp3s, whatever. 
Just have the client upload the junk and voila. Done.




=head1 DESCRIPTION


This is a system to generate and maintain a website.
It separates the process into three parts.

Back End / Installation / maintenance

Design

Content Management / End User


The autosite system does not have to impose itself on the way a present site works.
The system can be implemented on a website to add functionality, or just so you can test it out.

GOAL: give complete power/responsibility over the content of the website to the client/owner of the website.

Presenting content online is as easy as uploading a file.




You should be fully aware of the concepts behind autosite.


The L<content> is the file you want to generate content about.









=head1 BACKEND

=head2 The Router






=head2 The Handlers

Each handler will be passed as argument the full path to the content file.
A handler works under cli.
Your handler should be named according to what it does.
Handlers run cli, not cgi.
Your handler should work perfectly on the command line.
Your handler must reside alongside the router, in the same directory. 

Each handler must have fully documented inline pod.

	perldoc handlername 

Must show full documentation.










=head1 DESIGN


=head2 The Templating System


=head1 CONTENT MANAGEMENT



=head2 Metadata

What if you have a part of the document tree that has stuff for showing inventory.
Maybe each item has a picture, a title, a description, a price, a numbers part.
















=head1 CONCEPTS & GLOSSARY

Conventions used in this document.
For the sake of example, 'domain.com' refers to an imaginary site.
This is a loose glossary to convey concepts.

=over 4

=item user

The person who manages the L<content> on the site. This is the person who paid you to host and or design their site.

=item designer

The person who manages look and feel of the site. This person is in charge of layout, graphic design, and 
altering the templates.

=item handler

In this document a 'handler' is a script that creates L<sgc> on the fly.

Example: If you have a pod-html handler.
The user uploads file.pod. Then someone opens a browser and types in domain.com/file.pod.html, if the file does not exist,
the handler creates the file. This is managed by the L<router>.

The handler is in charge of fetching your templates, etc and generating content.

A handler is NOT a cgi script. It should function perfectly well as a cli tool.
Various handlers are included in this distro.

One of the major highlights of this system is to allow you to easily add new handlers without doing more then dropping in a file. 

=item content

This is what the L<user> uploads to the site. If your user is a band who paid you to host or design their site, then they may be uploading songs, for example. Then some of their content will be for example; song1.mp3, song2.mp3. 
Maybe they have a bio page, this would be bio.txt. Maybe they are uploading a press kit in zip format, press_kit.zip. These are all content files.
When you are designing a site in a conventional manner, you have the client email you their 'about us' text, 'contact info'- maybe some pictures. With autosite, the L<user> can upload all that content to the website and it is instantly presented with the layout you designed.


=item sgc

The (s)erver (g)enereated (c)ontent.
A 'server generated content' file is a file that was generated by a handler, about a content file.
It is automated content, about user provided content.


Example:
The user content is 'file.mp3'. This file resides in DOCUMENT ROOT. Thus, to download the file:

	http://domain.com/file.mp3

However, what if you want to see a presentation about the file, maybe am excerpt, a link to a zip file?

	http://domain.com/file.mp3.html
	
And maybe you just want to download a zipped up copy

	http://domain.com/file.mp3.zip

The html and the zip files are what we refer to as sgc.	
	
Sgc files should be regarded with contempt- they are not precious. They should not be edited directly. That
would defeat the whole purpose of autosite.

The sgc files can be extremely fine tuned via the editing of L<HTML::Template> files provided. New ones can be created.
Also, you are welcome to code your own L<handler> for whatever.


=item router

The router takes the client browser requests and forwards them to the appropriate handler, if one exists.
The router is a cgi script, an L<.htaccess> file is required to forward 404 errors to this script.

=item .htaccess

The htaccess file is crucial to the autosite system.
It should catch 404 errors and send them to the L<router>.


=item ENV AUTOSITE_TMPL

Required.
Environment variable. This is the absolute path to templates directory.

=item main template

Required.
Must reside in L<ENV AUTOSITE_TMPL>. 
Must be named main.html.
This template's only required L<TMPL_VAR> is BODY.

=item insertable template

Optional.
Begins with a _ (underscore).
If your handler processes pod to html, then the insertable template file name is _pod.html and it resides in L<ENV AUTOSITE_TMPL>.
An insertable template means it will be inserted into the L<main template> L<TMPL_VAR> BODY.
It is implied that your main template has full html headers and footers. So, your insertable template does not need to have any.  

=item overriding template

Optional.
Named as the handler. Does not begin with an underscore as the L<insertable template> does.
If your handler processes pod to html, then the overriding template's filename is pod.html, and it resides in L<ENV AUTOSITE_TMPL>. An overriding template will not be inserted into the L<main template>. Thus, it should have its own full html headers and footers.

=item TMPL_VAR

See L<HTML::Template>. 

=item metadata

If your handler feeds metadata, then 

=back







=head1 SEE ALSO

Programmer API: L<WWW::Autosite>

=head1 AUTHOR

Leo Charre 

=cut