Merge lp:~michihenning/unity-scopes-api/fallback-image into lp:unity-scopes-api

[Michi Henning]

Added "art-fallback" entry to "components" dictionary of the category renderer to allow a fallback image to be specified in case the art URI of a result cannot be retrieved.

Added "art-fallback" entry to "components" dictionary of the category renderer to allow a fallback image to be specified in case the art URI of a result cannot be retrieved.

[Michi Henning (michihenning)]

Facundo, I added you to the reviewer list because, for this to work, remote scopes also need to provide a fallback image.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:276
http://jenkins.qa.ubuntu.com/job/unity-scopes-api-ci/492/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-amd64-ci/17
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/17
        deb: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/17/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-i386-ci/17

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-ci/492/rebuild

review: Approve (continuous-integration)

[Michi Henning (michihenning)]

Marking as "In progress" because it looks like there is a whole bunch of other undocumented fields. See the linked bug, and please comment there, so we don't fragment the discussion.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:277
http://jenkins.qa.ubuntu.com/job/unity-scopes-api-ci/497/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-amd64-ci/22
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/22
        deb: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/22/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-i386-ci/22

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-ci/497/rebuild

review: Approve (continuous-integration)

[Michał Sawicz (saviq)]

Some inline comments.

On top of that, we probably need something similar for the preview widgets (gallery, image and header widgets). These would have to be just per-widget properties I think. Basically an additional "fallback" field for each of them.

review: Needs Fixing

[lp:~michihenning/unity-scopes-api/fallback-image]

278. By Michi Henning on 2015-01-07

Fixed release notes and changelog.

Made fallback a field of the "art" and "mascot" dictionaries.
Removed fallback for emblem.

279. By Michi Henning on 2015-01-07

Added "fallback" field to image, gallery, and header preview widgets.

[Michi Henning (michihenning)]

Thanks for the review! I agree, adding "fallback" into the existing "art" and "mascot" dictionaries is cleaner.

I've removed the emblem fallback, and I added "fallback" fields for the image, gallery, and header preview widgets.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:279
http://jenkins.qa.ubuntu.com/job/unity-scopes-api-ci/498/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-amd64-ci/23
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/23
        deb: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/23/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-i386-ci/23

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-ci/498/rebuild

review: Approve (continuous-integration)

[Facundo Batista (facundo)]

All looks great! Thanks

review: Approve

[Michał Sawicz (saviq)]

review: Approve

[Paweł Stołowski (stolowski)]

Looks good, thanks!

review: Approve

=== modified file 'CMakeLists.txt'
--- CMakeLists.txt	2014-12-09 15:26:12 +0000
+++ CMakeLists.txt	2015-01-07 23:05:33 +0000
@@ -207,7 +207,7 @@
 # API version
 set(UNITY_SCOPES_MAJOR 0)
 set(UNITY_SCOPES_MINOR 6)
-set(UNITY_SCOPES_MICRO 10)
+set(UNITY_SCOPES_MICRO 11)
 set(UNITY_SCOPES_SOVERSION 3)
 
 # Version for testing, with all symbols visible

=== modified file 'RELEASE_NOTES.md'
--- RELEASE_NOTES.md	2014-12-09 15:51:02 +0000
+++ RELEASE_NOTES.md	2015-01-07 23:05:33 +0000
@@ -1,6 +1,18 @@
 Release notes
 =============
 
+Changes in version 0.6.11
+=========================
+  - The JSON for a CategoryRenderer now supports a "fallback" field in the
+    "art" and "mascot" entries of the "components" dictionary.
+    This allows a scope to specify a category-specific
+    fallback image in case the artwork for a result cannot be retrieved.
+
+  - PreviewWidget now supports a "fallback" field for the "image",
+    "gallery", and "header" widget types. This allows the scope
+    to specify a fallback image in case the artwork for a widget
+    cannot be retrieved.
+
 Changes in version 0.6.10
 =========================
   - Renamed "Tags" scope .ini option to "Keywords".

=== modified file 'debian/changelog'
--- debian/changelog	2014-12-12 11:48:26 +0000
+++ debian/changelog	2015-01-07 23:05:33 +0000
@@ -1,3 +1,17 @@
+unity-scopes-api (0.6.11+15.04.20141212-0ubuntu2) UNRELEASED; urgency=medium
+
+  * The JSON for a CategoryRenderer now supports a "fallback" field in the
+    "art" and "mascot" entries of the "components" dictionary.
+    This allows a scope to specify a category-specific
+    fallback image in case the artwork for a result cannot be retrieved.
+
+  * PreviewWidget now supports a "fallback" field for the "image",
+    "gallery", and "header" widget types. This allows the scope
+    to specify a fallback image in case the artwork for a widget
+    cannot be retrieved.
+
+ -- Michi Henning <[e-mail]>  Tue, 06 Jan 2015 14:03:54 +1000
+
 unity-scopes-api (0.6.10+15.04.20141212-0ubuntu1) vivid; urgency=low
 
   [ Pawel Stolowski ]

=== modified file 'include/unity/scopes/PreviewWidget.h'
--- include/unity/scopes/PreviewWidget.h	2014-11-03 05:31:30 +0000
+++ include/unity/scopes/PreviewWidget.h	2015-01-07 23:05:33 +0000
@@ -64,12 +64,14 @@
     The JSON definition must be a dictionary that includes widget "id" and all the values of attributes required by desired
     \link previewwidgets widget type\endlink. For example, a definition of image widget may look as follows:
     \code{.cpp}
-    PreviewWidget img(R"({"id": "img", "type": "image", "source": "http://imageuri"})");
+    PreviewWidget img(R"({"id": "img", "type": "image", "source": "http://imageuri",
+                          "fallback": "file:///tmp/image.png"})");
     \endcode
 
     For cases where attribute mappings are to be used instead of direct values, they need to be enclosed in the "components" dictionary, e.g.
     \code{.cpp}
-    PreviewWidget img(R"({"id": "img", "type": "image", "components": { "source": "screenshot-url" } })");
+    PreviewWidget img(R"({"id": "img", "type": "image", "fallback": "file:///tmp/image.png",
+                          "components": { "source": "screenshot-url" } })");
     \endcode
     (this example assumes "screenshot-url" value is either available in the result object that's being previewed, or it will be pushed with
     unity::scopes::PreviewReply::push() method)

=== modified file 'src/scopes/CategoryRenderer.cpp'
--- src/scopes/CategoryRenderer.cpp	2014-08-11 11:28:07 +0000
+++ src/scopes/CategoryRenderer.cpp	2015-01-07 23:05:33 +0000
@@ -49,7 +49,8 @@
 
 As specified by the \c "category-layout" key of the \c "template" dictionary, Unity will render results associated with this category in a grid layout. The \c "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 \c "template" dictionary contains information to determine the correct renderer and its parameters, and the \c "components" dictionary contains mapping specifying which fields of the results are used by the renderer, where keys of the dictionary are understood by Unity and values specify either field name of the results directly (<tt>{"title": "album_name"}</tt> would mean that Unity will use <tt>result["album_name"]</tt> as a title for the grid tile), or the value can specify extra hints for the renderer as well as the result field name (<tt>{"art": {"field": "icon", "aspect-ratio": 1.3}}</tt>).
+To sum up, the \c "template" dictionary contains information to determine the correct renderer and its parameters, and the \c "components" dictionary contains mapping specifying which fields of the results are used by the renderer, where keys of the dictionary are understood by Unity and values specify either field name of the results directly (<tt>{"title": "album_name"}</tt> would mean that Unity will use <tt>result["album_name"]</tt> as a title for the grid tile), or the value can specify extra hints for the renderer as well as the result field name and a fallback image
+(<tt>{"art": {"field": "icon", "aspect-ratio": 1.3, "fallback": "file:///path_to_fallback_image}}</tt>).
 
 \section jsonschema1 JSON structure (v1)
 
@@ -68,9 +69,11 @@
 \subsection components1 components keys
 
 \arg \c title String specifying card's title
-\arg \c art URI specifying card's art (primary graphics), can contain subkeys: \c "aspect-ratio" (double specifying the aspect ratio of the graphics, default: 1.0)
 \arg \c subtitle String specifying subtitle of a card
-\arg \c mascot URI specifying card's mascot (secondary graphics)
+\arg \c art URI specifying card's art (primary graphics), can contain subkeys: \c "aspect-ratio" (double specifying the aspect ratio of the graphics, default: 1.0), \c "field" (specifying the result's field name that contains the URI), and
+\c "fallback" (fallback image to be used if the URI for a result's artwork cannot be retrieved).
+\arg \c mascot URI specifying card's mascot (secondary graphics), can contain subkeys: \c "aspect-ratio" (double specifying the aspect ratio of the graphics, default: 1.0), \c "field" (specifying the result's field name that contains the URI), and
+\c "fallback" (fallback image to be used if the URI for a result's mascot cannot be retrieved).
 \arg \c emblem URI specifying card's emblem
 \arg \c summary String specifying text summary
 \arg \c background Card background URI, can override the default specified in the card-background field of the template section (same format as for card-background)
@@ -79,9 +82,13 @@
 
 \section example 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.
+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 \c "components" dictionary), such fields will be preserved and available to the scope when handling result-specific methods (for example unity::scopes::ScopeBase::preview()).
+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 \c "components" dictionary), such fields will be
+preserved and available to the scope when handling result-specific methods (for example
+unity::scopes::ScopeBase::preview()).
 
 \code{.cpp}
 // use raw string literal, so we don't have to escape all the quotes
@@ -90,15 +97,16 @@
   "schema-version" : 1,
   "template" : {
     "category-layout" : "carousel",
-    "card-size": "small"
+    "card-size" : "small"
   },
   "components" : {
     "title" : "title",
     "art" : {
-      "field": "art",
-      "aspect-ratio": 1.3
+      "field" : "art",
+      "aspect-ratio" : 1.3
+      "fallback" : "file:///path_to_fallback_image",
     },
-    "subtitle": "publisher"
+    "subtitle" : "publisher"
   }
 }
 )";

=== modified file 'src/scopes/PreviewWidget.cpp'
--- src/scopes/PreviewWidget.cpp	2014-08-22 11:07:41 +0000
+++ src/scopes/PreviewWidget.cpp	2015-01-07 23:05:33 +0000
@@ -152,12 +152,14 @@
 
 \arg \c source A URI pointing to the image
 \arg \c zoomable A boolean specifying whether the image is zoomable (default: \c false)
+\arg \c fallback A fallback image to be used if the image URI cannot be retrieved (default: none)
 
 \code{.cpp}
 {
     PreviewWidget w1("img1", "image");
 
-    w1.add_attribute_value("source", Variant("file:///tmp/image.jpg"));
+    w1.add_attribute_value("source", Variant("http://example.com/image.jpg"));
+    w1.add_attribute_value("fallback", Variant("file:///tmp/image.jpg"));
     ...
 }
 \endcode
@@ -169,16 +171,18 @@
 List of attributes:
 
 \arg \c sources An array of image URIs
+\arg \c fallback A fallback image to be used if an image URI cannot be resolved (default: none)
 
 \code{.cpp}
 {
     PreviewWidget w1("gal", "gallery");
 
     VariantArray arr;
-    arr.push_back(Variant("file:///tmp/image1.jpg"));
+    arr.push_back(Variant("http://example.com/image1.jpg"));
     arr.push_back(Variant("file:///tmp/image2.jpg"));
     arr.push_back(Variant("file:///tmp/image3.jpg"));
     w1.add_attribute_value("sources", Variant(arr));
+    w1.add_attribute_value("fallback", Variant("file:///tmp/fallback.png"));
     ...
 }
 \endcode
@@ -192,6 +196,7 @@
 \arg \c title A string specifying the title
 \arg \c subtitle A string specifying the subtitle
 \arg \c mascot A URI specifying the mascot
+\arg \c fallback A fallback image to be used if the mascot URI cannot be retrieved (default: none)
 \arg \c emblem A URI specifying the emblem
 
 \code{.cpp}
@@ -199,7 +204,8 @@
     PreviewWidget w1("hdr", "header");
 
     w1.add_attribute_value("title", Variant("Result item"));
-    w1.add_attribute_value("mascot", Variant("file:///tmp/mascot.png"));
+    w1.add_attribute_value("mascot", Variant("http://example.com/image.png"));
+    w1.add_attribute_value("fallback", Variant("file:///tmp/fallback_mascot.png"));
     ...
 }
 \endcode