Documentation

Welcome to the documentation of the dotspersite framework.

Please notify me of errors and problems with the documentation.

1. Introduction

Dotspersite is a web application framework written in PHP5 code.
It's task is to do the routine work of a webdeveloper, the work he repeatedly does when creating a web application.
Sometimes this is only creating a Front Controller, sometimes it's a little more. We did not want to limit you in this concern, thus we created three main parts, which can be used independently.
We have a controller which receives user requests, we have a module handler allowing you to separate programm logic from the controller and the view and we have a simple API for accessing your libraries.
Read on to find information about these parts and how you can use them for building your application.

2. Requirements

The listed requirements apply to a basic installation of dotspersite.
Please note, that some of your classes or modules may require further settings.

3. Getting started

To start developing you simply need to download the dotspersite package and unpack it to the folder you are creating your application in.
In the example you see below, we unpacked the files to the directory /framework.

While dotspersite allows detailed configuration, very few settings are important to you.
You should set the dps_config::$BASEURL value to your host. If you want to install dotspersite in a subdirectory, add this to the baseurl value aswell.

So if your host is example.com, set it to:
dps_config::$BASEURL = 'http://example.com';

If you put dotspersite into the directory /framework, use this setting:
dps_config::$BASEURL = 'http://example.com/framework';

Please note, that there is no trailing slash in any of the URL (or PATH) settings.

That's it. You don't need to make any further settings for running dotspersite.
For additional options, look into the file /system/base/config/dps_config.base.php.
Default settings are done there (do not change), and you can see which variables are available.

4. The Controller concept

Dotspersite uses a Front Controller. This means, that all incoming requests are received in one file.
You will know this from URLs like index.php?page=foobar and might have developed in a similar way before.

The approach dotspersite takes to handle the incoming requests is similar.
We defaultly use mod_rewrite, but you can call it the old fashioned way, too.

In dotspersite, a request consists of two optional parts, while none is required (defaults used).
http://example.com/framework/example/ will call the default 'index' action of the controller 'example'.
http://example.com/framework/another/test will call the 'test' action of the controller 'another'.

What is actually done internally, is listed below:

In case anything fails (e.g. class does not exist, method is not callable) , a simple error message is shown to the user.
If you tried to call the example controller, you will have experienced that already. Move on to the next step, to see how you can create this controller.

4.1. Create your own controller

Creating your own controller is pretty simple.
In this example, we are going to create the controller we tried to call one step before.
Move to the directory /controllers and create a new file called example.controller.php

Now open the file and create a class called dps_controller_example.
To illustrate the example a bit, add two methods index and foo.

That's it, when you call http://exaple.com/framework/example/foo, you will see the output of this method.

4.2. Notes about controllers

If you want to create controllers totally on your own, simply remember the filename (somename.controller.php) and the classname (dps_controller_somename) conventions and you are set.

Controllers are always extending the abstract controller class dps_controller. This forces the controllers to implement an index action and gets the module handler as a member var into the controller.

You could use the controllers alone to create your application, by simply putting generic code into the methods.
However, this is not compliant to the MVC concept.
That is why we implemented the module handler.

5. The Module handler

Modularisation is always an issue when creating web applications.
Instead of writing all your code generic into a set of files, you can use a set of classes to build a 'module' part of an application.
Simply move on to the next step, where you will create your first module for dotspersite.

5.1. Create your own module

First off, move to the directory /modules and create the module file module_example.module.php.

There is no naming convention for modulenames (use your old classes?), but to avoid conflicts with other classes of your code, we suggest to use a module_ prefix when creating new modules.
Do not forget to add the prefix to the module class aswell.

As you can see above, we created an example module with two methods now.
You are done creating your first module.

5.2. The module-handler API

The module handler is available in the controllers as a member variable called $this->_MODULE.
This is implemented in the abstract dps_controller class.
The following code must be called in the controllers.

$this->_MODULE->add( modulename, [ params ] ) adds a module to the handler.

$this->_MODULE->cmd( modulename, methodname, [ params ] ) runs a command on the module.

$this->_MODULE->buffer( modulename, methodname, [ id ] ) retrieves the output of a module command.
The optional parameter id can be used when running a command more than once.
$this->_MODULE->buffer( modulename, methodname, 1 ) retrieves the output of the first call.

5.3. Running your module

Using the API, it is pretty simple to run your module now.
Change the dps_controller_example class, so that it calls a method of your module.

As you can figure, the above code will print Hello World when calling for http://example.com/framework/example/foo your browser.

6. The library

The library can be used to handle objects of user classes.
You can use your own classes, PEAR classes, Smarty, or whatever class you would like.

6.1. Getting an instance of your class

To get an instance of a class, move the class file into /system/library and make sure it condemns to the naming conventions.
A class with the name myclass must be in a file called myclass.class.php.

You can store the classes in subdirectories in /system/library.
Just pass the path to dps_core::singleton(), the method will filter out the real classname and handle inclusion of the proper file.

To get an instance of a class, use the following code:
$myobj = dps_core::singleton('myclass' [, param1 [, param2 [, ...]]] );

To get an instance of a class, which is in a subdirectory called /subdir, use the following code:
$myobj = dps_core::singleton('subdir/myclass' [, param1 [, param2 [, ...]]] );

To simply load a class into the scope, without generating an obect, use the following code:
dps_core::load('myclass');

6.2. Notes about the library

As long as your classes are saved in the correct directory (/system/library) and your filenames follow the naming convention (example.class.php), everything should work fine.

Jun 11, 01:00
Clemens Krack