view release on metacpan or  search on metacpan

lib/TUWF.pod  view on Meta::CPAN

=head1 DESCRIPTION

TUWF is a small framework designed for writing websites. It provides an
abstraction layer to various environment-specific tasks and has common
functions to ease the creation of both small and large websites.

For a gentle introduction to TUWF, see L<TUWF::Intro>.

TUWF has been superseded by L<FU>, which is conceptually very similar but has a
faster implementation, cleaned up API and uses modern Perl features. TUWF
remains available for those who prefer a smaller and more portable pure-Perl
solution.


=head2 Main features and limitations

TUWF may be The Ultimate Website Framework, but it is not the perfect solution
to every problem. This section introduces you to some main features and
limitations you will want to know about before using TUWF.

=over

=item TUWF is small.

I have seen many frameworks being advertised as "small" or "minimal", yet they
either require loads of dependencies or are not small at all. TUWF, on the
other hand, B<is> quite small. Its total codebase is significantly smaller than
the primary code of CGI.pm, and TUWF requires absolutely no extra dependencies
to run.

Some optional features, however, do require extra modules:

=over

=item * L<DBI>: For the L<TUWF::DB> database handling methods.

=item * L<FCGI>: To run TUWF in a FastCGI environment.

=item * L<HTTP::Server::Simple>: To run the standalone HTTP server.

=item * L<JSON::XS>, L<Cpanel::JSON::XS> or L<JSON::PP>: If you need to handle
requests with a JSON body or wish to output JSON yourself.

=item * L<PerlIO::gzip>: For output compression.

=back

=item The generated response is buffered.

This allows you to change the response completely while generating an other
one, which is extremely useful if your code decides to throw an error while a
part of the response has already been generated. In such a case your visitor
will properly see your error page and not some messed up page that does not
make sense. Thanks to this buffering, you will also be able to set cookies and
send other headers B<after> generating the contents of the page.  And as an
added bonus, your pages will be compressed more efficiently when output
compression is enabled.

On the other hand, this means that you can't use TUWF for applications that
require Websockets or other forms of streaming dynamic content (e.g. a chat
application), and you may get into memory issues when sending large files.

=item Everything is UTF-8.

All TUWF functions (with some exceptions) will only accept and return Unicode
strings in Perls native encoding. All incoming data is assumed to be encoded in
UTF-8 and all outgoing data will be encoded in UTF-8. This is generally what
you want when developing new applications. If, for some very strange reason,
you want all I/O with the browser to be in anything other than UTF-8, you won't
be able to use TUWF. It B<is> possible to use external resources which use
other encodings, but you will have to C<decode()> that into Perls native
encoding before passing it to any TUWF function.

=item Designed for FastCGI environments.

TUWF is designed and optimized to be run a FastCGI environment, but it can also
be used for plain old CGI scripts or run as a standalone HTTP server.

Due to the singleton design of TUWF, you should avoid running TUWF websites in
persistent environments that allow multiple websites to share the same process,
such as mod_perl.

=item One (sub)domain is one website.

TUWF assumes that the website you are working on resides directly under a
(sub)domain. That is, the homepage of your website has a URI like
I<http://example.com/>, and all sub-pages are directly beneath it. (e.g.
I<http://example.com/about> would be your "about" page).

While it B<is> possible to run a TUWF website in a subdirectory (i.e. the
homepage of the site would be I<http://example.com/mysite/>), you will have to
prefix all HTML links and registered URIs with the name of the subdirectory.
This is neither productive, nor will it be fun when you wish to rename that
directory later on.

=item One website is one (sub)domain.

In the same way as the previous point, TUWF is not made to handle websites that
span multiple (sub)domains and have different behaviour for each one. It is
possible - quite simple, even - to have a different subdomain affect some
configuration parameter while keeping the structure and behaviour of the
website the same as for the other domains. An example of this could be a
language setting embedded in a subdomain: I<en.example.com> could show to the
English version of your site, while I<de.example.com> will have the German
translation.

Things will become messy as soon as you want (sub)domains to behave
differently. If you want I<forum.example.com> to host a forum and
I<wiki.example.com> to be a wiki, you will want to avoid programming both
subdomains in the same TUWF script. A common solution is to write a separate
script for each subdomain. It is still possible to share code among both sites
by means of modules.

=back



=head2 General structure of a TUWF website

A website written using TUWF consists of a single Perl script, optionally