Icicle Web Application Framework,
Installation instructions and documentation.

This document was written at the time of Icicle 0.1.

[ X ] CONTENTS

1. Notes and requirements
2. Downloading and preparing Icicle
3. Understanding the component parts of Icicle
4. Configuring Icicle
4.1. Top-level configuration
4.2. Oceans
4.3. Subroutines
5. Adding content
6. Licence and copyright notices

[ 1 ] NOTES AND REQUIREMENTS

Icicle only requires a webserver running PHP 4 or later to run effectively. You'll also
need write access to the web folder, where you are installing Icicle. This can be just
about anywhere in your webroot.

Icicle is practically "platform independant", meaning that it will run on just about any
platform that is capable of running PHP.

[ 2 ] DOWNLOADING AND PREPARING ICICLE

So, you've got your webserver and PHP set up. Next thing is to install Icicle, which is
nice and easy.

Start by downloading the most recent version of Icicle from the Downloads page on
http://icicle.sourceforge.net/. You may wish to select a different archive type from the
default, depending on the tools available to you.

Open the archive, and extract the contents into a folder in your webroot. You may also
need to change the permissions on these files so that they can be read by your webserver.
However, usually you will not have to do this.

You should have the following file structure after extracting the archive:

index.php
default/
test.php
ocean.ice.ini
engine/
engine.php

To check your installation, simply enter the address to your installation in your web
browser. You should see a test page, confirming that the installation was successful.

[ 3 ] UNDERSTANDING THE COMPONENT PARTS OF ICICLE

The next thing that you need to do is to understand the component parts of Icicle. This
is important, since working with Icicle will be difficult if you don't!

The top level of configuration is the index.php file, which specifies some behavioural
options of your Icicle application. These will be explained in the next section of the
documentation, however, such things as default actions and permissions will be set in
this file.

The next level of configuration are called "oceans", which specify options for specific
"module" of the application, such as how to respond to specific actions, defining of
subroutines and defining where files for the ocean can be found.

[ 4 ] CONFIGURING ICICLE

Icicle is easy to configure and get running. The easiest way is to work in order,
starting from the index file and working down to the oceans and routines.

[ 4.1 ] TOP-LEVEL CONFIGURATION

By top-level configuration, we mean the index.php file that sets the most basic
options.

Most of the options are explained briefly in the file as it is, however, it is important
that the configuration in this file is correct or Icicle will not function properly.

If you want to change the name of "index.php" so that it suits the webserver (i.e.
default documents), then now is the time to do it. Rename "index.php" to whatever works
best, and then open it in your favourite text editor.

If you rename the file, then you should also change the following line in the file:

$application['settings']['thisfile'] = "index.php";

... so that it's value is the same as your new filename.

After doing this, simply check the rest of the options and adjust them to suit you.
Note that the identity variables are not all that important, and their values probably
won't ever impact anything.

Don't worry if you can't fill in the default values properly, you'll be able to soon!

- NOTE - It is very important that you do not mess up the permissions! If you understand
what they do, then change them. However, the default permissions are probably
best for most applications.

When you're done, save the file.

[ 4.2 ] OCEANS

Next thing to do is to work on your oceans! Like previously mentioned, the oceans are
basically the modules to your application. The model of your application entirely depends
on these oceans.

We have provided, with Icicle, a template ocean file, which can be found in the default/
folder. You can simply edit the default ocean, or copy it and create a new one! You can
have as many oceans as you like.

In each ocean folder, there should be an "ocean.ice.ini", which defines the behaviour
of each ocean, and then any files associated with it, for example, files to be included
on certain actions.

So, let's say that you're going to edit the default ocean. Navigate your way into the
default/ folder and open up ocean.ice.ini. You'll notice immediately, if you didn't from
the extension already, that the file is in the format of an INI file.

In this file, there are two sections, one called "main" and one called "test". The "main"
section is where the main behavioural settings for the ocean are set, for example, the
identity, the path of the ocean's files (relative to your index file), and the subroutines.

The subroutine "order" settings are lists, which should be seperated by ":" (colons).

However, there is capacity for more than one subroutine, so the following is important.

The "order" parameter defines what happens when the "entire" action is used, and by default,
this will be the default action for if no other action is specified. The default example
simply contains "test". In a more extensive structure, it may look like:

order="header:layout:index:footer"

The "order_name" parameters define what happen when the action called "name" is used, and
are in exactly the same format as the "order" parameter.

Underneath the subroutines, is another section. In the default example file, it is called
"test". It is called "test" for very good reason! One, this is how the subroutines address
the action. When you use "test" inside a subroutine, then it is running the action specified
in this section.

There are two settings inside this section, one called "method" and one that should be
called the same as the value of "method", i.e. method="include", include="test.php".

The "method" parameter specifies exactly what should be done. Currently the following options
are available:

- include: Includes a file from the ocean's path, i.e. "default/test.php"
- echo: Outputs a message specified by the "echo" parameter

If ever you want to add a new action, simply create a new section with the same layout, and
fill in the values.

The default example will method="include", as it's going to include the example file, and will
also include="test.php", because test.php is that example file.

[ 4.3 ] SUBROUTINES

Like said above, you can specify actions using routines. However, you can also specify a list
of routines to be run in given cases, like "entire", but more customised. These are called
subroutines, and are specified in the "main" section of the ocean file. They are specified
like this:

order_Subroutinename="action1:action2:action3...actionx"

... and are called by running action "!Subroutinename".

Here is another example:

order_info="header:pageinfo:footer"

And would be called by, say, navigating to "http://url/?spec=!info".

This makes it possible to make the links more user friendly, and to stop people dropping actions
that they don't want to see.

[ 5 ] ADDING CONTENT

Now you know how the oceans, routines and subroutines work, you can start adding content. It
is probably best to add this content into PHP files which are inside your ocean's directory.

If you want to add a HTML link easily to another action, you can use the generatelink() PHP
function, which works like this:

generatelink("destinationpage", "Text For Link");

For example:

generatelink("icicle.!about", "Read More");

- NOTE - It returns the value, it doesn't echo it.

[ 6 ] LICENSE AND COPYRIGHT NOTICES

This file, as with the rest of Icicle, is licensed under the PHP license (3.0), stating that
you can edit Icicle, and redistribute it (however, not for profit) providing that
the credit remains and to the original author either in source or binary form.

This product includes PHP, freely available from http://www.php.net/.