events

Events

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.

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.

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 event onBeforeInsert and onAfterInsert. Obvious what these components do ;-) These are described in the description of the components themselves.

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. Suppose you have two edit fields that accept a number, a label field that should represent the sum, and a button that will use ajax to calculate field a + field b and puts the result in field c.

First design your form. In this case we have changed the labels of the field and set the value to empty.
The button has been set to a color class so that it stands out. The result field contains an initial question mark.
It is obvious that if you look at the button, you will find an onClick event. If you create the event, then you can apply the calculation.
It is important to change the button type from submit (which would be a regular form submit) to 'button', this will suppress the submit and allow the ajax event to occur.
As the application needs to respond to a button click, we need to have some javascript to detect the click.
Because this event has the same name as the PHP event, PHsPeed will bind these together to an ajax event.
Remember, if you click on the event button, the JavaScript is generated. You do not have to write it, just assign it!

Now we can run the application.
Enter some values and select the + button.
  • events.txt
  • Last modified: 2021/06/10 15:52
  • by aducomadmin