Preserving the state of an element can be useful when you want to retain the special attributes and content across multiple web pages or during full page post back.
To preserve the state of an element you will need to add the "xt-preservestate" extended attribute to the element, or call the RaxanElement->preserveState() method. States can be either local to a web page or to the current user session.
Format:
xt-preservestate = "local | session"
Here's an example of a locally preserved element:
<?php
require_once('raxan/pdi/autostart.php');
class NewPage extends RaxanWebPage {
// change paragraph color
protected function changeColor($e) {
$this->myid->css('background','#ffcc00');
}
protected function reloadPage($e) {
// do something;
}
}
?>
<p id="myid" xt-preservestate="local">Lorem ipsum cu nam impedit efficiantur</p>
<a href="#" xt-bind="click,changeColor">Click to Change Color</a><br /><br />
<a href="#" xt-bind="click,reloadPage">Click to Reload Page</a>
When the user clicks on the link to change the background color, the of the <p> tag, the framework records the changes and preserve the state of the element during post backs.
When the "Reload Page" link is clicked the <p> tag element will be display with the new background color.
The "session state" is very similar to "local state" with the exception that the state is preserved for the duration of the user session. This means that an element can maintain it's state across web pages.
If we were to modify the above example and set xtpreservestate="session", then the framework will preserve and display the last saved state of myid across multiple web pages.
<?php
require_once('raxan/pdi/autostart.php');
class AnotherPage extends RaxanWebPage {
protected function _load() {
// code here
}
}
?>
<p id="myid" xt-preservestate="session">Lorem ipsum cu nam impedit efficiantur</p>
Raxan provides two methods for persisting data: The page and session data() methods
The page data method allow developers to persist serializable objects and variables during a page "POST" request. This data is only removed when the page is called via a "GET" request.
To do this use the $this->data() method as shown below:
<?php
require_once('raxan/pdi/autostart.php');
class NewPage extends RaxanWebPage {
protected $cnt = 0;
protected function _load() {
$this->cnt = $this->data('my-counter'); // get my-counter data value
}
protected function _prerender() {
$this->counter->text('Click Me : '.$this->cnt );
}
protected function countUp($e) {
$this->cnt++;
$this->data('my-counter',$this->cnt); // save my-counter data value
}
protected function callback($e) {
// do something;
}
}
?>
<a id="counter" href="#" xt-bind="click,countUp">Click Me</a> |
<a href="#" xt-bind="click,callback">Post Page</a>
The session data method allow developers to persist serializable objects and variables for the duration of the user session. This means that variables will remain persisted until the session is destroyed.
To do this use the $this->Raxan->data() method as shown below:
<?php
require_once('raxan/pdi/autostart.php');
class NewPage extends RaxanWebPage {
protected $cnt = 0;
protected function _load() {
$this->cnt = & $this->Raxan->data('my-counter',0,true); // get reference my-counter data value
}
protected function _prerender() {
if ($this->cnt)
$this->counter->text('Click Me : '.$this->cnt );
}
protected function countUp($e) {
$this->cnt++;
}
protected function callback($e) {
// do something;
}
protected function resetCounter($e) {
$this->cnt = 0;
$this->Raxan->removeData('my-counter'); // remove counter value
}
}
?>
<a id="counter" href="#" xt-bind="click,countUp">Click Me</a> |
<a href="#" xt-bind="click,callback">Post Page</a> |
<a href="#" xt-bind="click,resetCounter">Reset Counter</a>
To remove page or session data you can use the $this->removeData() or $this->Raxan->removeData() method.
In addition to the above you can also use the dataBank() method to set or retrieve data values from a data bank that is stored within the current user session:
<?php
protected function saveEntry($e) {
$title = $e->textVal();
// store title inside the TopMovie data bank
$this->Raxan->dataBank('TopMovie','dvd-pop-title',$title);
}
protected function loadEntry($e) {
// retrieves dvd-pop-title from TopMovie data bank
$title = $this->Raxan->dataBank('TopMovie','dvd-pop-title');
$this->txtPopTitle->text($title);
// retrieves the entire data bank array
$movies = & $this->Raxan->dataBank('TopMovie');
}
?>
To remove an entry from the data bank use the removeDataBank() method as shown below:
<?php
protected function removeEntry() {
// remove dvd-pop-title form TopMovie data bank
$this->Raxan->removeDataBank('TopMovie','dvd-pop-title');
// remove the TopMovie data bank
$this->Raxan->removeDataBank('TopMovie');
}
?>
There are two data storage classes available within the framework. These classes are responsible for storing and retrieving page/session data:
The RaxanSessionStorage class uses the PHP session object to store data values. If no current PHP session exists then one will be created. If a PHP session already exists, then it will be used but the session name and timeout properties will not be managed via the framework.
The RaxanPageStorage class uses Raxan's data storage methods to store and retrieve page data. This means that page data will also be storeg in the current user session. The only difference is that the data will be reset on first load if the resetDataOnFirstLoad property is set to true. The value for the page resetDataOnFirstLoad property defaults to true.
To prevent the page data from being reset on first load, set resetDataOnFirstLoad to false or use the storeName() method to change the data store name for the current page:
<?php
class NewPage extends RaxanWebPage {
protected function _config() {
$this->resetDataOnFirstLoad = false;
$this->storeName('my-data-store-name');
}
protected function _load() {
// do something here
}
}
?>
To create your own data storage you can extend the RaxanDatastorage class as shown below:
<?php
class MyStorageClass extends RaxanDatastorage {
protected function _init() {
$id = $this->id;
// code to initialize array $store here
$this->store = $store; // set storage array
}
protected function _reset() {
$id = $this->id;
// code to reset array $store here
$this->store = $store; // set new array
}
protected function _save() {
$id = $this->id;
$store = $this->store;
// code to save $store here
}
}
?>
To register your new data storage class you can the "session.data.storage", "page.data.session" config options:
<?php
Raxan::config('session.data.storage', 'MyStorageClass') ; // set default session storage class
Raxan::config('page.data.storage', 'MyStorageClass') ; // set default page storage class
?>
You can also use the dataStorage() method as show below:
<?php
protected function _config() {
// code to generate/retrieve unique page or session $id here
// register session data storage object
$st = new MyStorageClass($uniqueId);
$this->Raxan->dataStore($st);
// register page data storage object
// $this->dataStore($st);
}
?>
To learn more about the data APIs visit RaxanWebPage::data, Raxan::data() and Raxan::dataBank()
In addition to preserving the state of an element within the page, you can also preserve the content of a web form during post back by setting preserveFormContent property to true.
By enabling this feature you can eliminate the need to manually sanitize and update form elements with values that are submitted from the client:
<?php
class NewPage extends RaxanWebPage {
protected function _config() {
$this->preserveFormContent = true;
}
protected function _load() {
// do something here
}
}
?>
<form name="form1" action="" method="post">
<input type="text" name="text1" id="text1" value="I am a textbox" />
<input type="submit" name="submit1" id="submit1" value="Submit" />
</form>
When the "submit" button is clicked the content the current value text box will be redisplayed after a full page post back.
If an element is marked as readonly or disabled its content will not be updated:
<?php
class NewPage extends RaxanWebPage {
protected function _config() {
$this->preserveFormContent = true;
}
protected function _load() {
// do something here
}
}
?>
<form name="form1" action="" method="post">
<input type="text" name="text1" id="text1" value="I am a readonly textbox" readonly />
<input type="submit" name="submit1" id="submit1" value="Submit" />
</form>
By using the "preserve form content" feature you can save time and reduce the code size of the application.
Up Next: Web Page Plugins