Internals

Prerequisites

There are some prerequisite modules that you'll need; to avoid having to install them, you should check out the starter bundle at Windows.

Creating a new application

pike -x fins create MyNewApp

Once the app is created, you should edit the config file in MyNewApp/config/dev.cfg, to either define a model datasource or comment the entire "model" section out. If you don't do one of these, Fins will bail out because it won't be able to load the model.

After you have customized the configuration file, you can start up the application by running the following command (the MyNewApp directory should be in your current directory):

pike -x fins start MyNewApp

or

cd MyNewApp
bin/start.sh

Absolute Bare Minimum

APPDIR/
APPDIR/config
APPDIR/config/dev.cfg
APPDIR/classes/application.pike
APPDIR/classes/controller.pike 

(technically, the last file is optional, however the app won't really do much without it).

Optional bare-minimum components

APPDIR/classes/view.pike
APPDIR/classes/model.pike
APPDIR/templates/*
APPDIR/modules/*

A Fins application is stored with an application directory dedicated specifically to that application. Typically the application directory (which will call APPDIR) is named for the application, though this is not a requirement.

APPDIR/

This is the root of the application, and the full path to this directory is included as application->config->app_dir

APPDIR/config

This directory holds any necessary configuration files; at a minimum, a fins application consists of a config file and an application class. The files are named configname.cfg, where configname is the string passed as the configuration name argument to fin_serve. If no configuration name is supplied, it is assumed to be "dev". The format of the configuration file is similar to windows style "ini" files, which is broken into sections, with one or more values in each section.

Your application may use the configuration file to store its own data using the application->config object. Fins has a few settings that are required:

[model] <- optional, not necessary if you do not have a model in your app.

key-value pairs (if the model section is present, these values are mandatory):

class: the name of the class that implements Fins.FinsModel and will load all of your custom datatypes. Normally, this is "model".

datasource: the sql url of the database underlying your model.

debug: if set to "1", all sql statements generated by the model will be written to stderr.

[controller] <- required

key-value pairs (all mandatory):

class: the name of a class that implements Fins.FinsController.

[view] <- optional, not necessary if you do not have a view in your app.

key-value pairs (all mandatory):

class: the name of a class that implements Fins.FinsView.

reload: if set to "1", all first level templates will be checked for changes on each request, and reloaded if necessary. Currently this does not include files included using include directives.

APPDIR/classes

This directory should contain the pike classes you application requires, such as the application, model, view, and any controllers. Normally model object definitions would be stored in a module within the modules directory. This directory is placed in the Pike program path, so you can do things like (program)"myclass" and have the file myclass.pike compiled into a program.

APPDIR/modules

This directory can be used to store any application specific modules. A good example of classes and modules to place in this directory is model related object types.

APPDIR/static

Files contained within this directory are made automatically available on the path /static/. Additionally, a file "favicon.ico" placed in this directory will be automatically short-circuited from /favicon.ico. Note that content in this directory is not subject to any access restrictions, so sensitive content should be placed under the control of a secured controller. Also, directory listings are not generated from this directory; you must request a file directly.

APPDIR/templates

Templates used by the Fins.Template framework are stored within this directory by default (though custom templates can retrieve their source from any location, in theory).

Application startup process

1. classes and modules are added to the program and module paths, respectively.
2. the configuration file is parsed and loaded.
3. the file classes/application.pike is compiled and instantiated. the configuration is passed to the constructor. see section 2, Fins.Application initialization.
4. any listeners are started up by the respective servicing application (fin_serve, caudium module, etc).

1. application->config is set with the configuration file
2. load_cache() is called, which instantiates a copy of the Fins.Cache
3. load_model() is called, which instantiates the class specified in the model section of the config file (if it exists). See Fins.FinsModel initialization for details.
4. load_view() is called, which instantiates the class specified in the model section of the config file (if it exists). See Fins.FinsView initialization for details.
5. load_controller() is called, which instantiates the class specified in the controller section of the config file (if it exists). See Fins.FinsView initialization for details.
6. start() is called.

inherits Fins.FinsBase, which provides app, cache, view, config and model as local variables.

1. constructor is called with the application object passed as an argument.
2. load_model() is called within the local class.
3. an instance of Sql.Sql is created using the SQL datasource url provided in the model section of the config file.
4. an instance of Fins.Model.DataModelContext is created
5. the repository, cache, app and sql connection are populated in the DataModelContext object
6. the DMC is initialize()ed, which configures the model rdbms abstraction code for the particular database personality being used.
7. the method register_types() is called, which is something you should populate with repository->add_object_type() calls, unless you're using auto-model registration, which is described more fully at Model.

inherits Fins.FinsBase, which provides app, cache, view, config and model as local variables.

default_template, default_data and default_context are all pre-populated with classes from Fins.Template, making Fins.Template.Simple the default template type.

1. constructor is called with the application object passed as an argument.
2. load_macros() is called, which registers all functions that start with simple_macro_ as simple template macros.

inherits Fins.FinsBase, which provides app, cache, view, config and model as local variables.

you should add approppriate event handlers and sub controllers as necessary. normally you would place the instantiation code for any sub-controllers within start(), and pass the app object to the constructor. the sub-controllers will be "mounted" in the virtual filesystem at a subdirectory corresponding to the name of the variable that they are assigned to within the controller.

1. constructor is called with the application application object as an argument.
2. start() is called in the controller.

Event Methods

Any public functions present in your controller will be available as paths on your url; if no path is provided, the index method will be run. The base FinsController class expects event methods that take a Fins.Request object, a Fins.Response object and an argument of type "mixed ..." which will contain any arguments.

Event Method Example:

If you have a method called "boo" in your main controller, it will be available as "/boo". Any additional path past that will be sent as arguments to the method.

Note that your index function can't receive "arguments", as they could potentially mask other methods.

Sub-controllers

If you have a controller class present within the main controller, it will also be available as a subfolder on your application url.

Sub-controller Example:

For example, if you have a controller class called "gazonk" in your main controller, the sub-controller will be available as "/gazonk/". note that if you just choose "/gazonk", you'll automatically be redirected so that you're at the "index" level of that controller.

Also, your controller should instantiate any sub-controllers from the start() function within the parent controller. Always pass the app object to the constructor of your controllers.

Starting a Fins application

pike -x fins start [-p [port]|--hilfe] [appname [config]] 

where port is the port number your Fins application should run on, which defaults to port 8080. appname is the name of the app you'd like to run. it defaults to "default". config is the name of a configuration you'd like to use, which is loaded from appname/config/config.cfg. this value defaults to dev, which loads config/dev.cfg. if you have a Bonjour subsystem and Pike 7.7, you'll get automatic bookmarks in your Bonjour aware applications (such as Safari).

Interactive Fins

you can access your application through the "application" constant.

Not categorized | RSS Feed | BackLinks