NAME

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

CREATE STATIC WEB PAGES: TEMPLATING

An important goal of this framework is the fast creation of maintainable static content. Therefore the template (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.

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:

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>

nav.template (define the navigation):

(Some links here)

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
	<$ / $>
<& / &>

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>

Template syntax

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

Fields

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

Definition: some.template

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

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" / &>

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

Lists

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

Definition: some.template

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

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<$ / $>
	<@ / @>
<& / &>

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>

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:

linklist.template:

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

The templates will be recursively processed.

Comments

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

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

CREATE DYNAMIC WEB PAGES: PLUGINS

General usage and configuration

Actually each <& foo &> tag calls a plugin (in this case the plugin foo). So <& template src="some.template" / &> calls the plugin 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 created.

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 implement your own application logic as a plugin.

"Low level" plugins

date

date: Displays the current date (in german notation). Mainly a simple demonstration plugin.

Usage:

<& date / &>

Result:

23. April 2006 - 10:45:16

env

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

formavalidator

env: 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>

if

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!

kill

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!

mail::obfuscator

perl: 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>

param

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

perl

perl: Embedding perl code in your pages/templates.

Usage:

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

Result:

foo

perlvar

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

sortlines

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

sql

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 ;)

svar

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

template: Konstrukt templating engine.

For a description see above or at the manual page of this plugin.

upcase

upcase: Convert all text into upper case. Also mainly a demonstration plugin with no particular use...

Usage:

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

Result:

UPPER CASE

"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 /sql directory of the source distribution. The default templates can be found in /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.

blog

blog: Konstrukt blogging engine. A simple blog plugin offering wiki markup, tagging and RSS-export.

Usage:

<& blog / &>

bookmarks

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 / &>

calendar

calendar: Management of private and public calendar items (for registered users). Including RSS-export

Usage:

<& calendar / &>

guestbook

guestbook: Konstrukt guestbook. Plain simple guestbook with multipage view and admin features.

Usage:

<& guestbook / &>

hitstats

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 -->

log

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"
   / &>

usermanagement

usermanagement: User management. Extensible with plugins. Current plugins are basic, level and personal, 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" / &>

wiki

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 syntax reference.

Usage:

<& wiki &>
= Headline

some text
<& / &>

<& wiki page="FooBar" / &>

AUTHOR

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

CREATE STATIC WEB PAGES: TEMPLATING

Basic template example

Template syntax

Fields

Lists

Nested templates

Comments

CREATE DYNAMIC WEB PAGES: PLUGINS

General usage and configuration

"Low level" plugins

date

env

formavalidator

if

kill

mail::obfuscator

param

perl

perlvar

sortlines

sql

svar

upcase

"High level" plugins

blog

bookmarks

calendar

guestbook

hitstats

log

usermanagement

wiki

AUTHOR

SEE ALSO

Module Install Instructions