PHsPeed Application structure

If you look at a regular webpage, then, in general, you see a header, a detail, and a footer part. The header and footer are usually pretty standard; the detail part contains your working area and changes all the time.

The development of a PHsPeed project follows this approach. You can define simple 'blocks' that are reusable in headers and footers and might contain a menu for instance. More advanced blocks could define a detail needed in a master-detail relationship. You can define 'apps' ('stand-alone applications within a project') also. These are the working stones of your project, apps are executable, where modules are PHP classes and not directly executable.

So a project can contain several applications. But in general, there's only one application to start with, for example, a login page. In a PHsPeed project, this is called the 'main' page. If you start another file in your project by entering its URL, it will redirect to the main page. By default, it is not allowed to run an application stand-alone, which is a security measure. If you have more 'main' applications in your project, you must allow them to run stand-alone explicitly. There's a property in the root component that needs to be set. It is advised to call your initial program 'main.php.' You can set it whatever you like, but if you have many files in a directory, it might not be so clear which is the main PHP application to start your application. Of course, if you have set things up correctly, starting any application will lead to the defined main application. But if you need an URL for a portal, then it is convenient to have a standard. The only exception to this is when you want to create a utility that needs to run within the space of a user application. I.e., the config application that handles the credentials and connection to the database/email does not have a 'main.php.' It would overwrite the standard main.php which would corrupt your project.

A PHsPeed application 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; 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 and properties that you have set using the components.

When you create your first application within a new project than by default, a 'main.php' application is generated and set as the first application to run on your web server. If you create a new module, you can define some default components that PHsPeed creates for you, on your design panel. For a standard module that would be a form and a root component, and if you want to create a database-aware application, a database connector. Don't worry if you have set the wrong options, after generating the module; you can always correct by removing or defining components from the designer.

the root component

Other PHP applications that are part in your PHP project are not meant to be called directly from the browser unless you design them to. You can control this, by setting the property 'CanRunStandalone' to true in the 'root' component. The root component is responsible for the basic behavior of the application. By default, this property is set to 'no,' causing a warning on main.php when you generate your application. A project must have at least one runnable application; if that is not the case, PHsPeed will release the defined 'main.php.'

For each PHP project, there's only one application in control. This application will handle the initial setup, will handle CRUD situations and ajax calls.

While developing your screen, you will use components that you need to pick from the toolbar. PHsPeed will generate PHP modules (= class) for each component you have used. These modules follow an 'autoload' PHP rule. You can have only one class in a PHP file, and the name of the file and PHsPeed will automatically include these classes because of this, so you don't need to use 'include(_once)' to load these. All generated PHP component files contain a class with constructor, destructor and processing code, all inherited from their basic classes in the runtime. There is no mixed HTML code in the PHP programs. Instead, the rendering process will retrieve the HTML blocks from (generated) templates, will generate HTML for components depending on properties, modify it where necessary by the __render PHP method and then produce the page. During this process, several events are fired to allow the programmer to intercept in the process and apply your custom code.

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 more easy 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.

handle process flow:

Depending on the state of the program there are three options:

  • initialize the form
  • handle form input
  • handle ajax request

Schematic in short:

  1. start session
  2. setup pdo connection strings
  3. setup css includes
  4. setup js includes
  5. create html page class
    • create all allocated components (perform constructors)
    • assign components to the $app class
    • Activate the components
    • setup ajax links where applicable
  6. if not inititialized then initialize (return html)
  7. if initialized then handle process input (return html)
  8. if ajax request then handle the ajax request (return json)
  9. finalize