Preferences API

This is a technical summary of what is offered by our Preferences API and how to create your own Preferences within Cornerstone.

  1. Preference Data
  2. Preference UI
  3. Preference Functions

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