The Meridian App Sandbox API

Hosted web pages in the Meridian-powered app use the Sandbox API to trigger various actions in the Meridian-powered app, such as providing a visitor with directions to a destination. The Sandbox API enables you to extend the capabilities of the Meridian-powered app beyond its standard feature set.

Setting Up a Page for the Sandbox API

The Meridian Editor enables you to create custom screens in your Meridian-powered app called Pages. A Page can be created as one of several different preset types, such as, Calendars, Slideshows, and a standard web page via URL.

Create a Web Page in the Meridian Editor

In order to use the Sandbox API, create a Page with type Web Page, and enter the URL for your web page.

Complete these steps to create a Page of type Web Page and customize it for use with the Sandbox API.

  1. In the Meridian Editor sidebar, click PAGES.

  2. Click the Add Page + button.

  3. On the New Page screen, name the page, and then click the TYPE dropdown menu, and then click Web Page.

  4. In the URL field, enter the URL for the web page you'd like to use.

  5. Click the MODE dropdown menu, and then click Hosted.

    This option hides the browser controls and enables the Sandbox API.

  6. If your visitors will need to login to your web page, click the REQUIRES LOGIN checkbox.

    For more information on visitor logins, please see the User Login and Accounts page.

  7. If you want to assign a category to the page, in the CATEGORY field, enter your category.

  8. When everything looks good, click the Save button.

Creating a hosted page for the Sandbox API

Sandbox API Functions

The Sandbox API has basic functions that can be added to hosted web pages to interact with the Meridian-powered app. To start using the Sandbox API functions, include the following <script> tags inside the <head> section of the hosted web page:

<script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
<script src="//edit.meridianapps.com/sandbox/js/meridian-1.0.0.js" type="text/javascript"></script>

All the functions of the Sandbox API are called as methods of the global $Mr object.

alert

    $Mr.alert(title, message)

The alert() function displays an alert to the user. While similar to JavaScript's native alert() function, $Mr.alert() lets you add a title to your message.

    $Mr.alert("My Title", "My message to the user.");

setLocationListener

    $Mr.setLocationListener(callback)

The setLocationListener() function requests the user's location. When you use this function, use callback for name of the function you've defined. This will be called immediately when new location data is available, even if the location data may be inaccurate or missing.

Pass the function's name as a string.

The callback will be passed a location object serialized as a JSON string:

    // after calling JSON.parse(location)
    {
        "x": "200",
        "y": "200",
        "map": "1234",
        "timestamp": "2017-04-16T15:32:59Z"
    }

The map value is the unique identifier for the map in the user's location. The x and y values pinpoint a location on the map.

    var onLocationUpdated = function(location) {
        var loc = JSON.parse(location);
        console.log("Location is now " + loc.bounds);
    }

    $Mr.setLocationListener("onLocationUpdated");

getDirections

    $Mr.getDirections(placemark)

Use the getDirections() method to display directions to a Placemark. The placemark parameter describes a Placemark.

Please see the REST API documentation for examples of the structure of Placemark objects in JavaScript. You can construct the Placemark object yourself or get one from the REST API.

    var placemark = {
        map_id: "32",
        name: "The Tao of Tea",
        image: "http://lh6.ggpht.com/tao-of-tea.jpg",
        y: 883.3558863328823,
        x: 2199.7293640054127,
        type: "restaurant",
        id: "32_36",
    };
    $Mr.getDirections(placemark);

playMedia

    $Mr.playMedia(url)

Use the playMedia() function to play audio or video content. The url parameter must be an absolute URL string pointing to an audio or video file. Be sure to provide media files in formats compatible with mobile devices.

    var video_url = "http://somedomain.com/my_video.m4v";
    $Mr.playMedia(video_url);

showImages

    $Mr.showImages(data)

The showImages() function displays a slideshow using an array of image URLs as the data parameter.

    var slideshow = {
        index: 2, // optional, to enter a slideshow on a slide other than the first (index=0)
        images: [
            {
                url:'http://somedomain.com/media/img1.jpg',
                caption:'This is a caption'
            },
            {
                url:'http://somedomain.com/media/img2.jpg',
                caption:'Captions are displayed in an overlay on top of the image'
            },
            {
                url:'http://somedomain.com/media/img3.jpg',
                caption:'The user can tap to toggle caption visibility'
            }
        ]
    };
    $Mr.showImages(slideshow);

showLoginPrompt

    $Mr.showLoginPrompt(redirect_url)

The showLoginPrompt() method prompts the user to log in. Use this with Meridian's [Visitor Login][login] features to authenticate users with your own login scheme. Optionally, you can pass a redirect url to load on a successful login.

    var redirect = "http://somedomain.com/user_details.html";
    $Mr.showLoginPrompt(redirect);

If you don't pass a redirect url, the calling page will be reloaded on successful login.

Skinning

The Sandbox API provides some styles and graphic resources to help you skin your web page to look and feel like the rest of the app.

Basic

To take advantage of the Sandbox API styles and graphics, include the following inside the <head> tag:

<meta name="viewport" content="initial-scale = 1.0">
<link rel="stylesheet" href="/sandbox/css/meridian-2.0.0.css" type="text/css" media="screen" />
<script src="//ajax.googleapis.com/ajax/libs/jquery/2.0.3/jquery.min.js"></script>
<script src="/sandbox/js/meridian-1.0.1.js" type="text/javascript"></script>
<script src="/sandbox/js/meridian.skin-2.0.0.js" type="text/javascript"></script>
<script src="/sandbox/js/meridian.behaviors-1.0.1.js" type="text/javascript"></script>

Basic Skinning Demo

The basic demo and sample code shows an example of a Sandbox API skin.

Advanced

The Sandbox API provides advanced skinning behaviors for buttons and links to mimic a native application. Simply add the following to your <head> tag, in addition to the basic skinning code:

<script src="//edit.meridianapps.com/sandbox/js/meridian.behaviors-1.0.0.js" type="text/javascript"></script>

Advanced Skinning Demo

The advanced demo and sample code shows a more complicated example of a Sandbox API skin.