Namespaces | Functions

cms/widget.lib.php File Reference

Go to the source code of this file.

Namespaces

namespace  pragyan
 

Widget Framework for Pragyan CMS (c) 2010 Pragyan Team http://www.gnu.org/licenses/ GNU Public License For more details, see README Add support for File Upload/Download via the widget's configurations Reload Widgets ,Get Widget Instances. see bottom.


Functions

 populateWidgetVariables ($pageId)
 handleWidgetPageSettings ($pageId)
 getInheritedWidgets ($pageId)
 propagateWidgetInstance ($widgetId, $widgetInstanceId)
 unpropagateWidgetInstance ($widgetId, $widgetInstanceId)
 deleteWidgetInstance ($widgetId, $widgetInstanceId)
 modifyWidgetInstanceLocation ($pageId, $widgetId, $widgetInstanceId, $mod)
 modifyWidgetInstanceOrder ($pageId, $widgetId, $widgetInstanceId, $mod)
 createWidgetInstance ($pageId, $widgetId)
 getEnabledWidgets ($pageId)
 checkForWidgetIssues ($modulePath, $moduleName, &$issues)
 actualWidgetPath ($modulePath)
 getWidgetName ($actualPath)
 handleWidgetAdmin ($pageId)
 getConfigFormAsArray ($widgetconfigs, $containsFileUploadFields, $widgetinstanceid, $isglobal)
 getFormInputField ($configentry, $value="", $isglobal)
 renderTextareaTypeField ($elementName, $value, $options, &$htmlOutput)
 renderSelectTypeField ($elementName, $value, $options, &$htmlOutput)
 renderRadioTypeField ($elementName, $value, $options, &$htmlOutput)
 renderBoolTypeField ($elementName, $value, $options, &$htmlOutput)
 renderCheckboxTypeField ($elementName, $value, $options, &$htmlOutput)
 renderFileTypeField ($elementName, $value, $options, &$htmlOutput)
 renderTextTypeField ($elementName, $value, $options, &$htmlOutput)
 renderIntegerTypeField ($elementName, $value, $options, &$htmlOutput)
 renderHiddenTypeField ($elementName, $value, $options, &$htmlOutput)
 renderDatetimeTypeField ($elementName, $value, $options, &$htmlOutput)
 renderDateTypeField ($elementName, $value, $options, &$htmlOutput)
 renderNoinputTypeField ($elementName, $value, $options, &$htmlOutput)
 getWidgetPageConfigInfo ($widgetid)
 getWidgetGlobalConfigInfo ($widgetid)
 getWidgetInfo ($widgetid)
 getAllWidgetsInfo ()
 updateWidgetConf ($widgetid, $widgetinstanceid=-1, $isglobal=TRUE)
 interpretSubmitValue ($conftype, $postvar, $options=NULL)
 reloadWidgets ()
 getWidgetInstances ($widgetid)

Function Documentation

actualWidgetPath ( modulePath  ) 

Definition at line 548 of file widget.lib.php.

checkForWidgetIssues ( modulePath,
moduleName,
&$  issues 
)

Definition at line 511 of file widget.lib.php.

createWidgetInstance ( pageId,
widgetId 
)

Creates an instance of the widget on the given page using default location and order

Note:
Default location is 1, and it will chose the default order as the 'maximum order value + 1' for the location 1.
Parameters:
$pageId Page Id of the page in which to create the widget
$widgetId Widget Id of the widget to enable
Returns:
Boolean true if success, else false.

Initializing as global instance.

Now create the actual instance with a unique instance Id.

Definition at line 448 of file widget.lib.php.

deleteWidgetInstance ( widgetId,
widgetInstanceId 
)

Deletes a particular instance of the widget including all its configurations.

Parameters:
$widgetId ID of the widget to be deleted
$widgetInstanceId Instance ID of the particular widget instance to be deleted
Returns:
Boolean True if deletion was successful, else false.

Definition at line 376 of file widget.lib.php.

getAllWidgetsInfo (  ) 

Retrieves the widget id and name of all the widgets

Returns:
An associative 2D array containing the widget id, name, description, version and authorname.

Definition at line 1119 of file widget.lib.php.

getConfigFormAsArray ( widgetconfigs,
containsFileUploadFields,
widgetinstanceid,
isglobal 
)

Retrieves the configurations in the form of an HTML with all the fields and types appropriately put into place. Can be used for retrieveing both global and instance-specific configurations.

Parameters:
$widgetconfigs Contains the array of configuration settings
$containsFileUploadFields Must be set to true if the configuration form has file upload fields
$widgetinstanceid Instance ID of the widget for which to get the instance-specific configurations, for global settings must be -1.
$isglobal Must be set to true if handling global settings, else false.
Returns:
see description.

Initially load the default global configurations in the $formValues array

For those configurations which are set, overwrite the $formValues array

Definition at line 727 of file widget.lib.php.

getEnabledWidgets ( pageId  ) 

Returns an array of enabled widgets and related information

Note:
The order will be sorted by widget_location, then widget_order, to sync with the way it appears in the template.
Parameters:
$pageId The page id for which to get the enabled widgets list
Returns:
Array of enabled widgets and their names, description, order and location.

Definition at line 500 of file widget.lib.php.

getFormInputField ( configentry,
value = "",
isglobal 
)

Retrieves the HTML code of a particular form element type.

Parameters:
$configentry Contains the informations about a particular configuration
$value Current value of that configuration (not default)
$isglobal Must be set to true if handling global settings, else false.
Returns:
The HTML field of that configuration along with the javascript Validation function (if any).

To make sure that any special HTML character is converted into equivalent HTML code

Definition at line 784 of file widget.lib.php.

getInheritedWidgets ( pageId  ) 

Gets the information about all the widgets which are inherited to a page via any parent page.

Parameters:
$pageId Page Id of the given page
Returns:
Array of widgets containing widgets information

Definition at line 326 of file widget.lib.php.

getWidgetGlobalConfigInfo ( widgetid  ) 

Gets the widget information and global configuration settings about a particular widget

Parameters:
$widgetid Id of the widget type
Returns:
Configuration settings, only global.

Definition at line 1093 of file widget.lib.php.

getWidgetInfo ( widgetid  ) 

Gets the widget information and global configuration settings about a particular widget

Parameters:
$widgetid Id of the widget type
Returns:
widget information like name, description, version, authorname and widget folder name.

Definition at line 1109 of file widget.lib.php.

getWidgetInstances ( widgetid  ) 

Definition at line 1263 of file widget.lib.php.

getWidgetName ( actualPath  ) 

Definition at line 563 of file widget.lib.php.

getWidgetPageConfigInfo ( widgetid  ) 

Gets the widget information and instance-specific configuration settings about a particular widget

Parameters:
$widgetid Id of the widget type
Returns:
Configuration settings, only instance-specific and not global.

Definition at line 1076 of file widget.lib.php.

handleWidgetAdmin ( pageId  ) 

Handles the global widget administration interface.

Parameters:
$pageId Id of the current page
Returns:
HTML code of the widget admin page

Initializing as global instance.

POST variables are processed inside this function

Definition at line 573 of file widget.lib.php.

handleWidgetPageSettings ( pageId  ) 

Handles the widgets configurations for a particular page

Parameters:
$pageId Page ID of the current page
Returns:
HTML code of the widget configuration interface for page settings

Todo:
Add widget builder, template editor to change the $WIDGET locations, location-visualizer etc.

POST variables are processed inside this function

Todo:
Do something about file uploads by widgets

Definition at line 155 of file widget.lib.php.

interpretSubmitValue ( conftype,
postvar,
options = NULL 
)

Interprets the submit values of individual field types in the configuration form

Parameters:
$conftype The type of the input field
$postvar The POST variable name
$options The extra options like for checkbox
Returns:
The value in string format if successful, else returns boolean false.

Definition at line 1195 of file widget.lib.php.

modifyWidgetInstanceLocation ( pageId,
widgetId,
widgetInstanceId,
mod 
)

Modify the widget location.

Parameters:
$pageId Page Id of the page in which the widget exists
$widgetId The Widget ID of the widget to relocate
$widgetInstanceId The Widget Instance ID of the widget to relocate
$mod The modification to be done in the widget location. Should start with either + or - operator, followed by a number.
Note:
The widget location cannot be negative.
Returns:
Boolean True if relocation done successfully or else False.

Definition at line 413 of file widget.lib.php.

modifyWidgetInstanceOrder ( pageId,
widgetId,
widgetInstanceId,
mod 
)

Modify the widget order.

Parameters:
$pageId Page Id of the page in which the widget exists
$widgetId The Widget ID of the widget to relocate
$widgetInstanceId The Widget Instance ID of the widget to relocate
$mod The modification to be done in the widget order. Should start with either + or - operator, followed by a number.
Returns:
Boolean True if relocation done successfully or else False.

Definition at line 431 of file widget.lib.php.

populateWidgetVariables ( pageId  ) 

Idea : A widget is a small customized html code that can be put in any part of the generated page. The template's index.php will have variables $WIDGETS[1], $WIDGETS[2] to $WIDGETS[n] where n is user-defined (its 31 for now). Each $WIDGETS[i] represents a unique-location and NOT a unique widget i.e. $WIDGETi can have multiple widgets, but in same location.

Put all the widgets inside cms/widgets folder. Every widget should have a folder by its name inside cms/widgets. Inside every folder there will be a description file consisting of widget information and usage details. Each such folder will have widget.class.php file having a class which should extend widgetFramework abstract class. The class will have abstract functions like :

initWidget() which will be called prior to widget execution. getHTML() to get the widget's output html code

Besides these, the class should also create a constructor __construct which will call the parent constructor by passing the configurations to it along with other information.

widgetFramework will implement the following functions :

__construct() to pass main information like widget id, instance id and default configurations. createWidget() will create the entry of the widget in the database along with proper settings

See also:
widgetFramework.class.php for more detailed information about implemented functions.

----------------------------------------------------------------- Database Structure :

PragyanV3_widgetsinfo table : widget_id widget_name widget_classname widget_description widget_version widget_author widget_foldername

PragyanV3_widgetsconfiginfo table : widget_id *config_name config_type config_options config_displaytext config_default is_global

PragyanV3_widgets table : widget_id *widget_instanceid page_id widget_location widget_order

PragyanV3_widgetsconfig widget_id widget_instanceid config_name config_value

PragyanV3_widgetsdata widget_id widget_instanceid widget_datakey widget_datavalue

Note:
Global configurations are the configurations which are common to all the instances of a particular widget type.

Algo ::

When a page is being opened.

For all widget_id and widget_instanceid from PragyanV3_widgets for page_id order by widget_location, widget_order widget_name = Select widget_name from PragyanV3_widgetsinfo for widget_id Include file cms/widgets/widget_name/widget.class.php widget_object = Object of class widget_name passing widget_id , page_id and widget_instanceid as parameters to constructor Check if widget is installed properly using validInstall() method and if not, do installWidget() and loadWidget() widget_object->initWidget() widget_output = widget_object->getHTML() $WIDGETS[<widget_location>] .= widget_output

Note:
All the widgets will have the power to add/remove/modify their information in PragyanV3_widgetsdata table
The widgets will be given some RAM like or heap store in _widgetsdata table to add their own information in key => value format.

For administrators. (+admin&subaction=widgets)

1) Generate the list of all the widgets based on PragyanV3_widgetinfo table. 2) When clicking on a widget, a page should be displayed with some widget informations like authorname from PragyanV3_widgetsinfo table 3) The above page should also have links to change instance-specific and universal configurations for that widget. 4) When clicked on instance-specific, a list of all the page_urls (dereferenced from page_id in PragyanV3_widgets table) is generated. 5) Clicking on any url should open a form-type configuration page based upon PragyanV3_widgetsconfiginfo and PragyanV3_widgetsconfig. 6) When clicked on universal configurations in (3), it should open a form-like page from PragyanV3_widgetglobalconfig 7) Widget Installation and Removal (LATER)

For page-admins (+widgets)

1) List of available, enabled widgets for that page. 2) Configure button to configure the enabled widgets 3) Manipulate the ordering and Location ID of the widgets. Populates the widget variables $WIDGETS[1],... $WIDGETS[n] based on the widgets enabled in that page. All the variables are then replaced in template accordingly.

Parameters:
$pageId Page ID of the page for which to populate the widgets

Definition at line 108 of file widget.lib.php.

propagateWidgetInstance ( widgetId,
widgetInstanceId 
)

Marks the widget for propagation to all child pages.

Parameters:
$widgetId Widget ID
$widgetInstanceId Instance of the widget that is to be propagated

Definition at line 351 of file widget.lib.php.

reloadWidgets (  ) 

Reloads the widgets from the widget directoty and update proper entries in database.

Parameters:
@return 

Definition at line 1259 of file widget.lib.php.

renderBoolTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Bool type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 899 of file widget.lib.php.

renderCheckboxTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Checkbox type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 930 of file widget.lib.php.

renderDatetimeTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Datetime type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 1027 of file widget.lib.php.

renderDateTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Date type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 1046 of file widget.lib.php.

renderFileTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the File type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
See also:
getFileUploadField
Returns:
true if succesful, or false if rendering failed.

Used to maintain uniformity in upload fields in the CMS

Definition at line 958 of file widget.lib.php.

renderHiddenTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Hidden type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 1012 of file widget.lib.php.

renderIntegerTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Integer type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 997 of file widget.lib.php.

renderNoinputTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Noinput type element. Will only display some text, and not take any input.

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 1066 of file widget.lib.php.

renderRadioTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Radio type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 870 of file widget.lib.php.

renderSelectTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Select type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 844 of file widget.lib.php.

renderTextareaTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Text-Area type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 829 of file widget.lib.php.

renderTextTypeField ( elementName,
value,
options,
&$  htmlOutput 
)

Renders the Text type element

Parameters:
$elementName The name of the field
$value The current value
$options The extra options related to this field type
$htmlOutput Will contain the actual HTML Output
Returns:
true if succesful, or false if rendering failed.

Definition at line 982 of file widget.lib.php.

unpropagateWidgetInstance ( widgetId,
widgetInstanceId 
)

Unmarks the widget for propagation to all child pages. So that it wont be propagated anymore.

Parameters:
$widgetId Widget ID
$widgetInstanceId Instance of the widget that is to be unpropagated

Definition at line 363 of file widget.lib.php.

updateWidgetConf ( widgetid,
widgetinstanceid = -1,
isglobal = TRUE 
)

Handles the submission of the widget configuration forms (both global and instance-specific) and updates the database.

Parameters:
$widgetid ID of the widget.
$widgetinstanceid Widget Instance ID of the widget for instance-specific configurations, default is -1 for global configurations.
$isglobal Default is set to true if handling global configurations, for instance-specific configurations must be set to false explicitly.
Note:
It uses $_POST variables implicitly to retrieve submitted form values.

If there was no submit value, then check for the current value, if even that's missing then use the default value

Definition at line 1137 of file widget.lib.php.