Folder, File

A folder or file selection for use with RPCs

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	The URL of an RPC returning the list of folders or files.
object	A detailed configuration of the folder/file list.

Available parameters:

Parameter	Type	Specification
store	string	The URL of an RPC returning the list of folders or files.
ids	Boolean	If set to true , you can work with folder IDs. The 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	The label to be displayed.
value	string	The value of an option that 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 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: get 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.

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 files in your RPC result have to contain the "file": true property. Each time a file is selected, the RPC is called 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: get 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 the file property correctly inside the iterate directive.

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"