To modify the PHsPeed application flow, or to add your own business rules, you need to apply your code to events. There are two types of events:


  • PHP Events

These events occur server side in your PHP application. There are generic PHP events, like onCreate that is triggered on each component that is on your form. There are also events that are local to certain components. Events take place on predefined moments in the code.


  • JavaScript Events

These events occur on the client (=browser). PHsPeed generates all required JavaScript to let the application run, so you will rarely need to access it. However, some full-stack developers sometimes have special needs and you can edit and debug the JavaScript code when required.


What are events, and why do you need them?

PHsPeed is a low code development system. In general, you build your applications around a form, put components on them, and then generate code to view the result. But that doesn't mean that the application does exactly what you want. But you cannot change the generated code as it will be overwritten the next time you want to generate it again. So how do you change applications, and apply your own business rules?

The answer to this question is to apply your code in events. An event is a predefined 'injection point' where you can apply your own code to fulfill certain behavior. There are two sorts of events, the client-side which is JavaScript, and the server-side which is PHP. One thing though, most JavaScript is generated when you invoke a JavaScript event. You will very rarely need to change the default javascript. But you need to know when to invoke, which will be explained in this document.

Application structure

Before diving into events it is necessary that you understand the basic application flow of PHsPeed applications. In short, form applications have at least two stages, the initial stage where the basic template for the form is being generated and transferred to the web browser. Then the web browser will invoke at least one ajax request to obtain the content that is put into that template. Effectively, DIV's are being replaced by rendered pieces of HTML/JavaScript code. So your application is run at least twice before the final result is shown. If you have components with special behavior, like database grids, then they can perform their own ajax request to obtain data.

When your application starts it will first create your form and all components on them. Each component will try to call the onCreate event in its constructor, and the onDestroy event when the object is being destroyed (at the end of the program). Once all components have been created, each component will receive an onShow event. Visual components will have an onBeforeRender and onAfterRender event. So what does this mean?

onCreate

This event is used to set up defaults in your code, where you don't want to use the standard properties. Do not access the properties of other components, as you can never be sure that the component is already instantiated.

onActivate

This event will be triggered once all components have been created. So you can access other components and properties. One thing to keep in mind is that in the application flow only one component gets the event at a time. So if you set a value in component B that is later in the order than component A, then A can access the value property but will get the value before component B gets his onActivate event where it might change its value.

onBeforeRender

This event is used to render the components into its visual representation. In this stage, every component has its value, so if you want to do things depending on the value of another component this is the place. Like the onActivate, you must be aware that if you change the value of a component that is already rendered, that you will get unexpected results also.

onAfterRender

This event takes place after the component has been rendered.

onDestroy

This event takes place when the application terminates.

So, use the onActivate event, to set and use properties that are not changed in your application (and you know, because if they do, you programmed it by yourself). Use the onBeforeRender to make changes to the rendering depending on the values of other components.

Component private events

Beside the generic events (that most of the components have, like the onCreate.. components can have other events, that are dedicated to that component. For instance, a DBTable component has an onBeforeInsert and onAfterInsert event etc..  The non-standard events that are private to the components are described in the helpfile by the components themselves.

Ajax events

Ajax events are used, when you want the application to be responsive, without rebuilding the whole form. There are different components that support Ajax event, but the most common is a button. To let Ajax events work there are comonents in the PHP and JavaScript section with the same name, like 'onClick'. If you use both events then you only have to program the PHP part for the processing part. The JavaScript event is fully generated and does not require changing. With PHsPeed you might need to assign a JavaScript event, you do not have to write them.