Wille Apps
==========

`Wille Apps` are special web applications that run on Wille Server, and
can access services via a Wille Client. In this section, we will briefly
go through what is needed in order to create a new Wille App.

Wille Apps are written in Python using Wille's light-weight web application
framework. Various third-party Python libraries (such as template engines)
can be used together with Apps for easiest application development.

Creating an App
---------------

First, make sure your working directory is set to your apps folder::

	cd myproject/apps


The easiest way to start creating a new Wille App is to use `wille-admin`
script::

	wille-admin.py createapp myapp
	
For your convenience, the following files are created to the skeleton:

* `myapp.py` - Your application code file
* `willeapp.properties` - Description of your application for Wille 

The following application code is created for you as an app skeleton::

	class IndexPage:
		def GET(self, request):
			# (Insert your code here)
			return "Result view"

	urls = ( ("/", IndexPage),)

Once your app files have been created, you can already try it out in a Wille Server.

Writing Apps
------------

In order to test and try out Apps, Wille Server is required. Note that when
developing new Apps, it is generally good idea to enable reloader::

	wille-server.py -r

When enabled, Wille Server will automatically detect and reload changed Python
source code files, requiring fewer server restarts during application
development. Reloader works best when combined with debug mode::

	wille-server.py -dr
	
Note: reloader doesn't work with Jython.

Accessing Input Parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^

Input parameters (both GET and POST) can be accessed with `request.input()`.

For example::

	var1 = request.input('var1')`
	
In order to retrieve all parameters at once, simply call::

	vars = request.input()
	
Accessing Wille Client
^^^^^^^^^^^^^^^^^^^^^^
	
An instance of Wille Client can be retrieved with `request.wille_client()`.

For instance::

    client = request.wille_client()
    
With Wille client, services and keyring can be accessed. For more information,
see the section on `Wille Client`.

URL Mappings
^^^^^^^^^^^^

Multiple URLs maybe added to urls variable. Regular expressions (^re^) can
be used to match multiple URLs. In order to capture these expressions as
request variables, provide them with parenthesis ().

Processing POST Data
^^^^^^^^^^^^^^^^^^^^

If you wish to process input data sent via POST, make sure you encode them
as `multipart/form-data` when sending your form.

In HTML form this requires you to add enctype header to form element::

	<form enctype="multipart/form-data" method="post" />
		...
	</form> 

Returning with a Response
^^^^^^^^^^^^^^^^^^^^^^^^^

When returning from request handler methods (GET, POST) your return value
determines how the response from your application is generated.

A simple text response is generated by returning a text value (`str`, `unicode`)::

	return "Response"

By adding a second argument, you can add metadata fields to your response::

	return ("Response", {'Content-type': 'application/xml; charset=utf-8'})

Using profiles with Apps
^^^^^^^^^^^^^^^^^^^^^^^^

Similar to Wille Services, Apps can be also organised into groups by using
profiles. 

Profiles are specified per-app, by adding profile property into each App's
`willeapp.properties` file::

	profile=profile1,profile2

Profile names are common between services and apps, and can be therefore used
to group together various services and apps.