loadFile()

The loadFile() function (server-side) loads files from the File Cabinet by specifying their name and path. You can use this function the file content, the file internal ID, or the file URL. The function also supports loading multiple files at the same time and can run either synchronously or asynchronously.

Syntax

Use these syntax formats for the loadFile() function:

To load a single file using the file path:

                loadFile('fileName')
  .done(callback)
  .fail(callback);

In this case, the returned value is the file content.

To load multiple files or choose the returned data type using an object:

                loadFile({
    name: ['fileName1', 'fileName2', ... , 'fileNamen'],
    target: 'id' | 'url' | 'content',
    async: true | false
}).done(callback)
  .fail(callback);

Return Value

When using the loadFile() function in synchronous mode (async: false), the result (success or error data) is returned directly from the loadFile() call itself. You can assign the returned value to a variable and use it immediately.

When using the function in asynchronous mode, it returns a promise. The promise resolves to an object, which is passed to the callback functions attached using .done() and .fail().

If the file loads successfully, the loadFile() function returns a string or an array of strings depending on whether you load a single file or multiple files. The returned data contains the requested file information: file internal ID, file relative URL, or file content.

If the request fails because one or more files can't be found, the function returns an error object containing an error code and description.. The error object contains the following information:

            {
    name: "CPQ-FileCab error",
    code: "RCRD_DSNT_EXIST",
    message: "That record does not exist. path: path/filename.extension"
}

Parameters

Note:

The file name or names are required.

When passing an object parameter to the loadFile() function, the object includes the following properties:

name - Specifies the file name or names, including the path, as either a single string or an array of strings. The file name has the following format:
```
                'path/filename.extension' 

              
```
target (string) - Sets the type of file data to load. This property can take the following values:
- id - Loads the file internal ID.
- url - Loads the file URL.
- content - Loads the file content. This is the default value and can be omitted. For binary files, content is base64 encoded.
async - Determines whether file data is loaded synchronously or asynchronously. This property is true by default, so data is loaded asynchronously. Set it to false if your implementation requires a synchronous request.

Examples

The following examples show how to use the loadFile() function.

Retrieving File Content Asynchronously

These examples show various ways of loading the content of a text file asynchronously. In the examples, loadFile() returns the file content in the callback attached to the .done handler.

You can load a file using a string containing the file path.

              loadFile('Documents/notes.txt').done(function(data) {
    console.log('File content', data);
});

You can also load a file by passing the file path in an object.

              loadFile({
    name: 'Documents/notes.txt'
}).done(function(data) {
    console.log('File content',data);
});

This example loads a file by specifying the file name and explicitly setting the request to asynchronous mode.

              loadFile({
    name: 'Documents/notes.txt',
    async: true
}).done(function(data) {
    console.log('File content',data);
});

In this example, the file is loaded by explicitly requesting the file content.

              loadFile({
    name: 'Documents/notes.txt',
    target: 'content'
}).done(function(data) {
    console.log('File content',data);
});

Retrieving the File URL Asynchronously

This example retrieves the file URL instead of its content by setting the target property to 'url'. The returned URL is handled in the callback.

              loadFile({
    name: 'Documents/notes.txt',
    target: 'url'
}).done(function(data) {
    console.log('File content', data);
});

Retrieving the File ID Asynchronously

This example retrieves the file internal ID by setting the target parameter to 'id'. The returned ID is delivered to the callback.

              loadFile({
    name: 'Documents/notes.txt',
    target: 'id'
}).done(function(data) {
    console.log('File ID', data);
});

Retrieving the URL for Multiple Files in a Single Request

This example loads the URL of multiple image files in a single asynchronous request. The function returns an array of URLs corresponding to the requested files.

              loadFile({
    name: ['Images/lampA10.jpg', 'Images/lampA11.jpg', 'Images/lampA12.jpg'],
    target: 'url',
    async: true
}).done(function(data) {
    console.log('File URL', data);
});

Handling Errors when Loading Files

If a file can't be found, loadFile() returns an error object. You can handle the error by attaching a .fail() handler to the asynchronous request.

              loadFile({
    name: 'Documents/notes2.txt'
}).done(function(data) {
    console.log(data);
}).fail(function(error) {
    console.log('Load failed:', error);
});

When using a synchronous call, the error object is returned directly by the function. This example prints the error object to the console.

              let result = loadFile({
    name: 'Documents/notes2.txt',
    async: false
});
console.log(result);

Syntax

Return Value

Parameters

Examples

Retrieving File Content Asynchronously

Retrieving the File URL Asynchronously

Retrieving the File ID Asynchronously

Retrieving the URL for Multiple Files in a Single Request

Handling Errors when Loading Files

Related Topics