Namespace CKFinderAPI

Namespace Summary
Constructor Attributes	Constructor Name and Description
	CKFinderAPI The CKFinder API class.

Field Summary
Field Attributes	Field Name and Description
<static>	CKFinderAPI.id The ID of the CKFinder instance.
<static>	CKFinderAPI.inFrame Determines if CKFinder is running in a frame via URL.
<static>	CKFinderAPI.inIframe Determines if CKFinder is running in an iframe via URL.
<static>	CKFinderAPI.inPopup Determines if CKFinder is running in a popup.
<static>	CKFinderAPI.inUrlPopup Determines if CKFinder is running in a popup.
	_ Private scope

Method Summary
Method Attributes	Method Name and Description
	addFileContextMenuOption(optionDefinition, clickCallback, decisionCallback) Adds a new option to file context menu.
	addFolderContextMenuOption(optionDefinition, clickCallback, decisionCallback) Adds a new option to folder context menu.
	addFolderDropMenuOption(optionDefinition, clickCallback, decisionCallback) Adds a new option to folder drop menu - the one that opens when files are dropped into a folder.
	addTool(markup) Adds a tool space into the sidebar.
	addToolPanel(markup) Adds a tool panel into the sidebar.
	closePopup() Closes a popup window containing CKFinder.
	destroy(callback) Destroys the instance.
	disableFileContextMenuOption(option, addedUsingApi) Permanently disable specific file context menu option.
	disableFolderContextMenuOption(option, addedUsingApi) Permanently disable specific folder context menu option.
	disableFolderDropMenuOption(option, addedUsingApi) Permanently disable specific folder drop menu option.
	emptyBasket() Removes all files from the Basket folder (not from the filesystem folder).
	execCommand(name)
	filterFiles(lookup) Filter the displayed files according to the specified string.
	getResourceType(resourceTypeName) Returns an object of resource type by name.
	getSelectedFile() Gets a selected file object.
	getSelectedFiles() Gets an array of selected files.
	getSelectedFolder() Gets a selected folder object.
	hideTool(id) Hides a tool panel/space by its ID.
	openConfirmDialog(title, msg, okCallback) Opens an equivalent of a confirm() dialog window.
	openDialog(dialogName, callback) Loads and opens a registered dialog window.
	openFolder(resourceType, path) Opens a directory.
	openInputDialog(title, msg, value, okCallback) Opens an equivalent of a prompt() dialog window.
	openMsgDialog(title, msg) Opens an equivalent of an alert() dialog window.
	openSkippedFilesDialog(title, files, msg, okCallback) Opens a message dialog with a list of skipped files.
	refreshOpenedFolder() Refreshes the currently visible folder inside the files view.
	removeTool(id) Removes a tool panel/space by its ID.
	replaceUploadForm(html, onShow, showFocusIndicator, priority) Replaces the default upload form with custom HTML code.
	resizeFormPanel(height)
	selectFile(fileToSelect)
	setUiColor(string) Sets the main color of the UI.
	showTool(id) Shows a tool panel/space by its ID.

Namespace Detail

CKFinderAPI

Since: 2.0

The CKFinder API class. Contains methods that can be used to interact with CKFinder and extend CKFinder functionality. The API object contains instance-specific information, like currently selected file.

Note: The CKFinderAPI object is not directly accessible (CKFinderAPI is undefined).
The API object is returned by methods used to create CKFinder, like CKFinder.create, and is passed to selected callback functions, like CKFinder.config.callback.

Field Detail

<static> {String} CKFinderAPI.id

Since: 2.0

The ID of the CKFinder instance.

<static> {Boolean} CKFinderAPI.inFrame

Since: 2.0

Determines if CKFinder is running in a frame via URL.

<static> {Boolean} CKFinderAPI.inIframe

Since: 2.0

Determines if CKFinder is running in an iframe via URL.

<static> {Boolean} CKFinderAPI.inPopup

Since: 2.0

Determines if CKFinder is running in a popup.

<static> {Boolean} CKFinderAPI.inUrlPopup

Since: 2.0

Determines if CKFinder is running in a popup.

{Object} _

Since: 2.0

Private scope

Method Detail

{Undefined} addFileContextMenuOption(optionDefinition, clickCallback, decisionCallback)

Since: 2.0

Adds a new option to file context menu.

var menuItem = {
	label : 'Show Name',
	command : 'DisplayName'
};
api.addFileContextMenuOption( menuItem, function( api, file )
	{
		api.openMsgDialog( "", "The name of the selected file: " + file.name );
	}
);

var menuItem = {
	label : 'Show Name',
	command : 'DisplayName'
};
api.addFileContextMenuOption( menuItem, function( api, file )
	{
		api.openMsgDialog( "", "The name of the selected file: " + file.name );
	},
	function (file)
	{
		// Disable for images.
		if ( file.isImage() )
			return -1;
		return true;
	}
);

Parameters:

{Object} optionDefinition

Definition of a context menu item. A context menu item consists of three properties:

{String} label - Label displayed to the user.
{String} command - Command name (used later to refer to that context menu item).
{String} group (Optional) - Group of items to which an item should belong. Default is 'file1'.

{Function} clickCallback

Callback to be called when user chooses the option. Two parameters are passed:

CKFinderAPI CKFinder API object.
CKFinder.dataTypes.File Currently selected file.

{Function} decisionCallback

(Optional) Callback to be called before showing the context menu. One parameter is passed:

Clicked file object CKFinder.dataTypes.File

'this' context refers to the CKFinderAPI object. Accepted return values:

true Display item.
false Hide item.
-1 Display inactive (disabled) item.

{Undefined} addFolderContextMenuOption(optionDefinition, clickCallback, decisionCallback)

Since: 2.0

Adds a new option to folder context menu.

var menuItem = {
	label : 'Show Url',
	command : 'DisplayUrl'
};
api.addFolderContextMenuOption( menuItem, function( api, folder )
	{
		api.openMsgDialog( "", "The URL of the selected folder: " + folder.getUrl() );
	}
);

Parameters:

{Object} optionDefinition

Definition of a context menu item. A context menu item consists of three properties:

{String} label - Label displayed to the user.
{String} command - Command name (used later to refer to that context menu item).
{String} group (Optional) - Group of items to which an item should belong. Default is 'folder1'.

{Function} clickCallback

Callback to be called when the user chooses the option. Two parameters are passed:

CKFinderAPI CKFinder API object.
CKFinder.dataTypes.Folder Currently selected folder.

{Function} decisionCallback

(Optional) Callback to be called before showing the context menu. One parameter is passed:

Clicked folder object CKFinder.dataTypes.Folder

'this' context refers to the CKFinderAPI object. Accepted return values:

true Display item.
false Hide item.
-1 Display inactive (disabled) item.

{Undefined} addFolderDropMenuOption(optionDefinition, clickCallback, decisionCallback)

Since: 2.3

Adds a new option to folder drop menu - the one that opens when files are dropped into a folder.

NO EXAMPLE AVAILABLE

Parameters:

{Object} optionDefinition

Definition of a menu item. A menu item consists of two properties:

{String} label - Label displayed to the user.
{String} command - Command name (used later to refer to that menu item).
{String} icon (Optional) - Path to the icon file. Set to false to disable the icon.

{Function} clickCallback

Callback to be called when the user chooses the option. Two parameters are passed:

CKFinderAPI CKFinder API object.
CKFinder.dataTypes.Folder Destination folder.

{Function} decisionCallback

(Optional) Callback to be called before showing the menu. One parameter is passed:

Destination folder object CKFinder.dataTypes.Folder

'this' context refers to the CKFinderAPI object. Accepted return values:

true Display item.
false Hide item.

{String} addTool(markup)

Since: 2.0

Adds a tool space into the sidebar.

var toolId = api.addTool( '<h3>My tool</h3><p>Sample content.</p>' );
// Show tool
api.showTool( toolId );

Parameters:
{String} markup: (Optional) HTML content

Returns:: {String} The ID of the new DOM element.

{String} addToolPanel(markup)

Since: 2.0

Adds a tool panel into the sidebar. Tool panel features a panel layout.

var toolId = api.addToolPanel( '<h3>My tool</h3><p>Sample content.</p>' );
// Show tool
api.showTool( toolId );

Parameters:
{String} markup: (Optional) HTML content

Returns:: {String} The ID of the new DOM element.

{Undefined} closePopup()

Since: 2.0.2

Closes a popup window containing CKFinder. It is safe to use even when CKFinder is not hosted in a popup window.

var finder = new CKFinder();
finder.basePath = '/ckfinder/';
var api = finder.popup();
// Close popup after five seconds
window.setTimeout(function() {api.closePopup();}, 5000 );

{Undefined} destroy(callback)

Since: 2.1.1

Destroys the instance.

api.destroy( function()
{
	alert( 'The CKFinder instance was destroyed.' );
} );

Parameters:
{Function} callback: (Optional) A function to be invoked after the instance is destroyed.

{function} disableFileContextMenuOption(option, addedUsingApi)

Since: 2.0

Permanently disable specific file context menu option.

// Simply call disableFileContextMenuOption to disable the menu item.
api.disableFileContextMenuOption( 'viewFile', false );

// If you want to enable it back later, remember in a variable an unlocking function.
var enableAgain = api.disableFileContextMenuOption( 'viewFile', false );
// Enabling back
enableAgain();

Parameters:
{String} option: Name of menu item.
{Boolean} addedUsingApi: Boolean variable indicating whether a context menu item was added with CKFinderAPI#addFileContextMenuOption (true) or it is an internal CKFinder menu item (false).

Returns:: {function} Unlocking callback function.

{function} disableFolderContextMenuOption(option, addedUsingApi)

Since: 2.0

Permanently disable specific folder context menu option.

// Disable DisplayUrl context menu item.
api.disableFolderContextMenuOption( 'DisplayUrl', true );

Parameters:
{String} option: Name of menu item.
{Boolean} addedUsingApi: Boolean variable indicating whether a context menu item was added with CKFinderAPI#addFolderContextMenuOption (true) or it is an internal CKFinder menu item (false).

Returns:: {function} Unlocking callback function.

{function} disableFolderDropMenuOption(option, addedUsingApi)

Since: 2.0

Permanently disable specific folder drop menu option.

// Disable DisplayUrl drop menu item.
api.disableFolderContextMenuOption( 'DisplayUrl', true );

Parameters:
{String} option: Name of menu item.
{Boolean} addedUsingApi: Boolean variable indicating whether a menu item was added with CKFinderAPI#addFolderDropMenuOption (true) or it is an internal CKFinder menu item (false).

Returns:: {function} Unlocking callback function.

{Undefined} emptyBasket()

Since: 2.0

Removes all files from the Basket folder (not from the filesystem folder).

api.emptyBasket();

{Undefined} execCommand(name)

Since: 2.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} name

{Undefined} filterFiles(lookup)

Since: 2.0

Filter the displayed files according to the specified string.

api.filterFiles( 'abc' );

Parameters:
{String} lookup: The lookup string to test against. Omitting this parameter or passing null will show all files in the folder.

{CKFinder.dataTypes.ResourceType} getResourceType(resourceTypeName)

Since: 2.0

Returns an object of resource type by name.

alert( api.getResourceType( 'Files' ).isExtensionAllowed( 'exe' ) );

Parameters:
{String} resourceTypeName: Name of the resource type.

Returns:: {CKFinder.dataTypes.ResourceType}

{CKFinder.dataTypes.File} getSelectedFile()

Since: 2.0

Gets a selected file object.

var file = api.getSelectedFile();

Returns:: {CKFinder.dataTypes.File}

{Array} getSelectedFiles()

Since: 2.0

Gets an array of selected files.

var files = api.getSelectedFiles();

Returns:: {Array}

{CKFinder.dataTypes.Folder} getSelectedFolder()

Since: 2.0

Gets a selected folder object.

var folder = api.getSelectedFolder();
if ( folder )
	alert( folder.getUrl() );

Returns:: {CKFinder.dataTypes.Folder}

{Undefined} hideTool(id)

Since: 2.0

Hides a tool panel/space by its ID.

api.hideTool( toolId );

Parameters:
{Integer} id: Tool ID (returned by CKFinderAPI#addTool)

{Undefined} openConfirmDialog(title, msg, okCallback)

Since: 2.0

Opens an equivalent of a confirm() dialog window.

api.openConfirmDialog( "", "Are you sure?", function( value ) {
	api.openMsgDialog( "Processing", "OK, processing, please wait..." );
} );

Parameters:
{String} title: Dialog window title. If empty, the default title will be used.
{String} msg: Message
{Function} okCallback: Callback function called when a user submits the dialog window (presses the "OK" button).

{CKFinder.dialog} openDialog(dialogName, callback)

Since: 2.0

Loads and opens a registered dialog window.

api.openDialog( 'smiley' );

Parameters:
{String} dialogName: The registered name of the dialog window.
{Function} callback: (Optional) The function to be invoked after a dialog window instance is created.

Returns:: {CKFinder.dialog} The dialog window object corresponding to the dialog window displayed. null if the dialog window name is not registered.

See:: CKFinder.dialog.add

{Undefined} openFolder(resourceType, path)

Since: 2.0

Opens a directory. Note: This function will only work for folders that CKFinder is already aware of.

api.open( 'Images', '/' );

Parameters:
{string} resourceType: The name of the resource type.
{string} path: Path to the folder.

{Undefined} openInputDialog(title, msg, value, okCallback)

Since: 2.0

Opens an equivalent of a prompt() dialog window.

api.openInputDialog( "Enter number", "Enter a number: ", "0", function( value ) {
	api.openMsgDialog( "", "You have entered: " + value );
} );

Parameters:
{String} title: Dialog window title. If empty, the default title will be used.
{String} msg: Message
{String} value: Default value
{Function} okCallback: Callback function called when a user submits the dialog window (presses the "OK" button). Value from the dialog window text input is passed as the first argument.

{Undefined} openMsgDialog(title, msg)

Since: 2.0

Opens an equivalent of an alert() dialog window.

api.openMsgDialog( "Sample title", "Sample message." );

Parameters:
{String} title: Dialog window title. If empty, the default title will be used.
{String} msg: Message to display.

{Undefined} openSkippedFilesDialog(title, files, msg, okCallback)

Since: 2.0

Opens a message dialog with a list of skipped files.

api.openSkippedFilesDialog( "", [ "1.jpg", "2.txt" ], "Some files could not be used." );

Parameters:
{String} title: Dialog window title. If empty, the default title will be used.
{Array} files: An array of skipped files. Could be an array of strings, or array of parsed XML nodes.
{String} msg: Additional message to show.
{Function} okCallback: Callback function called when a user submits the dialog window (presses the "OK" button).

{Undefined} refreshOpenedFolder()

Since: 2.0

Refreshes the currently visible folder inside the files view.

api.refreshOpenedFolder();

{Undefined} removeTool(id)

Since: 2.0

Removes a tool panel/space by its ID.

api.removeTool( toolId );

Parameters:
{Integer} id: Tool ID (returned by CKFinderAPI#addTool or CKFinderAPI#addToolPanel)

{Object} replaceUploadForm(html, onShow, showFocusIndicator, priority)

Since: 2.0

Replaces the default upload form with custom HTML code. To get the upload URL, call the CKFinder.dataTypes.Folder#getUploadUrl method.

var form = api.replaceUploadForm( '<div>My upload form</div>' );
form.hide();

Parameters:
{String} html: HTML code to be shown in the form panel.
{Function} onShow: The function to be called when the form is replaced.
{Boolean} showFocusIndicator: Boolean variable indicating whether the replaced form should have a surrounding border when focused.
{Number} priority: Priority of the replacement, so if there are multiple calls, only the highest one will work.

Returns:

{Object} Object that helps you control the upload form. Available methods:

hide()

{Undefined} resizeFormPanel(height)

Since: 2.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} height

{Undefined} selectFile(fileToSelect)

Since: 2.0

NO EXAMPLE AVAILABLE

Parameters:
{Undefined} fileToSelect

{Undefined} setUiColor(string)

Since: 2.0

Sets the main color of the UI. Similar to the uiColor property of the configuration. Kama skin only.

api = (new CKFinder()).create();
api.setUiColor( 'white' );

Parameters:
{Undefined} string: color Color in CSS format.

{Undefined} showTool(id)

Since: 2.0

Shows a tool panel/space by its ID.

api.showTool( toolId );

Parameters:
{Integer} id: Tool ID (returned by CKFinderAPI#addTool)

CKFinder 2 JavaScript API Documentation

Namespaces

Classes

Namespace CKFinderAPI