Difference between revisions of "Preference API"

Jump to: navigation, search
m
 
(23 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Moodle 2.0}}
 
{{Moodle 2.0}}
{| style="border: 1px solid #aaaaff; background-color: #eeeeff; width: 80%; margin: 0 auto 1em auto; padding: .2em; text-align: {{{align|left}}}"
+
==Overview==
|{{{image|}}}
+
 
| '''WORK IN PROGRESS: I've currently just created a template, so please ignore this page until this wip notices has been removed.''' However, you are free to help in the construction of this page by improving it. Please review the [{{SERVER}}{{localurl:{{NAMESPACE}}:{{PAGENAME}}|ac tion=history}} edit history] if you would like to contact the user who put up this notice. If this article has not been edited by that user in a while, please remove this template.
+
The Preference API has been implemented in lib/moodlelib.php. It's used for the storage and retrieval of user preferences. These preferences are stored in the database for users with an account, however for guests or people who are not logged in the preferences are stored in a PHP Session. All of these functions operate on the current user by default, however you can specify the user you wish to operate on by passing a user ID or a moodle user object to the $user parameter. Normally this is used for state indicators, where it can be as simple as a yes or no, however you can also use it to store more complex user data, such as a serialized PHP object.
|}
+
 
<noinclude>
+
It is considered good practice to abstain from storing default values as a user preference as this creates a lot of redundancy. Instead you should apply the default value at the code level if there is no stored value for a given preference.
 +
 
 +
====get_user_preferences($name = null, $default = null, $user = null)====
 +
This function can be used to fetch the value of a requested (via $name) preference, or if it doesn't exist the value given in the $default parameter will be returned. If you do not specify a $name then all preferences will be returned.
 +
 
 +
====set_user_preference($name, $value, $user = null)====
 +
This function can be used to set the value of a preference named $name.
 +
 
 +
====set_user_preferences(array $prefarray, $user = null)====
 +
This function takes an array called $prefarray. For each element in the array this function passes the keys and values of each element as the $name and $value parameters (respectively) in calls to set_user_preferences().
  
 +
====unset_user_preference($name, $user = null)====
 +
This deletes the requested preference, specified by the $name parameter.
  
==Objectives==
+
==Preference API Usage==
  
The goals of Preferences API:
+
===Example usage===
  
* example goal
+
<code php>
 +
// Set a preference and then retrieve it
 +
set_user_preference('foo_nameformat', 'long');
 +
get_user_preferences('foo_nameformat') // Returns the string - "long"
  
 +
// Set another preference and then retrieve all preferences
 +
set_user_preference('foo_showavatars', 'no');
 +
get_user_preferences(); /*
 +
Returns array(
 +
    foo_nameformat  => "long"
 +
    foo_showavatars => "no"
 +
)
 +
*/
  
==Overview==
+
// Add an array of preferences and change foo_nameformat to short
 +
$listOfPreferences = array('foo_displaynum'=>'100', 'foo_nameformat'=>'short');
 +
set_user_preferences($listOfPreferences);
 +
get_user_preferences(); /*
 +
Returns array(
 +
    foo_nameformat  => "short"
 +
    foo_showavatars => "no"
 +
    foo_displaynum  => "100"
 +
)
 +
*/
  
Preference API provides following functionalities:
+
// Delete a preference
# example functionality
+
unset_user_preference('foo_showavatars');
 +
get_user_preferences(); /*
 +
Returns array(
 +
    foo_nameformat  => "short"
 +
    foo_displaynum  => "yes"
 +
)
 +
*/
 +
</code>
  
 
==Preference API database table==
 
==Preference API database table==
 +
 +
Note: This shows the schema for Moodle 2.2, earlier version had smaller limits on some of the fields. If you are not using Moodle 2.2, then please refer to whatever database administration tool you may be using.
  
 
{| class="nicetable"
 
{| class="nicetable"
Line 29: Line 69:
 
|-
 
|-
 
| id
 
| id
| int(10)
+
| unsigned int(10)
 
| auto-incrementing
 
| auto-incrementing
 
| The unique ID for this preference.
 
| The unique ID for this preference.
 
|-
 
|-
 
| userid
 
| userid
| int(10)
+
| unsigned int(10)
|
+
|  
 
| The user that the preference belongs to
 
| The user that the preference belongs to
 
|-
 
|-
| examplefield
+
| name
|  
+
| varchar(255)
|
 
|
 
|-
 
| timecreated
 
| int(10)
 
 
|
 
|
|  
+
| The name of the preference
 
|-
 
|-
| timemodified
+
| value
| int(10)
+
| varchar(1333)
|
 
 
|
 
|
 +
| The value of the preference
 
|}
 
|}
  
==Use Preference API==
+
==See also==
 
 
===Title for the example goes here===
 
 
 
Description of the example:
 
 
 
<code php>
 
shortexamplecode();
 
</code>
 
 
 
===Title for the second example goes here===
 
 
 
Description of the example:
 
 
 
<code php>
 
shortexamplecode();
 
</code>
 
 
 
==Preference API overview==
 
 
 
The Preference API has been implemented in lib/moodlelib.php.
 
  
====examplefunction()====
+
* [[Core APIs]]
Example function description.
 
  
==See also==
+
[[Category:API]]

Latest revision as of 05:52, 8 February 2012

Moodle 2.0


Overview

The Preference API has been implemented in lib/moodlelib.php. It's used for the storage and retrieval of user preferences. These preferences are stored in the database for users with an account, however for guests or people who are not logged in the preferences are stored in a PHP Session. All of these functions operate on the current user by default, however you can specify the user you wish to operate on by passing a user ID or a moodle user object to the $user parameter. Normally this is used for state indicators, where it can be as simple as a yes or no, however you can also use it to store more complex user data, such as a serialized PHP object.

It is considered good practice to abstain from storing default values as a user preference as this creates a lot of redundancy. Instead you should apply the default value at the code level if there is no stored value for a given preference.

get_user_preferences($name = null, $default = null, $user = null)

This function can be used to fetch the value of a requested (via $name) preference, or if it doesn't exist the value given in the $default parameter will be returned. If you do not specify a $name then all preferences will be returned.

set_user_preference($name, $value, $user = null)

This function can be used to set the value of a preference named $name.

set_user_preferences(array $prefarray, $user = null)

This function takes an array called $prefarray. For each element in the array this function passes the keys and values of each element as the $name and $value parameters (respectively) in calls to set_user_preferences().

unset_user_preference($name, $user = null)

This deletes the requested preference, specified by the $name parameter.

Preference API Usage

Example usage

// Set a preference and then retrieve it
set_user_preference('foo_nameformat', 'long');
get_user_preferences('foo_nameformat') // Returns the string - "long"
 
// Set another preference and then retrieve all preferences
set_user_preference('foo_showavatars', 'no');
get_user_preferences(); /*
Returns array(
    foo_nameformat  => "long"
    foo_showavatars => "no"
)
*/ 
 
// Add an array of preferences and change foo_nameformat to short
$listOfPreferences = array('foo_displaynum'=>'100', 'foo_nameformat'=>'short');
set_user_preferences($listOfPreferences);
get_user_preferences(); /*
Returns array(
    foo_nameformat  => "short"
    foo_showavatars => "no"
    foo_displaynum  => "100"
)
*/
 
// Delete a preference
unset_user_preference('foo_showavatars');
get_user_preferences(); /*
Returns array(
    foo_nameformat  => "short"
    foo_displaynum  => "yes"
)
*/

Preference API database table

Note: This shows the schema for Moodle 2.2, earlier version had smaller limits on some of the fields. If you are not using Moodle 2.2, then please refer to whatever database administration tool you may be using.

Field Type Default Info
id unsigned int(10) auto-incrementing The unique ID for this preference.
userid unsigned int(10) The user that the preference belongs to
name varchar(255) The name of the preference
value varchar(1333) The value of the preference

See also