Localhost.mapSymbol Action

Format

s = CS.Localhost.mapSymbol(name := ...ʃ, contentType := ...ʅ
ʃ, evaluateImmediately := ...ʅ)

Argument	Description	Types / Required
name	The name of the binary symbol (a logic object or dictionary item) to map.	string required
contentType	The MIME type of the mapped content.	string not required
evaluateImmediately	Whether to immediately load and cache the symbol's content. The default value is false.	boolean not required

Description

The Localhost.mapSymbol action creates a localhost URL that provides access to the binary data held by a binary logic object or dictionary item. This URL can be used to access the binary data in web views.

By specifying contentType, you can override how the local web server defines the Content-Type header when serving the symbol's content. If not specified, the MIME type of the symbol's data, if defined, is used.

The evaluateImmediately argument, when set to true, results in the immediate loading of the binary data. The data is cached, so if the object 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 object's binary data at the time of the request. At that point, if the object does not contain a value, the local web server will respond with a 404 error.

Return Value

The action returns a string containing the localhost URL that can be used to access the binary data. 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, if no symbol has the specified name, or if the symbol is not a binary object.

Example (CSPro)

Image fox_photo;
fox_photo.load("red-fox.jpg");

// Image.view shows the image using a custom display
fox_photo.view();

// image_url may look like: http://localhost:52381/vf/1/red-fox.jpg
string image_url = CS.Localhost.mapSymbol(name := "fox_photo");

// using view with this URL displays the image using the web view's default image handling
view(image_url);

Example (Question Text)

When processing text templates, template expressions around binary symbols specified using tilde delimiters are created using the same routine as used by Localhost.mapSymbol. For example, these two expressions, shown in Markdown, result in the same outcome:

![~~filename(bird_photo)~~](~~~bird_photo~~~)

![~~filename(bird_photo)~~](~~~CS.Localhost.mapSymbol(name := "bird_photo")~~~)