Application Structure

If you look at a regular website, then, in general, you see a header, a detail, and a footer part; sometimes a sidebar. Mostly, the detail section is where the application runs, the header mostly contains elements like a banner, menu, etc.

Designing web applications in PHsPeed follows this approach. Reusable elements are defined as 'building blocks' (PHP classes), details as a module that leads to an executable PHP script. While developing your project, you will create/generate a lot of PHP files. The result of this is that you might lose the overview of the PHP application that starts your application. Like in languages like 'c' the main PHP module to start is 'main.php'. It is configurable, so you can change it to index.php if you prefer. The main application usually contains a login screen that gives access to other modules in your application.

Note: PHsPeed keeps track of your main application and will by default disable direct access to your other PHP modules. If a user is trying to access another module outside of main directly, then the end-user will be redirected to the main application, unless the user is already logged in. For increased security PHsPeed works with tokens to avoid access to other modules outside of main.php. During development and testing, this can be an annoying feature as testing a certain module will also direct to the main login page. You can disable this feature by setting a property 'allow to run stand-alone'.

A PHsPeed module has different parts. If it has a form that is used to generate an HTML template, you have a PHP file that handles the server-side events (controller); you have a JavaScript file that controls the client-side events, and you have a CSS file that handles the layout. In many cases, a lot of these files are generated based upon your form design that contains components, and properties that control certain behavior.

Components and properties

Components can be seen as small Lego bricks that have a certain type of functionality that you can use, without the full knowledge of how it's done. There are non-visual components, that perform tasks like accessing your database, or creating a pdf document; visual components that are visual to the end-user, like an edit field, drop down, etc.; and layout components that format the look and feel of your application. PHsPeed uses the bootstrap grid system for generating your responsive layout. More information about the bootstrap grid system can be found here and here.

Standard application flow of a form application

If the application has been set up, then it is time to generate the code. Initially, you need to generate the code with a full deployment of run time libraries. In later versions of PHsPeed, this is done when you create a project, but if you look at the provided samples it still might be necessary. Then you can run the module.

PHsPeed will start by executing the main controller application. The controller will 'see' that this is the initial call, and will respond with the form design. The web browser receives this design and will start requesting for additional data. The controller will respond to these requests (in general these are Ajax calls) until the form has been build and ready for the end-user.

Application flow and events

When the end-user hit the submit button or an Ajax button, then the request is sent to the controller that will perform the appropriate steps to continue.

Although you can create applications without even programming, at some point you will have the need to interfere with application flow to model the system to your business processes.

During processing and on user actions, PHsPeed will generate events. You can apply your code to these events.

PHsPeed applications start in the browser with a multi-step approach. First, PHsPeed will send the basic layout to the browsers. Next, the application will perform Ajax calls to retrieve the physical content, like fields, labels, grid data, etc. This approach has been chosen to make applications more flexible, secure (as Ajax calls can be encrypted), and easier to debug. PHsPeed generated HTML forms are purely based upon <div>. PHsPeed makes NO use of IFrames.

Each PHP module that runs will create an application object ($app) and then all designed objects, including building blocks that are embedded in this project. Next, all objects are available for the application to use through the $app object. Each event contains this object as a parameter. It is important to realize that during the constructor phase you should not access other objects as you cannot be sure that they are already created and available. There are two events involved here: first, an OnCreate event is fired for each component within the constructor, and when all components are created, an OnActivate event for all components is executed.

The javascript will initiate the second step in your form. It will perform ajax requests. In regular forms, this will be one request to build up the form, set labels, initial values, etc. Some components have ajax handlers of themselves and can perform additional requests. I.e., the data grids will perform requests of its own.

Each PHP runnable module is by default a control application. It handles initialization, submits and ajax requests. It takes care of session handling, security checks like CSRF, checks if a module can be run stand-alone (not hosted by the main menu), etc. All other modules are PHP classes and cannot run by itself.

Detailed standard application flow

If a php module is started then it will first do some allocation stuff needed for localization, session management etc. Next the application object will be created. In this stage the onCreate event is fired. This event will be fired on each component designed and can be used for setting up default values for those that has not been initialized by the component properties.

Next, the application will go into the init stage. In this stage it will first setup the header (if any) and fire the onBeforeHeader and onAfterHeader events. Then an onActivate event will be fired for each designed component. Depending on the component other events might be fired. Look into the component documentation for more details.

Next, the application will go into the show stage. This will only occur by default on the initial run. If the application is run after a submit then the onExec event will occur and depending on the return value onExec ('show') the onShow can be triggered as well. In this case the current form will not be replaced by the output, but will refresh. In the show stage a lot of events will be fired: onBefore.. and onAfter.. events for the detail page, body page and footer page.

Finally the application will enter the final stage. This will call the onFinish event and all destructors will get fired causing an onDestroy event.