Client configuration options

Naoki Sawada edited this page Nov 24, 2016 · 36 revisions

This is a list of the available options for elFinder client (javascript) part, along with their default values. Options are specified by passing an object with certain properties into the first argument of $.elfinder(). Example:

var options = {
	url  : 'php/connector.php',
	lang : 'en'
}
$('#elfinder').elfinder(options);

Note: This page is in progress and as such will not list everything. For more options and further documentation, see inside the js/elFinder.options.js file.

Localization

You can use localization to change volume folder name (similar to alias option but without overwriting return path) like:

elFinder.prototype.i18.en.messages.volumes_media = 'User media files';
// or
elFinder.prototype.i18.ru.messages.volumes_files = 'мое папко';

where files or media is name of your volume root folder.

Contents

  • url - Connector URL
  • lang - The interface lang to use
  • customData - Data to append to all requests and to upload files
  • cssClass - Additional css class for filemanager node
  • rememberLastDir - Remeber last opened dir to open it after reload or in next session
  • useBrowserHistory - Use browser native history with supported browsers
  • onlyMimes - Display only certain files based on their mime type
  • validName - Used to validate file names
  • defaultView - Default view mode
  • sort - How to sort files in a directory view
  • sortDirect - Sort order
  • width - The width of the elFinder main interface
  • height - The height of the elFinder main interface (in pixels)
  • clientFormatDate - Format dates using client
  • UTCDate - Show datetime in UTC timezone
  • dateFormat - File modification datetime format
  • fancyDateFormat - File modification datetime format for last two days (today, yesterday)
  • commands - Active commands list
  • commandsOptions - Commands options used to interact with external callbacks, editors, plugins
  • getFileCallback - Callback function for "getfile" command
  • handlers - Event listeners to bind on elFinder init
  • ui - UI plugins to load
  • uiOptions - Specifies the configuration for the elFinder UI
  • contextmenu - The configuration for the right-click context menu
  • resizable - Whether or not the elFinder interface will be resizable
  • notifyDelay - Timeout before open notifications dialogs
  • dragUploadAllow - Allow to drag and drop to upload files
  • allowShortcuts - Allow shortcuts
  • loadTmbs - Amount of thumbnails to create per one request
  • showFiles - Lazy load
  • showThreshold - Lazy load
  • requestType - The AJAX request type
  • urlUpload - Separate URL to upload file to
  • iframeTimeout - Timeout for upload using iframe
  • sync - Sync content by refreshing cwd every N seconds
  • cookie - Cookie option for browsers that does not support localStorage
  • debug - Debug config

url

Connector URL. This is the only required option. Can be absolute or relative

Data type: string
Default value: ''

lang

The interface lang to use. Can currently be one of the following: ar, bg, ca, cs, de, en, es, fr, hu, jp, nl, pl, pt_BR, ru, zh_CN. You will also need to include corresponding language file from js/i18n directory.

Data type: string
Default value: 'en'

customData

Data to append to all requests and to upload files. These can be any extra data that must be passed to the connector script. For example, you could use these to pass authentication information.

Data type: object
Default value: {}

cssClass

Additional css class for filemanager node. This will be applied to the main filemanager container.

Data type: string
Default value: ''

rememberLastDir

Remeber last opened dir to open it after reload or in next session. This is stored in browser cookie.

Data type: boolean
Default value: true

useBrowserHistory

Use browser native history by hash-change with supported browsers. This option give URI hash that holder position hash of elFinder.

Data type: boolean
Default value: true

onlyMimes

Display only certain files based on their mime type.

Data type: array
Default value: []
Example:

onlyMimes: ["image"] // display all images
onlyMimes: ["image/png", "application/x-shockwave-flash"] // display png and flash

validName

Used to validate file names. By default, no empty names or '..' allowed.

Data type: boolean, regexp, or function
Default value: false
Example:

// disable names with spaces
validName: /^[^\s]$/

defaultView

Default view mode. Can be icons and list.

Data type: string
Default value: 'icons'

sort

How to sort files in a directory view.

Data type: string
Default value: 'nameDirsFirst'
Available options:
'nameDirsFirst' - sort by name, directory first
'kindDirsFirst' - sort by kind, name, directory first
'sizeDirsFirst' - sort by size, name, directory first
'name' - sort by name
'kind' - sort by kind, name
'size' - sort by size, name

sortDirect

Sort order.

Data type: string
Default value: 'asc'
Available options:
'asc' - ascent sorting
'desc' - descent sorting

width

The width of the elFinder main interface.

Data type: string or number
Default value: 'auto'
Available options: Can be the string 'auto' or any number measurement (in pixels).

height

The height of the elFinder main interface (in pixels).

Data type: number
Default value: 400

clientFormatDate

Format dates using client. If set to false - backend date format will be used.

Data type: boolean
Default value: true

UTCDate

Show datetime in UTC timezone. Requires clientFormatDate set to true.

Data type: boolean
Default value: false

dateFormat

File modification datetime format. Value from selected language is used by default.
Set format here to overwrite it. Format is set in PHP date maner

Data type: String
Default value: ''
Example: dateFormat : 'M d, Y h:i A' will return Mar 13, 2012 05:27 PM

fancyDateFormat

File modification datetime format for last two days (today, yesterday).
Same syntax as for dateFormat. Use $1 for "Today" and "Yesterday" placeholder.

Data type: String
Default value: ''
Example: fancyDateFormat : '$1 H:m:i' will return Today 21:59:34

commands

Active commands list. '*' means all of the commands that have been load. You can set any list of enabled commands here if some minimal required commands will be missed here, elFinder will add them to list automatically.

Data type: array
Default value:

commands : ['*']

Example:

// say you want to disable only a couple of commands
var myCommands = Object.keys(elFinder.prototype.commands);
var disabled = ['extract', 'archive'];
$.each(disabled, function(i, cmd) {
	(idx = $.inArray(cmd, myCommands)) !== -1 && myCommands.splice(idx,1);
});

var options = {
	url : 'php/connector.php',
	commands : myCommands
}

commandsOptions

Commands options used to interact with external callbacks, editors, plugins.

Data type: object
Default value:

commandsOptions : {
	// configure value for "getFileCallback" used for editor integration
	getfile : {
		// send only URL or URL+path if false
		onlyURL  : false,

		// allow to return multiple files info
		multiple : false,

		// allow to return folders info
		folders  : false,

		// action after callback (close/destroy)
		oncomplete : ''
	},

	// "upload" command options.
	upload : {
		ui : 'uploadbutton'
	},

	// "quicklook" command options. For additional extensions
	quicklook : {
		autoplay : true,
		jplayer  : 'extensions/jplayer'
	},

	// configure custom editor for file editing command
	edit : {
		// list of allowed mimetypes to edit
		// if empty - any text files can be edited
		mimes : [],

		// edit files in wysisyg's
		editors : [
			// {
			// 	/**
			// 	 * files mimetypes allowed to edit in current wysisyg
			// 	 * @type  Array
			// 	 */
			// 	mimes : ['text/html'], 
			// 	/**
			// 	 * Called when "edit" dialog loaded.
			// 	 * Place to init wysisyg.
			// 	 * Can return wysisyg instance
			// 	 *
			// 	 * @param  DOMElement  textarea node
			// 	 * @return Object
			// 	 */
			// 	load : function(textarea) { },
			// 	/**
			// 	 * Called before "edit" dialog closed.
			// 	 * Place to destroy wysisyg instance.
			// 	 *
			// 	 * @param  DOMElement  textarea node
			// 	 * @param  Object      wysisyg instance (if was returned by "load" callback)
			// 	 * @return void
			// 	 */
			// 	close : function(textarea, instance) { },
			// 	/**
			// 	 * Called before file content send to backend.
			// 	 * Place to update textarea content if needed.
			// 	 *
			// 	 * @param  DOMElement  textarea node
			// 	 * @param  Object      wysisyg instance (if was returned by "load" callback)
			// 	 * @return void
			// 	 */
			// 	save : function(textarea, editor) {}
			// 
			// }
		]
	},

	// help dialog tabs
	help : { view : ['about', 'shortcuts', 'help'] }
}

For more info how to use edit options refer Using custom editor to edit files within elFinder

getFileCallback

Callback function for "getfile" command. Required to use elFinder with WYSIWYG editors, external callbacks.
For more info how to use this function refer to wiki WYSIWYG integrations examples.

Data type: function
Default value: null (command not active)

handlers

Event listeners to bind on elFinder init.
For more info refer Client event API.

Data type: object
Default value: {}
Example:

handlers : {
	// extract archive files on upload
	upload : function(event, instance) {
		var uploadedFiles = event.data.added;
		var archives = ['application/zip', 'application/x-gzip', 'application/x-tar', 'application/x-bzip2'];
		for (i in uploadedFiles) {
			var file = uploadedFiles[i];
			if (jQuery.inArray(file.mime, archives) >= 0) {
				instance.exec('extract', file.hash);
			}
		}
	},

	open   : function(event) { console.log(event.data); }
}

ui

UI plugins to load. places value not activated by default.

Data type: array
Default value: ['toolbar', 'tree', 'path', 'stat']
Full value: ['toolbar', 'places', 'tree', 'path', 'stat']

uiOptions

Specifies the configuration for the elFinder UI.

Data type: object
Default value:

uiOptions : {
	// toolbar configuration
	toolbar : [
		['back', 'forward'],
		// ['reload'],
		// ['home', 'up'],
		['mkdir', 'mkfile', 'upload'],
		['open', 'download', 'getfile'],
		['info'],
		['quicklook'],
		['copy', 'cut', 'paste'],
		['rm'],
		['duplicate', 'rename', 'edit', 'resize'],
		['extract', 'archive'],
		['search'],
		['view'],
		['help']
	],

	// directories tree options
	tree : {
		// expand current root on init
		openRootOnLoad : true,
		// auto load current dir parents
		syncTree : true
	},

	// navbar options
	navbar : {
		minWidth : 150,
		maxWidth : 500
	},

	// current working directory options
	cwd : {
		// display parent directory in listing as ".."
		oldSchool : false
	}
}

contextmenu

The configuration for the right-click context menu. Need some better documentation on this.

Data type: object
Default value:

contextmenu : {
	// navbarfolder menu
	navbar : ['open', '|', 'copy', 'cut', 'paste', 'duplicate', '|', 'rm', '|', 'info'],

	// current directory menu
	cwd    : ['reload', 'back', '|', 'upload', 'mkdir', 'mkfile', 'paste', '|', 'info'],

	// current directory file menu
	files  : [
		'getfile', '|','open', 'quicklook', '|', 'download', '|', 'copy', 'cut', 'paste', 'duplicate', '|',
		'rm', '|', 'edit', 'rename', 'resize', '|', 'archive', 'extract', '|', 'info'
	]
},

resizable

Whether or not the elFinder interface will be resizable. This only works if jQuery UI has the resizable plugin loaded.

Data type: boolean
Default value: true

notifyDelay

Timeout before open notifications dialogs.

Data type: number
Default value: 500 (0.5 second)

dragUploadAllow

Allow to drag and drop to upload files.

Data type: string
Default value: 'auto'

allowShortcuts

Allow shortcuts

Data type: boolean
Default value: true

loadTmbs

Amount of thumbnails to create per one request

Data type: number
Default value: 5

showFiles

Lazy load. Amount of files display at once.

Data type: number
Default value: 30

showThreshold

Lazy load. Distance in px to cwd bottom edge to start displaying files.

Data type: number
Default value: 50

requestType

The AJAX request type. Available choices are post and get.

Data type: string
Default value: 'get'

urlUpload

Separate URL to upload file to. If not set - connector URL will be used.

Data type: string
Default value: ''

iframeTimeout

Timeout for upload using iframe.

Data type: number
Default value: 0 (no timeout)

sync

Sync content by refreshing cwd every N milliseconds. Value must be bigger than 1000.

Data type: number
Default value: 0 (do not sync)

cookie

Cookie option for browsers that does not support localStorage

Data type: object
Default value:

cookie : {
	expires : 30,
	domain  : '',
	path    : '/',
	secure  : false
}

debug

Debug config

Data type: array or boolean
Default value:

debug : ['error', 'warning', 'event-destroy']