http://bill.welliver.org//space/pike/Fins/InternalsGetting started with Fins and The inner workings of a Fins Application.<p class="paragraph"/> <h3 class="heading-1">Prerequisites<p class="paragraph"/></h3> Fins runs on Pike 7.8 or higher. Bonjour ready systems (such as MacOS X) will get you automatic announcement of your Fins apps. If you want to use the optional XSLT templating system, you'll need to install libxml, libxslt and the Public.Parser.XML2 module.<p class="paragraph"/> There are some prerequisite modules that you'll need; to avoid having to install them, you should check out the starter bundle at <a href="/space/pike/Fins/Windows">Windows</a>.<p class="paragraph"/> <h3 class="heading-1">Creating a new application<p class="paragraph"/></h3> To create a new web application, simply create the following file hierarchy, or use the <i class="ital">fins</i> tool to create one. You'll probably want to customize all of the files in it, based on your needs.<p class="paragraph"/> <div class="code"><pre><pre> pike -x fins create MyNewApp </pre></pre></div><p class="paragraph"/> Once the app is created, you should edit the config file in <i class="ital">MyNewApp/config/dev.cfg</i>, 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.<p class="paragraph"/> After you have customized the configuration file, you can start up the application by running the following command (the <i class="ital">MyNewApp</i> directory should be in your current directory):<p class="paragraph"/> <div class="code"><pre><pre> pike -x fins start MyNewApp </pre></pre></div><p class="paragraph"/> <i class="ital">or</i><p class="paragraph"/> <div class="code"><pre><pre> cd MyNewApp bin/start.sh </pre></pre></div><p class="paragraph"/> <h3 class="heading-1">Absolute Bare Minimum<p class="paragraph"/></h3> <div class="code"><pre><pre> APPDIR/ APPDIR/config APPDIR/config/dev.cfg APPDIR/classes/application.pike APPDIR/classes/controller.pike </pre></pre></div><p class="paragraph"/> (technically, the last file is optional, however the app won't really do much without it).<p class="paragraph"/> <h3 class="heading-1">Optional bare-minimum components<p class="paragraph"/></h3> <div class="code"><pre><pre> APPDIR/classes/view.pike APPDIR/classes/model.pike APPDIR/templates/* APPDIR/modules/* </pre></pre></div><p class="paragraph"/> 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.<p class="paragraph"/> <b class="bold">APPDIR/</b><p class="paragraph"/> This is the root of the application, and the full path to this directory is included as application->config->app_dir<p class="paragraph"/> <b class="bold">APPDIR/config</b><p class="paragraph"/> 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.<p class="paragraph"/> 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:<p class="paragraph"/> <b class="bold">&#91;model]</b> <- optional, not necessary if you do not have a model in your app.<p class="paragraph"/> key-value pairs (if the model section is present, these values are mandatory):<p class="paragraph"/> class: the name of the class that implements Fins.FinsModel and will load all of your custom datatypes. Normally, this is "model".<p class="paragraph"/> datasource: the sql url of the database underlying your model.<p class="paragraph"/> debug: if set to "1", all sql statements generated by the model will be written to stderr.<p class="paragraph"/> <b class="bold">&#91;controller]</b> <- required<p class="paragraph"/> key-value pairs (all mandatory):<p class="paragraph"/> class: the name of a class that implements Fins.FinsController.<p class="paragraph"/> <b class="bold">&#91;view]</b> <- optional, not necessary if you do not have a view in your app.<p class="paragraph"/> key-value pairs (all mandatory):<p class="paragraph"/> class: the name of a class that implements Fins.FinsView.<p class="paragraph"/> 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.<p class="paragraph"/> <b class="bold">APPDIR/classes</b><p class="paragraph"/> 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.<p class="paragraph"/> <b class="bold">APPDIR/modules</b><p class="paragraph"/> 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.<p class="paragraph"/> <b class="bold">APPDIR/static</b><p class="paragraph"/> 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.<p class="paragraph"/> <b class="bold">APPDIR/templates</b><p class="paragraph"/> 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).<p class="paragraph"/> <h3 class="heading-1">Application startup process<p class="paragraph"/></h3> Note that Fins makes use of Pike's object orientation features, so that most application startup and operations behavior can be overridden by implimenting replacement classes. Examples include XMLRPCController and DocController. Every application inherits Fins.Application, and by default, basic application setup is performed so that only a few functions need to be provided. <ol> <li>classes and modules are added to the program and module paths, respectively.</li> <li>the configuration file is parsed and loaded.</li> <li>the file classes/application.pike is compiled and instantiated. the configuration is passed to the constructor. see section 2, Fins.Application initialization.</li> <li>any listeners are started up by the respective servicing application (fin_serve, caudium module, etc).</li> </ol>1 Fins.Application initialization <ol> <li>application->config is set with the configuration file</li> <li>load_cache() is called, which instantiates a copy of the Fins.Cache</li> <li>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.</li> <li>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.</li> <li>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.</li> <li>start() is called.</li> </ol>1 Fins.FinsModel initialization<p class="paragraph"/> inherits Fins.FinsBase, which provides app, cache, view, config and model as local variables. <ol> <li>constructor is called with the application object passed as an argument.</li> <li>load_model() is called within the local class.</li> <li>an instance of Sql.Sql is created using the SQL datasource url provided in the model section of the config file.</li> <li>an instance of Fins.Model.DataModelContext is created</li> <li>the repository, cache, app and sql connection are populated in the DataModelContext object</li> <li>the DMC is initialize()ed, which configures the model rdbms abstraction code for the particular database personality being used.</li> <li>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 <a href="/space/pike/Fins/Developer/Model">Model</a>.</li> </ol>1 Fins.FinsView initialization<p class="paragraph"/> inherits Fins.FinsBase, which provides app, cache, view, config and model as local variables.<p class="paragraph"/> default_template, default_data and default_context are all pre-populated with classes from Fins.Template, making Fins.Template.Simple the default template type. <ol> <li>constructor is called with the application object passed as an argument.</li> <li>load_macros() is called, which registers all functions that start with simple_macro_ as simple template macros.</li> </ol>1 Fins.FinsController initialization<p class="paragraph"/> inherits Fins.FinsBase, which provides app, cache, view, config and model as local variables.<p class="paragraph"/> 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. <ol> <li>constructor is called with the application application object as an argument.</li> <li>start() is called in the controller.</li> </ol>1 How do my requests get directed?<p class="paragraph"/> <b class="bold">Event Methods</b><p class="paragraph"/> 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.<p class="paragraph"/> <b class="bold">Event Method Example:</b><p class="paragraph"/> 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.<p class="paragraph"/> Note that your index function can't receive "arguments", as they could potentially mask other methods.<p class="paragraph"/> <b class="bold">Sub-controllers</b><p class="paragraph"/> If you have a controller class present within the main controller, it will also be available as a subfolder on your application url.<p class="paragraph"/> <b class="bold">Sub-controller Example:</b><p class="paragraph"/> 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.<p class="paragraph"/> 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.<p class="paragraph"/> <h3 class="heading-1">Starting a Fins application<p class="paragraph"/></h3> Right now, the only way to run a Fins application is with the built in webserver (not that it's that bad). To start up your application, make sure that <i class="ital">Fins/lib</i> is in your pike module path and then run the fins start program:<p class="paragraph"/> <div class="code"><pre><pre> pike -x fins start &#91;-p &#91;port]|--hilfe] &#91;appname &#91;config]] </pre></pre></div><p class="paragraph"/> 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).<p class="paragraph"/> <h3 class="heading-1">Interactive Fins<p class="paragraph"/></h3> fin_serve also supports an interactive "hilfe" mode. This is just like regular hilfe, only your application is loaded and initialized, so that you can call functions within your application, such as the model, interactively.<p class="paragraph"/> you can access your application through the "application" constant. Fins 0.9.7http://blogs.law.harvard.edu/tech/rss