downloading.javascript

Interface SignStixFiles

SignStixFiles

Javascript-to-Player interface for processing downloaded files e.g. images, videos, CSV files etc.

Function Summary

Modifier and Type	Function and Description
String	getFileRef(String folderPath, String fileName) Create a reference to a specific file in the folder (if any) associated with the Web View.
String	getFilesMatching(String folderPath, String fileRegex, boolean recursive) Find the contents of the argument folder as a String formatted as a JSON array of objects.
String	getFileUrl(String folderPath, String fileName) Generates a local URL for a specified file within a folder, served through a local server.
String	getJsonFromCsvFile(String fileRef, int headingRowNumber, int dataRowNumber, String textEncoding) Read the contents of the referenced CSV file and convert it to a JSON string.
String	getTextFromFile(String fileRef, String textEncoding) Read the contents of the referenced file and convert it to text using the argument text-encoding.

Function Detail

getFileUrl

String getFileUrl(String folderPath,
                  String fileName)

Generates a local URL for a specified file within a folder, served through a local server.

This URL can be used by the WebView to access and load the file within the app environment.

Example usage:

   String url = getFileUrl("/Assets/Images/", "Silver.png");
 

This will create a URL pointing to the file "Silver.png" in the specified folder.

If the file does not exist or cannot be accessed, this Function may return null and log an error.

Parameters:

folderPath - the absolute or relative path to the directory containing the desired file.

fileName - the name of the file to be accessed, such as "background.png".

Returns:

the local URL to access the file via the local server, or null if there's an issue.

Since:

Player 3.3.19

getFileRef

String getFileRef(String folderPath,
                  String fileName)

Create a reference to a specific file in the folder (if any) associated with the Web View. The resulting reference can then be passed into other functions in this interface.

As an example, suppose the Web View is associated with the folder '/Assets/Spring2018/', which contains a subfolder called 'Images' that in turn contains an image called 'Silver.png'. To create a reference to 'Silver.png', you can either include a leading slash to use the absolute path:

   SignStixFiles.getFileRef('/Assets/Spring2018/Images/', 'Silver.png');
 

Or use a relative path:

   SignStixFiles.getFileRef('Images/', 'Silver.png');
 

If an attempt to create a reference using an absolute path fails due to there being no matching file in the folder associated with the Web View, the Player will also check for a matching file in any other folders that may have been specified in other deployed Web Views.

Parameters:

folderPath - absolute or relative path (see above) to the folder in Director where the file lives.

fileName - the name of the file e.g. 'metadata.txt'.

Returns:

the resulting reference, or null if there was a problem (in which case an error will be logged).

Since:

Player 3.2.1

getFilesMatching

String getFilesMatching(String folderPath,
                        String fileRegex,
                        boolean recursive)

Find the contents of the argument folder as a String formatted as a JSON array of objects. The "name" and "path" properties of the returned objects can be used in the getFileRef(...) Function. Example JSON return:

   [
     {
       "name": "Background.png",
       "path": "/Assets/Images/"
     },
     ...
   ]
 

If an absolute path is supplied, the Player will search both the folder associated with the Web View and any other folders that may have been specified in other deployed Web Views.

Parameters:

folderPath - absolute or relative path (see getFileRef) to the folder in Director.

fileRegex - a regular expression e.g. ".*" to mean match everything.

recursive - true to also search within child folders recursively.

Returns:

a JSON-formatted string, or null if there was a problem (in which case an error will be logged).

Since:

Player 3.2.1

getTextFromFile

String getTextFromFile(String fileRef,
                       String textEncoding)

Read the contents of the referenced file and convert it to text using the argument text-encoding.

Parameters:

fileRef - reference to a file within the associated folder structure.

textEncoding - name of the text encoding used in the file e.g. 'UTF-8'.

Returns:

the text content, or null if there was a problem (in which case an error will be logged).

Since:

Player 3.2.1

getJsonFromCsvFile

String getJsonFromCsvFile(String fileRef,
                          int headingRowNumber,
                          int dataRowNumber,
                          String textEncoding)

Read the contents of the referenced CSV file and convert it to a JSON string. The JSON result is an object with a single 'rows' parameter which maps to a JSON array. Each element of the array is a JSON object with properties indexed by the heading names defined in (usually) the first row of the CSV file e.g.

 *** CSV ***
 First Name,Surname,Age
 Bobby,Anderson,43
 June,Johnson,91

 *** JSON ***
 {"rows":[{"First Name":"Bobby","Surname":"Anderson","Age":"43"},{"First Name":"June",
 "Surname":"Johnson"," Age":"91"}]}
 

Values in columns which do not have a corresponding heading entry will be ignored. Values will be trimmed of leading and trailing whitespace. The CSV file will be processed according to the conventions of RFC 4180.

Parameters:

fileRef - reference to a CSV file looked-up via SignStixFiles.

headingRowNumber - the number (counting from 1) of the headings row. Usually this would be 1.

dataRowNumber - the number (counting from 1) of the row where the data starts. Usually this would be 2.

textEncoding - name of the text encoding used in the file e.g. 'UTF-8'.

Returns:

a JSON string, or null if there was a problem (in which case an error will be logged).

Since:

Player 3.2.1