====== Widget Management ======

By default in Wizard's Toolkit each user has their own dashboard of widgets.  These widgets give them important stats and information regarding the website.  Some pre-defined widgets are included with Wizard's Toolkit and any developer with a little SQL knowledge can easily create unlimited custom widgets.

In the back office (located at /admin/ by default), under **Client Control** you can see both "Widgets" and "Widget Groups".

First create Widgets and then assign them to Widget Groups.

===== Widget Creation =====

When defining a widget you choose the following:

  * Widget Name
  * Security Level - only users with this security level or higher will be able to see these widgets
  * Widget Type - List, Chart or Counter
  * Widget Color - only applicable for Counter widget types
  * Chart Type - only applicable for Chart widget types
  * Link to Page - if you want the widget to be clickable so clicking will navigate to a page
  * Use Modal Window - only applicable if "Link to Page" has a value, will open link in modal window
  * Skip Footer - only applicable for Counter widget types, will skip showing footer with row counts 
  * Description - this will show on widget
  * SQL - this will generate the data shown on widget

Note, if you are making a List widget and the list has links for navigation you should not also use "Link to Page" because then both will trigger.

===== Widget Groups =====

When defining a widget group you choose the following:

  * Widget Group Name
  * Security Level for Defaults
  * Staff Role for Defaults
  * Use for Personal Dashboard default - checkbox for Yes or No

Note that programmatically you can ignore the security level and staff role functionality.  You could make it so all users have access to these "Widget Dashboards" quite easily.  Ask and I will send demo code.

If the "Use for Personal Dashboard default" checkbox is checked then this widget set will be copied to the user's personal set of widgets the first time they visit the dashboard if they do not already have personal widgets.

===== wtkWidgetGroup_X_Widget =====

This data table is used as a many-to-many SQL table to associate wtkWidgets with wtkWidgetGroups.

Data columns include:

  * UID
  * AddDate
  * WidgetGroupUID
  * UserUID
  * WidgetUID
  * WidgetPriority - used to determine position of widget on dashboard

If **UserUID** is NULL then the Widget Group set is considered the Master Set.  User's cannot modify this in any way.  This can only be managed in the Back Office.

When a dashboard needs to be edited by a user, simply copy the WidgetGroup and fill the wtkWidgetGroup_X_Widget.UserUID value with the wtkUsers.UID value.  Then the user will be able to add, delete and re-prioritize widgets for their own dashboard.

===== Defaulting Widgets to User Dashboard =====

The logic used to determine if a widget set is copied to a user is as follows:

  * If user already has at least one personal widget then skip.
  * Otherwise check to see if there is a Widget Group with a Staff Role that matches the wtkUsers.StaffRole.  If so, copy that WidgetGroup regardless of SecurityLevel.
  * If there is not a matching StaffRole WiddgetGroup, then check to see if there is a matching SecurityLevel.  If so, copy that WidgetGroup.

The "copy" process copies the `wtkWidgetGroup_X_Widget` data for the associated wtkWidgetGroup with NULL UserUID values making the new set contain the wtkUsers.UID in the wtkWidgetGroup_X_Widget.UserUID value.

===== Use Widgets to Update Data and Refresh Widget =====

In the WTK Admin website if you have the Widget "Link to Page" and make that page "Use Modal Window", you can easily allow editing of data and have it update the widget upon saving.

The **/wtk/widgets.php** page automatically passes `wtkWidgets`.`UID` to the **wtkModal** JS function which is passed as **id** parameter.  The PHP page you have it call will automatically store that value in the $gloId global variable.

In your PHP page have the update buttons defined as follows:

<code PHP>
$pgBtns = wtkModalUpdateBtns('../wtk/lib/Save','widgetRefresh');
</code>

Make certain your PHP has the form defined as:

<code PHP>
<form id="FwidgetRefresh" method="POST">
</code>

Also in your PHP add this code to put the `wtkWidgets`.`UID` into a hidden field.

<code PHP>
$pgHtm .= wtkFormHidden('WidgetUID', $gloId);
</code>


The "widgetRefresh" is then sent back via the **modalSave** JS function.  That retrieves the hidden WidgetUID value and passes it back via an AJAX call to **/wtk/widgets.php**.  Normally widgets.php returns several widgets but when called this way it receives the UID and returns only the specific Widget requested, updating it on the dashboard.