unity.scopes.CategoryRenderer

A category renderer template in JSON format. More...

#include <unity/scopes/CategoryRenderer.h>

Public Member Functions

 CategoryRenderer (std::string const &json_text=DEFAULT_RENDERER)
 Creates a CategoryRenderer from a JSON string. More...
 
std::string data () const
 Returns complete renderer template definition in JSON format. More...
 
Copy and assignment

Copy and assignment operators (move and non-move versions) have the usual value semantics.

 CategoryRenderer (CategoryRenderer const &)
 
CategoryRenderer & operator= (CategoryRenderer const &)
 
 CategoryRenderer (CategoryRenderer &&)
 
CategoryRenderer & operator= (CategoryRenderer &&)
 
virtual ~CategoryRenderer ()
 

Static Public Member Functions

static CategoryRenderer from_file (std::string const &path)
 Creates a CategoryRenderer from a text file. More...
 

Detailed Description

A category renderer template in JSON format.

This class specifies how is a particular category rendered by Unity. Note that the data is likely to change between major versions of Unity, and therefore the definition isn't strongly typed and provided by a scope author as a JSON string.

A Category contains all the information needed by Unity to render results provided by a scope author (by handling unity::scopes::SearchQueryBase::run()) in a way that gives the user as much useful information as possible. When pushing results to the query originator (unity::scopes::SearchReply::push()), each result needs to have a category associated, and this association determines what will the result look like.

The most important part of a category definition is the unity::scopes::CategoryRenderer instance. If you use the default constructor CategoryRenderer(), the renderer will use the following definition:

{
"schema-version" : 1,
"template" : {
"category-layout" : "grid"
},
"components" : {
"title" : "title",
"art" : "art"
}
}

As specified by the "category-layout" key of the "template" dictionary, Unity will render results associated with this category in a grid layout. The "components" dictionary specifies which result fields are used by Unity. In case of this definition, each tile of the grid will map the "title" field from the result (set also by the call to unity::scopes::Result::set_title()) as title for the grid tile, and "art" field from the result (see unity::scopes::Result::set_art()) as the icon for the grid tile.

To sum up, the "template" dictionary contains information to determine the correct renderer and its parameters, and the "components" dictionary contains a mapping that specifies which fields of the results are used by the renderer. The keys of the dictionary are understood by Unity and the values specify a field name of the results. For example, {"title": "album_name"} means that Unity will use result["album_name"] as a title for the grid tile.r

A value also can specify extra hints for the renderer, such as the result field name and a fallback image. For example, {"art": {"field": "icon", "aspect-ratio": 1.3, "fallback": "file:///path_to_fallback_image}}. The fallback image is shown by Unity if no image URL is provided by the result, but the card requires an image. The fallback image is also shown if the result provides an empty URL for an image, the image does not load due to an error, or if loading results in an empty image. If a result does not specify a fallback image and the actual image is empty or cannot be loaded, Unity substitutes a generic fallback image.

JSON structure (v1)

When using {"schema-version": 1}, the following keys are understood:

template keys

  • category-layout Specifies renderer type; possible values: "grid" (default), "carousel", "vertical-journal", "horizontal-list"
  • card-layout Specifies layout of the individual result cards; possible values: "vertical" (default), "horizontal"
  • card-size Size of the result cards; possible values: "small", "medium" (default), "large"; when using "category-layout": "vertical-journal" any integer between 12 and 38
  • overlay Overlay text data on top of the art; boolean, default false
  • collapsed-rows Number of result rows displayed while the category is collapsed; possible values: any non-negative integer, where 0 fully expands the category (only affects grid and vertical journal)
  • card-background Background color for the cards; string; URI in the format
    color://.md#rrggbb
    or
    color:///color_name
    or
    gradient://.md#rrggbb.md#rrggbb
    or an image URI (will be stretched)
  • quick-preview-type The type of media content represented by result cards, for use with inline playback; the only currently supported type is "audio".

components keys

  • title String specifying card's title
  • subtitle String specifying subtitle of a card
  • art URI specifying card's art (primary graphics), can contain subkeys: "aspect-ratio" (double specifying the aspect ratio of the graphics, default: 1.0), "field" (specifying the result's field name that contains the URI), and "fallback" (fallback image to be used if the URI for a result's artwork cannot be retrieved).
  • mascot URI specifying card's mascot (secondary graphics), can contain subkeys: "aspect-ratio" (double specifying the aspect ratio of the graphics, default: 1.0), "field" (specifying the result's field name that contains the URI), and "fallback" (fallback image to be used if the URI for a result's mascot cannot be retrieved).
  • emblem URI specifying card's emblem
  • summary String specifying text summary
  • background Card background URI, can override the default specified in the card-background field of the template section (same format as for card-background)
  • attributes Array of dictionaries specifying text and an optional icon (keys: "value", "icon")
  • overlay-color Color of overlay for templates with overlay
  • quick-preview-data A dictionary with the following keys: "uri" (an uri of audio stream or file), "duration" (duration in seconds), "playlist" (an array of uris of additional songs to be played in sequence when the main song finishes).

Example

In the following example a category named "Recommended" containing three components is created (title, art, and subtitle), and a result providing values for these components is pushed.

Note that the scope is free to set any other extra result fields even if they are not used by the renderer (and therefore not specified in the "components" dictionary), such fields will be preserved and available to the scope when handling result-specific methods (for example unity::scopes::ScopeBase::preview()).

<span class="comment">// use raw string literal, so we don&#39;t have to escape all the quotes</span>
std::string CATEGORY_DEFINITION = R<span class="stringliteral">&quot;(</span>
<span class="stringliteral">{</span>
<span class="stringliteral">  &quot;schema-version&quot; : 1,</span>
<span class="stringliteral">  &quot;template&quot; : {</span>
<span class="stringliteral">    &quot;category-layout&quot; : &quot;carousel&quot;,</span>
<span class="stringliteral">    &quot;card-size&quot; : &quot;small&quot;</span>
<span class="stringliteral">  },</span>
<span class="stringliteral">  &quot;components&quot; : {</span>
<span class="stringliteral">    &quot;title&quot; : &quot;title&quot;,</span>
<span class="stringliteral">    &quot;art&quot; : {</span>
<span class="stringliteral">      &quot;field&quot; : &quot;art&quot;,</span>
<span class="stringliteral">      &quot;aspect-ratio&quot; : 1.3</span>
<span class="stringliteral">      &quot;fallback&quot; : &quot;file:///path_to_fallback_image&quot;,</span>
<span class="stringliteral">    },</span>
<span class="stringliteral">    &quot;subtitle&quot; : &quot;publisher&quot;</span>
<span class="stringliteral">  }</span>
<span class="stringliteral">}</span>
<span class="stringliteral">)&quot;;</span>
<span class="stringliteral"></span>
<span class="stringliteral"></span><span class="keywordtype">void</span> MyQuery::run(<a class="code" href="unity.scopes.md#a9cd604d9b842ac3b2b8636c2165dec1f">SearchReplyProxy</a> <span class="keyword">const</span>&amp; reply)
{
<span class="keyword">auto</span> category = reply-&gt;register_category(<span class="stringliteral">&quot;recommended&quot;</span>, <span class="stringliteral">&quot;Recommended&quot;</span>, icon, <a class="code" href="#a046414ae2092968686ee4ee00629054a">CategoryRenderer</a>(CATEGORY_DEFINITION));
<span class="comment">// push a sample result</span>
CategorisedResult result(category); <span class="comment">// create a result item in &quot;recommended&quot; category</span>
result.set_uri(<span class="stringliteral">&quot;http://www.example.org&quot;</span>);
result.set_title(<span class="stringliteral">&quot;Example Result&quot;</span>);
result.set_art(<span class="stringliteral">&quot;http://www.example.org/graphics.png&quot;</span>);
result.set_dnd_uri(<span class="stringliteral">&quot;http://www.example.org&quot;</span>);
result[<span class="stringliteral">&quot;publisher&quot;</span>] = <span class="stringliteral">&quot;Example.org&quot;</span>;
reply-&gt;push(result); <span class="comment">// send result to the client</span>
}

Constructor & Destructor Documentation

unity::scopes::CategoryRenderer::CategoryRenderer ( std::string const &  json_text = DEFAULT_RENDERER)
explicit

Creates a CategoryRenderer from a JSON string.

Parameters
json_textRenderer template in JSON format
Exceptions
unity::InvalidArgumentExceptionif json_text cannot be parsed

Member Function Documentation

std::string unity::scopes::CategoryRenderer::data ( ) const

Returns complete renderer template definition in JSON format.

Returns
The renderer template (JSON).
static CategoryRenderer unity::scopes::CategoryRenderer::from_file ( std::string const &  path)
static

Creates a CategoryRenderer from a text file.

Returns
The CategoryRenderer corresponding to the information in the file.