This is the base class to inherit from when creating new plugins for the pnForm framework. Every pnForm plugin is normally created in a Smarty plugin function file and registered in the pnForm framewith with the use of pnFormRender::pnFormRegisterPlugin().
Member variables in a plugin object is persisted accross different page requests. This means a member variable $this->X can be set on one request and on the next request it will still contain the same value. This probably removes 99% of the use of hidden HTML variables in your web forms. A member variable must be declared in order to be persisted:
class MyPlugin inherits pnFormPlugin
{
var $X;
}
Member variables in a plugin will be assigned automatically from Smarty parameters when the variable and parameter names match. So assume you have a plugin like this:
class MyPlugin inherits pnFormPlugin
{
var $X;
}
Then X will be set to 1234 through this template declaration:
<!--[MyPlugin X="1234"]-->
A registered plugin will be notified of various events that happens during it's life-cycle. When a specific event occurs then the corresponding event handler (class method) will be executed. Handlers are named exactly like their events - this is how the framework knows which methods to call.
The list of events is:
create: Similar to a constructor since it is called directly after the plugin has been created.
In this event handler you should set the various member variables your plugin requires. You can access
Smarty parameters through the $params object. The automatic setting of member variables from Smarty
parameters happens after the create event.
This event is only fired the first time the plugin is instantiated,
but not when restored from saved state.
load: Called immediately after member variables has been set from their Smarty parameters. So
the plugin is assumed to be fully initialized when the load event is fired. During the load event the plugin
is expected to load values from the render object.
A typical load event handler will just call the loadValue handler and pass it the values of the render object (to improve reuse). The loadValue method will then take care of the rest. This is also the place where validators should be added to the list of validators. Example:
This event is only fired the first time the plugin is instantiated, but not when restored from saved state.
initialize: this event is the opposite of the create/load event pair. It fires when a plugin
has been restored from a postback (and before then decode event).
decode: this event is fired on postback in order to let the plugin decode the HTTP POST values
sent by the browser. It is left to the plugin to decide where to store the decode data.
dataBound: this event is fired when plugin is loaded and ready - both on postback and the
initial page display.
render: this event is fired when the plugin is required to render itself based on the data
it got through the previous events. This function is only called on Smarty function plugins.
The event handler is supposed to return the rendered output.
renderBegin: this event is for Smarty block plugins only. It is fired in order to allow
the plugin to render something before the plugins contained within it.
renderContent: this event is for Smarty block plugins only. It is fired in order to allow
the plugin to modify content renderes by the plugins contained within it.
renderEnd: this event is for Smarty block plugins only. It is fired in order to allow
the plugin to render something after the plugins contained within it.
postRender: this event is fired after all rendering is done for all plugins on the page.
In this event handler you can use pnFormRender::pnFormGetPluginById() to fetch other plugins
and read/modify their data.
Most events on one plugin happens before the next plugin is loaded (except the postRender event). So for two plugins A and B you would get the event sequence (assuming B is placed after A in the Smarty template):
This contains the identifier for the plugin. You can use this ID in pnFormRender::pnFormGetPluginById() as well as in JavaScript where it should be set on the HTML elements (this does although depend on the plugin implementation).
Name of function to call in form event handler when plugin is loaded
If you need to notify the form event handler when the plugin has been loaded then specify the name of this handler here. The prototype of the function must be: function MyOnLoadHandler(&$render, &$plugin, $params) where $render is the form render, $plugin is this plugin, and $params are the Smarty parameters passed to the plugin.
The data bound handler is called both on postback and first page render.
This is the function that takes care of reading smarty parameters and storing them in the member variables or attributes (all unknown parameters go into the "attribues" array). You can override this for special situations.
