~gary-wzl77/scope-aggregator/fix_1609230

# Scope aggregator introduction

This is a *declarative* aggregator scope template. You declare aggregated scopes and keywords  for inclusion in json files.

Consistent with release tag 1.5.

## No compilation

You may combine the various text files and icons with the built scope-aggregator .so file into a click package, thus creating rich aggregator scopes with no c++ coding and compilation.

## Including scopes

You may declare:

 * *scopes* to include (called "declared scopes")
 * *keywords* to aggregate scopes that advertise such keywords (called "declared keywords")
 * *categories* that contain specific declared scopes and declared keywords (called "declared categories")

## Order

You declare scopes, keywords and categories in a specific *order* that dictates the overall order of display at run time.

When declaring keywords and not using `shared_category` (which keeps its results together in a single category), the order it not entirely determinant. Therefore `shared_category` is recommended.

This order is used whether or not you also declared departments. (A department is treated as a section of the overall order, so even though you see only part of the overall order, the part you see still adheres to the order)

## Departments

You may declare departments. When doing so, every declared scope, declared keyword and declared category must be assigned to a department or it is not visible at run time.

## Categories

A category is automatically created for each declared scope, declared category, and declared keyword (when using shared categories, see below).

You can set various category items, including title, renderers, and, when a cagetegory contains a single child scope, whether tapping the category title switches focus to the child scope (called "link to child"). Note, enabling link to child on categories that contain multiple child scopes is not advisable because the category can only link to a single child but results from multiple child scopes are contained in the category.

## Renderers

You can declare renderers to control display of results (of declared scopes, declared keywords and declared categories) for three cases:

 * surfacing: declare a `renderer` in place (or use a common renderer with `renderer_common_id`) to control result display for normal results
 * searching: declare a `search_renderer` in place (or use a common renderer with `search_renderer_common_id`) a to control result display for results when the user is searching
 * first result: declare a `first_result_renderer` in place (or use a common renderer with `first_result_renderer_common_id`) to provide a different display for the first result. For example, the first news result may have a large photo with overlay text and the rest may use a small photo. The rest of the results are displayed using the surfacing renderer. Note that there are cases where first result renderer is not supported, for example keyword scopes that do not use a shared category.

In general, when no render is declared, the renderer is taken from the incoming result.

For convenience, you may declare renderers once in `common_templates` and refer to them by id for reuse.

## Cardinality

Cardinality means the number of results returned and displayed by any child scope instance whether included as a declared scope, a declared keyword, or a declared category. For example, if a child scope has two instances and the cardinality is 2, four results are displayed.

There are two apporaches to cardinality:

 * user settings: in this case, the user may use settings to to set cardinality, and the default cardinality is obtained from settings. This approach requires setttings.ini and matching declarations in child_scopes.json. (if they do not match the scope may  not function.)
 * declared for each declared scope, declared keyworrd and declared category. This approach only requires child_scopes.json.

You may use botth approachest simultaneously. If so, declared cardinality for declared scopes, keywords and categories preempt user settings.

### Cardinality by user settings

Suppose you want the user to choose between cardinality of 1,2,4, and 8, and you want the defaul to be 2. Here is your settings.ini:

        [cardinality]
        type = list
        defaultValue = 1
        displayValues = 1,2,4,8
        displayName = Results per source:

Note that the defaultValue is an *index*, thus a value of 0  would set the default to 1.

With this setttings.ini you *must* declare the same values in child_scopes.json as follows:

        "cardinality_settings":
        [
            {
                "value": 1
            },
            {
                "value": 2
            },
            {
                "value": 4
            },
            {
                "value": 8
            }
        ],

Note that the default value is set in settings.ini and is not mentioned elsewhere.

### Cardinality for any declared scope, keyword and category

When not using user settings for cardinality you can set cardinalities for any declared scope, keyword and category. Any not set use a default value.


        "scope|keyword|category":
        {
            [...]
            "cardinality": 3,


## Declared keyword shared categories

When you declare a keyword, you can optinally set it to display all results from all matching child scopes in a *single* category. This is a called a "shared category". If you do not, each matching child scope's results appear in a category unique to the child scope and the overall order of child scopes is less determinant. Therefore, if you choose not to use a shared category, you might consider placing the keyword in a department that contains nothing else, thus keeping the categories together.

## Keyword results should use common template

All keyword sccopes that advertise a particular keyword should provide results using a the same template (for example, title, art and summary, or title, subtitle and mascot) because the aggregator generally assumes such a template provides a renderer to display it. If any aggregated scope does not use the expected template, its results may be missing expected template data at run time when aggregated. Note: This is a social convention: child scope developers who add a keyword to their scope should check what the expected template is for that keyword.

# Declarations in child_scopes.json

All declarations are made `data/child_scopes.json`. This json file is divided into the following objects:

* `departments`: Here you declared your departments or declare you do not want departments
* `order`: Here you declare your specific scopes, keywords and cagtegories for aggregation
* `commmon_templates`: Here you declare category renderer tempalates you may use for multiple specified categories

## `departments` (required)

Structure:

        {
            "departments":
            {
                "do_not_use_departments": "false",
                "declarations":
                [
                    {
                        "id": "dept1",
                        "root": "true",
                        "_title": "Department 1"
                    },
                    {
                        "id": "dept2",
                        "root": "false",
                        "_title": "Department 2"
                    }
                ]
            }
            [...]
        }


### `do_not_use_departments` (optional)

Value: string. "true" or "false"

When this key is present and the value is "true" departments are not used (even if you separately declare departments). When not using departments, all current enabled scopes display in surfacing mode in the declared order.

### `declarations` (required)

Contains your declared departments for child scopes (but not for keyword aggregated scopes -- each keyword automatically  gets its own department). When `do_not_use_departments` is `true`, these declarations are ignored and the declarations array may be empty.

#### `id` (required)

Value: string

Each department needs a unique id.

#### `root` (required)

Value: "true" or "false

Sets the top level ("root") department.

One department must be "root": "true" and all the rest must be "root": "false".

#### `_title` (required)

Value: string

The department title. If you include the value as a msgid in your po/mo files, the title displays localized as avaiable.

### Examples

Using departments:

        {
            "departments":
            {
                "do_not_use_departments": "false",
                "declarations":
                [
                    {
                        "id": "dept1",
                        "root": "true",
                        "_title": "Department 1"
                    },
                    {
                        "id": "dept2",
                        "root": "false",
                        "_title": "Department 2"
                    }
                ]
            }
            [...]
        }

Not using departments:

        {
            "departments":
            {
                "do_not_use_departments": "true",
                "declarations":
                [
                ]
            }
            [...]
        }

## `order` (required)

Here you declare scopes, keywords and categories, with options for each. The order of declaration determines the order of display  at runtime, although not all scopes always display. (For example, if you are using departments, only the scopes in thee current department are displayed, but they still display in the declared order.)

        {
            [...]
            "order":
            [
                {
                    "scope":
                    {
                        [...]
                    },
                },
                {
                    "category":
                    {
                        [...]
                    },
                },
                {
                    "keyword":
                    {
                        [...] 
                    }
                },
                {
                    "scope":
                        [...]
                    },
                    [...]
                }
                {
                    "keyword":
                    {
                        [...] 
                    }
                },
                {
                    "category":
                    {
                        [...]
                    },
                }
            ]
            [...]
        }

### `scope` (optional)

Declare a specific scope for aggregation. 

        {
            [...]
            "order":
            [
                {
                    "scope":
                    {
                        "id": "com.canonical.texts_texts"
                        "local_id": "texts-1",
                        [...]
                    },
                },

#### `id` key (required)

Value: string

The id is a fully qualified scope name.

If you include only this with no further declared customization the child scope is aggregrated as is with a tappable category navigation link to child.

#### `local_id` key (required)

Value: string

Must be unique in this file. This diffferentiates scopes and allows multiple instances of the same scope, for example to include the scope several times using `child_department` to pull different results from it.

#### `department` (required when using departments)

Value: string

Places the child scope in this department. 

**Note**: This department must be declared in `departments`.

#### Category title

The category title may be set in various ways described below. 

Note: You must have a non-empty category title if the category provides a tap link to open the child scope because without a title that layout is currently broken, therefore, for child scopes where you want an empty title, set `"link_to_child": "false"`

##### `category_title` key (optional)

Value: string

Sets the category title to declared string.

##### `_category_title` key (optional)

Value: string

Sets the category title to the returned translation of declared string, where translations are obtained from the aggregator scope's .mo files.

##### `category_title_use_incoming` key (optional)

Value: can be anything (the key's existence alone triggers the action)

When this key exists, the category title is set from the first incoming child result that matches the various declared criteria.

#### `first_result_renderer_common_id` key (optional)

Value: string

The id must equal a template defined in `common_templates`.

Creates a new category specifically for the first result using the refered to renderer.

Only used if `_shared_category` present.

#### `first_result_renderer` key (optional)

Value: json defining a category renderer

Only used if `_shared_category` present.

Creates a new category specifically for the first result using the defined renderer. 

#### `renderer_common_id` key (optional)

Value: string

The id must equal a template defined in `common_templates`.

Uses the renderer referred to and defined in `common_templates` for all results (except for the first result if a renderer is provided for that).

Only used if `_shared_category` present.

#### `renderer` key (optional)

Value: json defining a category renderer

Only used if `_shared_category` present.

This provides the CategoryRenderer template use for results in this category. When this is not present, the template used is taken from the first result of the keyword scopes.

#### `search_renderer_common_id` key (optional)

Value: string

The id must equal a template defined in `common_templates`.

Uses the renderer referred to and defined in `common_templates` for all results when searching.

Only used if `_shared_category` present.

#### `search_renderer` key (optional)

Value: json defining a category renderer

Only used if `_shared_category` present.

This provides the CategoryRenderer to use when searching.

#### `child_department` key (optional)

Value: string: a department id of the child scope.

Displays only results from the specified child department.

Note: To limit the number of results displayed when using `child_department`, use `cardinality`.

Note: Because scope user searches by design only return matching results onnly from the top level department, searches in the aggregator scope will not return results when this is used.

#### `child_category` key (optional) DEPRECATED

Value: string

When present, only child results from the specified child catagory are displayed, and you may also set the maximum number of child results using `child_category_max_results` key.

Note: To limit the number of results displayed when using `child_category`, use `child_category_max_results`.

Note: If you also use `result_category_id_to_common_template`, results from that specified category *are* displayed (that is, they are not filterd out) using that specified common template (as documented).

This is deprecated becuase keywords are a more robust approach. 

#### `child_category_max_results` key (optional) DEPRECATED

Value: number

Only application when using `child_category`. (See `cardinality`.)

Sets the maximum number of results to display.

Deprecated along with  `child_category`.

#### `link_to_child` key (optional)

Value: string: "false"

By default, the category header for the child scope provides a widget to tap to switch to the child scope. Declaring `"link_to_child": "false"` removes this, making it impossible to switch to the child scope from the category header.

Note: When the category title is empty, this should not be set to "false" due to layout issues.

Note: When `"link_to_child": "true"` (either due to explicit declaration or when using the default value which is "true"), the scope framework does not currently support `"collapsed-rows": NUMBER` in the renderer template. When link_to_child is on, `"cardinality": NUMBER` may not appear to be respected if that number causes more results than display in the available vertical space for the child scope, although it is respected and does limit the number of results.

#### `swap_result_attributes` key (optional)

Value: json list of objects.

This allows you to move values among attibutes in the result. 

Example:

        [...]
        "swap_result_attributes":
        [
           {
                "incoming_result_key": "subtitle",
                "new_result_key": "title"
           }
        ]
        [...]

Note: To literally swap two attributes, three steps are required including an intermediate attribute, like so:

        [...]
        "swap_result_attributes":
        [
           {
                "incoming_result_key": "mascot",
                "new_result_key": "tmp"
           },
           {
                "incoming_result_key": "art",
                "new_result_key": "mascot"
           },
           {
                "incoming_result_key": "tmp",
                "new_result_key": "mascot"
            }
        ]
        [...]

#### `result_category_id_to_common_template` key (optional)

Value: json list of objects.

Allows you to display results with a specified category using a CategoryRenderer declared in `common_templates`. Useful for child scopes requiring login to use the same design for all login results from all child scopes.

Note: When also `child_category`, results using the specified category id(s) do display (are not filtered out), using the specified template.

        [...]
        "result_category_id_to_common_template":
        [
            {
                "result_category_id": "fbphotos_login",
                "common_template": "not_logged_in"
            }
        ]
        [...]

#### `sources` key (optional)

Value: json list of objects.

This key only applies to "com.canonical.scopes.clickstore" scope. 

"com.canonical.scopes.clickstore" scope is used to inform the user which scopes can be downloaded from the store for this aggregator in case there is little child scopes preinstalled.

`sources` key is most useful if your child_scopes.json only includes keyword scopes. Usage Example:
        [...]
        "scope":
        {
            "_category_title": "Install More Sources:",
            "id": "com.canonical.scopes.clickstore",
            "link_to_child": "true",                
            "local_id": "com.canonical.scopes.clickstore",
            "department": "dept-movies",
            "cardinality": 10,
            "sources":[
                {
                    "id": "com.canonical.scopes.eros_eros"
                },
                {
                    "id": "com.canonical.scopes.hotstar_hotstar"
                },
                {
                    "id": "com.canonical.scopes.timesofindia_timesofindia"
                },
                {
                    "id": "com.canonical.scopes.shemaroo_shemaroo"
                },
                {
                    "id": "com.canonical.scopes.zeetv_zeetv"
                }
            ]
        }
        [...]
For declared scopes, you don't need to specify them here in `sources` key. In detail,
If your child_scopes.json includes both keyword scopes and declared scopes, you can also use this key to specify the keyword scopes you want to include. You don't need to specify declared scopes here and they will be counted automatically.
If your child_scopes.json only includes declared scopes, you don't need this key and can use below example directly.
        [...]
        "scope":
        {
            "_category_title": "Install More Sources:",
            "id": "com.canonical.scopes.clickstore",
            "link_to_child": "true",                
            "local_id": "com.canonical.scopes.clickstore",
            "department": "dept-movies",
            "cardinality": 10,
        }
        [...]

### `keyword` (optional)

Declare a specific keyword for aggregation. 

The first result of aggregated child scopes is placed in the declared order. To keep all results in this order, use `shared_category`, which confines the results into a single category.

When not using `shared_category`, each aggregated keyword scope appears in its own category whose title is the child scope display name.

When using departments, you may assign these to a department with `department`. Or, use `_departmentt_title` to auto create a department for them. 

#### `keyword` key (required)

Value: a keyword whose advertising scopes will be aggreagated in this position in the order.

Defining two `keyword`s with identical values is not supported at this time.

#### `department` key (optional)

Value: string

If present, places the keyword aggegrateed scopes into the department. The department must be declared in `departments`.

#### `_department_title` key DEPRECATED

Value: string

When you have not assigned the keyword to a department, you create a department for this keyword automatically by declaring this key.

Do not declare this key when you have assigned the keyword to a department.

**Note**: If the value is a msgid in your po files, the department title is localized according to po files.

This is deprecated because it is easy to declare a department and assign the keyword to it. 

#### `shared_category` key (optional)

Value: string, "true" or "false"

When "true", all results from all scopes aggregated by this keyword are displayed in one category.

#### `_shared_category_title` key (optional)

Value: string

Only used if `_shared_category_title` present.

String that will be used (localized) for the category title.

### Renderers

These are identical to those described for `scope`. See that section.

### Examples

Place all "sports" scopes in a certain position in the order:

        {
            "order":
            [
                [...]
                {
                    "keyword":
                    {
                        "keyword": "sports"
                    }
                },
                [...]
            ]
        }

Example. Place all "sports" scopes in a certain position in the order and in a specific department:

        {
            "order":
            [
                [...]
                {
                    "keyword":
                    {
                        "keyword": "sports",
                        "department": "dept-sports"
                    }
                },
                [...]
            ]
        }

Example: Place all "news" keyword scopes in a certain position in the order and in a deparmentt. Use a single shared category for all such results, providing the category title, and renderers (by reference to `common_templates` for first result, the result of the normal results, and search results: 

        {
            "order":
            [
                [...]
                {
                    "keyword":
                    {
                        "keyword": "news",
                        "department": "dept-news",
                        "shared_category": "true",
                        "_shared_category_title": "News Headlines",
                        "first_result_renderer_common_id": "renderer-news-first-result",
                        "category_renderer_common_id": "renderer-news",
                        "search_renderer_common_id": "renderer-news-search",
                    }
                },
                [...]
            ]
        }

### `category`

You can declare a category that includes a specified set of scopes and keywords. All results from these child scopes are displayed in a single category.

You can place the category in a department and define the renderers for it (first result, normal, and search) in place or by referent to `common_templates`.

When not using user settings for cardinality, you can set it.

Each scope requires an `id` and a `local_id` (as described in `scope` material. It may optionally have a `child_department` that specifies to show only results from that. 

Each keyword also requires an `id` and a `local_id`.

Example using all currently supported keys:

        "order":
        [
            {
                "category":
                {
                    "id": "cat-1",
                    "_title": "A Title",
                    "cardinality": 1,
                    "department": "dept-cats",
                    "first_result_renderer_common_id": "news-first",
                    "renderer_common_id": "news",
                    "search_renderer_common_id": "news-search",
                    "scopes":
                    [
                        {
                            "id": "com.canonical.scopes.fbphotos_fbphotos",
                            "local_id": "fbphotos"
                        },
                        {
                            "id": "com.canonical.scopes.bbc_bbc",
                            "local_id": "bbc_business_cat-1",
                            "child_department": "http://feeds.bbci.co.uk/news/business/rss.xml"
                        },
                        {
                            "id": "com.canonical.scopes.bbc_bbc",
                            "local_id": "bbc_health_cat-1",
                            "child_department": "http://feeds.bbci.co.uk/news/health/rss.xml"
                        }
                    ],
                    "keywords":
                    [
                        {
                            "id": "news",
                            "local_id": "news_kw_cat-1"
                        },
                        {
                            "id": "headlines",
                            "local_id": "headlines_kw_cat-1"
                        }

                    ]
                }
            },
 

## `common_templates` key (optional)

Allows you to declare a category renderer once and use it multiple times. Useful for a common login result design. Each template requires a unique `id` and a `template`.
 
        {
            [...]
            "common_templates":
            [
                {
                    "id" : "not_logged_in",
                    "template":
                    {
                        [...]
                    }
                },
                {
                    "id" : "renderer-news-first-result",
                    "template":
                    {
                        [...]
                    }
                }
            ],
            ['...]
        }

### `id` (required)

Value: string

The `id` is used to refer to the common template when using `result_category_id_to_common_template`.

### `template` (required)

Value: json

The `template` is the categoryRenderer template to use for categories whose id matches `id`.

        {
            [...]
            "common_templates":
            [
                {
                    "id" : "not_logged_in",
                    "template":
                    {
                        "schema-version": 1,
                        "template":
                        {
                            "category-layout": "grid",
                            "card-size": "large",
                            "card-background": "color:///#5E2750"
                        },
                        "components":
                        {
                            "title": "title",
                            "subtitle": "subtitle"
                        }
                    }
                }
            ]
            [...]
        }


#### `default_query_string` key (optional)

Value: string: a query string passed to child scope

The key is useful for developer to display results with specific query string by default instead of results fetched with empty query string.


#### `only_in_search` key (optional)

Value: string: "true" or "false", default value: "false"

Displays only results of specified scope on search, not in surface.

Note:If aggregator has multiple departments, in order to display results in current departments, you need to declare the scope with different deparment and local_id separately.

        {
            "departments":
            {   
                "do_not_use_departments": "false",
                 "declarations":[
                     {   
                        "id": "dept-movies",
                        "root": "true",
                        "_title": "Movies"
                     },  
                     {   
                        "id": "dept-music",
                        "root": "False",
                        "_title": "Music"
                     }  
                 ]   
           },  
           [...]
           "order":
           [
                {
                    "scope":
                    {
                         "id": "your_scope_id",
                         "local_id": "your_scope_id_1",
                         "only_in_search":"true",
                         "department": "dept-movies"
                    },
                    [...]
                    "scope":
                    {
                         "id": "your_scope_id",
                         "local_id": "your_scope_id_2",
                         "only_in_search":"true",
                         "department": "dept-music"
                    }
                }
           ]


#### `exclude_scopes` key (optional)

Value:  json list of objects.

Suppose you want some scopes which supports one certain keywords not to display results, you can specify scope id in the exclude_scopes and scope aggregator will not display results of specified scopes. 

Note:This key is only supposed to be declared in a `keywords` json object, which doesn't not use a shared category.
e.g. amazon supports 'books' keyword, but in most cases it returns something unrelated to 'books' keyword. we can get rid of its results in the way as following.
     "order":
      [
        {
            "keyword":
            {
                "keyword": "books",
                "link_to_child" : "true",
                "exclude_scopes" :[
                    {
                        "id": "com.canonical.scopes.amazon"
                    }
                ]
            }
        }
     ]


#### `display_order` key (optional)

Value:  json list of objects.

display_order allows developer to set child scopes display order of keyword scope. You can specify multiple scope id in the display_order and scope aggregator will display child scopes according to the order you defined in display_order.Installed keyword child scopes that are not listed in display_order are displayed after installed display_order scopes and in a indeterminate order. 

Note: `display_order` must be a direct child of a `keyword`.
e.g. the following scopes support 'bollywood.movie' keyword, 
    1.Shemaroo
    2.Eros
    3.ZeeTV
    4.Star-plus
     
if we define display_order as following, shemaroo scope will be shown in the first place, then eros at 2nd place.And zeeTV and star-plus will be shown randomly
     "order":
      [
        {
            "keyword":
            {
                "keyword": "bollywood.movie",
                "link_to_child" : "true",
                "display_order" :[
                    {
                        "id": "com.canonical.scopes.shemaroo_shemaroo"
                    },
                    {
                        "id": "com.canonical.scopes.eros_eros"
                    }
                ] 
            }
        }
     ]