Image Policy

Overview

Displays a single, dynamically updatable, image to the user.

This face is similar to the ImageFaceView, but is able to dynamically update the displayed image based on real-time vAtom events. The set of rules that determine which image should be displayed are defined in the face config and are known as the Image Policy Face rules.

This array of rules is specified when the face is registered and is therefore immutable. Changes to the vAtom's properties cause the face to re-evaluated the rule set. If as a result of re-evaluation, a new image is selected, the face view updates its image. In this way the Image Policy Face view is able to update it's image in real-time.

Registering the face

This example below shows how to register the image face onto your vAtom's template.

{
  "template": "MyTemplateName",
  "display_url": "native://image-policy",
  "package_url": ".",
  "constraints": {
    "bluetooth_le": false,
    "contact_list": false,
    "gps": false,
    "three_d": true,
    "view_mode": "icon",
    "platform": "generic",
    "quality": "high"
  },
  "config": {
    "image_policy": [
      {
        "count_max": 0,
        "resource": "Image_X"
      },
      {
        "count_max": 1,
        "resource": "Image_Y"
      },
      {
        "field": "private.foo",
        "resource": "Image_T",
        "value": "taz"
      },
      {
        "resource": "Image_Z"
      }
    ]
  }
}

Image Policies

Image policies are a set of rules used by the face view to determine what image resource to display. The polices are stored in a ordered heterogenous array under the key: image_policy. The face advances through the array and displays the image for the first matching policy.

Two types of image policy are supported:

1. Child Count
2. Field Lookup

More policies will be added over time.

Child Count

This policy specifies an image to display based on the number of children a vAtom has. In this example, the resource named "Image_X" is shown if the number of children in the folder is less than or equal to two. If the number of children is greater than two the policy match fails and the next policy is evaluated.

{
  "count_max": 2,       // max child count
  "resource": "Image_X" // resource name to load
}

Field Lookup

This policy specifies an image to display based on the value of a field in the vAtom's private section. In the example below, if there exists a field color in the vAtom's private section, and the value is equal to white then the face will display the image resource named WhiteImage.

{
  "field": "private.color",  // key-path of the private property
  "value": "white",          // value for equality check
  "resource": "WhiteImage"   // resource name to load
}

The image policy array is heterogenous, this means the members of the array may be of any policy type. This gives the vAtom creator flexibility.

Face Config

The face config contains an image_policy field containing an array of policies. These policies are evaluated top-down, until a match is found. If no match is found, the face falls back onto the ActivatedImage.

Child Count

Configuring a policy rule for child count comparison.

Example JSON config:

 "config": {
    "image_policy": [
      {
        "count_max": 0,
        "resource": "Image_X"
      },
      {
        "count_max": 1,
        "resource": "Image_Y"
      },
      {
        "resource": "Image_Z"
      }
    ]
  }

Field Lookup

Configuring a policy rule for filed lookup and comparison.

  "config": {
    "image_policy": [
      {
        "field": "private.foo",
        "resource": "Image_T",
        "value": "taz"
      }
    ]
  }