CKFinder 3 Documentation

User Settings

The aim of this article is to explain how to manage user settings in CKFinder.

About User Settings

CKFinder includes a settings panel that can be opened by the user with the Settings button. Its main purpose is to offer the user the possibility to adjust selected bits of CKFinder configuration to one's needs.

By default CKFinder allows the user to adjust thumbnail size and limit the amount of displayed information about the file. CKFinder API allows you to define additional, custom user settings.

Settings values are persistent — they are stored in the user browser local storage, so they are available after the user closes and opens the browser again.

Creating Settings

In order to provide custom settings, use the settings:define request. Settings are stored in groups so they are visually separated from other settings. The following types of settings can be created:

  • checkbox – Stores the {Boolean} type of data. It renders as checkbox elements.
  • hidden – Stores a {String} value that is not displayed and cannot be changed.
  • radio – Stores a {String} value that can be only one from the defined values. It renders as radio buttons.
  • range – Stores the {Numeric} type of data whose values are within the given range and can change only by a given step size.
  • select – Stores a {String} value that can be only one from the defined values. It renders as a select drop-down list.
  • text – Stores a {String} value. It renders as a text input element.

Setting values are automatically stored in the local storage. The setting type and attributes are not stored, so you can safely change the setting type when updating the plugin.

Reading Setting Values

You can read the current value of a setting using the settings:getValue request. To set a value of a setting use the settings:setValue request.

When a setting value is changed by the user, the setting:change:GROUP and setting:change:GROUP:NAME events are fired. The first event gives you the values of the entire group and the name of the modified setting, the latter only returns the modified setting value.

Enabling and Disabling Settings

Each (with the exception of the hidden type) setting is rendered in the settings panel. Using dedicated requests, it is possible to settings:enable and settings:disable selected settings.

Example

Check the SettingsDemo plugin for a complete example of using CKFinder settings.