Ninja_widget_Model Class Reference

A widget consists of four (or, well, five) identifying pieces of information. More...

Public Member Functions

 __construct ($db_row)
 You should not call this constructor directly!
 save ()
 Save any changes to the widget.
 merge_settings ($new_setting)
 Given an array of new settings, update the local settings with those.
 copy ()
 Create new instance of widget and save.
 delete ()
 Deletes a copy of a widget.

Static Public Member Functions

static fetch_all ($page)
 Fetches a list of widget names for a given page.
static get ($page, $widget, $instance_id=null)
 Fetch info on a saved widget for a page.
static install ($page, $name, $friendly_name)
 Add a new widget to ninja_widgets table.
static uninstall ($name)
 Remove any instance of a widget from the ninja_widgets stable Scary to expose to end users, as it does no authorization checks.
static update_all_widgets ($page=false, $value=false, $type='refresh_interval')
 Update setting for all widgets on a page.
static fetch_widget_order ($page=false)
 Parse the widget order for use on a page.
static set_widget_order ($page, $widget_order)
 Given a structure like array(placeholder1 => array(widget1, widget2, widgetn), placeholder2 => array(.
static rename_widget ($old_name, $new_name)
 DANGER WILL ROBINSON! This makes a ton of assumptions, and should only be called after much consideration.
static rename_friendly_widget ($old_name, $new_name)
 Renames the friendly name of a widget.

Data Fields

const FIRST_INSTANCE_ID = 1
 When getting "any" instance of a widget, we will specifically look for this.
 $name
 The internal name of the widget.
 $page
 The page the widget is shown on.
 $instance_id
 The widget's instance id.
 $username
 The user's username.
 $setting
 The widget's settings.

Detailed Description

A widget consists of four (or, well, five) identifying pieces of information.

It has a name. The name links it to the on-disk PHP files.

It has a page. This means the same widget can/will look different depending on your URL.

It has a user. This means that different users see the same widget differently.

It has an instance id. This means that the same user can see the same widget multiple times on the same page, with different options in each.

(there's also an ID column, but it's pretty useless)

When showing a widget, we first try to find a widget with the same page, user and instance id. If that's not possible, we fall back to the same page and user, but any id we can find, then to the same page but with blank user and id, and then to the 'tac/index' page with a blank user and id. When returning data from this model, nobody should have to bother about whether the widget information was returned from a fallback or not.

(If you have a clever, quick, cross-database solution to do this whole thing in-database, please don't hesitate to do it)

We no longer send hidden default widgets to the user. We must thus send empty widget instances that the user can copy into their own namespace.

Saving an edited widget must never save to any of the fallback options. In particular, for legacy systems, that means we must never write to anything with an empty instance id. FIXME: tested?

There are two add/remove pairs of functions: install/uninstall, and copy/delete. The first pair works globally, the second per-user.


Constructor & Destructor Documentation

Ninja_widget_Model::__construct ( db_row  ) 

You should not call this constructor directly!

What you're looking for is probably get.


Member Function Documentation

Ninja_widget_Model::copy (  ) 

Create new instance of widget and save.

Returns:
A widget object for the copy
static Ninja_widget_Model::fetch_all ( page  )  [static]

Fetches a list of widget names for a given page.

Parameters:
$page The page name
Returns:
array of Ninja_widget_Model objects - not all of them with ID's!
static Ninja_widget_Model::get ( page,
widget,
instance_id = null 
) [static]

Fetch info on a saved widget for a page.

Parameters:
$page The page the widget is to be shown at
$widget The widget name to retrieve
$instance_id The instance_id to retrieve. Sending in NULL will create a new widget
Returns:
A widget object, or false if none could be found matching the input
static Ninja_widget_Model::install ( page,
name,
friendly_name 
) [static]

Add a new widget to ninja_widgets table.

Parameters:
$page The name of the page this should be displayed on - usually 'tac/index'
$name The internal name of the widget
$friendly_name The widget name that users should see
Returns:
false on error, true otherwise
Ninja_widget_Model::merge_settings ( new_setting  ) 

Given an array of new settings, update the local settings with those.

Any preexisting settings not in $new_setting will be kept around. This does not write to database - see save()

Parameters:
$new_setting Array of new settings to overwrite the old ones with
static Ninja_widget_Model::rename_friendly_widget ( old_name,
new_name 
) [static]

Renames the friendly name of a widget.

Friendly name is the name shown on widget title bar.

Ninja_widget_Model::save (  ) 

Save any changes to the widget.

If the widget is new or not yet copied to the user's own widgets, a new ID and instance ID will be chosen.

static Ninja_widget_Model::set_widget_order ( page,
widget_order 
) [static]

Given a structure like array(placeholder1 => array(widget1, widget2, widgetn), placeholder2 => array(.

..)) serialize it and save it in the database.

static Ninja_widget_Model::uninstall ( name  )  [static]

Remove any instance of a widget from the ninja_widgets stable Scary to expose to end users, as it does no authorization checks.

Parameters:
$name The name of the widget to uninstall

The documentation for this class was generated from the following file:
 All Data Structures Functions Variables

Generated on 22 Nov 2012 for ninja by  doxygen 1.6.1