CKFinder.Config
Configuration settings for CKFinder. To change the settings, edit the <ckfinder>/config.js
file or pass configuration
options when instantiating CKFinder:
var config = {};
config.language = 'de';
CKFinder.popup( config );
or even shorter:
CKFinder.popup( {
language: 'de'
} );
Configuration for CKFinder might be set in many different ways:
- By changing the contents of the
<ckfinder>/config.js
file (see also configPath). - By calling the global CKFinder.config method.
- By passing configuration options to one of CKFinder API methods when creating an instance of CKFinder.
- By passing the parameters of a page that contains a CKFinder instance as an URL query string (works only if CKFinder is launched as a full-page application using CKFinder.start).
Default configuration options are overridden by above methods in the given order.
For example the language defined in the config.js
file will be discarded by instance configuration passed
to the CKFinder.widget method.
Config options
Configures the timeout in seconds after which HTML5 uploads are automatically closed when all files are uploaded without
errors or warnings. Set to false
to disable — the user will have to close the HTML5 upload interface manually.
// Close the uploads UI after 3.5 seconds.
config.autoCloseHTML5Upload = 3.5;
// Do not close uploads.
config.autoCloseHTML5Upload = false;
Defaults to: 5
Enables the file selection menu and toolbar items.
config.chooseFiles = true;
Defaults to: false
Automatically closes the CKFinder popup on file selection. If set to false
, you must close the CKFinder popup manually
by running the closePopup
request.
Defaults to: true
Enables file selection with double click. This option works when CKFinder is integrated with CKEditor
or when chooseFiles is set to true
.
config.chooseFilesOnDblClick = false;
Defaults to: true
The size of icon in compact view. Available sizes are:
- 16
- 22
- 32
- 48
Defaults to: 22
Available since: 3.4
Configuration file location relative to basePath
(CKFinder location). Can be also set to an absolute URL.
Note: This option can be only set inline when creating a CKFinder instance.
CKFinder.widget( 'ckfinder-widget', {
configPath: '/path/to/my-config.js'
} );
For maximum performance, it is possible to instruct CKFinder to skip loading the configuration completely by passing the inline configuration option set to an empty string when creating CKFinder:
CKFinder.widget( 'ckfinder-widget', {
configPath: '',
// Set other required configuration options inline.
language: 'de'
} );
You can also add parameters to config.js
to enforce the browser to require a new version of this file without using cache.
CKFinder.widget( 'ckfinder-widget', {
// Old setting was configPath: 'config.js?timestamp=20160101'
configPath: 'config.js?timestamp=20160808'
} );
Defaults to: 'config.js'
Additional (GET) parameters to send to the server with each request. The value of this configuration is appended to the query string of each server request.
config.connectorInfo = 'token=7901a26e4bc422aef54eb45';
See also pass
Defaults to: ''
The server-side connector language.
Do not change this option unless you write your own server connector for CKFinder.
Defaults to: 'php'
The path to the server-side connector. The default value is different between various server-side versions of CKFinder.
config.connectorPath = '/path/to/custom/server/connector.php';
Defaults to: ''
The path to CKFinder's structure CSS file. This file contains CSS for widgets like file thumbnails or folders tree.
config.coreCSS = 'some/path/ckfinder.css';
Defaults to: 'skins/core/ckfinder.css'
Whether to display the modification time in the files pane.
config.defaultDisplayDate = false;
Note: This setting sets the default value which will be used during the first launch of CKFinder. In order to test it you might need to clear cookies (local storage) or check it in Incognito mode. CKFinder automatically remembers user settings and uses them instead of default values on consecutive visits.
Defaults to: true
Whether to display file names in the files pane.
config.defaultDisplayFileName = false;
Note: This setting sets the default value which will be used during the first launch of CKFinder. In order to test it you might need to clear cookies (local storage) or check it in Incognito mode. CKFinder automatically remembers user settings and uses them instead of default values on consecutive visits.
Defaults to: true
Whether to display the size of a file in the files pane.
config.defaultDisplayFileSize = false;
Note: This setting sets the default value which will be used during the first launch of CKFinder. In order to test it you might need to clear cookies (local storage) or check it in Incognito mode. CKFinder automatically remembers user settings and uses them instead of default values on consecutive visits.
Defaults to: true
The language to be used if language is left empty and it is not possible to localize the application to the user language.
config.defaultLanguage = 'it';
Defaults to: 'en'
The default sort by option.
Available sort options:
'name'
– Files will be sorted by file name.'size'
– Files will be sorted by size.'date'
– Files will be sorted by date.config.defaultSortBy = 'size';
Note: This setting sets the default value which will be used during the first launch of CKFinder. In order to test it you might need to clear cookies (local storage) or check it in Incognito mode. CKFinder automatically remembers user settings and uses them instead of default values on consecutive visits.
Defaults to: 'name'
Available since: 3.2
The default sort order option.
Available sort options:
'asc'
– Files will be sorted ascending.'desc'
– Files will be sorted descending.config.defaultSortByOrder = 'desc';
Note: This setting sets the default value which will be used during the first launch of CKFinder. In order to test it you might need to clear cookies (local storage) or check it in Incognito mode. CKFinder automatically remembers user settings and uses them instead of default values on consecutive visits.
Defaults to: 'asc'
Available since: 3.2
The default files pane view.
Available view types:
'thumbnails'
– The "thumbnails" mode will display each file as a "box". For images, a small preview of it (called thumbnail) will be displayed inside the box. For other files, an icon will be available instead.'list'
– The "list" mode will display all files as a list, one below the other. No image previews are available in this mode.'compact'
– The "compact" mode will display all files in columns. No image previews are available in this mode.config.defaultViewType = 'list';
Note: This setting sets the default value which will be used during the first launch of CKFinder. In order to test it you might need to clear cookies (local storage) or check it in Incognito mode. CKFinder automatically remembers user settings and uses them instead of default values on consecutive visits.
Defaults to: 'thumbnails'
Available since: 3.2
Sets the automatic focus for dialogs. If set to true
, the dialog will focus the first found form element
— input, select or textarea. If dialogFocusItem
is a string, it is used as a jQuery selector used to find
elements to focus.
config.dialogFocusItem: '.my-class'
Defaults to: true
Sets the minimal height of the dialog content pane (excluding the title bar and buttons).
config.dialogMinHeight: '400px'
Defaults to: '4em'
Sets the minimal width of the dialog content pane.
config.dialogMinWidth: '600px'
Defaults to: '18em'
Defines an overlay swatch setting for the jQuery mobile widget when building the dialog. If set to false
, the overlay
will not have a swatch setting applied. If set to true
, the current config.swatch will be applied.
The "moono" skin forces true
for this setting.
CKFinder.start( {
skin: 'jquery-mobile',
dialogOverlaySwatch: 'b'
} );
CKFinder.start( {
skin: 'jquery-mobile',
swatch: 'c',
dialogOverlaySwatch: true // Will apply 'c' swatch.
} );
Defaults to: false
Changes the folders display mode. When set to true
, folders are displayed as a tree in the primary panel. When set to
false
, folders are displayed inline with files, there is no folders tree, and breadcrumbs are displayed.
Defaults to: true
Adjustment sliders available in the image editing interface. The names of sliders are taken from the CamanJS built-in filters. The full list of sliders:
config.editImageAdjustments = [
'brightness', 'clip', 'contrast', 'exposure', 'gamma', 'hue', 'noise', 'saturation', 'sepia',
'sharpen', 'stackBlur', 'vibrance'
];
Defaults to: ['brightness', 'contrast', 'exposure', 'saturation', 'sepia', 'sharpen']
Presets available in the image editing interface. The names of presets are taken from the CamanJS presets example. The full list of presets:
config.editImagePresets = [
'clarity', 'concentrate', 'crossProcess', 'glowingSun', 'grungy', 'hazyDays', 'hemingway', 'herMajesty',
'jarques', 'lomo', 'love', 'nostalgia', 'oldBoot', 'orangePeel', 'pinhole', 'sinCity', 'sunrise', 'vintage'
];
Defaults to: ['clarity', 'herMajesty', 'nostalgia', 'pinhole', 'sunrise', 'vintage']
The map of file extensions for the file icon name. File icons are loaded from the folder defined in config.fileIconsPath.
Required icons are 'default'
(an icon displayed for all files if an icon for a file type cannot be found) and 'folder'
(used
for folders when config.displayFoldersPanel is set to false
).
// Use only file icons for pdf.
config.fileIcons: {
'default': 'unknown.png',
'folder': 'directory.png',
'pdf': 'pdf.png'
}
Defaults to: {'default': 'unknown.png', folder: 'directory.png', '7z': '7z.png', accdb: 'access.png', avi: 'video.png', bmp: 'image.png', css: 'css.png', csv: 'csv.png', doc: 'msword.png', docx: 'msword.png', flac: 'audio.png', gif: 'image.png', gz: 'tar.png', htm: 'html.png', html: 'html.png', jpeg: 'image.png', jpg: 'image.png', js: 'javascript.png', log: 'log.png', mp3: 'audio.png', mp4: 'video.png', odg: 'draw.png', odp: 'impress.png', ods: 'calc.png', odt: 'writer.png', ogg: 'audio.png', opus: 'audio.png', pdf: 'pdf.png', php: 'php.png', png: 'image.png', ppt: 'powerpoint.png', pptx: 'powerpoint.png', rar: 'rar.png', README: 'readme.png', rtf: 'rtf.png', sql: 'sql.png', tar: 'tar.png', tiff: 'image.png', txt: 'plain.png', wav: 'audio.png', weba: 'audio.png', webm: 'video.png', xls: 'excel.png', xlsx: 'excel.png', zip: 'zip.png'}
The path to the root folder that contains file icons. Icons are stored in subfolders named after file icon sizes defined in fileIconsSizes.
config.fileIconSizes = '128,32';
config.fileIconsPath = 'my/path/';
// Server must contain paths: 'my/path/128/' and 'my/path/32'.
Defaults to: 'skins/core/file-icons/'
Available icon sizes in fileIconsPath used when rendering file thumbnails. Define sizes in a descending order as comma-separated values. When changing the available icon size, check thumbnail settings such as thumbnailDefaultSize, thumbnailMinSize and thumbnailMaxSize. File icons are not scaled up when changing the thumbnail size.
// Use fewer icon sizes
config.fileIconSizes = '256,64,32';
Defaults to: '256,128,64,48,32,22,16'
The height of CKFinder application, in a relative or absolute value, e.g. 30px, 5em. Note: Percentage units (e.g. 30%) are not supported yet.
config.height = 500;
config.height = '25em';
config.height = '300px';
Defaults to: 400
The path to additional icons. Usually provided by a custom skin. Icon classes must be compatible with jQuery Mobile.
Defaults to: ''
The ID of the CKFinder instance. An optional setting used to distinguish various CKFinder instances. Instances with the same ID will share the same user runtime settings across the web application.
If the ID is not set, all CKFinder instances within the same domain will share the user settings (e.g. the last opened folder, whether to display file size/name, the preferred size of thumbnails).
CKFinder.start( { id: 'myCKFinderNo1' } );
If the ID should be passed to the server connector with each request, it needs to be added in the pass option. Unlike in CKFinder 2.x, this is not done automatically.
CKFinder.start( { id: 'myCKFinderNo1', pass: 'id' } );
Defaults to: ''
Passes the path to jQuery. Useful to load jQuery from CDN.
config.jquery = '//code.jquery.com/jquery-2.1.0.js';
Defaults to: 'libs/jquery.js'
Passes the path to jQuery Mobile. Useful to load jQuery Mobile from CDN.
config.jqueryMobile = '//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js';
Defaults to: 'libs/jquery.mobile.js'
The path to the jQuery Mobile icons CSS file. CKFinder does not use jQuery Mobile icons, so set this if you want to use the icons from jQuery Mobile. Useful to load jQuery Mobile CSS files from CDN.
config.jqueryMobileIconsCSS = '//code.jquery.com/mobile/1.4.5/jquery.mobile.icons-1.4.5.min.css';
Defaults to: ''
The path to the jQuery Mobile structure CSS file. Useful to load jQuery Mobile CSS files from CDN.
config.jqueryMobileStructureCSS = '//code.jquery.com/mobile/1.4.5/jquery.mobile.structure-1.4.5.min.css';
Defaults to: 'libs/jquery.mobile.structure.css'
The user interface language localization to use. If empty, CKFinder automatically localizes the application to the user language, if supported, otherwise the defaultLanguage language is used.
// Load the Polish interface.
config.language = 'pl';
Defaults to: ''
Map of available language files used to determine supported language when detecting browser language. Also allows to add your own language file. The name of the language should be in lower case and be compatible with navigator.language.
// Allow only certain languages to be detected.
config.languages = { en: 1, pl: 1, fr: 1 };
Defaults to: {'az': 1, 'bg': 1, 'bs': 1, 'ca': 1, 'cs': 1, 'cy': 1, 'da': 1, 'de': 1, 'de-ch': 1, 'el': 1, 'en': 1, 'eo': 1, 'es': 1, 'es-mx': 1, 'et': 1, 'eu': 1, 'fa': 1, 'fi': 1, 'fr': 1, 'gu': 1, 'he': 1, 'hi': 1, 'hr': 1, 'hu': 1, 'it': 1, 'ja': 1, 'ko': 1, 'ku': 1, 'lt': 1, 'lv': 1, 'nb': 1, 'nl': 1, 'nn': 1, 'no': 1, 'pl': 1, 'pt-br': 1, 'ro': 1, 'ru': 1, 'sk': 1, 'sl': 1, 'sr': 1, 'sv': 1, 'tr': 1, 'uk': 1, 'uz-cyrl': 1, 'uz-latn': 1, 'vi': 1, 'zh-cn': 1, 'zh-tw': 1}
The size of icon in list view. Available sizes are:
- 16
- 22
- 32
- 48
Defaults to: 22
Available since: 3.2
If configured, it adds an overlay for the jQuery mobile loader widget. If set to false
, the overlay will not be added.
If set to true
, the current config.swatch will be applied.
The "moono" skin forces true
for this setting.
CKFinder.start( {
skin: 'jquery-mobile',
loaderOverlaySwatch: 'b'
} );
CKFinder.start( {
skin: 'jquery-mobile',
swatch: 'c',
loaderOverlaySwatch: true // Will apply 'c' swatch.
} );
Defaults to: false
The callback function to be executed when CKFinder is initialized. The callback function receives the CKFinder.Application instance object.
CKFinder.popup( {
onInit: function( finder ) {
console.log( 'Now I have a CKFinder instance!' );
}
} );
Parameters
- finder : CKFinder.Application
Comma-separated list of parameters that will be additionally passed to the server connector with each request.
Passing additional data with each request might be really useful together with a custom logic on the server side. E.g. a unique token may be used to set different server-side paths for uploaded files, depending on the context where CKFinder is used.
config.pass = 'token';
// Set the actual value to be passed.
config.token = '7901a26e4bc422aef54eb45';
Sample Ajax request performed by CKFinder with the configuration above:
http://example.com/ckfinder/connector.php?command=GetFiles¤tFolder=%2F&langCode=en&token=7901a26e4bc422aef54eb45
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In a way this option duplicates config.connectorInfo, however, it allows for even more (see below).
It is possible to set argument values in the query string when CKFinder is launched using ckfinder.html
.
This may be particularly useful when manually integrating CKFinder with CKEditor.
// In config.js:
config.pass = 'token';
// Option passed in the query string:
http://example.com/ckfinder.html?token=7901a26e4bc422aef54eb45
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the situation above, Ajax requests sent by CKFinder to the server connector will also contain token
.
Defaults to: ''
List of additional plugins to be loaded. This is a tool for loading optional plugins for CKFinder. It can be either a comma-separated list of plugin names or an array. When passing an array it is possible to define the plugin location as a relative or absolute directory in the CKFinder installation or as a full URI to an external resource.
config.plugins = 'MyPlugin';
config.plugins = [
'MyPlugin',
'plugins/Plugin/Plugin, // Load from a path relative to the ckfinder.js file.
'http://example.com/ckfinder-plugins/plugin/plugin.js'
];
Defaults to: ''
Sets the width of the primary panel (left in LTR and right in RTL) and overrides the jQuery Mobile panel width CSS settings. Affects all panels on the left side of the view.
config.primaryPanelWidth = '15em'
Defaults to: ''
If this configuration option is set to true
, CKFinder will work in read-only mode, so the
user will be able to browse the files but will not be able to introduce any changes. Thanks to
this setting you will be able to use CKFinder as an online gallery. This setting is really a shortcut for
disabling modules by config.removeModules with the list of modules set
to CreateFolder,DeleteFile,DeleteFolder,EditImage,FilesMoveCopy,FormUpload,Html5Upload,RenameFile,RenameFolder,UploadFileButton
Note: This will only disable certain UI elements. In order to successfully block file uploads or modifications you will need to adjust ACL settings accordingly in the server-side configuration file.
config.readOnly = true;
Defaults to: false
Exclude additional modules when config.readOnly is set to true
.
// This will also disable the Maximize module in readOnly mode.
config.readOnlyExclude = 'Maximize';
Defaults to: ''
Whether CKFinder should remember the last used folder in the local storage and open it automatically next time.
config.rememberLastFolder = false;
Note: In some cases it may be more handy to keep the values of the last used folder separately for each CKFinder instance. In such case, assign the id property.
Defaults to: true
List of modules that must not be loaded. This is a tool setting which makes it easier to avoid loading modules that are otherwise automatically loaded by CKFinder. Available modules are:
Connector
* - Sends requests to the server connector.ContextMenu
- Manages context menu display.CreateFolder
- Adds a Create Folder command.DeleteFile
- Adds a Delete File command.DeleteFolder
- Adds a Delete Folder command.Dialogs
* - Manages dialogs display.EditImage
- Adds an image editor.FileDownload
- Adds file download actions.FilePreview
- Adds a file preview.Files
* - Manages files and files pane display.FilesMoveCopy
- Adds a Files Move and Files Copy commands.FilterFiles
- Adds a filter files box to the toolbar.FocusManager
- Allows to remember focus.Folders
* - Manages folders and folders pane display.FormUpload
- Adds single file upload for browsers that do not support HTML5 uploads.Html5Upload
- Adds multiple files upload.KeyListener
- Allows to listen to global key events.Loader
- Displays loading messages.Maximize
- Adds a maximize/minimize button to the toolbar.Pages
* - Manages displaying jQuery mobile pages.Panels
* - Displays panels.RenameFile
- Adds a Rename File command.RenameFolder
- Adds a Rename Folder command.Settings
- Manages user settings.Shortcuts
- Manages displaying a dialog with application keyboard shortcuts.StatusBar
- Manages displaying status bar inside pages.Toolbars
- Manages displaying toolbars inside pages.UploadFileButton
- Adds an upload file button to the toolbar.
Items marked with * are considered as core modules and should not be removed.
// Disable toolbars.
config.removeModules = 'Toolbars';
Defaults to: ''
Controls available options in the context menu / toolbar for the "Choose Resized" feature. Possible values:
true
– The user can choose all resized images according to the folder'sIMAGE_RESIZE
/IMAGE_RESIZE_CUSTOM
ACL permissions.false
– Disables the "Choose Resized" option in the context menu / toolbar.array
– Shows just a subset of predefined allowed sizes, even if custom thumbnails are available.config.resizeImages = [ 'small', 'medium' ];
Defaults to: true
Resource type to display. By default CKFinder displays all available resource types. If the ResourceType
property
is set, CKFinder will display only the specified resource type.
CKFinder.popup( {
resourceType: 'Images'
} );
Sets the width of the secondary panel (right in LTR and left in RTL) and overrides the jQuery Mobile panel width CSS settings. Affects all panels on the right side of the view.
config.secondaryPanelWidth = '20em'
Defaults to: ''
Sets the skin used by CKFinder. By default CKFinder comes with two skins: "moono" and "jquery-mobile". The "moono" skin has a visual appearance similar to the CKEditor "moono" skin. The "jquery-mobile" skin is a basic skin that uses default swatches from jQuery mobile. The "jquery-mobile" skin swatch can also be easily changed using ThemeRoller.
// Use the "jquery-mobile" theme instead of the default "moono".
config.skin = 'jquery-mobile';
// Use you own theme located at a network location.
config.skin = 'http://www.example.com/skins/my-skin';
Defaults to: 'neko'
Used only when startupPath is set.
If set to true
, the initial folder will be opened automatically on startup.
config.startupFolderExpanded = false;
Defaults to: true
The resource type and name of the startup folder, separated with a colon. If defined, on startup CKFinder will open the given folder and will list its contents.
config.startupPath = "Images:/cars/";
Note: CKFinder remembers the last opened folder, so in order to enforce opening
CKFinder in the specified location you need to also set rememberLastFolder to false
.
Defaults to: ''
Sets the jQuery-mobile swatch used by CKFinder. The "moono" skins comes with only one swatch ("a"). The "jquery-mobile" skins has two swatches ("a" and "b"). A theme might discard the swatch setting, for instance the "moono" skin will enforce the "a" swatch.
config.swatch = 'b';
Defaults to: 'a'
The CKFinder tabindex value used in widget mode.
config.tabIndex = 1;
Defaults to: 0
The path to the jQuery Mobile structure CSS file. Useful to load jQuery Mobile CSS files from CDN.
config.themeCSS = '//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css';
Defaults to: ''
Additional classes that will be applied to the files pane when using thumbnail resizing. After configuring steps 120px as 'small' and 180px as 'medium', CKFinder will add CSS classes to files pane in the following way:
- 'ckf-files-thumbs-small' for thumbnails smaller then 120px.
- 'ckf-files-thumbs-medium' for thumbnails that are between 120px and 180px.
- (none class) for thumbnails greater then 180px.
You can add as many steps as you wish.
Defaults to: {120: 'small', 180: 'medium'}
Defines the default thumbnail size for cases when the user does not change the thumbnail size.
Defaults to: 150
The number of milliseconds before requesting another thumbnail. If your server has problems with handling many requests in a short time, increase this value.
// disable delay
config.thumbnailDelay = 0;
Defaults to: 50
Defines the maximum thumbnail size used for thumbnail resizing. When thumbnailMaxSize
is bigger than the maximum thumbnail
size returned by the server, the server maximum thumbnail size will be used.
Defines the minimum thumbnail size used for thumbnail resizing.
Defines the minimum thumbnail size used for thumbnail resizing.
Defines the thumbnail size step used for thumbnail resizing.
Defaults to: 2
An alias for resourceType
This cfg has been deprected
Please use resourceType instead.
The window width threshold between desktop and mobile UI mode,
expressed in em
units.
config.uiModeThreshold = 38;
Defaults to: 48
The application width in CSS size format or an integer denoting a value in pixels.
config.width = 850;
config.width = '75%';
Defaults to: '100%'