Events
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.