Layer with Actions

In the first tutorial - Create a simple Geo-location layer, we went through the steps to create a simple geolocation layer. In this tutorial, we are going to explain how to include actions in this layer. In general, the following changes are made:

• MySQL database - Add a new table called "POIAction" to the database.
• PHP code - Add one function called "getPoiActions" to handle the actions defined for POIs.

Before reviewing the PHP script, you are strongly recommended to check out the Howto introduction on what kind of actions are supported in Layar. In this tutorial, we will add the following actions:

NOTE that since we are using POI level actions defined in API version 4.0, in layer editing section(listing & indexing tab), we need to change the Minimum API version to version 4.0 (see screenshot below):

Now, we are going to explain how to implement Actions on top of the sample code created in the First Tutorial. If you have not read the first tutorial, please do so to help better understand the following content.

Create a separate table for Actions

In this tutorial, we create a separate table called "POIAction" to store actions defined for POIs. Each action has its own id as primary key and a poiID field to store the corresponding POI id in the POI table (POI table is created in the first tutorial to store POIs).

Based on the Action definition in the API, we created the following POIAction table.

Please NOTE that Actions can be applied to both Geo POIs and Vision enabled POIs. The only difference is the auto-trigger Actions. In this Tutorial, we will explain how to applied actions to Geo POIs as an example. 

An example of the action table is below. The first action "Contact Layar" has an auto-trigger range of 5000m, which means that this action will be auto-triggered when a user is within this range of the POI. For "params" field, we use comma to separate the parameters. The rest fields, "method","closeBiw", "showActivity" and "activityMessage" are left as default.

Create a new function to retrieve actions

A new function called getPoiActions() is created to fetch actions for each POI.

// Put fetched actions for each POI into an associative array.
//
// Arguments:
//   db ; The database connection handler.
//   poi ; The POI array.
//
// Returns:
//   array ; An associative array of received actions for this POI.Otherwise,
//   return an empty array.
//
function getPoiActions($db , $poi) {
  // Define an empty $actionArray array.
  $actionArray = array();

  // A new table called "POIAction" is created to store actions, each action
  // has a field called "poiID" which shows the POI id that this action belongs
  // to.
  // The SQL statement returns actions which have the same poiID as the id of
  // the POI($poiID).
  $sql_actions = $db->prepare("
      SELECT label,
             uri,
             autoTriggerRange,
             autoTriggerOnly,
             contentType,
             activityType,
             params
        FROM POIAction
       WHERE poiID = :id ");

  // Binds the named parameter marker ":id" to the specified parameter value
  // "$poiID.                 
  $sql_actions->bindParam(':id', $poi['id'], PDO::PARAM_STR);
  // Use PDO::execute() to execute the prepared statement $sql_actions.
  $sql_actions->execute();
  // Iterator for the $actionArray array.
  $count = 0;
  // Fetch all the poi actions.
  $actions = $sql_actions->fetchAll(PDO::FETCH_ASSOC);

  /* Process the $actions result */
  // if $actions array is not empty.
  if ($actions) {
    // Put each action information into $actionArray array.
    foreach ($actions as $action) {
      // Assign each action to $actionArray array.
      $actionArray[$count] = $action;
      // put 'params' into an array of strings
      $actionArray[$count]['params'] = changetoArray($action['params'] , ',');
      // Change 'activityType' to Integer.
      $actionArray[$count]['activityType'] = changetoInt($action['activityType']);
      // Change 'autoTriggerRange' to Integer.
      $actionArray[$count]['autoTriggerRange'] = changetoInt($action['autoTriggerRange']);
      // Change 'autoTriggerOnly' to Boolean.
      $actionArray[$count]['autoTriggerOnly'] = changetoBool($action['autoTriggerOnly']); 

      $count++;
    }// foreach
  }//if
  return $actionArray;
}//getPoiActions

As you can see that we used several other functions such as changetoArray(), to convert the returned values into the right type.

// Convert a string into an array.
//
// Arguments:
//  string ; The input string
//  separater, string ; The boundary string used to separate the input string
//
// Returns:
//  array ; An array of strings. Otherwise, return an empty array.
function changetoArray($string, $separator){
  $newArray = array();
  if($string) {
    if (substr_count($string,$separator)) {
      $newArray= array_map('trim' , explode($separator, $string));
        }//if
    else
      $newArray[0] = trim($string);
  }
  return $newArray;
}//changetoArray

Modify the getHotspots function to include POI actions in the JSON response

In getHotspots function, we use getPoiActions() function to retrieve POI actions.

// Use function getPoiActions() to return an array of actions associated with the current POI.
      $poi["actions"] = getPoiActions($db, $rawPoi); 

This is the end of this tutorial. The code used above is provided in the sample code file below.  A more generic solution is also provided to support:

• layer level actions, a separate table (LayerActions) is created in the database and a new function getLayerActions() is defined to return actions applied to the entire layer.

For detailed information, please check out the attached Sample Code.