# **Chapter 3: The Gate Lifecycle Events - Understanding Event Flow**
> **File Extension Reference:**
> - Gate Files: `*.gate.php` (e.g., `Index.gate.php`)
> - Front Files: `*.front` (e.g., `index_main.front`)
> - Master Files: `*.mast.php` (e.g., `default/master.mast.php`)
> - Front Places: `*.place.front` or `*.place.php`
---
## **3.1 What are Lifecycle Events?**
Lifecycle events are special methods in your Gate class that get called at specific times during request processing. They're different from Page Events (like `page_new()`) because they're triggered automatically by the framework, not by URL requests.
Think of lifecycle events as the "behind-the-scenes" setup and teardown of each request.
## **3.2 The Complete Lifecycle Order**
Here's when each lifecycle event fires:
```
Request Received
↓
onstart() ← First - Initialize your Gate
↓
FrontFile Loaded (if used)
↓
onfrontinit() ← FrontFile is ready
↓
onfrontprocess() ← FrontFile processed
↓
onready() ← Gate is ready to process
↓
onrun() ← Before Page Event executes
↓
Page Event ← e.g., page_new() or page_event_*
↓
onrender() ← After Page Event, before output
↓
Response Sent ← Final HTML to browser
```
## **3.3 onstart() - The Initialization Event**
`onstart()` fires FIRST when your Gate is created. Use it for:
- Creating FrontFile objects
- Initializing resources
- Setting up authentication
- Loading configuration
### **Example: Initializing FrontFile in onstart**
```php
<?php
// apps/Index.gate.php
use Sphp\tools\BasicGate;
class Index extends BasicGate
{
// Property to hold our FrontFile
private $frtMain;
/**
* Lifecycle Event: onstart
* Called once at the beginning of the request
*/
public function onstart()
{
// use filename for Front file as:- Class name of Gate + _ + filename + .front
// Create FrontFile object
$this->frtMain = new \Sphp\tools\FrontFile($this->mypath . "/fronts/index_main.front");
}
/**
* Default Page Event
*/
public function page_new()
{
// Use the FrontFile we created in onstart
$this->setFrontFile($this->frtMain);
}
}
```
### **Example: Authentication in onstart**
```php
public function onstart()
{
// Require ADMIN or MEMBER role
$this->getAuthenticate("MEMBER,ADMIN");
// Initialize FrontFile
$this->frtMain = new \Sphp\tools\FrontFile($this->mypath . "/fronts/admin_main.front");
}
```
## **3.4 onready() - The Preparation Event**
`onready()` fires AFTER FrontFile is parsed and Components are created. Use it for:
- Modifying Component properties
- Setting default values
- Accessing Components by ID
- Pre-processing form data
### **Example: Modifying Components in onready**
```php
public function onstart()
{
$this->frtMain = new \Sphp\tools\FrontFile($this->mypath . "/fronts/form.front");
}
public function onready()
{
// All Components are now created and accessible
// Get a text field component
$txtName = $this->frtMain->getComponent("txtName");
// Set default value
$txtName->fu_setDefaultValue("John Doe");
// Get a dropdown component
$sltCountry = $this->frtMain->getComponent("sltCountry");
// Populate options
$sltCountry->setOptions("USA,Canada,Mexico,UK");
}
```
## **3.5 onrun() - The Pre-Processing Event**
`onrun()` fires BEFORE the Page Event executes. Use it for:
- Final permission checks
- Logging
- Data pre-processing
- Redirects before Page Event runs
### **Example: Pre-Event Processing in onrun**
```php
public function onstart()
{
$this->frtMain = new \Sphp\tools\FrontFile($this->mypath . "/fronts/dashboard.front");
}
public function onrun()
{
// Log this access
$this->logAccess();
// Check specific permission
$this->page->getAuthenticatePerm("view_dashboard");
// Pre-process request data
$this->currentPage = $this->Client->request("page", 1);
}
public function page_new()
{
// By the time we reach here, onrun has already executed
$this->setFrontFile($this->frtMain);
}
```
## **3.6 onrender() - The Post-Processing Event**
`onrender()` fires AFTER the Page Event completes but BEFORE the final HTML is sent. Use it for:
- Adding JavaScript/CSS
- Modifying Master File
- Adding Front Places
- Final output adjustments
### **Example: Post-Processing in onrender**
```php
public function onstart()
{
$this->frtMain = new \Sphp\tools\FrontFile($this->mypath . "/fronts/page.front");
}
public function page_new()
{
$this->setFrontFile($this->frtMain);
}
public function onrender()
{
// Page Event has executed, FrontFile is rendered
// Add custom CSS
addFileLink("custom_style.css");
// Add custom JavaScript
addHeaderJSCode("console.log('Page rendered!');");
// Add a Front Place to Master File
addFrontPlace("sidebar", __DIR__ . "/places/sidebar.place.front");
}
```
## **3.7 FrontFile Events - Template Interaction**
Beyond lifecycle events, you can also handle events from your FrontFile templates:
### **onfrontinit() - FrontFile Just Loaded**
```php
public function onfrontinit($frontobj)
{
// FrontFile object is now available
// $frontobj is the FrontFile instance
// Do something with the FrontFile
$frontobj->addMetaData("title", "My Page");
}
```
### **onfrontprocess() - FrontFile Processed**
```php
public function onfrontprocess($frontobj)
{
// FrontFile has been fully processed
// All Components created, Fusion attributes executed
// Can modify components here too
$component = $frontobj->getComponent("txtTitle");
$component->fu_setReadonly(true);
}
```
## **3.8 When to Use Each Event**
| Event | When | Best Use For |
|-------|------|--------------|
| `onstart()` | First | Create FrontFiles, auth check, init |
| `onfrontinit()` | After FrontFile loaded | Set metadata, prepare data |
| `onfrontprocess()` | After FrontFile processed | Modify Components |
| `onready()` | Before Page Event | Modify Components, defaults |
| `onrun()` | Just before Page Event | Final checks, logging |
| `onrender()` | After Page Event | Add CSS/JS, Front Places |
## **3.9 Complete Example**
Here's a Gate showing all lifecycle events in action:
```php
<?php
// apps/Product.gate.php
use Sphp\tools\BasicGate;
class Product extends BasicGate
{
private $frtList; // For listing page
private $frtEdit; // For edit page
/**
* Lifecycle Event: onstart
* Initialize our FrontFiles here
*/
public function onstart()
{
// Require authentication
$this->getAuthenticate("MEMBER,ADMIN");
// Create FrontFile objects
$this->frtList = new \Sphp\tools\FrontFile($this->mypath . "/fronts/product_list.front");
$this->frtEdit = new \Sphp\tools\FrontFile($this->mypath . "/fronts/product_edit.front");
}
/**
* FrontFile Event: onfrontinit
* Called when FrontFile is loaded
*/
public function onfrontinit($frontobj)
{
// Add page metadata
$frontobj->addMetaData("author", "My App");
}
/**
* Lifecycle Event: onready
* Modify Components before Page Event
*/
public function onready()
{
// Set default values for form
$this->frtEdit->getComponent("txtDate")->fi_setDefaultValue(date("Y-m-d"));
}
/**
* Lifecycle Event: onrun
* Pre-processing before Page Event
*/
public function onrun()
{
// Check permission for this specific action
if ($this->page->getEvent() === "delete") {
$this->page->getAuthenticatePerm("delete_product");
}
}
/**
* Page Event: page_new
* Display product list - URL: product.html
*/
public function page_new()
{
// Get products from database
$products = $this->getProducts();
// Pass to FrontFile
$this->frtList->getComponent("divProducts")->setInnerHTML($products);
$this->setFrontFile($this->frtList);
}
/**
* Page Event: page_view
* View single product - URL: product-view-5.html
*/
public function page_view()
{
$productId = $this->page->evtp;
$product = $this->getProduct($productId);
// Populate edit form
$this->frtEdit->getComponent("txtName")->fu_setValue($product["name"]);
$this->frtEdit->getComponent("txtPrice")->fu_setValue($product["price"]);
$this->setFrontFile($this->frtEdit);
}
/**
* Lifecycle Event: onrender
* Add final touches after Page Event
*/
public function onrender()
{
// Add analytics
addHeaderJSCode("ga('send', 'pageview');");
}
// Helper methods
private function getProducts() { /* ... */ }
private function getProduct($id) { /* ... */ }
}
```
## **3.10 Chapter Summary**
1. **Lifecycle events** fire automatically at specific times during request processing
2. **onstart()** - First, for initialization and FrontFile creation
3. **onfrontinit()** - After FrontFile loaded, for metadata
4. **onfrontprocess()** - After FrontFile processed, for Component modification
5. **onready()** - Before Page Event, for final Component setup
6. **onrun()** - Just before Page Event, for pre-processing
7. **onrender()** - After Page Event, for adding CSS/JS and Front Places
8. **FrontFile events** (`onfrontinit`, `onfrontprocess`) - For template interaction
## **3.11 What's Next?**
Now you understand lifecycle events. In the next chapter, you'll learn about Page Events in detail - how to handle different browser requests and form submissions.
---
*Next: Chapter 4 - Page Events: Handling Browser Requests*