Lets you examine and modify the files associated with a particular File Uploader. This is done by activating - or Initialising - the function for the chosen file uploader, after which the function can be used to perform several different actions. When you have finished working with the chosen uploader, you should terminate the function by Closing it.
The function has several different methods of operation, one of which is used each time the function is called. The method chosen - otherwise known as the Instruction - is determined by the value passed to the function's first parameter.
You can only initialise one instance of WithUploadedItems at a time. The initialised function will remain active for the duration of the current session, or until it is closed by an expression. It is best practice to close the function instead of relying on KnowledgeKube to do it at the end of your session.
Syntax
WithUploadedItems( InstructionType, [other parameters determined by instruction] );
Parameters
| Parameter Name | Type | Description | Optional? | Default Value |
|---|---|---|---|---|
| InstructionType | Integer OR String | Determines which of the available instructions is activated by the function. | No | n/a |
| UploaderKeyword | String | The keyword of a File Uploader question. | Depends on the InstructionType | n/a |
| FileIndex | Integer | The zero-based index of the file you want to target with the instruction. | No | n/a |
Output
The function's output depends on the argument set for InstructionType, so refer to the following table for all available instructions and their output:
| Integer | String Equivalent | Description | Parameters |
|---|---|---|---|
| 1 | "Initialise" | Initialises the WithUploadedItems function for a file uploader in the current model. This must be done before most of the other instructions are used, or those instructions will fail. The function will return True if the instruction is successful, and False if not. | UploaderKeyword |
| 2 | "IsInitialised" | Checks whether WithUploadedItems is currently active, returning True if it is and False if not. If you pass the keyword of a particular file uploader to the optional second parameter, the function will check whether the process has been initialised for that specific uploader. | UploaderKeyword (Optional) |
| 3 | "GetCount" | Returns the number of files associated with the uploader. | |
| 4 | "GetFileId" | Returns the unique ID of the uploaded file at the specified index. | FileIndex |
| 5 | "GetFileName" | Returns the file name, including extension, of the uploaded file at the specified index. | FileIndex |
| 6 | "GetSize" | Returns the size, in bytes, of the uploaded file at the specified index. | FileIndex |
| 7 | "GetExtension" | Returns the extension of the uploaded file at the specified index. | FileIndex |
| 8 | "GetBase64" | Returns the base64 binary contents of the uploaded file at the specified index. | FileIndex |
| 9 | "GetItem" | Returns a comma-separated string list of information about the uploaded file at the specified index. In order, the list contains the file's ID, original file name, original directory, original path, file type, and size in bytes. | FileIndex |
| 10 | "Remove" | Deletes the uploaded file at the specified index. Returns True if successful, and False if not. | FileIndex |
| 11 | "RemoveAll" | Deletes all files associated with the uploader. Returns True if successful, and False if not. | |
| 12 | "GetList" | Returns a string containing CSV data about all files associated with the uploader. The structure of each row in this CSV is the same as the list returned by the GetItem instruction, and each row is separated using a pipe symbol (|). | |
| 13 | "GetLastBase64" |
Returns the base64 binary contents of the last file added to the uploader. |
|
| 14 | "GetLastItem" |
Returns a comma-separated string list of information about the last file added to the uploader. In order, the list contains the file's ID, original file name, original directory, original path, file type, and size in bytes. |
|
| 15 | "GetLastFileId" | Returns the unique ID of the last file added to the uploader. | |
| 16 | "GetLastFileName" | Returns the file name, including extension, of the last file added to the uploader. | |
| 17 | "RemoveLast" | Deletes the last file added to the uploader. Returns True if successful, and False if not. | |
| 18 | "Close" | Terminates the active WithUploadedItems function, removing it from session memory. The function will return True if the instruction was successful, and False if not. |
Use Case
WithUploadedItems can be used in a number of ways, the most basic of which is to retrieve information about an uploaded file. For example, if you wanted to obtain the name and base64 binary of the last file to be added to MyFileUploader, you could use the following expression:
WithUploadedItems( 1, "MyFileUploader" );
ImageBase64:= WithUploadedItems( 13 );
ImageName:= WithUploadedItems( 16 );
WithUploadedItems( 18 );
The first statement initialises WithUploadedItems, associating it with the chosen file uploader. The next statement assigns the base64 contents of the most recently-uploaded file to the ImageBase64 variable. A similar statement assigns the same file's name to the ImageName variable, and the final statement simply terminates the function, ending the process.
You could also use a While loop combined with a counter to perform actions on each file associated with a particular uploader. By using the counter as your FileIndex argument, you can dynamically target each file in turn.
To begin with, you'd need to initialise WithUploadedItems and assign the number of files associated with the chosen uploader to a variable. Notice that both of the following statements use the string equivalents to call the necessary instruction, instead of the integers used in the previous example:
WithUploadedItems( "Initialise", "MyImageUploader" );
TotalDocuments:= WithUploadedItems( "GetCount" );
Next, you'll need to expand the expression so it initialises the loop counter and executes the While loop a number of times equal to the value of TotalDocuments. Each iteration of the loop will extract the name and base64 contents of the corresponding file, then write those values away to a data source:
CurrentIndex:= 0;
While:( CurrentIndex < TotalDocuments )
{
CurrentImageName:= WithUploadedItems( "GetFileName", CurrentIndex );
CurrentImageBase64:= WithUploadedItems( "GetBase64", CurrentIndex );
WriteData( "CurrentImageName, CurrentImageBase64", "", "MyImageDataSource" );
CurrentIndex:= CurrentIndex + 1;
}
Finally, remember to terminate the WithUploadedItems function by placing a Close instruction after the closing braces of the While loop:
WithUploadedItems( "Close" );