=head1 NAME

Konstrukt::Doc::Usage - Usage to create web sites

=head1 CREATE STATIC WEB PAGES: TEMPLATING

An important goal of this framework is the fast creation of maintainable static
content. Therefore the template (L<Konstrukt::Plugin::template>) plugin was developed.

You are enouraged to encapsulate your web site components that are used in several
places in templates, which then can be reused to avoid redundancy.
A website usually consists of several components, that are used in many pages
(layout, navigation, frames, tables, ...).

Each template consists of static text and variable parts, that can be
substituted on the usage of the template.

=head2 Basic template example

The simplest example for this is the encapsulation of the layout. The layout
will probably be the same across all your pages, so reuse of the layout instead
of copy and paste is a good idea. With Konstrukt you will do it like that:

B<layout.template> (define the layout and the variable fields):

	<html>
	<head><title><+$ title +$>Default Title<+$ / $+></title></head>
	<body>
		<table>
			<tr><td>
				Navigation: <+$ nav $+>None<+$ / $+>
			</tr></td>
			<tr><td>
				Content: <+$ content $+>No content<+$ / $+>
			</tr></td>
		</table>
	</body>
	</html>

B<nav.template> (define the navigation):

	(Some links here)

B<index.html> (use the layout and replace the variable fields with custom content):

	<& template src=“layout.template“ &>
		<$ title $>My web page<$ / $>
		<$ nav $>
			<& template src=“nav.template“ / &>
		<$ / $>
		<$ content $>
			Some great content
		<$ / $>
	<& / &>	

B<result> (some whitespaces may vary...):

	<html>
	<head><title>My web page</title></head>
	<body>
		<table>
			<tr><td>
				Navigation: (Some links here)
			</tr></td>
			<tr><td>
				Content: Some great content
			</tr></td>
		</table>
	</body>
	</html>

=head2 Template syntax

Basically you define some slots in your template using C<<+$ field_name $+>> and
C<<+@ list_name @+>> tags and fill them using a C<<& template &>> tag containing
C<<$ field_name $>value<$ / $>> and C<<@ list_name @>list_fields...<@ / @>> tags
that define the content to fill the slots.

See also L<Konstrukt::Plugin::template>.

=head3 Fields

Templates can contain single variable B<fields>, which can be substituted on the
usage of the template and may have a default value.

B<Definition>: some.template

	some text here
	this <+$ field_name $+>should be<+$ / $> replaced.
	some text there
	a field without a default value: <+$ no_default / $+>
	end

B<Usage>:
	
	here we will use the template:
	<& template src="some.template" &>
		<$ field_name $>has been<$ / $>
		<$ no_default $>foo<$ / $>
	<& / &>
	you can also define the field values with a tag attribute:
	<& template src="some.template" no_default="bar" / &>

B<Result>: (whitespaces may vary...)

	here we will use the template:
	
	some text here
	this has been replaced.
	some text there
	a field without a default value: foo
	end
	
	you can also define the field values with a tag attribute:
	
	some text here
	this should be replaced.
	some text there
	a field without a default value: bar
	end

=head3 Lists

You may define B<lists> to generate repetitive content inside a template.

B<Definition>: some.template

	<table>
		<tr><th><+$ head1 / $+></th><th><+$ head2 / $+></th></tr>
		<+@ items @+>
		<tr><td><+$ col1 / $+></td><td><+$ col2 / $+></td></tr>
		<+@ / @+>
	</table>

B<Usage>:

	<& template src="some.template" head1="Name" head2="Telephone number" &>
		<@ items @>
			<$ col1 $>foo<$ / $><$ col2 $>555-123456<$ / $>
			<$ col1 $>bar<$ / $><$ col2 $>555-654321<$ / $>
			<$ col1 $>baz<$ / $><$ col2 $>555-471123<$ / $>
		<@ / @>
	<& / &>

B<Result>: (whitespaces may vary...)

	<table>
		<tr><th>Name</th><th>Telephone number</th></tr>
		<tr><td>foo</td><td>555-123456</td></tr>
		<tr><td>bar</td><td>555-654321</td></tr>
		<tr><td>baz</td><td>555-471123</td></tr>
	</table>

=head2 Nested templates

Templates can (as any Konstrukt tag) be nested:

	<& template src="layout.template" title="perl links" &>
		<$ content $>
			Some perl links:
			<& template src="linklist.template" &>
				<@ links @>
					<$ target      $>http://www.cpan.org/<$ / $>
					<$ description $>Comprehensive Perl Archive Network<$ / $>
					
					<$ target      $>http://dev.perl.org/perl6/<$ / $>
					<$ description $>Perl 6 Development Page<$ / $>
					
					<$ target      $>http://www.perlfoundation.org/<$ / $>
					<$ description $>The Perl Foundation<$ / $>
				<@ / @>
			<& / &>
		<$ / $>
	<& / &>

Each used template can in turn contain template (and other special Konstrukt) tags:

B<linklist.template>:

	<ul>
	<+@ links @+>
		<li><a href="<+$ target / $+>"><+$ description $+>(No Description)<+$ / $+></a></li>
	<+@ / @+>
	<& template src="linkdisclaimer.template" / &>

The templates will be recursively processed.

=head2 Comments

Comments are written as plain HTML comments. Konstrukt tags inside comments will
be ignored:

	<!-- <& this_tag will="be ignored" / &> -->

=head1 CREATE DYNAMIC WEB PAGES: PLUGINS

=head2 General usage and configuration

Actually each C<<& foo &>> tag calls a plugin (in this case the plugin C<foo>).
So C<<& template src="some.template" / &>> calls the plugin C<template> and
passes the tag attributes and content to this plugin, which in turn returns
its result, which will replace the tag.

There are several plugins available (probably not all documented here - 
take a look at the Plugin directory) and own plugins can be
L<created|Konstrukt::Doc::PluginDevelopment>.

I will only give a brief overview of some of the existing plugins.
For more detatiled information about the plugins and their configuration take
a look at the manual pages of each plugin.

I divide this section into "Low Level" plugins, which perform rather basic tasks
and will be used to add some logic to the presentation/templates, and "High level"
plugins, which represent complex applications that can be easily and
seamlessly integrated into your web site.

If the existing plugins don't offer the funktionality you need/the application
you want to create, you usually would L<implement|Konstrukt::Doc::PluginDevelopment>
your own application logic as a plugin.

=head2 "Low level" plugins

=head3 date

L<date|Konstrukt::Plugin::date>: Displays the current date (in german notation).
Mainly a simple demonstration plugin.
	
Usage:

	<& date / &>

Result:

	23. April 2006 - 10:45:16

=head3 env

L<env|Konstrukt::Plugin::env>: Access to the environment variables.
	
Usage:

	<!-- set value -->
	<& env var="var_name" set="value"/ &>

	<!-- print out value -->
	<& env var="var_name" / &>

Result:

	<!-- set value -->
	
	<!-- print out value -->
	value

=head3 formavalidator

L<env|Konstrukt::Plugin::formvalidator>: HTML form validator.
	
Usage:

	<!-- add form validation code to your page -->
	<& formvalidator action="print_js_code"
	   form="/some/dialogue.form"
	   script="/formvalidator/formvalidator.js"
	   strings="/formvalidator/formvalidator_strings.js" / &> 

Result:

	<!-- add form validation code to your page -->
	<script type="text/javascript" src="/formvalidator/formvalidator.js"></script>
	<script type="text/javascript" src="/formvalidator/formvalidator_strings.js"></script>
	<script type="text/javascript">
		<!-- JS definitions of your form -->
	</script>

=head3 if

L<if|Konstrukt::Plugin::if>: Conditional blocks.
	
Usage:

	<!-- will put out "elsif1" -->
	<& if condition="0" &>
		<$ then $>then<$ / $>
		<$ elsif condition="1" $>elsif1<$ / $>
		<$ elsif condition="1" $>elsif2<$ / $>
		<$ else $>else<$ / $>
	<& / &>

	<!-- shortcut, when only using "then" and no elsif or else -->
	<!-- will put out "The condition is true!" -->
	<& if condition="2 > 1" &>
		The condition is true!
	<& / &>

Result:

	<!-- will put out "elsif1" -->
	elsif1
	
	<!-- shortcut, when only using "then" and no elsif or else -->
	<!-- will put out "The condition is true!" -->
		The condition is true!

=head3 kill

L<kill|Konstrukt::Plugin::kill>: Remove content from a website. May be used
to create "invisible" comments.
	
Usage:

	We will never <& kill &>agree that we always <& / &>do censoring!

Result:

	We will never do censoring!

=head3 mail::obfuscator

L<perl|Konstrukt::Plugin::mail::obfuscator>: Hide email addresses from SPAM harvesters.
	
Usage:

	<& mail::obfucator name="John Doe" mail="john@doe.com" / &>

Result:

	<!-- used to decrypt the email address -->
	<script type="text/javascript">
	<!--
	function xor_enc(text, key) {
		var result = '';
		for(i = 0; i < text.length; i++)
			result += String.fromCharCode(key.charCodeAt(i % key.length) ^ text.charCodeAt(i));
		return result;
	}
	// -->
	</script>
	
	<script type="text/javascript">
	<!--
	document.write(xor_enc(unescape('encrypted link'), 'key to decrypt'));
	-->
	</script>
	<noscript>
	John Doe: john<img src="/gfx/layout/s.gif" alt="&gt; add @-character here &lt;" />doe.com
	</noscript>

=head3 param

L<param|Konstrukt::Plugin::param>: Displays the value of a specified HTTP parameter.
	
Usage:

	<& param key="param_name" &>default value if not defined<& / &>

Result: (when invoked like: /page.html?param_name=foo)

	foo

=head3 perl

L<perl|Konstrukt::Plugin::perl>: Embedding perl code in your pages/templates.
	
Usage:

	<& perl &>print "foo"<& / &>

Result:

	foo

=head3 perlvar

L<perlvar|Konstrukt::Plugin::perlvar>: Access to Perl variables
	
Usage:

	<!-- set value -->
	<& perlvar var="$Foo::Bar" set="baz"/ &>

	<!-- print out value -->
	<& perlvar var="$Foo::Bar" / &>

Result:

	<!-- set value -->

	<!-- print out value -->
	baz

=head3 sortlines

L<sortlines|Konstrukt::Plugin::sortlines>: Sort all lines of contained plaintext
	
Usage:

	<& sortlines &>
		some
		<!-- comments -->
		unsorted
		lines
		<!-- will be put -->
		here
		<!-- on top of the list -->
	<& / &>

Result:

	<!-- comments -->
	<!-- will be put -->
	<!-- on top of the list -->
	here
	lines
	some
	unsorted

=head3 sql

L<sql|Konstrukt::Plugin::sql>: Perform SQL queries. Usually combined with
templates to display the results.
	
Usage:

	<!-- put query results into a template using the dbi default settings defined in your konstrukt.settings
	     see the Konstrukt::DBI documentation for the configuration of the default settings -->
	<& sql query="SELECT * FROM some_table" template="list_layout.template" / &>
	<!-- you must have a list <+@ sql @+> in your template file to which the results are passed.
	     the fields inside the list should be named like the columns in your query. -->

	<!-- but you may also define the listname yourself -->
	<& sql query="SELECT * FROM some_table" template="list_layout.template" list="some_list_name" / &>
	<!-- then you should have a list <+@ some_list_name @+> in your template file. -->
	
	<!-- using custom connection settings -->
	<& sql query="..." template="..." source="dbi_dsn" user="username" pass="password" / &>
	
	<!-- some query that won't return result data -->
	<& sql query="DELETE FROM some_table WHERE id=23" / &>

Result:

	depends ;)

=head3 svar

L<svar|Konstrukt::Plugin::svar>: Access to session values.
	
Usage:

	<!-- set value -->
	<& svar var="var_name" set="value "/ &>
	
	<!-- print out value -->
	<& svar var="var_name" / &>

Result:

	<!-- set value -->
	
	<!-- print out value -->
	value

L<template|Konstrukt::Plugin::template>: Konstrukt templating engine.

For a description see L<above|/CREATE STATIC WEB PAGES: TEMPLATING> or at the manual page of this plugin.

=head3 upcase

L<upcase|Konstrukt::Plugin::upcase>: Convert all text into upper case. Also
mainly a demonstration plugin with no particular use...
	
Usage:

	<& upcase &>upper case<& / &>

Result:

	UPPER CASE

=head2 "High level" plugins

Almost any "high level" plugin currently uses a (MySQL) DBI backend and some
templates for the output. So you have to create the tables and copy the templates
to your document directory (and modify them).

The table definitions are supplied as sql-scripts in the C</sql> directory of
the source distribution. The default templates can be found in C</templates>.

You can adjust the path to the templates and the database settings as described
in the plugin and backend module documentation.

This is just a very short introduction into every described plugin and you are
encouraged to take a closer look at the specific documentation for each plugin,
which is linked for each plugin.

=head3 blog

L<blog|Konstrukt::Plugin::blog>: Konstrukt blogging engine. A simple blog plugin
offering wiki markup, tagging and RSS-export.

Usage:

	<& blog / &>
	
=head3 bookmarks

L<bookmarks|Konstrukt::Plugin::bookmarks>: Bookmark management (for registered users).
Bookmarks can be organized by registered users in a folder structure. Private and
public bookmarks. Public ones can be viewed by every visitor.

Usage:

	<& bookmarks / &>
	
=head3 calendar

L<calendar|Konstrukt::Plugin::calendar>: Management of private and public calendar
items (for registered users). Including RSS-export

Usage:

	<& calendar / &>
	
=head3 guestbook

L<guestbook|Konstrukt::Plugin::guestbook>: Konstrukt guestbook. Plain simple
guestbook with multipage view and admin features.

Usage:

	<& guestbook / &>

=head3 hitstats

L<hitstats|Konstrukt::Plugin::hitstats>: Hit statistics plugin. Collect and
display/sort/order hit statistics.

Usage:

	<!-- count hit. use the current filename as title -->
	<& hitstats / &>
	
	<!-- display the overall top sites -->
	<& hitstats show="all" / &>
	
	<!-- many more options. see plugin doc -->

=head3 log

L<log|Konstrukt::Plugin::log>: Konstrukt logging facilities. Log important
web site events like user registration.

Usage:

	<!-- add a log entry.
	     key1-5 are optional. -->
	<& log
   	action="put" 
      type="login"
      description="user 'foo' logged in"
      key1="some additional info"
      key2="some additional info"
      key3="some additional info"
      key4="some additional info"
      key5="some additional info"
   / &>
   
   <!-- display log entries -->
   <& log
      type="log type"
      keycount="number of additional keys to display"
      orderby="column"
      limit="42"
   / &>

=head3 usermanagement

L<usermanagement|Konstrukt::Plugin::usermanagement>: User management. Extensible with plugins.
Current plugins are
L<basic|Konstrukt::Plugin::usermanagement::basic>,
L<level|Konstrukt::Plugin::usermanagement::level> and
L<personal|Konstrukt::Plugin::usermanagement::parsonal>, which provide basic
user management (register, login, ...), user level management (for access
control) and personal data (name, email, ...).

Usage:

	<!-- example for a page for basic user management -->
	<& usermanagement::basic show="login, register, sendpass, changepass" / &>
	
	<!-- user level management -->
	<!-- Show the level of the current user. May be useful in conditional templates. -->
	<& usermanagement::level show="level" / &>
	<!-- Show a list of all users and forms to change each user's level -->
	<& usermanagement::level show="users" / &>
	
	<!-- personal info/management -->
	<& usermanagement plugin="personal" / &>

=head3 wiki

L<wiki|Konstrukt::Plugin::wiki>: Plugin to convert wiki markup and manage wiki content.
Extensible with plugins for markup and content. Currently supports articles,
images and files as content.
You may also be interested in the L<syntax reference|Konstrukt::Plugin::wiki::syntax>.

Usage:

	<& wiki &>
	= Headline
	
	some text
	<& / &>
	
	<& wiki page="FooBar" / &>

=head1 AUTHOR 

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved. 

This document is free software.
It is distributed under the same terms as Perl itself.

=head1 SEE ALSO

L<Konstrukt::Doc>, L<Konstrukt::Plugin::template>

=cut
