Jigsaw Web Application Fwk - Home

Home

The Jigsaw application framework allows developers to write dynamic web application in the Falcon programming language without having to build the application from scratch. The framework provides developers with readymade solution for common requirements, such as the ability to have user sessions, ability to partition code into business logic and display logic (a.k.a models and templates) , database abstraction layer, user error handling, among others. The framework allows it’s users to create, install and run different applications, all which share the same framework.

Directory and File Structure

assets/ -- This directory contains javascript files, images and other client media files that can be used by any application. Currently, only the JQuery main file lives there.
core/ -- This directory contains the engine of the framework. The classes and structures in this directory are responsible to driving the common logic of the framework, such as selecting the application to run, start/stopping the session, initializing the database among others.
core/support/ -- The classes in this directory are automatically included in every page request and provide the applications with commonly used utilities so they don’t have to be re-implemented.
install/ -- This directory contains files necessary while installing the framework itself.
jigs/ -- Every application written for the Jigsaw Application Framework must be installed within a subdirectory of the ‘jigs’ directory. Each application must have the following structure:
- actions/ -- Contains application “action” classes.
- assets/ -- Contains client-side files, such as Javascript files, images, flash files, css, etc.
- controllers/ -- Contains application “controllers” classes.
- i18n/ -- Internationalization (i18n) support files.
- models/ -- Classes which provide common application-specific algorithms and structures.
- templates/ -- Display templates.
- views/ -- Contains application “view” classes.
library/ -- This directory contains common classes and structures that can be used by both the framework and the applications running on top of the framework.
volatile/ -- This directory is used by the framework to write temporary files. It must be writable by the web server.
config.fal -- This file is used to configure various aspects of the framework.
index.ftd -- Every request made passed through the index. This is the driver script of the framework.

Anatomy of a Jigsaw HTTP request.

Because the framework allows different kinds of applications to run, the applications need to follow a certain structure.

Every page than can be run in the Jigsaw framework is a dynamic page. For that reason, one “page” that is shown to the user actually needs 4 different files: A controller, an action, a view and a template.

Controllers

A controller is used to define common logic shared among many pages of the application. For instance, an application may have a “public” section and a “user’s section”. 2 different controllers can be used so that logic which must be run for the public pages is stuff into one controller, and logic which must be ran for the private area is handled by the other controller. For instance, the user’s area may have checks to make sure the user is signed in, and redirect to a page if the user is not signed in.

If the application is very simple, it may only need one controller for the whole application. If the application is really, really simple, it may even get away with using an empty controller, which does nothing. Every page request needs to have an active controller, though, even if empty – therefore every application must have at least one controller.

Actions

When a user requests a page, they actually request an “action”, which is a signal to the framework to provide the user with some resource. The resource can be anything possible within the world wide web: an html page, a redirect to another page, an image, a sound, a text file, etc.

Actions can be thought of as the directors of requests. Actions are in charge of setting the controller to be used by the request, validating if the request meets the requirements of that specific page, and setting the “view” to use to gather data for the request.

Views

Views are the classes used to actually gather to data to be used on the page. They also select which template to use to display the gathered data.

The reason for separating the controller selection and page variable validation from the gathering of data (actions vs views) is so that different actions can use the same view. For instance, if there is a view which gathers information to be shown on the login screens, that view can be used by my actions. For instance, if we have a page used to show the user mailing address, we would need for the user to be logged in. If the user visits the address display page, and the action notices that the user is not logged in, the action and chose to display the user-login view, instead of the user-mailing-address view. This helps cut down on code duplication because the login page is only coded once, but can be shown to the user regardless of what resource the user is trying to see.

Templates

Templates are where the HTML is actually written. By separating how the data is presented to the user from how the data is gathered, we can cut down on code duplication. For instance, an infinite number HTML templates can use the same user-mailing-address gathering code.

Installing Jigsaw

Place the jigsaw directory at the root of your public HTML folder.
Open the file config.fal and edit the variables under the “config” enumeration to suit your particular configuration. The variables under the “Framework” enumeration shouldn’t be changed.
Create a database, preferably called “Jigsaw” (notice the upper case) to be used to create the tables needed by the framework. If you op for using a different database name, or if you would like to use an existing database, make sure to update the Config.dbDB variable within config.fal to the correct name.
Run the SQL located under the “install” directory on the database chosen in step 3
Visiting www.yourdomain.com/jigsaw/index.ftd should display a page.

Tutorial: Hello World

This section is a mini tutorial on writing an application that shows a page with the words “Hello, World.” We will call our application “chunky”.

Begin by creating a directory called “chunky” within the <install-path>/jigs directory.

Then, create the following directories within the “chunky” directory:

	actions/
	assets/
	controllers/
	i18n/
	models/
	templates/
	views/

As the next step, copy the “DefaultController.fal” file located in the “jigs/default/controllers/” directory to “jigs/chunky/controllers/” directory. This file will be the controller we will use for all our requests. Because the file is named “DefaultController.fal”, it will be automatically selected as the controller to be used by any action that doesn’t specifically set a controller.

Then, copy the “DefaultAction.fal” file located in the “jigs/default/actions/” directory to “jigs/chunky/actions/” directory. This file represents the action for the index page (the index page is the default action). Whenever we DO NOT specify an action to run via the URL, this is the action that will be selected.

Then, copy the “Shell.ftd” file located in the “jigs/default/templates/” directory to “jigs/chunky/templates/” directory.

Copy the “DefaultView.fal” file located in the “jigs/default/views/” directory to “jigs/chunky/views/” directory. Open this file in an editor and remove any code in the process() function, but leave the function there. The process() function is now an empty function. Remove any code in the init function, and add the following code:

   self.setTemplate(‘Default’)

Because this view is named “DefaultView.fal”, when no view is specified in an action, this is the view that is run.

Finally, Create a file named “Default.ftd” in “jigs/chunky/templates/” directory and add the following code.

<? import X ?>
<html>
<head><title>Hello World</title></head>
</title>
<body>
Hello, World! <br />
</body>
</html>

Now you can visit the index page of your jigsaw installation in your browser: http://www.yourdomain.com/jigsaw/index.ftd?jig=chunky You should see you a page with the words “Hello, World!”

User ID:
Password:

Jigsaw Web Application Fwk - Home

Go To Page...