Events

This may look complicated but its usage is very simple and natural.

When you have a form or a link and you want the next page to execute some PHP you can send it to a PHP script that will process it.

Events are the same thing.

All the scripts that process requests from forms and links are in the /events/ folder; we call them EventActions.

The Event Object allow you to create the link or form, then you send the param to the EventAction. You can execute more than one EventAction at a time.

When EventActions are executed they are executed inside a function of the EventControler as they are in a function we use: $this→getParam(“paraname”) to retrieve data from the $_REQUEST and $this→getSession(“variablename”) to get data from the $_SESSION. To redirect after executing the EventAction we use an Object called: Display. That Display object is passed to the EventControler with the method:

$disp = new Display("pagename.php");
$disp->addParam("message", "eventaction has been executed");
$this->setDisplayNext($disp).

The EventController will redirect after the EventActions of the Event are executed.

The event logic is composed of 3 elements : EventObject, EventAction and EventController. The EventObject calls and collects parameters to execute one or more EventActions. When an event is triggered by the user, it is sent to the EventController which manages the execution of event actions and their variables.

Every Form and most links in PAS are Event Objects. The Event Object appears in the user interface in the form of an HTML Link or an HTML Form. It contains the list of parameters and EventActions that will be sent to the EventController for execution.

You create an Event Object on WebPages, Forms or Reports. An Event can be a link or a form. A link is used when your EventAction doesn't require user input. The form allows you to create additional fields that allow the user to enter information that is be sent to the EventAction.

Sample 1 : a simple Event :

<?php
  $e_Logout = new Event("webide.logout") ;
  $e_Logout->addParam("userid", $userid) ;
?>
<?php echo $e_Logout->getLink("Log Out")?>

The eventLogout will call the EventAction “webide.logout” and send the parameter (or variable) “userid”. The method getLink(“link lable”, “link params”) returns a correctly formatted link with a url that points to the event controller. The “link param” can be any param accepted by the <a> tag. The Event Object can call multiple EventActions and defines the order in which the EventActions will be executed.

Sample 2 : Event Object calling 2 EventActions.

<?php
  $e_register = new Event("myapp.RegisterNewUser") ;
  $e_register->setLevel(20) ;
  $e_register->addParam("username", $username) ;
  $e_register->addEventAction("myapp.checkIfUserExists", 10) ;
?>
<A href="<?php=$e_register->getUrl();?>">Register User</A>

We want to register a new user who's entered a username. But before we want to make sure that user is not already registered. We set the first event action at level 20 and the second one at 10 so its executed first.

The method getUrl() returns a correctly formatted url that can be inserted as a link or sent to the HTTP header as a new location.

When you need data input from the users you display the Event as a Form.

<?php
    $e_payments = new Event("morgage.calculateMonthlyPayments");
    $e_payments->setLevel(400);
    $e_payments->addParam("errorpage", $_SERVER['PHP_SELF']);
    $e_payments->addEvent("mydb.gotoPage", 500);
    $e_payments->addParam("goto", "result.php");
    $e_payments->addParam("idbrooker", "45");
 
    echo $e_payments->getFormHeader();
    echo $e_payments->getFormEvent();
?>
<table>
 <tr>
   <td>Loan Amount</td>
   <td><input type="text" name="loan_amount" size="6"></td>
 </tr>
 <tr>
   <td>Interest rate</td>
   <td><input type="text" name="interest_rate" size="5"></td>
 </tr>
   <td>Number of months</td>
   <td><input type="text" name="number_of_months" size="5"></td>
 </tr>
</table>
<?php
    echo $e_payments->getFormFooter("Calculate");
?>

This event will execute the event Actions morage.calculateMonthlyPayments and then the mydb.gotoPage to redirect the user to the result.php page. Both events will receive all the parameters from addParam() methods as well as the content of the fields load_amount, interest_rate, number_of_months. Instead of using the getLink() or getUrl() methods we use the getFormHeader() to display the opening form tag, the getFormEvent() to display the Event Actions and the parameters, the getFormFooter to display the submit button and close the form tag.

The event actions are pieces of code that are executed by the EventController when called by an EventObject. Event actions hold the business logic of your application.

We suggest you name your events starting with the name of your application or package. This keeps the events organized when your application size grows. For example: mydb.updateRecord or myapps.calculatePayroll. The EventAction is executed inside the EventController.

Here is a sample of a simple event action : faq.recordView

     $idfaq = $this->getParam("idfaq");
     if ($idfaq>0) {
        $q_incView = new sqlQuery($this->getDbCon()) ;
        $q_incView->query("update faq set views=views+1 where idfaq=".$idfaq);
        $q_incView->free();
     }

This event records each time a user clicks on an FAQ question. It uses the $this→getParam() method from the EventController to grab a parameter from the event that triggered it. Additionally it gets the database connection used by the EventController with : $this→getDbCon(). This event action assumes that another event action will set the next display. If none of the event actions set the $this→setDisplayNext(displayobject) then the user will get an infinite redirection error from the EventController. This is an example of how to set a display next :

    $disp = new Display("index.php") ;
    $disp->addParam("message", "Welcome Back to the home page") ;
    $this->setDisplayNext($disp) ;

We suggest that all messages used in the events to be stored in a string on top of the event action script.

To enable errors and logs you can use the event controller log methods.

$this->setLogRun(true); 
$this->setLog("\n This is a log message");

See the BaseObject for more information on Errors and Logs.

You can make your event data live through a session. Session events are an important part of PAS applications. The are the most used way to store information to be reused in forms, reports, saved querys and web pages. For example, you have 3 pages. You want your event to be executed after page one but you want the data stored in that event to be available until the user arrives on page 3, no matter what is executed in between.

<?php 
  $e_mclient = new Event("myapp.moreclient") ; 
  $e_mclient->addParam("idclient", $idclient) ; 
  $e_mclient->addParam("name", $name) ; 
  $e_mclient->requestSave("moreClientInfoForm", "formpage5.php") ; 
?>
  <a href="<?php=$e_mclient->getUrl()?>">Edit Client information</A>

In this example we have an event object that calls the “myapp.moreclient” event action. It uses the method requestSave to store this event into an object called “moreClientInfoForm”; this object will be available until the user reaches the page “formpage5.php”. On the page formpage2.php the event will release all of its params as global variables and the “moreClientInfoForm” object will be set to be destroyed on the next page. Until the user has reached the formpage5.php you can access and modify the the parameters of that event in Events or Web Pages using:

<?php
    $idclient = $moreClientInfoForm->getParam("idclient");
    $lastname =  "Doe";
    $moreClientInfoForm->addParam(“lastname”, $lastname);
?>

The values of parameters in session events can also be retrieved in Saved queries and as Default values of fields in forms in the registry. (See Parameters in Saved Query chapter and function call for default value in Registry chapter for more information). Get the param of a session event in a SQL statement of a Saved query:

SELECT * FROM category_product AS cp LEFT JOIN products AS p ON (cp.idproducts=p.idproducts)  WHERE cp.idclient='[getParam:moreClientInfoForm:iclient]'

Get Param of a session event as a default form value in a registry:

<rfield name="idclient">
    <rdata type="label">idclient</rdata>
    <rdata type="readonly">1</rdata>
    <rdata type="default">[getparam;moreClientInfoForm;idclient]</rdata>
    <rdata type="fieldtype">strFBFieldTypeInt</rdata>
  </rfield>

Note the “;” instead of “:”, this is specific to the registry function calls.

By default event objects are in secure mode.

The “Secured” is too much, but it helps by hiding the parameters of links and forms in the session.

This means that none of the parameters you set in your event object are visible in the web page. Instead those events are stored in the Session and will be recalled when the Event Object will be triggered by the user. To turn off the secure event mode uncomment the line:

  //define("RADRIA_EVENT_SECURE", false);

in your config.php file.

<?php
    $e_sel_lic = new Event("reseller.select_licenses");
    $e_sel_lic->setLevel(1100);
    $e_sel_lic->setSecure(true);
    $e_sel_lic->addParam("errorpage", $_SERVER['PHP_SELF']);
    $e_sel_lic->addEvent("mydb.gotoPage", 500);
    $e_sel_lic->addParam("goto", "thankyou.php");
 
    $e_sel_lic->addParam("idreseller", "345", "no_secure_hidden");
 
    $e_sel_lic->addParamToSave("simple_users");
 
    $e_sel_lic->requestSave("eSelLic", "reseller_panel.php");
 
    echo $e_sel_lic->getFormHeader();
    echo $e_sel_lic->getFormEvent();
?>
 
<input type="text" name="simple_users" size="5" maxsize="20" value="10">
 
<?php
    echo $e_sel_lic->getFormFooter("Submit");
?>

You can individually set an event insecure or secure using the setSecure(bool) method. You can display individual parameters using the “no_secure_hidden” as the third parameter of the addParam() method. “no_secure_hidden” is usefull to display selected parameters for users to view or to be used by Javascript Scripts.

If you want to store a param in the session event but its value is set later in the script you need to declare it using addParamToSave before the requestSave() method call.

This object is old and deprecated, but it still has its usefulness sometimes. It should be replaced by session persistent Events and the DataObject.

The Record Event Object inherits from the Event Object and adds useful features to create Events for Database Record management. It is very useful inside a Report to add, edit and delete links.

Sample 3: Manage Records in a Report. Header Section:

<?php 
     $e_ManageRecord = new RecordEvent("employes") ;
?>
<A href="<?php=$e_ManageRecord->getUrlAdd();?>">Add an employe</A>
<TABLE>
Row Section :
<TR>
  <TD>[firstname] </TD>
  <TD>[lastname]</TD>
  <TD>[socialsecurity</TD>
  <TD>[monthlypay]</TD>
  <TD><A href=”<?php=$e_ManageRecord->getUrlEdit([idemploye])?>
        Edit Employe
      </A>
  </TD>
  <TD><A href=”<?php=$e_ManageRecord->getUrlDelete([idemploye])?>
         Delete Employe
      </A>
  </TD>
</TR>
Footer Section :
</TABLE>

Record events assume that the primary key of your table is id<tablename>, if the primary key is different you will need to set the primary key manually :

 $e_ManageRecord->setPrimaryKeyVar("keyemploye_id");

This is an object inside a php file. Usually it is the page: eventcontroler.php. that comes with the default application structure. You can create your own event controller by creating an instance of the EventController Object inside a PHP page.

The EventController looks for events triggered by the user. Each time a user clicks on a link or submits a form that was created with an Event Object, a list of Event Actions and parameters will be sent to the Event Controller.

The event controller will then order the event actions and create a secure environment with the parameters and global variables. Once the environment is set, and referrer verified, it includes the requested Event Action files from the pas/events or ./events directory. After all of the events have been executed it will check if a display object as been set and redirect the user to that display.

The event controller provides the event actions with all of the session variables and get/post/cookie variables. They can be accessed within an event action using the following syntax :

 $firstname = $this->getParam("firstname");
 $username = $this->getSession("username");

The event controller also allows the different event actions to share information. This is done by sharing an Array in the event controller. Event Actions can access that Array using the $this→setParam() and $this→getParam() methods.

The event actions are pieces of code that are executed by the Event Controller when called by an EventObject.

Below you will find a list of all the event actions in pas/events/. The EventAction can use all of the methods of the EventController object that was called. mydb.addParamToDisplayNext : will add all of the parameters of your event to the display so they will be displayed in the url after the event is executed.

Following is a short description of the Event actions. For a detailed description of the built-in Event Actions see Appendix D. Event actions to manage records in a database :

mydb.addRecord: uses the fields array and table parameters to add a record to a table.

mydb.manageRecord: used by the recordevent to manage records in a table.

mydb.tableorder: Used by the reportTable object to manage the variables for ordering and next - previous tabs.

mydb.updateRecord: Update a record in a table using the primary key, fields array and table name.

Event actions to validate and format values from forms : The Event actions below are called by the Registry. When a form is displayed the registry checks each field for when events will need to be executed on the server side to validate that field.

mydb.checkEmail: Checks if the domain of the email address exists

mydb.checkRequired: Checks if a field set as require contains something

mydb.checkUsernamePassword: Checks that the two passwords are identical

mydb.formatDateField: Convert a date to a unix time stamp

mydb.formatDateSQLField: Convert a date to an sql data format

mydb.formatPictureField: Manage the file upload

mydb.formatTimeField: Format a time field

Event actions to manipulate variables and page redirection:

mydb.addVariablesToSession : Save a variable to the session

mydb.callDisplay : Call a default page to display a form or a report

mydb.delVariablesFromSession : Remove a variable from the session

mydb.fieldsToArray : Convert all of the fields : fields_fieldname to fields[fieldname]

mydb.gotoPage: Create a display event and use the goto parameter to redirect to the page defined by goto

mydb.loadParamsFromSession: Load the paramaters of an event when events are in secure mode

mydb.registerGlobalEvent: Used to register an event in the session

mydb.SaveForm: Totally depreciated

mydb.stripslashes.Fields: Check the PHP addslashes policy and stripslashes if needed

Event actions to synchronize databases :

mydb.synchronise.db.Data: Synchronize the data using backupsync.data.sql

mydb.synchronise.db.Structure: Synchronize the structure using backupsync.struct.sql