Folder, File

Folder and file selection

The list of common settings for parameters is available here.

To choose a file instead of a folder, the desired option has to contain "file": true. When the field type is file, the file is required and only the folder is passed, the validation will fail.

Specification

options

• Available types:

Type	Specification
string	A URL of RPC returning the list of folders or files.
object	A detailed configuration of folder/file list.

• Available parameters:

Parameter	Type	Specification
store	string	An URL of RPC returning the list of folders or files.
ids	boolean	If set to true , you can work with folder IDs. That means that GUI loads previously selected folders and their labels after reopening the form without having to call the RPC again.
showRoot	showRoot	Default: true. If set to false , top-level folders aren't prefixed with / and there's no option to choose the root /. When the type is file , the root selection is blocked automatically.
singleLevel	boolean	Default: false. If set to true , only a single level of folders is available.

Examples

Result of RPC

To display the folder/file selector properly, the output from your RPC should contain only objects matching the following samples.

option

• Available parameters:

Parameter	Type	Specification
label	string	A label to be displayed.
value	string	A value of an option which will be used in code.
file	boolean	Boolean to determine if the option is a file or a folder.

Folder

{
    "label": "Documents and Settings",
    "value": "documentandsettings"
}

File

{
    "label": "Document",
    "value": "document.txt",
    "file": true
}

Folder Selection

To make your folder selection work properly, you need to create a remote procedure that will return the corresponding folders. Each time a folder is selected, the RPC is called once again and the parameter path containing the whole path in the string is passed. You need to filter the folders inside this RPC.

Appearance

Source

[
	{
		"name": "home",
		"label": "Choose your home directory",
		"type": "folder",
		"options": {
			"store": "rpc://getFolders"
		}
	}
]

RPC for getting folders

{
	"url": "/api/folders",
	"method": "GET",
	"qs": {
		"path": "{{encodeURL(parameters.home)}}"
	},
	"response": {
		"iterate": "{{body.data}}",
		"output": {
			"label": "{{item.name}}",
			"value": "{{item.name}}"
		}
	}
}

As you can see, this RPC will be called repeatedly each time the next item is chosen. The passed parameter (parameters.home in our case) will contain the full path, not only the last item! If you want to get only the last item, you should consider using a split IML function.

TIP: Because the folder path could contain slashes (/) which are also part of the URL, you may need to escape it using escapeURL IML function before sending the path in query string.

If the endpoint returns files too, you need to create a container and set condition in iterate directive. See the iterate collection below.

{
	"url": "/api/file,
	"method": "GET",
	"qs": {
		"path": "{{encodeURL(parameters.home)}}"
	},
	"response": {
		"iterate": {
			"container": "{{body.data}}",
			"condition": "{{item.type === 'folder'}}		
			},
		"output": {
			"label": "{{item.name}}"			
			"value": "{{item.name}}"
		}
	}
}

Sample RPC results

First call (no folders chosen yet)

[
    {
        "value": "usr",
        "label": "usr"
    },
    {
        "value": "srv",
        "label": "srv"
    },
    {
        "value": "home",
        "label": "home"
    }
]

Second call (passed path: /home)

[
    {
        "value": "make",
        "label": "make"
    },
    {
        "value": "guest",
        "label": "guest"
    }
]

Output

"/home/make"

File Selection

The file selection is very similar to the folder selection, but keep in mind that files in your RPC result have to contain "file": true property. Each time a file is selected, the RPC is called once again and the parameter path containing the whole path in the string is passed. You need to filter the folders and files inside this RPC.

Appearance

Source

[
	{
		"name": "path",
		"label": "Pick a file to download",
		"type": "file",
		"options": {
			"store": "rpc://getFiles"
		}
	}
]

RPC for getting files

{
	"url": "/api/files/tree",
	"method": "GET",
	"temp": {
		"crumbs": "{{split(parameters.path, '/')}}"
	},
	"qs": {
		"directory": "{{get(temp.crumbs,length(temp.crumbs))}}"
	},
	"response": {
		"iterate": "{{body.data}}",
		"output": {
			"label": "{{item.name}}",
			"value": "{{item.name}}",
			"file": "{{if(item.type === 'file', true, false)}}"
		}
	}
}

The implementation of this RPC is quite similar to the getFolders RPC above. This RPC is called repeatedly each time the next item is chosen until the type of item is file.

Don't forget to check whether the item is file or folder and to set file property correctly inside the iterate directive.

TIP: Here you can see how to get the last item from the path. Some APIs may require the last directory as an input for getting a list of contents of that directory.

Sample RPC results

First call

[
    {
        "value": "Documents",
        "label": "Documents"
    },
    {
        "value": "myPaint.png",
        "label": "myPaint.png",
        "file": true
    },
    {
        "value": "contacts.csv",
        "label": "contacts.csv",
        "file": true
    }
]

Second call

[
    {
        "value": "secret.txt",
        "label": "secret.txt",
        "file": true
    },
    {
        "value": "plain.txt",
        "label": "plain.txt",
        "file": true
    }
]

Output

"/documents/plain.txt"