FlexView API - Examples

Basic Usage

The FlexView API is a JavaScript API that renders content of the Outdooractive Platform into an HTML node creating all markup automatically and loading all objects automatically through asynchronous loading. The look and feel of all visible elements of the FlexView API may be influenced with CSS.

The FlexView API consists of two parts:

  • The Overview: explore all content of your project on a map or as list or gallery
  • The Detail View: read all details of a content object like a tour, a hut etc.

The default integration starts with the overview and opens the detail view of an object depending on user interaction. A standalone integration is available for both views.

The FlexView API overview offers four views:

  • list: a sortable list with infinite scrolling
  • map: a map with catory based icons and clustering
  • list/map: a list interacting with a map
  • gallery: thumbnail boxes showing an image and basic information of an object

Views of the overview

An instance of the Outdooractive FlexView API renders objects of one of the following content types:

  • tour (including stage tour)
  • lodging
  • hut
  • destination (POI, region)
  • skiresort
  • story
  • offer
  • current condition

The attribute frontendtype of the configration object is used to choose the content type.

Content types can’t be mixed. The FlexView API overview will always show objects of one content type.

The FlexView API overview comes with two optional main selectors:

  • “What?”: a drop down menu that let’s the user filter the content by activity/category
  • “Where?”: an auto-complete field that let’s the user find a place

There is an optional “Refine your search” box that is collapsed by default. The attributes and values used to refine a search depend on the content type.

You can choose between the following actions (configuration parameter actionOpenType) that are performed as soon as the user selects an object inside the FlexView API overview:

  • InPage: integrates the FlexView Widget in a single page and opens the detail view of any content object as a pure JavaScript action on the same page (see example).
  • Pageload: shows how a custom detail page url may be defined and how a content detailpage is rendered with help of the FlexView API Detailpage (see example).
  • None: no action or implement custom action with help of JavaScript callback (see example).

The FlexView API Detail View may be integrated stand-alone (see detail page example).

Integration

You just have to add one <script /> tag linking the Outdooractive Javascript Library to the page header. Add a <div /> container with css class oax-top-cont to the page body and instantiate the FlexView API. Implement some CSS rules to change the look and feel if needed.

The steps to integrate the FlexView API:

  • Script Tag: load the Outdoorative JavaScript Library
  • HTML Container: specify the container that is filled with the FlexView API
  • JavaScript Initialization: pass a configuration object to the FlexView API constructor
  • CSS Design: influence the FlexView API’s look and feel

The basic HTML 5 template below illustrates the described steps:

<!DOCTYPE html>
<html>
  <head>
    <title>outdooractive platform - API Template</title>
    <meta charset="utf-8">

    
    <!-- load Outdooractive Javascript API -->
    <script type="text/javascript" 
            src="//www.outdooractive.com/alpportal/oa_head.js?proj=api-dev-oa&amp;key=yourtest-outdoora-ctiveapi&amp;lang=en"></script>


  </head>
  <body>
    <h1>Hello, world!</h1>

    <!-- container used by FlexView API -->
    <div class="oax-top-cont"></div>


    <!-- and some lines of javascript inside a script tag -->
    <script type="text/javascript">

      var conf = {
          frontendtype:   "tour",          // choose content type
          zoom:           11,              // set initial zoom level
          center:       [ 10.292, 47.546 ] // set initial map center
      };
      
      var fvp = oa.api.flexviewpage( conf );

    </script>
  </body>
</html>

Responsive layout

The FlexView API uses a responsive layout for all overviews and two responsive layouts for all detail views. The layouts are based on a grid that is described here: FlexView API - Layout and Responsive Design.

Mobile websites

The FlexView API includes a representation for mobile devices that is optimized for smaller screen sizes, touch gestures and that saves bandwidth.

Read about the background here: Optimizing for mobile devices

The Outdooractive JavaScript library is linked inside the html header:

<!-- load Outdooractive Javascript API -->
<script type="text/javascript" 
        src="//www.outdooractive.com/alpportal/oa_head.js?proj=api-dev-oa&amp;key=yourtest-outdoora-ctiveapi&amp;lang=en"></script>

Replace the filename in the path with one of three options:

  • oax_head.js: FlexView API desktop-only representation
  • oam_head.js: FlexView API mobile-only representation
  • oa_head.js: the Outdooractive JavaScript API automatically decides between desktop and mobile representation based on user agent settings

All FlexView API examples use oa_head.js. Use your browser’s developer tools to set the http headers to a mobile device to see the mobile version on a desktop device.

Note

Please use the namespace oa if you implement for desktop and mobile. The namespaces oax and oam may only be used in the equivalent use cases. The APIs oax.api and oam.api may offer some special and exclusive methods in the future.

Language

The Outdooractive API uses the browser locale by default to choose the language of the FlexView GUI and the content. Just use the HTTP GET parameter lang to overwrite it:

oax_head.js?lang=en

values : de, en, fr, it

Server Side Include

The Outdooractive FlexView API is a JavaScript widget loading content and resources directly from the Outdooractive platform. The html content of a FlexView API detailpage may be loaded on server side with one simple http request.

Note: The SSI response is an empty string if the source of an content object (e.g. a tour) is not activated for indexing (in your API project).

See it in action:

All you have to do is to load a html snippet over http on server side and put it into the <div /> container with css class “oax-top-cont”. The Url to the snippet is (replace the value of get parameter i with the id of the tour that should be rendered):

http://www.outdooractive.com/alpportal/ssi/desktop/detail?i=152449&proj=api-dev-oa&lang=de

The FlexView API server side include example may be called with parameter i to load a different tour:

This example uses PHP to load the snippet. Don’t forget the wrapping div container:

<div class="oax-top-cont">
 <?php
  // default id if no id is set through http get parameter
  $i = '1524449';

  // check if http get parameter i is an id
  if (preg_match('/^-?[0-9]+$/',$_GET["i"])) {
   $i = $_GET["i"];
  }

  // Url to load SSI snippet including project key and object id
  $url = "http://www.outdooractive.com/alpportal/ssi/desktop/detail?i=${i}proj=api-dev-oa&lang=de";

  // Load snippet
  $snippet = file_get_contents( $url );

  // write snippet into html source
  echo $snippet;
 ?>
</div>

Events

The Outdooractive FlexView API offers three events to allow user tracking:

  • onModeChange: is triggered when a user changes between the view modes “map”, “list”, “map/list”, “gallery”, “magazine”
  • onInpageOpen: is triggered when a content object’s detail view is opened on the same page
  • onFullscreenChange: is triggered when the fullscreen view is opened or closed

Events of the FlexView API overview

  • onGalleryClick: click on a gallery snippet
  • onIwClick: click on info window
  • onListClick: click on list item
  • onMagazineClick: click on an article snippet (content type “history”)
  • onMapListClick: click on list item (map list)
  • onMapMarkerClick: click on map marker

  • onOoiClick: is triggered in all of the cases above

Have a look a the FlexView API LightBox example to learn more about these events.

Map Callback

var fvp = oa.api.flexviewpage( conf );

fvp.whenMap( callback );

function callback( map ) {

    // do something...

}

See FlexView API NearBy example.

Configuration

Standard Configuration

The standard configuration of the FlexView API chooses the content type and sets the initial map zoom and center (see example):

var conf = {
    frontendtype:   "tour",          // choose content type
    zoom:           11,              // set initial zoom level
    center:       [ 10.292, 47.546 ] // set initial map center
};

var fvp = oa.api.flexviewpage( conf );

FlexView API WebApps

The type of the FlexView instance:

  • “tour”, “hut”
  • “poi”, “hut”, “loging”
  • “offer”
  • “skiresort”
  • “story”
  • “condition”
var conf = {

    "frontendtype": "tour", 

};

POIs

FlexView API instances of the frontend type “poi” show only POIs marked as “destination” by default (“Refine your search” checkbox “Show further POIs” is not checked). Set “check_init_destination” to true to remove this filter and to show all POIs:

conf.cfg = { filter: {check_init_destination: true} };

Modes

conf.modes = [
    "gallery", 
    "map", 
    "list", 
    "listMap"
    //, "magazine" // this mode is only available if content type story is chosen
],

conf.initMode = "listMap";

List of OOIs

Show a list of OOIs and let the FlexView API set the map extent fitting to the loaded objects:

var conf = {

    "frontendtype": "any", 

};

conf.initDataPointList = [ '1397449', '5345254' ];

conf.fitDataBounds = true;

What-Menu

Preset what?-menu:

conf.cfg = {
    "what": {
	"selected_init": "8982342"
    }
};

Configure what? menu:

    // add "what" filter to GUI
    // "simple", "none"
conf.whatType =  "simple";

Where-Menu

Preset where?-menu:

conf.cfg = {
    "where": {
        "selected_init": '1044895'
    };
};

Configure where?-menu:

    // add "where" filter to GUI
    // "outdooractive", "none"
conf.whereType = "outdooractive";

Filter by Source

Filter by content source:

conf.cfg = {
    "initFilterNoGui" : { 

        // filter by content source
        orgId: "1010"

    }
};

Base Map

Set base map:

conf.cfg = {
    "maplayer": {

	// the base maps (at the bottom)
        "basemap": {

            // list of available base map types
            "layer": [
                "satellite", 
                "terrain", 
                "oa_topo", 
                "earth_plugin", 
                "roadmap", 
                "oa_map", 
                "oa_map_winter", 
                "oa_hybrid",
		"oa_osm"
            ], 

            // map type after map was created
            "init": "oa_map"

            // initial map center
            "center": [
		10.2210235,
		47.560012
            ], 

            // initial map zoom
            "zoom": 10,

        }
    }
};

Map overlays:

conf.cfg = {

    "maplayer": {

	// map overlays on top of the base map
        "mapoverlay": {

            // list of map overlays that are available to the user
            "layer": [
                "longDistanceCycling", 
                "weather", 
                "cycling", 
                "hiking", 
                "horseback", 
                "longDistanceHiking", 
                "skiresort_transp", 
                "avalanche_transp", 
                "panoramio", 
                "transalpMountainbiking"
            ],

            // list of map overlays that are shown on load
            "init": {
                "cycling": false, 
                "hiking": true
            }

        }
    }

};
    // behaviour when a detail view is opened
conf.actionOpenType = "in-page";
// FlexView API: click on OOI
// parameter ooi is a data object

// click on info window
conf.onIwClick = function ( ooi ) {
    console.debug( "Info window: " + ooi.id );
};

// click on list item
conf.onListClick = function ( ooi ) {
    console.debug( "List: " + ooi.id );
};

// click on map marker
conf.onMapMarkerClick = function ( ooi ) {
    console.debug( "Map marker: " + ooi.id );
};

// click on an OOI (gallery, info window, list, ...)
conf.onOoiClick = function ( ooi, eventStr ) {

    // parameter ooi is a content object
    console.debug( "OOI " + eventStr + ": " + ooi.id );

    // eventStr is a string with the event's name
    if ( eventStr == "mapMarker" ) {}

};
// open advanced filter options menu initially
conf.initFilterOpen = false;
// pass the configuration object to the constructor
var fvp = oa.api.flexviewpage( conf );
// click on gallery item
conf.onGalleryClick =   function ( ooi ) { console.debug( ooi.id ); };

// click on magazine snippet
conf.onMagazineClick =  function ( ooi ) { console.debug( ooi.id ); };

// click on list item on map
conf.onMapListClick =   function ( ooi ) { console.debug( ooi.id ); };
// initialize filter ("refine your search")
conf.cfg.filter = {
    // checkbox "easy" checked (filter easy tours)
    check_init_easy:true,

    // checkbox "Suitable for families and children" checked
    check_init_suitableforfamilies:true,
};
// set sort order of lists:
// (sort by title asc)
conf.cfg.sort = {
    // use information out of configuration object
    selected_initFromDom : false,

    // initially sort by "distance"
    selected_init_value : "distance",

    // set initial sort order for columns (see "little arrows")
    key2ascendant_init : {
	title : true,
	distance : true
    }

};
// open full screen mode on page load
// default: false
conf.initFullscreen = false;
// docking controls on scrolling web page
// default: true
conf.autoDockingControls = false;
// Write FlexView and map state to url hash (or not)
// default: true
conf.withUrlHash = true;
if (oa.PREFIX==="oax") {

    // show map content panel
    conf.mcpCatList = "poi,hut,lodging";

    // show huts (checkbox map content panel checked)
    conf.mcpInitList = [ "hut" ];

}
    // FlexView API: view mode and full screen
conf.onModeChange = function( mode ) { 

    // list, map, map/list, gallery
    console.debug(mode); 

}; 
  
conf.onFullscreenChange = function() {

    // full screen open/close
    console.debug("onFullscreenChange");

};

Methods

// callback when FlexView API was loaded
fvp.whenLoaded( function() {} );

// callback when the map instance inside the FlexView API was loaded
// Note: this callback has to be registered inside "whenLoaded"
// Note: oax only (Desktop)
fvp.flexview.mapCB( function(map) {} );

// use a list of ids to define the set of OOIs
// note: see "initDataPointList" configuration option
fvp.setDataPointList( [ '1397449', '5345254' ] );

// an empty list may be used and leads to "0 results"
fvp.setDataPointList([]): empty list -> show no object (0 results)

// calling setDataPointList without parameter will reset the FlexView API
// all objects of the API project will be shown
fvp.setDataPointList()

// set map zoom and center fitting to an object
fvp.fitOOI( '5345254' );

// set map zoom and center fitting to a list of objects
fvp.fitOOI( [ '1397449', '5345254' ] );