Localhost.mapFile Action

Format

s = CS.Localhost.mapFile(path := ...ʃ, contentType := ...ʅ
ʃ, evaluateImmediately := ...ʅ
ʃ, pathOverride := ...ʅ)

Argument	Description	Types / Required
path	The path of the file to map.	string required
contentType	The MIME type of the mapped file.	string not required
evaluateImmediately	Whether to immediately load and cache the file. The default value is false.	boolean not required
pathOverride	An alternative path to use when creating the mapping.	string not required

Description

The Localhost.mapFile action creates a localhost URL that provides access to a file on the local file system, specified by path. Because web views do not easily allow access to files on the local file system, this action is particularly useful when used running actions from web views.

By specifying contentType, you can override how the local web server defines the Content-Type header when serving the file content. If not specified, the MIME type is deduced from the file's extension. For example, a file with the extension ".jpg" would correspond to the content type "image/jpeg".

The evaluateImmediately argument, when set to true, results in the immediate loading of the file. The contents of the file are cached, so if the file changes after the localhost URL is created, the URL will access the original cached contents. When not evaluating the contents immediately, the URL will access the contents of the file at the time of the request. At that point, if the file no longer exists, the local web server will respond with a 404 error.

For some advanced uses, particularly when mapping HTML files that use relative paths to images or other resources, you may want to map the file as if exists in a different directory. The pathOverride argument allows you to spoof the location of the mapped file.

Return Value

The action returns a string containing the localhost URL that can be used to access the file. The URL is valid as long as the CSPro application is running.

Exceptions

The action throws an exception if any of its arguments are not specified in a valid form or if the file does not exist. If specifying a pathOverride, exceptions are thrown if trying to map as a directory, or as a file in a directory that does not exist.

Example (CSPro)

string url1 = CS.Localhost.mapFile(path := "PopulationPyramid.html");

// if PopulationPyramid.html uses resources that are in different directory, we can override the path:
string url2 = CS.Localhost.mapFile(path := "PopulationPyramid.html");
pathOverride := "../Resources/PopulationPyramid.html");

// url1 may look like: http://localhost:62028/lfs/C/CSProWork/SwissPopulationSurvey/PopulationPyramid.html
// url2 may look like: http://localhost:62028/vf/1/vfsC:/CSProWork/Resources/PopulationPyramid.html

// by viewing the second URL, any relative paths used in PopulationPyramid.html are evaluated from
// C:\CSProWork\Resources, not C:\CSProWork\SwissPopulationSurvey
view(url2);

Example (HTML + JavaScript)

<p><a href="#" onclick="selectImage(); return false;">Select an Image to Show</a></p>

<script>
const CS = new CSProActionInvoker();

function selectImage() {
// prompt the user to select an image on the local file system
CS.Path.selectFileAsync({
filter: "|FileType.Image"
})
.then(path => {
return ( path !== undefined ) ? path :
Promise.reject("User did not select an image.");
})
.then(selectedPath => {
// if a file was selected, map it so that we can access it from this web view
return CS.Localhost.mapFile({
path: selectedPath
});
})
.then(imageUrl => {
// add the image to the bottom of the page
const img = document.createElement("img");
img.src = imageUrl;

const div = document.createElement("div");
div.appendChild(img);

document.body.appendChild(div);
})
.catch(error => {
console.log(error);
});
}
</script>