Preferences API
This is a technical summary of what is offered by our Preferences API and how to create your own Preferences within Cornerstone.
Preferences offer a nice a way to change the UI based on. For the most part they control the internal UI, however this data can also be used in the backend. In our examples we are going to be creating a custom preference named custom_preference. Join us as we extend the Preferences of Cornerstone.
Preference Data
All preference data is stored in usermeta under cs_app_preferences as a serialized associative array. It initially uses the defaults unless set by a user.
Changing the Default Preferences
The filter cs_app_preference_defaults can be used to change the default preferences
// Filter to change default preferences
add_filter('cs_app_preference_defaults', function($defaults) {
// Workspace defaults to left
$defaults['workspace_side'] = 'left';
// Set default of our custom preference
$defaults['custom_preference'] = true;
return $defaults;
});Preference UI
The preference ui controls can be extend through the filter cs_preference_controls. Adding a new group or item is preferred to adding to one of the built in Cornerstone groups. In the future a function to combine the actions of setting defaults and adding controls will be created to streamline this setup.
// Extend preference controls
add_filter("cs_preference_controls", function($controls) {
// Add a custom group to preferences
$controls[] = [
'type' => 'group',
'label' => __( 'Custom Preference Group', 'cornerstone' ),
'controls' => [
// Single control item
// @see element api
[
// Key we created a default for earlier
'key' => 'custom_preference',
'type' => 'toggle',
'label' => __('Custom Preference', 'cornerstone'),
],
]
];
return $controls;
});Preference Functions
@since CS 7.4.0
The following helper functions are offered to interact with the Preference data. Sending null to any of the functions that have a $user_id parameter will result in using the current users preferences.
Preference Function Sample
The following is a basic example using the preference we created earlier
add_action("init", function() {
// Using our preference from earlier
// echo "Hello World"
$ourCustomPreference = cs_preference_user("custom_preference");
if ($ourCustomPreference) {
echo "Hello World";
}
});Function List
/**
* Gets alls preferences for a given user
* or if null, the current user
*
* @param mixed $user_id
*
* @return array
*/
function cs_preferences_user($user_id = null);
/**
* Gets singular preference by key for a given user
* or if null, the current user
*
* @param string $key
* @param mixed $fallback value to use when no preference set
* @param mixed $user_id
*
* @return array
*/
function cs_preference_user($key, $fallback = null, $user_id = null);
/**
* Gets all preferences in Cornerstone system
*
* @return array
*/
function cs_preferences();See something inaccurate? Let us know