Merge lp:~knitzsche/scope-aggregator/refactor-handle-methods_add-login_remove-shared-category into lp:scope-aggregator

[Kyle Nitzsche]

For a proposed 4.13 release.

* Significant refactor of the three methods that handle results:
handle_category_child(), handle_keyword_child(), handle_declared_child(). These
were simply too hard to debug and understand, and they had redundant code to
lookup and, if needed, to register Categories. Each of the three methods is
refactored as follows: define an enum that states the possible run types for
the method: get state variables, analyze state and set run type, switch on run
type to select code. Category lookup and registration is now moved to new
set_result_category() method, which has two signatures depending on whether a
link to child is needed. The three methods (and related) are moved to a new
file for clarity: handle_results.cpp.

* Added support for a "login_renderer" and
"login_renderer_incoming_category_id" declarations in child_scopes.json. See
the updated README.md. I also added gtests for this.

* Removed "shared category" from "keywords". This feature is not used, I think.
I did not find it in all child_scopes.json files in clicks branch. It is mostly
redundant with a "category". That is, they both confine keywords to a Category
(although category type also can include scopes). We can reimplemented any
features that were supported only in keywords that are not supported in
categories if needed.

* Added Query::is_using_departments() method. And added gtesting for this.
Note: With this MP, an agg scope child_scopes.json file does not need a
"departments" object: it's absence is sufficient to signal no departments.

* Updated/rewrote README.md.

I tested this in Today, News, Nearby and Photos. It would be awesome if the .so
could be tested with our other aggregators!

[Kyle Nitzsche (knitzsche)]

Note: I started doing this refactoring to help debug https://bugs.launchpad.net/canonical-devices-system-image/+bug/1622423. However, after the refactor that issue continues, and I suspect it may be a unity8 rendering issue (I am working with unity api team on this separately).

[Zhang Enwei (zhangew401)]

LGTM except some typos.
I verified on food, films, china-dashboard, news-china and baidu aggregator scopes.

review: Approve

[Kyle Nitzsche (knitzsche)]

thanks Enwei.

=== added file 'DELETED_FEATURES.md'
--- DELETED_FEATURES.md	1970-01-01 00:00:00 +0000
+++ DELETED_FEATURES.md	2016-09-30 19:17:35 +0000
@@ -0,0 +1,1 @@
+4.12: keyword object with shared_shared category: just use category.

=== modified file 'README.md'
--- README.md	2016-08-04 01:11:41 +0000
+++ README.md	2016-09-30 19:17:35 +0000
@@ -1,65 +1,90 @@
-# 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
+# Scope aggregator
+
+This is a *declarative* aggregator scope template. You declare aggregated scopes and keywords for inclusion in json files.
 
 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)
+Here are couple examples:
+
+ * Today Scope: https://launchpad.net/today-scope
+ * News Scope: https://launchpad.net/news-scope
+
+## Declaring scopes and the overall order
+
+You may declare one or more:
+
+ * `scope`: includes a single scope
+ * `category`: includes a set of scopes and keywords
+ * `keyword`: includes child scopes that answer to the keywords
+
+These are declared directly inside the `order` json list element. The order of declaration determines the order of presentation in the aggregator scope, with the exception of `keyword` (explained below)
+
+The unity scope framework API provides Category objects. These are used to group together scope results. Scope-aggregator uses Categories as follows:
+
+ * `scope`: A single Category is created for each `scope`. It contains all results from the scope. The Category displays in the declared order.
+ * `category`: A single Category is created for each `category`. It contains all results from the internally declared set of scopes and from all present scopes that answer to the internally declared set of keywords. The Category displays in the declared order.
+ * `keyword`: A Category is created for each scope that answers to the declared keyword. By default, the only guarantee relating to the overall order is that the first such child scope appears in the declared order. Categories for all other scopes that answer to the keyword display in an determinant order (but always after the first). You can use the additional `display_order` feature to set the order of child scopes answering to this keyword.
 
 ## 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.
+The unity scope framework provides Department objects. When used, these are selectable by tapping the magnifying glass, which displays a tappable list of Departments.
+
+You may declare departments. When doing so, every declared `scope`, `category` and `keyword` must be assigned to a department or it is not visible at run time.
+
+The declared order applies with declared departments. A department is treated as a sub-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.
+
+Each Department requires a title and a unique ID that you use to place each `scope`, `category` and `keyword` in a department.
+
+One department is declared as the default root department (it is the one displayed before the user selects any other department).
 
 ## 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.
+As noted, a Category is automatically created for each `scope`, `category`, and for each scope answering to a `keyword`.
+
+You can set various Category items, including title, renderers, and, whether tapping the category header (which displays the title) switches focus to another child scope (called "link to child"). 
+
+By default, the link to child feature is enabled for `scope` and `keyword` categories. It can be disabled with `"link_to_child": "false"`.
+
+For `category` declaration, the link to child feature may or may not make sense. By default, there is no link to child for `category`. But, if the `category` always and only contains a single child scope, it usually makes sense. This is enabled with `"link_to_child_specified": "scope ID"`.
+
+But, when a `category` contains multiple child scopes, either when the `category` is declared with more than one child scope or when it is declared to include a keyword (which may result in multiple child scopes, link to child may not be appropriate because there may be no reasonable single child scope to link to. But even with multiple child scopes, link to child may still be appropriate: for example, the Today scope has a `category` that aggregates news headlines. It has a link to child that takes the user to the News scope
+Headlines department. 
 
 ## 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.
+The unity scope framework has the concept of a layout renderer that controls the display of results. The renderer dictates what the displayed result consists of, that is, its "components" (for example a title and an art, or a title, a subtitle, and a mascot). Each component consist of the key (which dictates the type of component) and the name of the property in the result that contains the value to be used. For example, "art": "image", which means each result has an "art" attribute whose value is derived from the result field named "image".
+
+The renderer also dictates the layout (for example, large card with grid layout, or vertical-journal, etc.).
+
+You can declare renderers to control display as follows:
+
+ * Surfacing: declare a `renderer` in place (or use a common renderer with `renderer_common_id`) to control result display for normal results.
+ * Login: declare a `login_renderer` with a `login_renderer_incoming_category_id` to control display of login results for the specified category_id. When declared, if the incoming result has the specified category, then ID the declared login renderer is used. This is not available for `keyword` declarations because one generally does not know the category ID for scopes that may answer to the keyword, and keyword scopes probably all use different category IDs for login 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. This is only available for `category` declarations.
+
+In general, when no render is declared, the renderer is taken from the first incoming result in the Category. This works, but the layout and design is not in control of the aggregator scope developer, and there is no consistency in the layout and design among the multiple child scopes displayed. Therefore, designing and declaring renderers is a critical part or aggregator scope development.
+
+Typically you declare your renderers right inside your `scope`, `category` or `keyword` object. 
+
+If you wish to declare renderers once and reuse them, you may declare each type of renderer (except for the login renderer) once in a `common_templates` object and  include them by ID inside your `scope`, `category` or `keyword` object, as explained below.
 
 ## 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 is the number of results returned and displayed by any single child scope instance. That is, the cardinality is sent to each child scope when asking for results to display, and the child scope follows this and returns no more than the requested number of result (it may return less).
+
+Note that in the case of a `category` that contains more than one scope, the overall maximum number of results displayed is the cardinality multiplied by the number of child scopes in the `categoory`.
+
+There are two approaches to implementing cardinality:
+
+ * Scope settings: in this case, you implement the cardinality choices for scope settings, including the default. This allows user cardinality choice. This approach requires a settings.ini file and matching declarations in child_scopes.json. (if they do not match the scope may  not function.)
+ * Declared for each `scope`, `category` and `keyword`. 
+
+You may use both approaches simultaneously. If so, declared cardinality for `scope`, `category` and `keyword` preempts settings.
+
+### Cardinality with scope settings
+
+Suppose you want the user to choose between cardinality of 1,2,4, and 8, and you want the default to be 2. Here is your settings.ini:
 
         [cardinality]
         type = list
@@ -67,9 +92,9 @@
         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.
+Note that the defaultValue is an *index* starting at 0, thus a value of 1 would set the default to 2.
 
-With this setttings.ini you *must* declare the same values in child_scopes.json as follows:
+With this settings.ini you *must* declare the same values in child_scopes.json as follows:
 
         "cardinality_settings":
         [
@@ -87,12 +112,10 @@
             }
         ],
 
-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.
-
+You can set cardinalities for any `scope`, `category` and `keyword`. This locally preempts any settings cardinality.
 
         "scope|keyword|category":
         {
@@ -100,23 +123,70 @@
             "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.
+## Fallbacks and Result Attribute Swaps
+
+Sometime child scopes provide results that contain the pieces of information the renderer needs, but they are not arranged as expected.
+
+For example, a scope might provide a news result with the url to the art in the "mascot" attribute, yet your aggegrator scope may expect the art to be in the "art" attribute.
+
+There are two methods for dealing with this:
+
+ * Fallbacks
+ * Attribute swaps
+
+### Fallbacks
+
+Fallbacks allows you to declare that for a given attribute in your renderer (for example "art"), you want to check a specified series of fields in the incoming result and use the first one that exists. For example, to get a value for your "art" field, you might want to check the "art" field, then the "mascot" field, and finally the "emblem" field of each incoming result. 
+
+This is currently support using `common_templates`. Your template in common templates declares a `fallbacks` object. And of course, you declare a renderer to use the common template (instead of being declared in place).
+
+This example accomplishes the above goal:
+
+        "common_templates":
+        [   
+            {   
+                "id" : "news-first",
+                "fallbacks":
+                [   
+                    {   
+                        "key": "art",
+                        "fields":
+                        [   
+                            {"field": "art"},
+                            {"field": "mascot"},
+                            {"field": "emblem"}
+                        ]   
+                    }   
+                ],  
+                "template":
+                {   
+                [...]
+                }   
+            }, 
+        [...]
+        }
+
+
+### Result Attribute Swaps
+
+For `scope` types, you may also declare a specific attribute swaps to make on every incoming result. For example, if you know the child scope puts the art url in the mascot field, you can declare that the "art" attribute should be populated by the incoming "mascot" field.
+
+See `swap_result_attributes`.
 
 # Declarations in child_scopes.json
 
-All declarations are made `data/child_scopes.json`. This json file is divided into the following objects:
+All declarations are made `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)
+* `cardinality`: Here you declared cardinality options for use with scope settings.
+* `order`: Here you declare your specific scopes, keywords and categories for aggregation
+* `commmon_templates`: Here you declare category renderer templates you may use for multiple specified categories
+
+The order of these objects in the file has no affect.
+
+## `departments` (optional)
+
+When not present, departments are not used.
 
 Structure:
 
@@ -146,7 +216,7 @@
 
 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.
+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. This is useful during development. As noted, when the `departments` object is not present, objects are not used. 
 
 ### `declarations` (required)
 
@@ -170,7 +240,7 @@
 
 Value: string
 
-The department title. If you include the value as a msgid in your po/mo files, the title displays localized as avaiable.
+The department title. If you include the value as a msgid in your po/mo files, the title displays localized as available.
 
 ### Examples
 
@@ -212,7 +282,7 @@
 
 ## `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.)
+Here you declare `scope`s, `keywords` and `category` objects, with options for each. The order of declaration determines the order of display at runtime, as described above.
 
         {
             [...]
@@ -281,13 +351,13 @@
 
 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.
+If you include only this with no further declared customization the child scope is aggregated 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.
+Must be unique in this file. This differentiates 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)
 
@@ -321,24 +391,6 @@
 
 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
@@ -347,14 +399,10 @@
 
 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)
@@ -365,48 +413,46 @@
 
 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)
 
+DEPRECATED. Use keywords in the child scope and here instead. There is no way to determine whether a child scope has a particular department at run time, and if you use this key and the specified department does not exists, there is an uncaught exception in the child scope that causes problems. 
+
 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.
+Note: Because scope user searches by design return matching results only from the top level department, searches in the aggregator scope will not return results when this is used.
 
 #### `child_category` key (optional) DEPRECATED
 
+DEPRECATED. Use keywords, a much more robust approach.
+
 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.
+When present, only child results from the specified child category 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. 
+Note: If you also use `result_category_id_to_common_template`, results from that specified category *are* displayed (that is, they are not filtered out) using that specified common template (as documented).
 
 #### `child_category_max_results` key (optional) DEPRECATED
 
+DEPRECATED along with  `child_category`.
+
 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"
@@ -415,13 +461,13 @@
 
 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.
+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. (Note: this needs to be tested)
 
 #### `swap_result_attributes` key (optional)
 
 Value: json list of objects.
 
-This allows you to move values among attibutes in the result. 
+This allows you to move values among attributes in the result. 
 
 Example:
 
@@ -459,9 +505,7 @@
 
 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.
+Allows you to display results with a specified category using a CategoryRenderer declared in `common_templates`. 
 
         [...]
         "result_category_id_to_common_template":
@@ -473,13 +517,15 @@
         ]
         [...]
 
+Note: This has often been used for a common layout for login results from different child scopes. As of scope aggregator release 4.12 you can use the new `login_renderer`/`login_renderer_incoming_category_id` pair of keys for directly declaring a renderer in your declared `scope`, or `category`. 
+
 #### `keyword_scope_ids` key (optional)
 
 Value: json list of objects.
 
 This key is only used on the special clickstore scope declared with "id": "com.canonical.scopes.clickstore".
 
-This clickstore scope displays scopes that are not installed and allows the user to install them.
+This clickstore scope can display scopes that are declared but are not installed and allows the user to install them.
 
 By default, the clickstore scope (when declared) displays all child scopes declared in the child_scopes.json file by scope ID that are not currently installed.
 
@@ -530,128 +576,21 @@
         }
         [...]
 
-### `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`
+### `category` (optional)
 
 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`.
+You can place the category in a department and define the renderers for it (normal, first result, and search) in place or by reference to `common_templates`.
 
-When not using user settings for cardinality, you can set it.
+You can declare cardinality that overrides scope settings for cardinality, if used.
 
 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:
+You may declare `"link_to_child_specified": "SCOPE_ID"` to provide a tappable link to the child scope on the Category header.
+
+Example:
 
         "order":
         [
@@ -697,13 +636,103 @@
                 }
             },
  
+### `keyword` (optional)
+
+Declare a specific keyword for aggregation. 
+
+The category for the first child scope that answers under the specified keyword is always placed in declared position in the overall order. 
+
+If multiple child scopes reply under the specified keyword, a category is created for each child scope whose title is taken from the first such incoming result. The order of the second scope and later child scopes is not determinant: they are positioned in the over all order in the order in which they are received. Therefore, `keyword` may be useful as the last item declared in the `order` as a catch-all to pick up additional relevant content without affecting the declared order that precedes it. order of 
+
+Note: To keep all results from all child scopes that answer a specific keyword together in a single category (thus preserving the overall order),  use `category` with `keywords` instead.
+
+You can place the keyword scopes in a department and define the renderers for it (normal, first result, and search - but not login) in place or by reference to `common_templates`.
+
+You can declare cardinality that overrides scope settings for cardinality, if used.
+
+#### `keyword` key (required)
+
+Value: a keyword whose advertising scopes will be aggregated in this position in the order.
+
+This is the unique ID with file scope. `Defining two `keyword`s with identical values is not supported.
+
+#### `department` key (optional)
+
+Value: string
+
+If present, places the keyword aggregated scopes into the department. The department must be declared in `departments`.
+
+#### Renderers
+
+These are identical to those described for `scope` except `login_renderer` is not supported.
+
+### `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.
+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"
+                        }
+                    ] 
+                }
+            }
+         ]
 
 ## `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`.
+Allows you to declare a renderer once and use it multiple times. Each template requires a unique `id` and a `template`.
+
+
  
         {
-            [...]
             "common_templates":
             [
                 {
@@ -715,13 +744,18 @@
                 },
                 {
                     "id" : "renderer-news-first-result",
+                    "fallbacks:
+                    {
+                        [...]
+                    }                    
                     "template":
                     {
                         [...]
                     }
                 }
             ],
-            ['...]
+            "order":
+            [...]
         }
 
 ### `id` (required)
@@ -737,6 +771,9 @@
 The `template` is the categoryRenderer template to use for categories whose id matches `id`.
 
         {
+            "departments":
+            [...]            
+            "order":
             [...]
             "common_templates":
             [
@@ -762,21 +799,25 @@
             [...]
         }
 
-
-#### `default_query_string` key (optional)
+### `fallbacks` (optional)
+
+See Fallbacks discussion.
+
+## Other Features
+
+### `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)
+### `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.
+Note: If aggregator has multiple departments, in order to display results in current departments, you need to declare the scope with different department and local_id separately.
 
         {
             "departments":
@@ -818,60 +859,3 @@
            ]
 
 
-#### `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"
-                    }
-                ] 
-            }
-        }
-     ]

=== modified file 'gtests/CMakeLists.txt'
--- gtests/CMakeLists.txt	2016-08-19 20:20:58 +0000
+++ gtests/CMakeLists.txt	2016-09-30 19:17:35 +0000
@@ -34,6 +34,7 @@
     ../src/resultforwarder.cpp
     ../src/scope.cpp
     ../src/utils.cpp
+    ../src/handle_results.cpp
     ../src/aggchildscope.cpp
     ../src/listener.cpp
     ../src/action.cpp
@@ -72,6 +73,9 @@
     COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/scope_directory/hints_local.json" "${CMAKE_CURRENT_BINARY_DIR}/scope_directory/hints_local.json"
     COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/scope_directory/hints.json" "${CMAKE_CURRENT_BINARY_DIR}/scope_directory/hints.json"
     COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/scope_directory/hints_remote.json" "${CMAKE_CURRENT_BINARY_DIR}/scope_directory/hints_remote.json"
+    COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/scope_directory/login_1.json" "${CMAKE_CURRENT_BINARY_DIR}/scope_directory/login_1.json"
+    COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/scope_directory/login_2.json" "${CMAKE_CURRENT_BINARY_DIR}/scope_directory/login_2.json"
+    COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/scope_directory/login_3.json" "${CMAKE_CURRENT_BINARY_DIR}/scope_directory/login_3.json"
     COMMAND ${CMAKE_COMMAND} -E make_directory "${CMAKE_CURRENT_BINARY_DIR}/cache_directory"
 )
 

=== modified file 'gtests/MockRegistry.h'
--- gtests/MockRegistry.h	2016-08-17 16:17:03 +0000
+++ gtests/MockRegistry.h	2016-09-30 19:17:35 +0000
@@ -154,6 +154,13 @@
         {
            mm.insert(pair<string, ScopeMetadata>("full_keyword_3", full_keyword_3));
         }
+
+        set<string> keywords_login = {"login-test"};
+        auto login_metadata = build_scope_metadata("login-test", keywords_login);
+        if (predicate(login_metadata))
+        {
+           mm.insert(pair<string, ScopeMetadata>("login-test", login_metadata));
+        }
         return mm;
     }
 };

=== added file 'gtests/scope_directory/login_1.json'
--- gtests/scope_directory/login_1.json	1970-01-01 00:00:00 +0000
+++ gtests/scope_directory/login_1.json	2016-09-30 19:17:35 +0000
@@ -0,0 +1,74 @@
+{
+    "common_templates":
+    [
+        {
+            "id" : "default-renderer",
+            "template":
+            {
+                "components":
+                {
+                    "art": "art",
+                    "title": "title",
+                    "subtitle": "subtitle",
+                    "summary": "summary",
+                    "emblem": "emblem"
+                },
+                "schema-version": 1,
+                "template":
+                {
+                    "card-layout": "horizontal",
+                    "card-size": "large",
+                    "collapsed-rows": 0,
+                    "category-layout": "vertical-journal"
+                }
+            }
+        }
+    ],
+    "order":
+    [
+        {
+            "scope": {
+                "id": "scope_login",
+                "local_id": "local_scope_2",
+                "renderer_common_id": "fallbacks"
+            }
+        },
+        {
+            "category":
+            {
+                "id": "headlines",
+                "department": "dept-headlines",
+                "_title": "Headlines",
+                "renderer_common_id": "default-renderer",
+                "login_renderer_incoming_category_id": "login-category",
+                "login_renderer":
+                {
+                    "components":
+                    {
+                        "mascot": "login-art",
+                        "title": "login-title"
+                    },
+                    "schema-version": 1,
+                    "template":
+                    {
+                        "card-layout": "horizontal",
+                        "card-size": "small",
+                        "collapsed-rows": 1,
+                        "category-layout": "grid"
+                    }
+                },
+                "scopes":
+                [
+                ],
+                "keywords":
+                [
+                    {
+                        "id": "login-test",
+                        "local_id": "login1-localid"
+                    }
+
+                ]
+            }
+         }
+    ]
+}

=== added file 'gtests/scope_directory/login_2.json'
--- gtests/scope_directory/login_2.json	1970-01-01 00:00:00 +0000
+++ gtests/scope_directory/login_2.json	2016-09-30 19:17:35 +0000
@@ -0,0 +1,73 @@
+{
+    "common_templates":
+    [
+        {
+            "id" : "default-renderer",
+            "template":
+            {
+                "components":
+                {
+                    "art": "art",
+                    "title": "title",
+                    "subtitle": "subtitle",
+                    "summary": "summary",
+                    "emblem": "emblem"
+                },
+                "schema-version": 1,
+                "template":
+                {
+                    "card-layout": "horizontal",
+                    "card-size": "large",
+                    "collapsed-rows": 0,
+                    "category-layout": "vertical-journal"
+                }
+            }
+        }
+    ],
+    "order":
+    [
+        {
+            "scope": {
+                "id": "scope_login",
+                "local_id": "local_scope_2",
+                "renderer_common_id": "fallbacks"
+            }
+        },
+        {
+            "category":
+            {
+                "id": "headlines",
+                "department": "dept-headlines",
+                "_title": "Headlines",
+                "renderer_common_id": "default-renderer",
+                "login_renderer_incoming_category_id": "login-category",
+                "login_renderer":
+                {
+                    "components":
+                    {
+                        "mascot": "login-art",
+                        "title": "login-title"
+                    },
+                    "schema-version": 1,
+                    "template":
+                    {
+                        "card-layout": "horizontal",
+                        "card-size": "small",
+                        "collapsed-rows": 1,
+                        "category-layout": "grid"
+                    }
+                },
+                "scopes":
+                [
+                    {
+                        "id": "login-test",
+                        "local_id": "login1-localid"
+                    }
+                ],
+                "keywords":
+                [
+                ]
+            }
+         }
+    ]
+}

=== added file 'gtests/scope_directory/login_3.json'
--- gtests/scope_directory/login_3.json	1970-01-01 00:00:00 +0000
+++ gtests/scope_directory/login_3.json	2016-09-30 19:17:35 +0000
@@ -0,0 +1,35 @@
+{
+    "order":
+    [
+        {
+            "scope": {
+                "_category_title": "Login Declared Scope Test",
+                "id": "login-test",
+                "local_id": "login1-localid",
+                "renderer": {
+                    "components": {
+                        "art": "art"
+                    },
+                    "schema-version": 1,
+                    "template": {
+                        "card-size": "small",
+                        "category-layout": "grid",
+                        "collapsed-rows": 10
+                    }
+                },
+                "login_renderer_incoming_category_id": "login-category",
+                "login_renderer": {
+                    "components": {
+                        "mascot": "mascot",
+                        "title": "title"
+                    },
+                    "schema-version": 1,
+                    "template": {
+                        "card-size": "large",
+                        "category-layout": "grid"
+                    }   
+                }   
+            }   
+        }
+    ]
+}

=== modified file 'gtests/scope_test.cpp'
--- gtests/scope_test.cpp	2016-08-19 20:46:32 +0000
+++ gtests/scope_test.cpp	2016-09-30 19:17:35 +0000
@@ -81,6 +81,7 @@
     QJsonArray depts_a = depts["declarations"].toArray();
     ASSERT_EQ(depts_a.size(), 3);
 
+
     NiceMock<unity::scopes::testing::MockSearchReply> reply;
     unity::scopes::SearchReplyProxy search_reply_proxy
     {   
@@ -97,6 +98,7 @@
 
     Query * q = new Query(cq, smd, string("scope_directory"), string("cache_directory"), reg, scope_ptr); 
     q->load_declarations(scope_ptr->child_root());
+    ASSERT_TRUE(q->is_using_departments());
     q->create_departments(search_reply_proxy);
 
     ASSERT_TRUE(child_root.contains("cardinality_settings"));
@@ -105,8 +107,11 @@
     ASSERT_TRUE(child_root.contains("common_templates"));
     ASSERT_TRUE(child_root.contains("order"));
 }
+
+
 /**
  * Verifies that no call to register_departments() made when no depts declared in json
+ * and that is_using_departments() returns false
  */
 TEST_F(TestAggScope, verify_no_departments){
     AggScope * scope_ptr;
@@ -127,9 +132,6 @@
     {   
         &reply, [](unity::scopes::SearchReply*) {}
     };  
-   
-    //verify a call is made to register departments 
-    //EXPECT_CALL(reply, register_departments(_)).Times(0);
 
     shared_ptr<MockRegistry> reg = make_shared<MockRegistry>();
     SearchMetadata smd("en_US", "phone");
@@ -139,6 +141,7 @@
     Query * q = new Query(cq, smd, string("scope_directory"), string("cache_directory"), reg, scope_ptr); 
     q->load_declarations(scope_ptr->child_root());
     q->create_departments(search_reply_proxy);
+    ASSERT_FALSE(q->is_using_departments());
 }
 
 /**
@@ -643,3 +646,107 @@
     //tests that hints DOES iNOT display when hints_is_hidden file exists in cachee dir
     ASSERT_FALSE(q->assert_hints_display((proxy)));
 }
+
+/*
+ * Verifies that a category keyword defined to use a login renderer uses it.
+ * Particularly, the return value of Query::is_login_case() method is verified as true
+ * when the incoming result category id is the same as the declared one, and false otherwise.
+ * As with many tests, the MockRegistry is configured to have a scope that answers to
+ * the keyword defined in the login_1.json file used here.
+ */
+TEST_F(TestAggScope, is_login_case_category_keyword){    
+    AggScope * scope_ptr;
+    scope_ptr = &(*scope);
+    string fbj = "login_1.json";
+    scope_ptr->set_child_scopes_json_filename(fbj);
+    ASSERT_EQ(scope_ptr->child_scopes_json_filename(), fbj);
+    QJsonObject child_root = scope_ptr->get_child_root(); 
+    std::string path = scope_ptr->scope_directory() + "/" + scope_ptr->child_scopes_json_filename();
+    ASSERT_TRUE(scope_ptr->load_json_file(child_root, path, scope_ptr->scope_id())) << "Problem with: " << path;
+    scope_ptr->set_child_root(child_root);
+    SearchMetadata smd("en_US", "phone");
+    CannedQuery cq("not_an_id");
+    shared_ptr<MockRegistry> reg = make_shared<MockRegistry>();
+    Query * q = new Query(cq, smd, string("scope_directory"), string("cache_directory"), reg, scope_ptr); 
+    q->load_declarations(scope_ptr->child_root());
+    ChildScopeList csl = scope->find_child_scopes();
+    ASSERT_EQ(csl.size(), 1); 
+    ASSERT_EQ(csl.front().id, "login-test"); 
+    q->current_child_scopes = csl;
+    q->make_categories();
+    auto cat = q->categories[0];
+    auto child = q->scopes_m["login-test:category=headlines:keyword=login-test"];
+    bool login_case = q->is_login_case(child, "login-category");
+    ASSERT_TRUE(login_case);
+    login_case = q->is_login_case(child, "NOT-login-category");
+    ASSERT_FALSE(login_case);
+}
+
+/*
+ * Verifies that a category scope defined to use a login renderer uses it.
+ * Particularly, the return value of Query::is_login_case() method is verified as true
+ * when the incoming result category id is the same as the declared one, and false otherwise.
+ * As with many tests, the MockRegistry is configured to have a scope with the id
+ * defined in login_2.json used here.
+ */
+TEST_F(TestAggScope, is_login_case_category_scope){    
+    AggScope * scope_ptr;
+    scope_ptr = &(*scope);
+    string fbj = "login_2.json";
+    scope_ptr->set_child_scopes_json_filename(fbj);
+    ASSERT_EQ(scope_ptr->child_scopes_json_filename(), fbj);
+    QJsonObject child_root = scope_ptr->get_child_root(); 
+    std::string path = scope_ptr->scope_directory() + "/" + scope_ptr->child_scopes_json_filename();
+    ASSERT_TRUE(scope_ptr->load_json_file(child_root, path, scope_ptr->scope_id())) << "Problem with: " << path;
+    scope_ptr->set_child_root(child_root);
+    SearchMetadata smd("en_US", "phone");
+    CannedQuery cq("not_an_id");
+    shared_ptr<MockRegistry> reg = make_shared<MockRegistry>();
+    Query * q = new Query(cq, smd, string("scope_directory"), string("cache_directory"), reg, scope_ptr); 
+    q->load_declarations(scope_ptr->child_root());
+    ChildScopeList csl = scope->find_child_scopes();
+    ASSERT_EQ(csl.size(), 1); 
+    ASSERT_EQ(csl.front().id, "login-test"); 
+    q->current_child_scopes = csl;
+    q->make_categories();
+    auto cat = q->categories[0];
+    auto child = q->scopes_m["login1-localid"];
+    bool login_case = q->is_login_case(child, "login-category");
+    ASSERT_TRUE(login_case);
+    login_case = q->is_login_case(child, "NOT-login-category");
+    ASSERT_FALSE(login_case);
+}
+
+/*
+ * Verifies that a declared scope defined to use a login renderer uses it.
+ * Particularly, the return value of Query::is_login_case() method is verified as true
+ * when the incoming result category id is the same as the declared one, and false otherwise.
+ * As with many tests, the MockRegistry is configured to have a scope with the id
+ * defined in login_2.json used here.
+ */
+TEST_F(TestAggScope, is_login_case_declared_scope){    
+    AggScope * scope_ptr;
+    scope_ptr = &(*scope);
+    string fbj = "login_3.json";
+    scope_ptr->set_child_scopes_json_filename(fbj);
+    ASSERT_EQ(scope_ptr->child_scopes_json_filename(), fbj);
+    QJsonObject child_root = scope_ptr->get_child_root(); 
+    std::string path = scope_ptr->scope_directory() + "/" + scope_ptr->child_scopes_json_filename();
+    ASSERT_TRUE(scope_ptr->load_json_file(child_root, path, scope_ptr->scope_id())) << "Problem with: " << path;
+    scope_ptr->set_child_root(child_root);
+    SearchMetadata smd("en_US", "phone");
+    CannedQuery cq("not_an_id");
+    shared_ptr<MockRegistry> reg = make_shared<MockRegistry>();
+    Query * q = new Query(cq, smd, string("scope_directory"), string("cache_directory"), reg, scope_ptr); 
+    q->load_declarations(scope_ptr->child_root());
+    ChildScopeList csl = scope->find_child_scopes();
+    ASSERT_EQ(csl.front().id, "login-test"); 
+    q->current_child_scopes = csl;
+    ASSERT_EQ(csl.size(), 1); 
+    q->make_declared_scopes();
+    auto child = q->scopes_m["login1-localid"];
+    bool login_case = q->is_login_case(child, "login-category");
+    ASSERT_TRUE(login_case);
+    login_case = q->is_login_case(child, "NOT-login-category");
+    ASSERT_FALSE(login_case);
+}

=== modified file 'include/aggchildscope.h'
--- include/aggchildscope.h	2016-06-29 10:29:37 +0000
+++ include/aggchildscope.h	2016-09-30 19:17:35 +0000
@@ -146,6 +146,37 @@
     us::Category::SCPtr category();
 
     /**
+    \brief Whether scope uses login renderer
+    \return Return whether scope uses login renderer
+    */
+    bool using_login_renderer();
+
+    /**
+    \brief Enable using login renderer
+    */
+    void enable_using_login_renderer();
+
+    /**
+    \brief Set the incoming category id which triggers use a the login_renderer
+    */
+    void set_login_renderer_incoming_category_id(std::string const& cat_id);
+
+    /**
+    \brief Get the incoming category id which triggers use a the login_renderer
+    */
+    std::string login_renderer_incoming_category_id();
+
+    /**
+    \brief The json defining the CategoryRenderer json used when when incoming result has catgegory id == login_renderer_incoming_category_id.
+    */
+    void set_login_template(std::string const& login_template);
+
+    /**
+    \brief Return the json defining the CategoryRenderer template used for login when login_renderer_incoming_category_id set and current incoming result matches.
+    */
+    const std::string & login_template() const;
+
+    /**
     \brief The json defining the CategoryRenderer json used when surfacing the first result. You must also declare surface_template to handle the rest.
     */
     void set_first_result_template(std::string const &first_result_template);
@@ -154,8 +185,9 @@
     \brief Return the json defining the CategoryRenderer template used when surfacing first result.
     */
     const std::string & first_result_template() const;
+
     /**
- *
+    *
     \brief The json defining the CategoryRenderer template used when surfacing results.
     \param surface_template The json passed to the CategoryRenderer
     */
@@ -375,6 +407,8 @@
     std::string id_;
     std::string local_id_;
     std::string cat_title = "";
+    std::string login_renderer_incoming_category_id_;
+    bool using_login_renderer_ =false;
     bool using_category_link_to_child;
     bool using_category_title_incoming_ = false;
     bool using_category_title_display_name_ = false;
@@ -396,6 +430,7 @@
     us::Category::SCPtr cat;
     bool override_surface_template_ = true;
     bool override_search_template_ = true;
+    std::string template_login_;
     std::string TEMPLATE_NOT_LOGGED_IN;
     std::string template_first_result_;
     std::string first_common_template_id_;

=== modified file 'include/query.h'
--- include/query.h	2016-08-19 17:04:10 +0000
+++ include/query.h	2016-09-30 19:17:35 +0000
@@ -44,6 +44,8 @@
     std::string category_link_to_child_specified;
     std::string renderer;
     std::string search_renderer;
+    std::string login_renderer;
+    std::string login_renderer_incoming_category_id;
     std::vector<std::pair<std::string,std::string>> scopes; // id and local_id of scopes
     std::vector<std::string> keywords; // keywords in this cat
     std::vector<std::pair<std::string,std::string>> keyword_ids; // id and local id of keywords
@@ -90,6 +92,8 @@
     bool using_child_category_max_results = false;//NOT A JSON KEY
     bool overriding_surface_template = false;//NOT A JSON KEY
     bool overriding_search_template = false;//NOT A JSON KEY
+    std::string login_renderer;
+    std::string login_renderer_incoming_category_id;
     std::vector<std::shared_ptr<std::pair<std::string,std::string>>> swap_result_attributes;
     std::pair<std::string,std::string> if_category_use_template;
     std::map<std::string, std::string> result_category_id_to_common_template;//id is result category id. maps to id to use in common_templates
@@ -110,7 +114,6 @@
 
     virtual void run(unity::scopes::SearchReplyProxy const& upstream_reply) override;
 
-    bool using_departments = true;
 
     Client client;
 
@@ -130,26 +133,32 @@
                               unity::scopes::CategorisedResult & res,
                               std::string const& inc_res_cat_id,
                               std::string const& inc_res_cat_title);
+    bool is_login_case(std::shared_ptr<AggChildScope> scope, std::string const& res_cat_id);
+    void make_categories();
+    void make_declared_scopes();
+    std::vector<std::shared_ptr<category>> categories;
+    us::ChildScopeList current_child_scopes;
+    std::map<std::string, std::shared_ptr<AggChildScope>> scopes_m;//key is local_id
+    bool is_using_departments();
+
 private:
-    void make_declared_scopes();
+    bool using_departments = false;
     void make_keyword_scopes();
-    void make_categories();
-
     void set_scope_order();
-
     void display_local_hints_quickstart(us::SearchReplyProxy const& upstream_reply_);
     void display_remote_hints_quickstart(us::SearchReplyProxy const& upstream_reply_);
     bool show_hints(us::SearchReplyProxy const& upstream_reply_);
     bool hints_exists();
     bool hints_hidden();
     void dismiss_hints_quickstart();
+    us::Category::SCPtr set_result_catgory(us::SearchReplyProxy const& upstream_reply, us::CategorisedResult & res, std::string const& id, std::string const& title, std::string const& rdr, std::string const& link_to);
+    us::Category::SCPtr set_result_catgory(us::SearchReplyProxy const& upstream_reply, us::CategorisedResult & res, std::string const& id, std::string const& title, std::string const& rdr);
 
-    void handle_current_child_scopes(bool empty_search, us::SearchReplyProxy const& upstream_reply);
+    void complete_child_scopes();
     void handle_child_scope_results(std::string const &query_string, bool empty_search, us::SearchReplyProxy const& upstream_reply);
     void noSources(unity::scopes::SearchReplyProxy const& reply);
     std::map<std::string,std::string> localId_defaultQryStr;
     std::map<std::string,std::string> scopeLocalId_childDept_m; // local_id of scope to scope's child department
-    std::vector<std::shared_ptr<category>> categories;
     std::map<std::string,std::shared_ptr<category>> id_category_m;
     std::map<std::string,std::string> categoryId_titleMsgid;
     std::vector<std::string> categoryIds;
@@ -200,7 +209,6 @@
     std::map<std::string,std::string> keyword_deptId;
     std::map<std::string,std::string> keyword_surfaceRdr;
 
-    us::ChildScopeList current_child_scopes;
 
     std::string first_result_owner; // set to first declaared keyword or scope that declared a first result renderer
     std::list<std::string> declared_keywords;// the declared list of keywords, in declared order
@@ -217,7 +225,6 @@
     std::map<std::string,bool> sharedcat_catregistered;//stores whether the shared cat's ctegory is registered yet
 
     std::vector<us::ScopeProxy> scopes; // will hold all enabled and present child scopes
-    std::map<std::string, std::shared_ptr<AggChildScope>> scopes_m;//key is local_id
     std::map<int,std::string> scopes_m_int_localId;
     std::string scope_dir_;
     std::string cache_dir_;

=== modified file 'src/CMakeLists.txt'
--- src/CMakeLists.txt	2016-08-11 20:24:03 +0000
+++ src/CMakeLists.txt	2016-09-30 19:17:35 +0000
@@ -10,6 +10,7 @@
     notify-strategy.cpp
     aggchildscope.cpp
     utils.cpp
+    handle_results.cpp
     action.cpp
 )
 find_package(Qt5Core REQUIRED)

=== modified file 'src/aggchildscope.cpp'
--- src/aggchildscope.cpp	2016-06-29 10:29:37 +0000
+++ src/aggchildscope.cpp	2016-09-30 19:17:35 +0000
@@ -71,12 +71,45 @@
     using_category_title_display_name_ = b;
 }
 
-
 us::Category::SCPtr AggChildScope::category()
 {
     return cat;
 }
 
+bool AggChildScope::using_login_renderer()
+{
+    return using_login_renderer_;
+}
+
+void AggChildScope::enable_using_login_renderer()
+{
+    using_login_renderer_ = true;;
+}
+
+/*
+ * When login renderer is used, this required call defines the category id of the 
+ * invoming result for which the login renderer is used.
+ */
+void AggChildScope::set_login_renderer_incoming_category_id(std::string const& cat_id)
+{
+    login_renderer_incoming_category_id_ = cat_id;
+}
+
+std::string AggChildScope::login_renderer_incoming_category_id()
+{
+    return login_renderer_incoming_category_id_;
+}
+
+void AggChildScope::set_login_template(std::string const& login_template)
+{
+    template_login_ = login_template;
+}
+
+const std::string & AggChildScope::login_template() const
+{
+    return template_login_;
+}
+
 void AggChildScope::set_first_result_template(std::string const &first_result_template)
 {
     template_first_result_ = first_result_template;

=== added file 'src/handle_results.cpp'
--- src/handle_results.cpp	1970-01-01 00:00:00 +0000
+++ src/handle_results.cpp	2016-09-30 19:17:35 +0000
@@ -0,0 +1,960 @@
+/*
+ * Copyright (C) 2016 Canonical Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 3 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Authored by: Kyle Nitzsche <[e-mail]>
+ *              Scott Sweeny <[e-mail]>
+ *
+ */
+
+#include "query.h"
+#include "aggchildscope.h"
+#include "i18n.h"
+
+#include <unity/UnityExceptions.h>
+
+#include <QFile>
+#include <QJsonParseError>
+#include <QJsonDocument>
+#include <QJsonObject>
+#include <QJsonArray>
+#include <QDateTime>
+#include <iostream>
+#include <fstream>
+#include <sstream>
+
+using namespace unity::scopes;
+
+#define UNUSED(x) (void)(x);
+
+bool Query::is_login_case(std::shared_ptr<AggChildScope> scope, std::string const& res_cat_id)
+{
+    return scope->using_login_renderer() &&
+             res_cat_id == scope->login_renderer_incoming_category_id();
+
+}
+
+void Query::complete_child_scopes()
+{
+    // Cycle through child scopes (in current_scopes) and, if enabled in settings, complete set up
+    try
+    {
+        for (const std::string & local_id : current_scopes)
+        {
+            qDebug() << "==== CURRENT. local_id: " << client.qstr(local_id);
+            std::string id = localId_id_m[local_id];
+            qDebug() << "==== CURRENT. id: " << client.qstr(id);
+            std::shared_ptr<AggChildScope> scope = scopes_m[local_id];
+
+            scope->set_proxy(registry_);
+
+            if (!scope->exists()) {
+                std::string sep = query_store_  == "" ? "name:" : "+";
+                std::string name = std::string(id, 0, id.find('_'));
+                query_store_.append(sep + name);
+            }
+            else
+            {
+                if (!scope->source_finder())
+                    has_one_source = true;
+            }
+        }
+        for (auto source : sources_for_clickstore)
+        {
+            AggChildScope scope(source);
+            scope.set_proxy(registry_);
+            if (!scope.exists()) {
+                std::string sep = query_store_  == "" ? "name:" : "+";
+                std::string name = std::string(source, 0, source.find('_'));
+                query_store_.append(sep + name);
+            }
+        }
+    }
+    catch (unity::Exception const& e)
+    {
+        qWarning() << "NotFoundException: " << e.what();
+    }
+}
+
+void Query::noSources(unity::scopes::SearchReplyProxy const& reply) {
+    std::string MESS_GRID = R"(
+        {
+            "schema-version" : 1,
+            "template" : {
+                "category-layout" : "grid",
+                "card-layout": "horizontal",
+                "card-size": "small",
+                "non-interactive": true
+            },
+            "components" : {
+                "title" : "title"
+            }
+        }
+    )";
+
+    CategoryRenderer emptyCat(MESS_GRID);
+    auto messGrid = reply->register_category("emptyMess", _("Welcome"), "", emptyCat);
+    CategorisedResult res(messGrid);
+    res.set_uri("http://ubuntu.com");
+    res["title"]=_("To start using this scope please install sources from the list below");
+    reply->push(res);
+}
+
+bool Query::hints_exists()
+{
+    auto scopes = registry_->list();
+    us::MetadataMap::const_iterator scope;
+    scope = scopes.find(HINTS_SCOPE_ID);
+    if (scope != scopes.end()) {
+        auto meta = registry_->get_metadata(HINTS_SCOPE_ID);
+        hints_scope = meta.proxy();
+        return true;
+    }
+    return false;
+}
+
+void Query::display_local_hints_quickstart(us::SearchReplyProxy const& upstream_reply_)
+{
+    if (!local_hints)
+        return;
+    if (!hints_local_json.contains(QStringLiteral("content")))
+        return;
+    auto content = hints_local_json[QStringLiteral("content")].toObject();
+    if (!content.contains(QStringLiteral("categories")))
+        return;
+
+    QJsonArray cats = content[QStringLiteral("categories")].toArray();
+    for (const auto & cat_ : cats)
+    {
+        auto cat = cat_.toObject();
+
+        std::string id = client.sstr(cat[QStringLiteral("id")].toString());
+        std::string title = _(client.sstr(cat[QStringLiteral("_title")].toString()).c_str());
+        QJsonDocument layout_d(cat[QStringLiteral("layout")].toObject());
+        std::string local_hints_template = client.sstr(layout_d.toJson());
+        auto category = upstream_reply_->lookup_category(id);
+        if (!category) {
+            category = upstream_reply_->register_category(id, title, "", us::CategoryRenderer(local_hints_template));
+        }
+        QJsonArray items = cat[QStringLiteral("items")].toArray();
+        for (const auto & res__ : items)
+        {
+            auto res_ = res__.toObject();
+            us::CategorisedResult res(category);
+            res.set_title(_(client.sstr(res_[QStringLiteral("_title")].toString()).c_str()));
+            res["subtitle"] = _(client.sstr(res_[QStringLiteral("_subtitle")].toString()).c_str());
+            res["description"] = _(client.sstr(res_[QStringLiteral("_description")].toString()).c_str());
+            std::string uri = "http://www.ubuntu.com";
+            if (res_.contains(QStringLiteral("hide_in_locales")))
+            {
+                QStringList hide_in_locales = res_[QStringLiteral("hide_in_locales")].toString().split(",");
+                std::string lcRaw = setlocale(LC_ALL, ""); 
+                std::string lc_lang = lcRaw.size() > 5 ? lcRaw.substr(0, 2) : "";
+                std::string lc_country  = lcRaw.size() > 5 ? lcRaw.substr(3, 2) : "";
+                std::string lc = lc_lang + "_" + lc_country;
+                if (hide_in_locales.contains(client.qstr(lc)))
+                {
+                    continue;
+                }
+            }
+            if (res_.contains("uri"))
+            {
+                uri = client.sstr(res_["uri"].toString());
+            }
+            if (res_.contains(QStringLiteral("action")))
+            {
+                auto action = res_[QStringLiteral("action")].toObject();
+                VariantBuilder builder;
+                builder.add_tuple({
+                    {"id", Variant("Open")},
+                    {"label", Variant(_(client.sstr(action[QStringLiteral("_name")].toString()).c_str()))},
+                    {"uri", Variant(client.sstr(action[QStringLiteral("uri")].toString()))}
+                });
+                res["actions"]=builder.end();
+                if (action.contains(QStringLiteral("uri")))
+                {
+                    uri = client.sstr(action[QStringLiteral("uri")].toString());
+                }
+            }
+            if (res_.contains(QStringLiteral("oaccount")))
+            {
+                auto oaccount = res_[QStringLiteral("oaccount")].toObject();
+                auto queryScope = client.sstr(oaccount[QStringLiteral("QueryScope")].toString());
+
+                // before framework 15.0.4.4 the service name is the FQ scope id and contains one "_"
+                // with 15.04.4, it is FQ scope id += _PROVIDER
+                // we also want the fully qualified scope id to check with registry if it is installed.
+                // to support both cases:
+                QStringList parts = oaccount[QStringLiteral("ServiceName")].toString().split("_");
+                QString provider = oaccount[QStringLiteral("ProviderName")].toString();
+                QString sc_id = parts[0] + "_" + parts[1];
+                QString id = sc_id;
+                if (parts.size() > 2) // framework 15.04.4 or higher 
+                {
+                    id += "_" + provider;
+                }
+                us::OnlineAccountClient oa_client(client.sstr(id),
+                                                  client.sstr(oaccount[QStringLiteral("ServiceType")].toString()),
+                                                  client.sstr(provider));
+                bool alreadyLoggedIn = false;
+                oa_client.refresh_service_statuses();
+                for (auto const& status : oa_client.get_service_statuses())
+                {
+                    if (status.service_enabled)
+                    {
+                        alreadyLoggedIn = true;
+                        break;
+                    }
+                }
+                // do not display quick start help for scopes that are not registered in the system
+                auto reg_scopes = registry_->list();
+                us::MetadataMap::const_iterator scope_it;
+                scope_it = reg_scopes.find(client.sstr(sc_id));
+                if (scope_it == reg_scopes.end()) {
+                    qWarning () << QString("%1: OA scope is NOT REGISTERED, skipping for HINTS: %2").arg(oaccount[QStringLiteral("ServiceName")].toString());
+                    continue;
+                }
+                if (alreadyLoggedIn) {
+                    //the hints code does this when the person is already logged in to the service.
+                    //auto tmp = oaccount["_loggedin"].toString().toStdString();
+                    //res["title"] = std::string(_(tmp.c_str()));
+                    //
+                    //this continue statement means if the person is logged in, we do not show
+                    //a result for the item
+                    continue;
+                }
+                us::CannedQuery query(queryScope);
+                oa_client.register_account_login_item(res,
+                                                      query,
+                                                      OnlineAccountClient::InvalidateResults,
+                                                      OnlineAccountClient::DoNothing);
+
+            }
+            if (res_.contains(QStringLiteral("hide_hints")))
+            {
+                qDebug() << "=== NHINTS. utils. hide hints found in json";
+                res["action"] = "hide_hints";
+                res.set_intercept_activation();
+            }
+            res.set_uri(uri);
+            res.set_art(scope_dir_ + "/images/" + client.sstr(res_["art"].toString()));
+            upstream_reply_->push(res);
+        }
+    }
+}
+
+void Query::display_remote_hints_quickstart(us::SearchReplyProxy const& upstream_reply_)
+{
+    qDebug() << "==== HINTS in display_remote_hints_quickstart()";
+    Category::SCPtr hint_cat;
+    SearchMetadata metadata(search_metadata());
+    auto reply = std::make_shared<ResultForwarder>(upstream_reply_,
+    [this, &hint_cat](CategorisedResult& res) -> bool {
+        UNUSED(res)
+        return true;
+    });
+
+    subsearch(hints_scope, "", HINTS_THIS_SCOPE, FilterState(),
+              metadata, reply);
+}
+
+bool Query::hints_hidden() {
+
+    auto filepath1 = QString::fromStdString(cache_dir_) +"/" + hints_file;
+    auto filepath2 = QString::fromStdString(cache_dir_) +"/" + firstboot;
+    if (QFile::exists(filepath1) || QFile::exists(filepath2))
+        return true;
+    return false; //don't show hints as fall back
+}
+
+void Query::dismiss_hints_quickstart() {
+    qDebug() << "==== HINTS in dismiss()";
+    auto filepath= QString::fromStdString(cache_dir_) +"/" + hints_file;
+    QFile file(filepath);
+    file.open(QIODevice::WriteOnly);
+    QString msg = QString("Timestamp for %1 %2").arg(client.qstr(HINTS_THIS_SCOPE), QDateTime::currentDateTime().toString());
+    file.write(client.sstr(msg).c_str(), client.sstr(msg).size());
+    file.close();
+}
+
+void Query::handle_keyword_child(unity::scopes::SearchReplyProxy const& upstream_reply,
+                                 std::shared_ptr<AggChildScope> scope,
+                                 us::CategorisedResult & res){
+
+    //the supported cases
+    enum RunType {
+                    Search,
+                    SearchNoLink,
+                    SearchNoRdr,
+                    SearchNoRdrNoLink,
+                    Surface,
+                    SurfaceNoLink,
+                    SurfaceNoRdr,
+                    SurfaceNoRdrNoLink
+                  };
+    RunType runType;        
+
+    std::string keyword = scope->keyword();
+    std::string scope_id = scope->id();
+    std::string cat_id = keyword + ":" + scope_id;
+    std::string cat_title = registry_->get_metadata(scope->id()).display_name();
+    std::string search_rdr = scope->search_template();
+    std::string rdr = scope->surface_template();
+    bool link = scope->category_link_to_child();
+    
+    qDebug() << "==== KW scope cat_id prefix: " << client.qstr(rdr);
+    qDebug() << "==== KW scope: " << client.qstr(scope->id()) << " keyword: " << client.qstr(keyword);;
+    qDebug() << "==== KW scope shared cat name: " << client.qstr(scope->keyword_scope_shared_cat_name());
+    qDebug() << "==== KW scope search rdr: " << client.qstr(search_rdr);
+    qDebug() << "==== KW scope rdr: " << client.qstr(rdr);
+    qDebug() << "==== KW scope link: " << QString::number(link);
+    
+    // Determine the current case based on state
+    if (!query().query_string().empty())
+    {//search
+        if (!search_rdr.empty())
+        {//rdr
+            if (link)
+            {//link
+                runType = Search;
+            }
+            else
+            {//no link
+                runType = SearchNoLink;
+            }
+        }
+        else
+        {//no rdr
+            if (link)
+            {//link
+                runType = SearchNoRdr;
+            }
+            else
+            {//link
+                runType = SearchNoRdrNoLink;
+            }
+        }
+    }
+    else
+    {//surface
+        if (!rdr.empty())
+        {
+            if (link)
+            {
+                runType = Surface;
+            }
+            else
+            {
+                runType = SurfaceNoLink;
+            }
+        }
+        else
+        {
+            if (link)
+            {
+                runType = SurfaceNoRdr;
+            }
+            else
+            {
+                runType = SurfaceNoRdrNoLink;
+            }
+        }
+    }
+
+    switch (runType) 
+    {
+        case RunType::Search:
+            qDebug() << "=== run type: keyword Search";
+            cat_id += ":keyword:search:rdr:" + cat_title;
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, search_rdr, scope_id);
+            break; 
+        case RunType::SearchNoLink:
+            qDebug() << "=== run type: keyword SearchNoLink";
+            cat_id += ":keyword:search:rdrnolink:" + cat_title;
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, search_rdr);
+            break; 
+        case RunType::SearchNoRdr:
+            qDebug() << "=== run type: keyword SearchNoRdr";
+            cat_id = ":keyword:search:nordr:" + cat_title;
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, scope_id);
+            break; 
+        case RunType::SearchNoRdrNoLink:
+            qDebug() << "=== run type: keyword SearchNoRdrNoLink";
+            cat_id = ":keyword:search:nordr:nolink:" + cat_title;
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break; 
+        case RunType::Surface:
+            qDebug() << "=== run type: keyword Surface";
+            cat_id += ":keyword:surface:rdr:" + cat_title;
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, scope_id);
+            break; 
+         case RunType::SurfaceNoLink:
+            qDebug() << "=== run type: keyword SurfaceNoLink";
+            cat_id += ":keyword:surface:rdr:noLink::" + cat_title;
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break; 
+        case RunType::SurfaceNoRdr:
+            qDebug() << "=== run type: keyword SurfaceNoRdr";
+            cat_id += ":keyword:surface:nordr:" + cat_title;
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, scope_id);
+            break; 
+        case RunType::SurfaceNoRdrNoLink:
+            qDebug() << "=== run type: keyword SurfaceNoRdrNoLink";
+            cat_id += ":keyword:surface:nordr:nolink:" + cat_title;
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break; 
+    }
+}
+
+us::Category::SCPtr Query::set_result_catgory(us::SearchReplyProxy const& upstream_reply, us::CategorisedResult & res, std::string const& id, std::string const& title, std::string const& rdr, std::string const& link_to)
+{
+    qDebug() << "=== category type in set result with child link";
+    qDebug() << QString("=== in set_result_category() with link. id: %1, title: %2, link_to: %3, rdr: %4").arg(client.qstr(id), client.qstr(title), client.qstr(link_to), client.qstr(rdr));
+
+    us::Category::SCPtr cat = upstream_reply->lookup_category(id);
+    if (cat == nullptr)
+    {
+        qDebug() << QString("=== in set_result_category() with link. lookup_category() returns nullptr, so register it");
+        cat = upstream_reply->register_category
+        (
+            id,
+            title,
+             "",
+            us::CannedQuery(link_to),
+            us::CategoryRenderer(rdr)
+        );
+    }
+    res.set_category(cat);
+    qDebug() << "=== in set_result_category() with link. here's the res category json: " << client.qstr(Variant(res.category()->query()->serialize()).serialize_json());
+    return cat;
+}
+
+us::Category::SCPtr Query::set_result_catgory(us::SearchReplyProxy const& upstream_reply, us::CategorisedResult & res, std::string const& id, std::string const& title, std::string const& rdr)
+{
+    qDebug() << "=== category type in set result no link";
+    qDebug() << QString("=== in set_result_category() no link. id: %1, title: %2, rdr: %3").arg(client.qstr(id), client.qstr(title), client.qstr(rdr) );
+
+    us::Category::SCPtr cat = upstream_reply->lookup_category(id);
+    if (cat == nullptr)
+    {
+        qDebug() << QString("=== in set_result_category() no link. lookup_category() returns nullptr, so register it");
+        cat = upstream_reply->register_category
+        (
+            id,
+            title,
+             "",
+            us::CategoryRenderer(rdr)
+        );
+    }
+    res.set_category(cat);
+    return cat;
+}
+
+void Query::handle_category_child(unity::scopes::SearchReplyProxy const& upstream_reply,
+                                 std::shared_ptr<AggChildScope> scope,
+                                 us::CategorisedResult & res){
+
+    enum RunType {
+                    Search,
+                    SearchNoRdr,
+                    SearchNoLink,
+                    SearchNoLinkNoRdr,
+                    Login,
+                    LoginNoLink,
+                    SurfaceUsesFirstIsFirst,
+                    SurfaceUsesFirstIsFirstNoLink,
+                    SurfaceUsesFirstNotFirst,
+                    SurfaceUsesFirstNotFirstNoLink,
+                    Surface,
+                    SurfaceNoRdr,
+                    SurfaceNoLink,
+                    SurfaceNoLinkNoRdr
+                  };
+    RunType runType;        
+
+    //get state
+    bool login_case = is_login_case(scope, res.category()->id());
+    bool uses_first_result_rdr = categoryId_first_result_renderers.find(scope->category_id()) != categoryId_first_result_renderers.end();
+    bool is_first_result = categoryId_isFirstResult[scope->category_id()];
+    bool not_first_result = categoryId_isSecondResult[scope->category_id()];
+    bool link = false;
+    bool has_rdr = !scope->surface_template().empty();
+    std::string category_id = scope->category_id();
+    std::string link_to = categoryId_linkToChildSpecified[category_id];
+    //qDebug() << "link: scope->category_id " << client.qstr(scope->category_id());
+    
+    for (auto i : categoryId_linkToChildSpecified)
+    {
+        if ( i.first == scope->category_id())
+        {
+            if ( !i.second.empty() )
+            {
+                link = true;
+            }
+        }
+    }
+
+    // Determine the current case based on state
+    if (!query().query_string().empty())
+    {
+        if (!scope->search_template().empty())
+        {
+            if (link)
+            {
+                runType = Search;
+            }
+            else
+            {
+                runType = SearchNoLink;
+            }
+        }
+        else
+        {
+            if (link)
+            {
+                runType = SearchNoRdr;
+            }
+            else
+            {
+                runType = SearchNoLinkNoRdr;
+            }
+        }
+    }
+    else if (login_case)
+    {
+        if (link)
+        {
+            runType = Login;
+        }
+        else
+        {
+            runType = LoginNoLink;
+        }
+    }
+    else
+    {//surface
+        if (uses_first_result_rdr)
+        {//uses first
+            if (is_first_result)
+            {//is first
+                if (link)
+                {
+                    runType = SurfaceUsesFirstIsFirst;
+                }
+                else
+                { 
+                    runType = SurfaceUsesFirstIsFirstNoLink;
+                }
+            }
+            else if (not_first_result)
+            {// not first
+                if (link)
+                {
+                    runType = SurfaceUsesFirstNotFirst;
+                }
+                else
+                {
+                    runType = SurfaceUsesFirstNotFirstNoLink;
+                }
+            }
+        }
+        else {//not uses first
+            if (link)
+            {
+                if (has_rdr)
+                {
+                    runType = Surface;
+                }
+                else
+                {
+                    runType = SurfaceNoRdr;
+                }
+            }
+            else
+            { // no link
+                if (has_rdr)
+                {
+                    runType = SurfaceNoLink;
+                }
+                else
+                {
+                    runType = SurfaceNoLinkNoRdr;
+                }
+            }
+        }
+    }
+
+    qDebug() << "=== login: using login renderer: " << QString::number(scope->using_login_renderer());
+    qDebug() << "=== login: res cat id: " << client.qstr(res.category()->id());
+    qDebug() << "=== login: login_renderer_incoming_category_id: " << client.qstr(scope->login_renderer_incoming_category_id());
+
+    // for use in category registration
+    std::string cat_id;
+    std::string cat_title;
+    std::string rdr;
+
+    if (!categoryId_titleMsgid[category_id].empty())
+        cat_title = _(categoryId_titleMsgid[category_id].c_str());
+    else
+        cat_title = "";
+
+    switch (runType) 
+    {
+        case RunType::Search:
+            qDebug() << "=== run type: category Search";
+            cat_id = scope->local_id() + ":category:search-renderer:searching:" + cat_title;
+            rdr = scope->search_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+            break; 
+        case RunType::SearchNoLink:
+            qDebug() << "=== run type: category SearchNoLink";
+            cat_id = scope->local_id() + ":category:search-renderer:no-link:searching:" + cat_title;
+            rdr = scope->search_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break; 
+        case RunType::SearchNoRdr:
+            qDebug() << "=== run type: category SearchNoRdr";
+            cat_id = scope->local_id() + ":category:no-renderer:searching:" + cat_title;
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+        case RunType::SearchNoLinkNoRdr:
+            qDebug() << "=== run type: category SearchNoLinkNoRdr";
+            cat_id = scope->local_id() + ":category:no-renderer:no-link:searching:" + cat_title;
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+        case RunType::Login:
+            qDebug() << "=== run type: category Login";
+            cat_id = scope->local_id() + ":category:login-renderer:" + cat_title;
+            rdr = scope->login_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+            break;
+        case RunType::LoginNoLink:
+            qDebug() << "=== run type: category LoginNoLink";
+            cat_id = scope->local_id() + ":category:login-renderer:no-link" + cat_title;
+            rdr = scope->login_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break;
+        case RunType::SurfaceUsesFirstIsFirst:
+            qDebug() << "=== run type: category SurfaceUsesFirstIsFirst";
+            if ((first_result_owner.empty()) || (first_result_owner == category_id))
+            {
+                qDebug() << "==== CATREG. uses FIRST result. FIRST result. NO LINK to child ";
+                first_result_owner = category_id;
+                cat_id = category_id + ":category:uses-first-result:is-first:surfacing";
+                rdr = categoryId_first_result_renderers[category_id];
+                categoryId_isFirstResult[category_id] = false;
+                categoryId_isSecondResult[category_id] = true;
+                catname_catptr[category_id] = set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+                scope->set_category(catname_catptr[category_id]);
+            }
+            break;
+         case RunType::SurfaceUsesFirstIsFirstNoLink:
+            qDebug() << "=== run type: category SurfaceUsesFirstIsFirstNoLink";
+            if ((first_result_owner.empty()) || (first_result_owner == category_id))
+            {
+                qDebug() << "==== CATREG. uses FIRST result. FIRST result. NO LINK to child ";
+                first_result_owner = category_id;
+                cat_id = category_id + ":category:uses-first-result:is-first:no-link:surfacing";
+                rdr = categoryId_first_result_renderers[category_id];
+                categoryId_isFirstResult[category_id] = false;
+                categoryId_isSecondResult[category_id] = true;
+                catname_catptr[category_id] = set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+                scope->set_category(catname_catptr[category_id]);
+            }
+            break;
+        case RunType::SurfaceUsesFirstNotFirst:
+            qDebug() << "=== run type: cateogry SurfaceUsesFirstNotFirst";
+            cat_id = category_id + ":category:uses-first-result:not-first:surfacing:" + cat_title;
+            rdr = scope->surface_template();
+            catname_catptr[category_id] = set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+            scope->set_category(catname_catptr[category_id]);
+            break;
+         case RunType::SurfaceUsesFirstNotFirstNoLink:
+            qDebug() << "=== run type: category SurfaceUsesFirstNotFirstNoLink";
+            cat_id = category_id + ":category:uses-first-result:not-first:no-rdr:no-linksurfacing:" + cat_title;
+            rdr = scope->surface_template();
+            catname_catptr[category_id] = set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            scope->set_category(catname_catptr[category_id]);
+            break;
+         case RunType::Surface:
+            qDebug() << "=== run type: category Surface";
+            cat_id = category_id + ":category:surface-rdr:surfacing:" + cat_title;
+            rdr = scope->surface_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+            break;
+         case RunType::SurfaceNoRdr:
+            qDebug() << "=== run type: category SurfaceNoRdr";
+            cat_id = category_id + ":category:no-rdr::surfacing:" + cat_title;
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+            break;
+        case RunType::SurfaceNoLink:
+            qDebug() << "=== run type: category SurfaceNoLink";
+            cat_id = category_id + ":category:surface-rdr:no-link:surfacing:" + cat_title;
+            rdr = scope->surface_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            //qDebug() << "CQ json: " << client.qstr(Variant(catname_catptr[category_id]->query()->serialize()).serialize_json());
+            break;
+        case RunType::SurfaceNoLinkNoRdr:
+            qDebug() << "=== run type: category SurfaceNoLinkNoRdr";
+            cat_id = category_id + ":category:no-rdr:surfacing:" + cat_title;
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            //qDebug() << "CQ json: " << client.qstr(Variant(upstream_reply->lookup_category(cat_id)->query()->serialize()).serialize_json());
+            break;
+    }
+
+    //TODO: put FALLBACK into method to avoid duplication needed by refactor
+    // perform res component fallback, as needed
+    if(!scope->surface_common_template_id().empty())
+    {
+        std::string res_str = us::Variant(res.serialize()).serialize_json(); 
+        auto change = this->client.check_result_fallbacks(res_str,
+                                                          scope->surface_common_template_id(),
+                                                          this->get_common_templates_fallbacks());
+        if (!std::get<0>(change).empty())
+        {
+            res[std::get<0>(change)] = std::get<1>(change);
+        }
+    }
+}
+
+void Query::handle_declared_child(unity::scopes::SearchReplyProxy const& upstream_reply,
+                                 std::shared_ptr<AggChildScope> scope,
+                                 us::CategorisedResult & res,
+                                 std::string const& inc_res_cat_id,
+                                 std::string const& inc_res_cat_title) {
+
+    //the supported cases
+    enum RunType {
+                    Search,
+                    SearchNoRdr,
+                    SearchNoLink,
+                    SearchNoLinkNoRdr,
+                    Login,
+                    LoginNoLink,
+                    Surface,
+                    SurfaceNoRdr,
+                    SurfaceNoLink,
+                    SurfaceNoLinkNoRdr
+                  };
+    RunType runType;        
+
+    //get state
+    bool login_case = is_login_case(scope, res.category()->id());
+    qDebug() << "==== DECLARED. login_case: " << QString::number(login_case); 
+    bool link = scope->category_link_to_child();//this means the category links, not that we get a specific child scope's category
+    std:: string link_to = scope->id();
+    bool has_rdr = !scope->surface_template().empty();
+
+    // Determine the current case based on state
+    if (!query().query_string().empty())
+    {
+        if (!scope->search_template().empty())
+        {
+            if (link)
+            {
+                runType = Search;
+            }
+            else
+            {
+                runType = SearchNoLink;
+            }
+        }
+        else
+        {
+            if (link)
+            {
+                runType = SearchNoRdr;
+            }
+            else
+            {
+                runType = SearchNoLinkNoRdr;
+            }
+        }
+    }
+    else if (login_case)
+    {
+        if (link)
+        {
+            runType = Login;
+        }
+        else
+        {
+            runType = LoginNoLink;
+        }
+    }
+    else
+    {//surface
+        if (link)
+        {
+            if (has_rdr)
+            {
+                runType = Surface;
+            }
+            else
+            {
+                runType = SurfaceNoRdr;
+            }
+        }
+        else
+        { // no link
+            if (has_rdr)
+            {
+                runType = SurfaceNoLink;
+            }
+            else
+            {
+                runType = SurfaceNoLinkNoRdr;
+            }
+        }
+    }
+
+    // for use in category registration
+    std::string cat_id;
+    std::string cat_title;
+    std::string rdr;
+
+    qDebug() << "==== DECLARED. scope is declared: " << client.qstr(scope->local_id());
+
+    // set the category tiile
+    if (scope->using_category_title_incoming() )
+    {
+        scope->set_category_title(inc_res_cat_title);
+    }
+    else if (scope->using_category_title_display_name() )
+    {
+        scope->set_category_title(scope->metadata()->display_name());
+    }
+
+    cat_title = scope->category_title();
+
+    switch (runType)
+    {
+        case RunType::Login:
+            qDebug() << "=== run type: declared scope Login";
+            cat_id = scope->local_id() + ":declared:login";
+            rdr = scope->login_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to); 
+            break;
+        case RunType::LoginNoLink:
+            qDebug() << "=== run type: declared scope LoginNoLink";
+            cat_id = scope->local_id() + ":declared:login:no-link";
+            rdr = scope->login_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break;
+        case RunType::Search:
+            qDebug() << "=== run type: declared scope Search";
+            cat_id = scope->local_id() + ":declared:search";
+            rdr = scope->search_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+            break;
+        case RunType::SearchNoRdr:
+            qDebug() << "=== run type: declared scope SearchNoRdr";
+            cat_id = scope->local_id() + ":declared:no-rdr:search";
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+            break;
+        case RunType::SearchNoLink:
+            qDebug() << "=== run type: declared scope Search";
+            cat_id = scope->local_id() + ":declared:no-link:search";
+            rdr = scope->search_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break;
+        case RunType::SearchNoLinkNoRdr:
+            qDebug() << "=== run type: declared scope SearchNoRdr";
+            cat_id = scope->local_id() + ":declared:no_rdr:no-link:search";
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break;
+         case RunType::Surface:
+            qDebug() << "=== run type: declared scope Surface";
+            cat_id = scope->local_id() + ":declared:rdr:surface";
+            rdr = scope->surface_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+            break;
+        case RunType::SurfaceNoRdr:
+            qDebug() << "=== run type: declared scope SurfaceNoRdr";
+            cat_id = scope->local_id() + ":declared:no-rdr:surface";
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr, link_to);
+            break;
+        case RunType::SurfaceNoLink:
+            qDebug() << "=== run type: declared scope SurfaceNoLink";
+            cat_id = scope->local_id() + ":declared:rdr:no-link:surface";
+            rdr = scope->surface_template();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break;
+        case RunType::SurfaceNoLinkNoRdr:
+            qDebug() << "=== run type: declared scope SurfaceNoLinkNoRdr";
+            cat_id = scope->local_id() + ":declared:link:no-link:no-rdr:surface";
+            rdr = res.category()->renderer_template().data();
+            set_result_catgory(upstream_reply, res, cat_id, cat_title, rdr);
+            break;
+    }
+
+    //TODO: put FALLBACK into method to avoid duplication needed by refactor
+    // perform res component fallback, as needed
+    if(!scope->surface_common_template_id().empty())
+    {
+        std::string res_str = us::Variant(res.serialize()).serialize_json(); 
+        auto change = this->client.check_result_fallbacks(res_str,
+                                                          scope->surface_common_template_id(),
+                                                          this->get_common_templates_fallbacks());
+        if (!std::get<0>(change).empty())
+        {
+            res[std::get<0>(change)] = std::get<1>(change);
+        }
+    }
+
+    //for child scopes that declare attribute swaps, do them
+    for (std::shared_ptr<std::pair<std::string,std::string>> swap : this->child_scopes_m[scope->local_id()]->swap_result_attributes)
+    {
+        try
+        {
+            if (!res[swap->first].get_string().empty())
+            {
+                res[swap->second] = res[swap->first];
+            }
+        }
+        catch (unity::LogicException)
+        {
+            qWarning() << QString("Scope %1 swap: result does not contain attribute 2").arg(client.qstr(scope->local_id()), client.qstr(swap->second));
+        }
+    }
+
+    //TODO: deprecate child category as brittle. should use keywords instead.
+    // if child_category set, filter out other child categories  by adding "dont_use" key to result
+    // also impose max category results if set
+    if (!scope->child_category().empty())
+    {
+        if (client.qstr(inc_res_cat_id) != client.qstr(scope->child_category()))
+        {
+            res["dont_use"] = "true";
+        }
+        else if (scope->using_child_category_max_results())
+        {
+            scope->inc_result_idx(); // allows constraining num results to child_category_max_results declaration
+            if (scope->result_idx() > scope->child_category_max_results() )
+            {
+                res["dont_use"] = "true";
+            }
+        }
+    }
+
+}

=== modified file 'src/query.cpp'
--- src/query.cpp	2016-08-19 20:23:21 +0000
+++ src/query.cpp	2016-09-30 19:17:35 +0000
@@ -312,8 +312,8 @@
     // create child scope instances from keywords and scopes
     make_categories();
 
-    // complete initializations inlcuding cutting child scopes to those present and enabled
-    handle_current_child_scopes(empty_search, upstream_reply);
+    // complete initializations including cutting child scopes to those present and enabled
+    complete_child_scopes();
 
     // convert current_scopes into scope_order based on declared order
     set_scope_order();
@@ -546,11 +546,6 @@
 
             qDebug() << "==== RESULT scope: " << client.qstr(scope->id());
 
-            // for use in category registration
-            std::string cat_id;
-            std::string cat_title;
-            std::string rdr;
-
             if (scope->keyword_scope())
             {
                 handle_keyword_child(upstream_reply, scope, res);
@@ -670,7 +665,6 @@
         {
             for (auto ch : current_child_scopes)
             {
-
                 if (ch.id == localId_id_m[locID])
                 {
                     qDebug() << "=== subsearch non KEYWORD scope local_ id " << client.qstr(scope->local_id());
@@ -692,7 +686,6 @@
                         adj_qry = localId_defaultQryStr[locID];
                     else
                         adj_qry = "";
-
                     subsearch
                     (
                         ch,

=== modified file 'src/utils.cpp'
--- src/utils.cpp	2016-08-19 20:46:32 +0000
+++ src/utils.cpp	2016-09-30 19:17:35 +0000
@@ -155,6 +155,7 @@
 
             if (cat_o.contains(QStringLiteral("link_to_child_specified")))
             {
+                qDebug() << "=== CAT UTILs. id: link_to_child_specified FOUND for category: " << client.qstr(cat_ptr->id);
                 categoryId_linkToChildSpecified[cat_ptr->id] = cat_o[QStringLiteral("link_to_child_specified")].toString().toStdString();
             }
             int card = client.get_cardinality_setting(settings(), setting_cardinalities);
@@ -221,7 +222,20 @@
                 QJsonDocument st_d(renderer_o);
                 cat_ptr->search_renderer = client.sstr(st_d.toJson());
             }
-
+            if (cat_o.contains(QStringLiteral("login_renderer")))
+            {
+                qDebug() << "==== UTILs. load. CATRES. login_renderer";
+                QJsonObject renderer_o = cat_o[QStringLiteral("login_renderer")].toObject();
+                QJsonDocument st_d(renderer_o);
+                cat_ptr->login_renderer = client.sstr(st_d.toJson());
+                if (cat_o.contains(QStringLiteral("login_renderer_incoming_category_id")))
+                {
+                    qDebug() << "==== UTILs. load. CATRES. login_renderer_incoming_category_id";
+                    cat_ptr->login_renderer_incoming_category_id = cat_o[QStringLiteral("login_renderer_incoming_category_id")].toString().toStdString();
+                }
+            }
+            qDebug() << "==== UTILs. load. CATRES. login_renderer: " << client.qstr(cat_ptr->login_renderer);
+            qDebug() << "==== UTILs. load. CATRES. login_renderer_incoming_category_id: " << client.qstr(cat_ptr->login_renderer_incoming_category_id);
             if (cat_o.contains(QStringLiteral("scopes")))
             {
                 QJsonArray scope_a = cat_o[QStringLiteral("scopes")].toArray();
@@ -298,6 +312,17 @@
             if (scope_o.contains(QStringLiteral("department")))
                 cs->department = scope_o[QStringLiteral("department")].toString().toStdString();
 
+            if (scope_o.contains(QStringLiteral("login_renderer")))
+            {
+                QJsonObject renderer_o = scope_o[QStringLiteral("login_renderer")].toObject();
+                QJsonDocument st_d(renderer_o);
+                cs->login_renderer = client.sstr(st_d.toJson());
+                if (scope_o.contains(QStringLiteral("login_renderer_incoming_category_id")))
+                {
+                    cs->login_renderer_incoming_category_id = scope_o[QStringLiteral("login_renderer_incoming_category_id")].toString().toStdString();
+                }
+            }
+
             cs->link_to_child = true;
             if (scope_o.contains(QStringLiteral("link_to_child")))
             {
@@ -532,85 +557,32 @@
                 else if (dept_id_of_root_keywords_only.empty())
                     dept_id_of_root_keywords_only = keyword_id;
             }
-            std::string category;
-            if (keyword_o.contains(QStringLiteral("shared_category")))
-            {
-                category = keyword_id; // note category is synomous with keyword and is therefore used even when not shared category
-                //note: removed support for shared_category value other than "true"
-                if (keyword_o[QStringLiteral("shared_category")] == TRUE)
-                {
-                    std::string title_msgid = keyword_o[QStringLiteral("_shared_category_title")].toString().toStdString();
-                    shared_keyword_cat_titlemsgid[category] = title_msgid;
-                    shared_keyword_cats[keyword_id] = category;
-                    shared_keywords.emplace_back(keyword_id);
-                }
-            }
-            //we do not support first result with non shared category keyword scopes
-            if (category == keyword_id && keyword_o.contains(QStringLiteral("first_result_renderer_common_id")))
-            {
-                std::string id = keyword_o[QStringLiteral("first_result_renderer_common_id")].toString().toStdString();
-                keyword_catname_first_result_renderers[category] = common_templates[id];
-            }
-            else if (category == keyword_id && keyword_o.contains(QStringLiteral("first_result_renderer")))
-            {
-                QJsonObject template_o = keyword_o[QStringLiteral("first_result_renderer")].toObject();
-                QJsonDocument t_d(template_o);
-                keyword_catname_first_result_renderers[category] = client.sstr(t_d.toJson());
-            }
-            else if (category == keyword_id && keyword_o.contains(QStringLiteral("first_result_template")))
-            {
-                //support deprecated for backwards compatibiliity
-                qWarning () << QString("%1: DEPRECATED use of 'first_result_template'. Switch to 'first_result_renderer'")
-                    .arg(client.qstr(agg_scope_->scope_id()));
-                QJsonObject template_o = keyword_o[QStringLiteral("first_result_template")].toObject();
-                QJsonDocument t_d(template_o);
-                keyword_catname_first_result_renderers[category] = client.sstr(t_d.toJson());
-            }
-            //NOTE: README.md does not mention "category" renders. they exist for backwards compatibility.
-            //It says render declaration
-            //is the same as with a declared scope, which means "renderer_common_id", "renderer",
-            //"first_result_renderer_common_id", "first_result_renderer", "search_renderer_common_id",
-            //and "search_renderer"
             if (keyword_o.contains(QStringLiteral("renderer_common_id")))
             {
-                qDebug() << "==== UTILs. load. KW CAT. renderer_common_id. keyword&category: " << client.qstr(category);;
+                qDebug() << "==== UTILs. load. KW CAT. renderer_common_id. keyword&category: " << client.qstr(keyword_id);
                 std::string id = keyword_o[QStringLiteral("renderer_common_id")].toString().toStdString();
-                keyword_catname_renderer[category] = common_templates[id];
+                keyword_catname_renderer[keyword_id] = common_templates[id];
 
-                qDebug() << "==== UTILs. load. KW CAT. renderer_common_id: "<< client.qstr(keyword_catname_renderer[category]).replace("\n", " ");
+                qDebug() << "==== UTILs. load. KW CAT. renderer_common_id: "<< client.qstr(keyword_catname_renderer[keyword_id]).replace("\n", " ");
             }
             else if (keyword_o.contains(QStringLiteral("renderer")))
             {
                 qDebug() << "==== UTILs. load. KW CAT. renderer";
                 QJsonObject renderer_o = keyword_o[QStringLiteral("renderer")].toObject();
                 QJsonDocument rdr_d(renderer_o);
-                keyword_catname_renderer[category] = client.sstr(rdr_d.toJson());
-
-                qDebug() << "==== UTILs. load. KW CAT. renderer:" << client.qstr(keyword_catname_renderer[category]).replace("\n", " ");
-            }
-            else if (keyword_o.contains(QStringLiteral("category_renderer_common_id")))
-            {
-                qDebug() << "==== UTILs. load. KW SHARED CAT. category_renderer_common_id";
-                std::string id = keyword_o[QStringLiteral("category_renderer_common_id")].toString().toStdString();
-                keyword_catname_renderer[category] = common_templates[id];
-            }
-            else if (keyword_o.contains(QStringLiteral("category_renderer")))
-            {
-                qDebug() << "==== UTILs. load. KW CAT. category_renderer";
-                QJsonObject renderer_o = keyword_o[QStringLiteral("category_renderer")].toObject();
-                QJsonDocument rdr_d(renderer_o);
-                keyword_catname_renderer[category] = client.sstr(rdr_d.toJson());
+                keyword_catname_renderer[keyword_id] = client.sstr(rdr_d.toJson());
+                qDebug() << "==== UTILs. load. KW CAT. renderer:" << client.qstr(keyword_catname_renderer[keyword_id]).replace("\n", " ");
             }
             if (keyword_o.contains(QStringLiteral("search_renderer_common_id")))
             {
                 std::string id = keyword_o[QStringLiteral("search_renderer_common_id")].toString().toStdString();
-                keyword_catname_search_renderer[category] = common_templates[id];
+                keyword_catname_search_renderer[keyword_id] = common_templates[id];
             }
             else if (keyword_o.contains(QStringLiteral("search_renderer")))
             {
                 QJsonObject renderer_o = keyword_o[QStringLiteral("search_renderer")].toObject();
                 QJsonDocument rdr_d(renderer_o);
-                keyword_catname_search_renderer[category] = client.sstr(rdr_d.toJson());
+                keyword_catname_search_renderer[keyword_id] = client.sstr(rdr_d.toJson());
             }
             if (keyword_o.contains(QStringLiteral("link_to_child"))
                     && keyword_o[QStringLiteral("link_to_child")].toString() == TRUE) {
@@ -643,8 +615,6 @@
             id_keyword_map[keyword_id]  = keyword_;
         }
     }
-    //for (auto str : declared_order)
-    //    qDebug() << "==== ORDER. declared scope: " << client.qstr(str);
 }
 
 void Query::set_scope_order()
@@ -800,6 +770,15 @@
             ch_ptr->set_override_search_template(false);
         }
 
+        if (!child->login_renderer_incoming_category_id.empty() &&
+            !child->login_renderer.empty())
+        {
+            qDebug() << "==== SCOPE LOGIN";
+            ch_ptr->enable_using_login_renderer();
+            ch_ptr->set_login_template(child->login_renderer);
+            ch_ptr->set_login_renderer_incoming_category_id(child->login_renderer_incoming_category_id);
+        }
+
         ch_ptr->set_only_in_search(child->only_in_search);
 
         ch_ptr->set_source_finder(child->source_finder);
@@ -810,6 +789,10 @@
     }
 }
 
+bool Query::is_using_departments(){
+    return using_departments;
+}
+
 void Query::create_departments(us::SearchReplyProxy const &reply_)
 {
     if (!using_departments)
@@ -856,7 +839,6 @@
         if (!keyword_child.enabled)
             continue;
         auto keych_ptr = std::make_shared<AggChildScope>(keyword_child.id);
-        QString time_str = QDateTime::currentDateTimeUtc().toString();
         keych_ptr->set_keyword_scope(true);
         auto dept_ptr = std::make_shared<dept>();
         dept_ptr->id = keyword_child.id;
@@ -890,14 +872,22 @@
             keych_ptr->set_department(kw);
             keych_ptr->set_keyword(kw);
             keych_ptr->set_category_link_to_child(id_keyword_map[kw]->link_to_child);
+            qDebug() << "===_ UTILs. KW. link to child: " << QString::number(keych_ptr->category_link_to_child());
+            //get rdr if any
             if (!keyword_catname_renderer[kw].empty())
             {
-                qDebug()<< "==== UTILs. adding renderer to: " << client.qstr(keyword_child.id);
+                qDebug()<< "==== UTILs. KW adding renderer to: " << client.qstr(keyword_child.id);
                 keych_ptr->set_surface_template(keyword_catname_renderer[kw]);// this is overwritten below for shared cat scopes
             }
             else
             {
-                qDebug()<< "==== UTILs. renderer not declared: " << client.qstr(keyword_child.id);
+                qDebug()<< "==== UTILs. KW renderer not declared: " << client.qstr(keyword_child.id);
+            }
+            //get search rdr if any
+            if (!keyword_catname_search_renderer[kw].empty())
+            {
+                qDebug()<< "==== UTILs. KW adding searchrenderer to: " << client.qstr(keyword_child.id);
+                keych_ptr->set_search_template(keyword_catname_search_renderer[kw]);// this is overwritten below for shared cat scopes
             }
 
             bool a_dup = false;
@@ -946,7 +936,6 @@
                     depts[kw] = dept_ptr;
                 }
             }
-
             auto iter = find(shared_keywords.begin(), shared_keywords.end(), kw);
             if (iter != shared_keywords.end())
             {
@@ -954,18 +943,11 @@
                 qDebug() << QString("==== UTILs. set ky scope kw %1 as a a shared cat in kw: %2").arg(client.qstr(keych_ptr->id()), client.qstr(kw));
                 keych_ptr->set_keyword_scope_shared_cat_name(shared_keyword_cats[kw]);
 
-                //initially the category is set to false meaning there have been
-                //no results yet for it and it has not yet been registered
-                sharedcat_catregistered[shared_keyword_cats[kw]] = false;
-                // set more default values
-                keywordSharedCat_isFirstResult[kw] = true;
                 qDebug() << "===== UTILs. kw: " << client.qstr(kw);
                 qDebug() << "===== UTILs. keywordSharedCat_isFirstResult[kw] " << keywordSharedCat_isFirstResult[kw];
                 keywordSharedCat_isSecondResult[kw] = false;
                 qDebug() << "===== UTILs. kw shared surface: " << client.qstr(keyword_catname_renderer[kw]).replace("\n"," ");
                 keych_ptr->set_surface_template(keyword_catname_renderer[kw]);
-//                if (keyword_catname_first_result_renderers[kw].empty())
-//                    keych.set_first_resulte_template(keyword_catname_first_result_renderer[kw]);
             }
             found = true;
             //this break ensures the scope is associated with *first* decared keyword, thus
@@ -1002,6 +984,19 @@
             auto scope_ptr = std::make_shared<AggChildScope>(ids.first);
             scope_ptr->set_category_scope(true);
             scope_ptr->set_category_id(cat->id);
+
+            if (!cat->login_renderer_incoming_category_id.empty() &&
+                !cat->login_renderer.empty())
+            {
+                scope_ptr->enable_using_login_renderer();
+                scope_ptr->set_login_template(cat->login_renderer);
+                scope_ptr->set_login_renderer_incoming_category_id(cat->login_renderer_incoming_category_id);
+            }
+
+            qDebug() << "==== MKCAT SCOPE cat->login_renderer CAT incoming_category_id: "<< QString::fromStdString(cat->login_renderer_incoming_category_id);
+            qDebug() << "==== MKCAT SCOPE cat->login_renderer: "<< QString::fromStdString(cat->login_renderer);
+            qDebug() << "==== MKCAT SCOPE login_renderer  SCOPE incoming_category_id: "<< QString::fromStdString(scope_ptr->login_renderer_incoming_category_id());
+
             qDebug() << "==== MKCAT SCOPE cat card"<< QString::number(cat->cardinality);
             scope_ptr->set_cardinality(cat->cardinality);
             qDebug() << "==== MKCAT SCOPE get cat card"<< QString::number(scope_ptr->cardinality());
@@ -1058,6 +1053,7 @@
                 if (found_scopes.size() == 0 )
                     continue;
 
+
                 qDebug() << client.qstr("==== CATKW ID found: %1 %2").arg(client.qstr(kw),client.qstr(id));
                 auto keych_ptr = std::make_shared<AggChildScope>(id);
                 std::string local_id = id + ":category=" + cat->id + ":keyword=" +  kw;
@@ -1066,6 +1062,7 @@
                 keych_ptr->set_category_scope(true);
                 keych_ptr->set_category_id(cat->id);
                 qDebug() << "==== CATKW adding id: " << client.qstr(id);
+                qDebug() << "==== CATKW adding. local_id: " << client.qstr(local_id);
                 qDebug() << "==== CATKW adding kw: " << client.qstr(kw);
                 type_ids_m[cat->id].emplace_back(keych_ptr->local_id());
                 keych_ptr->set_keyword(kw);
@@ -1073,7 +1070,15 @@
                 keych_ptr->set_department(cat->dept_id);
                 keych_ptr->set_department(cat->dept_id);
                 keych_ptr->set_cardinality(cat->cardinality);
-
+                //set up login renderer usage, if any
+                if (!cat->login_renderer_incoming_category_id.empty() &&
+                    !cat->login_renderer.empty())
+                {
+                    qDebug() << "==== CATKW: login renderer in use";
+                    keych_ptr->enable_using_login_renderer();
+                    keych_ptr->set_login_template(cat->login_renderer);
+                    keych_ptr->set_login_renderer_incoming_category_id(cat->login_renderer_incoming_category_id);
+                }
                 // set more default values
                 categoryId_isFirstResult[kw] = true;
                 categoryId_isSecondResult[kw] = false;
@@ -1100,1005 +1105,3 @@
         }
     }
 }
-
-void Query::handle_current_child_scopes(bool empty_search, us::SearchReplyProxy const& upstream_reply)
-{
-    UNUSED(empty_search)
-    UNUSED(upstream_reply)
-    // Cycle through child scopes (in current_scopes) and, if enabled in settings, complete set up
-    try
-    {
-        for (const std::string & local_id : current_scopes)
-        {
-            qDebug() << "==== CURRENT. local_id: " << client.qstr(local_id);
-            std::string id = localId_id_m[local_id];
-            qDebug() << "==== CURRENT. id: " << client.qstr(id);
-            std::shared_ptr<AggChildScope> scope = scopes_m[local_id];
-
-            scope->set_proxy(registry_);
-
-            if (!scope->exists()) {
-                std::string sep = query_store_  == "" ? "name:" : "+";
-                std::string name = std::string(id, 0, id.find('_'));
-                query_store_.append(sep + name);
-            }
-            else
-            {
-                if (!scope->source_finder())
-                    has_one_source = true;
-            }
-        }
-        for (auto source : sources_for_clickstore)
-        {
-            AggChildScope scope(source);
-            scope.set_proxy(registry_);
-            if (!scope.exists()) {
-                std::string sep = query_store_  == "" ? "name:" : "+";
-                std::string name = std::string(source, 0, source.find('_'));
-                query_store_.append(sep + name);
-            }
-        }
-    }
-    catch (unity::Exception const& e)
-    {
-        qWarning() << "NotFoundException: " << e.what();
-    }
-}
-
-void Query::noSources(unity::scopes::SearchReplyProxy const& reply) {
-    std::string MESS_GRID = R"(
-        {
-            "schema-version" : 1,
-            "template" : {
-                "category-layout" : "grid",
-                "card-layout": "horizontal",
-                "card-size": "small",
-                "non-interactive": true
-            },
-            "components" : {
-                "title" : "title"
-            }
-        }
-    )";
-
-    CategoryRenderer emptyCat(MESS_GRID);
-    auto messGrid = reply->register_category("emptyMess", _("Welcome"), "", emptyCat);
-    CategorisedResult res(messGrid);
-    res.set_uri("http://ubuntu.com");
-    res["title"]=_("To start using this scope please install sources from the list below");
-    reply->push(res);
-}
-
-bool Query::hints_exists()
-{
-    auto scopes = registry_->list();
-    us::MetadataMap::const_iterator scope;
-    scope = scopes.find(HINTS_SCOPE_ID);
-    if (scope != scopes.end()) {
-        auto meta = registry_->get_metadata(HINTS_SCOPE_ID);
-        hints_scope = meta.proxy();
-        return true;
-    }
-    return false;
-}
-
-void Query::display_local_hints_quickstart(us::SearchReplyProxy const& upstream_reply_)
-{
-    if (!local_hints)
-        return;
-    if (!hints_local_json.contains(QStringLiteral("content")))
-        return;
-    auto content = hints_local_json[QStringLiteral("content")].toObject();
-    if (!content.contains(QStringLiteral("categories")))
-        return;
-
-    QJsonArray cats = content[QStringLiteral("categories")].toArray();
-    for (const auto & cat_ : cats)
-    {
-        auto cat = cat_.toObject();
-
-        std::string id = client.sstr(cat[QStringLiteral("id")].toString());
-        std::string title = _(client.sstr(cat[QStringLiteral("_title")].toString()).c_str());
-        QJsonDocument layout_d(cat[QStringLiteral("layout")].toObject());
-        std::string local_hints_template = client.sstr(layout_d.toJson());
-        auto category = upstream_reply_->lookup_category(id);
-        if (!category) {
-            category = upstream_reply_->register_category(id, title, "", us::CategoryRenderer(local_hints_template));
-        }
-        QJsonArray items = cat[QStringLiteral("items")].toArray();
-        for (const auto & res__ : items)
-        {
-            auto res_ = res__.toObject();
-            us::CategorisedResult res(category);
-            res.set_title(_(client.sstr(res_[QStringLiteral("_title")].toString()).c_str()));
-            res["subtitle"] = _(client.sstr(res_[QStringLiteral("_subtitle")].toString()).c_str());
-            res["description"] = _(client.sstr(res_[QStringLiteral("_description")].toString()).c_str());
-            std::string uri = "http://www.ubuntu.com";
-            if (res_.contains(QStringLiteral("hide_in_locales")))
-            {
-                QStringList hide_in_locales = res_[QStringLiteral("hide_in_locales")].toString().split(",");
-                std::string lcRaw = setlocale(LC_ALL, ""); 
-                std::string lc_lang = lcRaw.size() > 5 ? lcRaw.substr(0, 2) : "";
-                std::string lc_country  = lcRaw.size() > 5 ? lcRaw.substr(3, 2) : "";
-                std::string lc = lc_lang + "_" + lc_country;
-                if (hide_in_locales.contains(client.qstr(lc)))
-                {
-                    continue;
-                }
-            }
-            if (res_.contains("uri"))
-            {
-                uri = client.sstr(res_["uri"].toString());
-            }
-            if (res_.contains(QStringLiteral("action")))
-            {
-                auto action = res_[QStringLiteral("action")].toObject();
-                VariantBuilder builder;
-                builder.add_tuple({
-                    {"id", Variant("Open")},
-                    {"label", Variant(_(client.sstr(action[QStringLiteral("_name")].toString()).c_str()))},
-                    {"uri", Variant(client.sstr(action[QStringLiteral("uri")].toString()))}
-                });
-                res["actions"]=builder.end();
-                if (action.contains(QStringLiteral("uri")))
-                {
-                    uri = client.sstr(action[QStringLiteral("uri")].toString());
-                }
-            }
-            if (res_.contains(QStringLiteral("oaccount")))
-            {
-                auto oaccount = res_[QStringLiteral("oaccount")].toObject();
-                auto queryScope = client.sstr(oaccount[QStringLiteral("QueryScope")].toString());
-
-                // before framework 15.0.4.4 the service name is the FQ scope id and contains one "_"
-                // with 15.04.4, it is FQ scope id += _PROVIDER
-                // we also want the fully qualified scope id to check with registry if it is installed.
-                // to support both cases:
-                QStringList parts = oaccount[QStringLiteral("ServiceName")].toString().split("_");
-                QString provider = oaccount[QStringLiteral("ProviderName")].toString();
-                QString sc_id = parts[0] + "_" + parts[1];
-                QString id = sc_id;
-                if (parts.size() > 2) // framework 15.04.4 or higher 
-                {
-                    id += "_" + provider;
-                }
-                us::OnlineAccountClient oa_client(client.sstr(id),
-                                                  client.sstr(oaccount[QStringLiteral("ServiceType")].toString()),
-                                                  client.sstr(provider));
-                bool alreadyLoggedIn = false;
-                oa_client.refresh_service_statuses();
-                for (auto const& status : oa_client.get_service_statuses())
-                {
-                    if (status.service_enabled)
-                    {
-                        alreadyLoggedIn = true;
-                        break;
-                    }
-                }
-                // do not display quick start help for scopes that are not registered in the system
-                auto reg_scopes = registry_->list();
-                us::MetadataMap::const_iterator scope_it;
-                scope_it = reg_scopes.find(client.sstr(sc_id));
-                if (scope_it == reg_scopes.end()) {
-                    qWarning () << QString("%1: OA scope is NOT REGISTERED, skipping for HINTS: %2").arg(oaccount[QStringLiteral("ServiceName")].toString());
-                    continue;
-                }
-                if (alreadyLoggedIn) {
-                    //the hints code does this when the person is already logged in to the service.
-                    //auto tmp = oaccount["_loggedin"].toString().toStdString();
-                    //res["title"] = std::string(_(tmp.c_str()));
-                    //
-                    //this continue statement means if the person is logged in, we do not show
-                    //a result for the item
-                    continue;
-                }
-                us::CannedQuery query(queryScope);
-                oa_client.register_account_login_item(res,
-                                                      query,
-                                                      OnlineAccountClient::InvalidateResults,
-                                                      OnlineAccountClient::DoNothing);
-
-            }
-            if (res_.contains(QStringLiteral("hide_hints")))
-            {
-                qDebug() << "=== NHINTS. utils. hide hints found in json";
-                res["action"] = "hide_hints";
-                res.set_intercept_activation();
-            }
-            res.set_uri(uri);
-            res.set_art(scope_dir_ + "/images/" + client.sstr(res_["art"].toString()));
-            upstream_reply_->push(res);
-        }
-    }
-}
-
-void Query::display_remote_hints_quickstart(us::SearchReplyProxy const& upstream_reply_)
-{
-    qDebug() << "==== HINTS in display_remote_hints_quickstart()";
-    Category::SCPtr hint_cat;
-    SearchMetadata metadata(search_metadata());
-    auto reply = std::make_shared<ResultForwarder>(upstream_reply_,
-    [this, &hint_cat](CategorisedResult& res) -> bool {
-        UNUSED(res)
-        return true;
-    });
-
-    subsearch(hints_scope, "", HINTS_THIS_SCOPE, FilterState(),
-              metadata, reply);
-}
-
-bool Query::hints_hidden() {
-
-    auto filepath1 = QString::fromStdString(cache_dir_) +"/" + hints_file;
-    auto filepath2 = QString::fromStdString(cache_dir_) +"/" + firstboot;
-    if (QFile::exists(filepath1) || QFile::exists(filepath2))
-        return true;
-    return false; //don't show hints as fall back
-}
-
-void Query::dismiss_hints_quickstart() {
-    qDebug() << "==== HINTS in dismiss()";
-    auto filepath= QString::fromStdString(cache_dir_) +"/" + hints_file;
-    QFile file(filepath);
-    file.open(QIODevice::WriteOnly);
-    QString msg = QString("Timestamp for %1 %2").arg(client.qstr(HINTS_THIS_SCOPE), QDateTime::currentDateTime().toString());
-    file.write(client.sstr(msg).c_str(), client.sstr(msg).size());
-    file.close();
-}
-
-void Query::handle_keyword_child(unity::scopes::SearchReplyProxy const& upstream_reply,
-                                 std::shared_ptr<AggChildScope> scope,
-                                 us::CategorisedResult & res){
-
-    // for use in category registration
-    std::string cat_id;
-    std::string cat_title;
-    std::string rdr;
-
-    std::string keyword = scope->keyword();
-    qDebug() << "==== KW scope: " << client.qstr(scope->id()) << " keyword: " << client.qstr(keyword);;
-    qDebug() << "==== KW scope shared cat name: " << client.qstr(scope->keyword_scope_shared_cat_name());
-
-    if (!query().query_string().empty())
-    {
-        if (!keyword_catname_search_renderer[keyword].empty()) // keyword has declared cat search renderer
-        {
-            qDebug() << "==== KW SEARCH keyword using search renderer";
-            cat_id = keyword + ":keyword:search_renderer:searching:" + cat_title;
-            rdr = keyword_catname_search_renderer[keyword];
-        }
-        else
-        {
-            qDebug() << "==== KW SEARCH using incoming result renderer";
-            cat_id = keyword + ":keyword:incoming_renderer:searching:" + cat_title;
-            rdr = res.category()->renderer_template().data();
-        }
-        if (!upstream_reply->lookup_category(cat_id))
-        {
-            catname_catptr[scope->keyword_scope_shared_cat_name()] = upstream_reply->register_category
-            (
-                cat_id,
-                cat_title,
-                 "",
-                us::CategoryRenderer(rdr)
-            );
-            res.set_category(catname_catptr[scope->keyword_scope_shared_cat_name()]);
-        }
-        else
-            res.set_category(upstream_reply->lookup_category(cat_id));
-        qDebug() << "==== KW SEARCH. cat_id: " << client.qstr(cat_id);
-    }
-    else if (!scope->keyword_scope_shared_cat_name().empty())
-    {//uses shared category
-        cat_title = _(shared_keyword_cat_titlemsgid[keyword].c_str());
-        qDebug() << "==== KW SHAREDCAT uses shared cat";
-        if (!keyword_catname_first_result_renderers[keyword].empty()) // uses first result rdr
-        {
-            if ((first_result_owner.empty()) || (first_result_owner == keyword))
-            {
-                qDebug() << "==== KW SHAREDCAT uses first result: " << client.qstr(scope->id());
-                if (keywordSharedCat_isFirstResult[keyword])
-                {
-                    first_result_owner = keyword;
-                    keywordSharedCat_isFirstResult[keyword] = false;
-                    keywordSharedCat_isSecondResult[keyword] = true;
-                    qDebug() << "==== KW SHAREDCAT is FIRST result: " << client.qstr(scope->keyword_scope_shared_cat_name());
-                    qDebug() << "==== KW SHAREDCAT claims FIRST result: " << client.qstr(scope->keyword_scope_shared_cat_name());
-                    cat_id = keyword + ":keyword:is_shared_category:is_first_result:" + cat_title;
-                    rdr = keyword_catname_first_result_renderers[keyword];
-                    if (!upstream_reply->lookup_category(cat_id))
-                    {
-                        catname_catptr[scope->keyword_scope_shared_cat_name()] = upstream_reply->register_category
-                        (
-                            cat_id,
-                            cat_title,
-                             "",
-                            us::CategoryRenderer(rdr)
-                        );
-                    }
-                    res.set_category(upstream_reply->lookup_category(cat_id));
-                }
-                else if ( keywordSharedCat_isSecondResult[keyword] )// second result
-                {
-                    //keywordSharedCat_isSecondResult[keyword] = false;
-                    qDebug() << "==== KW SHAREDCAT uses FIRST result. is SECOND+ result: " << client.qstr(scope->keyword_scope_shared_cat_name());
-                    if (!keyword_catname_renderer[keyword].empty()) // keyword has declared cat renderer
-                    {
-                        qDebug() << "==== KW SHAREDCAT uses FIRST result. is SECOND+ result. NOT uses surface_template ";
-                        cat_id = scope->keyword_scope_shared_cat_name() + ":keyword:is_shared_category:uses_first_result:second_result+:surface_template:surfacing:"  + cat_title;
-                        rdr = keyword_catname_renderer[keyword];
-                    }
-                    else //no surface template found, use incoming result
-                    {
-                        qDebug() << "==== KW SHAREDCAT uses FIRST result. is SECOND+ result. NOT uses result template ";
-                        cat_id = scope->keyword_scope_shared_cat_name() + ":keyword:is_shared_category:uses_first_result:second_result+:result_template:surfacing:"  + cat_title;
-                        rdr = res.category()->renderer_template().data();
-                    }
-                    if (!upstream_reply->lookup_category(cat_id))
-                    {
-                        catname_catptr[scope->keyword_scope_shared_cat_name()] = upstream_reply->register_category
-                        (
-                            cat_id,
-                            cat_title,
-                             "",
-                            us::CategoryRenderer(rdr)
-                        );
-                    }
-                    res.set_category(upstream_reply->lookup_category(cat_id));
-                }
-                qDebug() << "==== KW SHAREDCAT uses FIRST result. cat_id: " << client.qstr(cat_id);
-                
-            }
-        }
-        else // not search and does not use declared first result rdr
-        {
-            if (!scope->surface_template().empty())// has a decared surface template
-            {
-                qDebug() << "==== KW SHAREDCAT not uses first result. uses surface template";
-                cat_id = scope->keyword_scope_shared_cat_name() + ":keyword:is_shared_category:not_uses_first_result:surface_template:surfacing:"  + cat_title;
-                rdr = scope->surface_template();
-                qDebug() << "==== KW SHAREDCAT. rdr" <<  client.qstr(rdr).replace("\n", " ");
-            }
-            else // use result template
-            {
-                qDebug() << "==== KW SHAREDCAT not uses first result. NOT uses surface template";
-                cat_id = scope->keyword_scope_shared_cat_name() + ":keyword:is_shared_category:not_uses_first_result:result_template:surfacing:"  + cat_title;
-                rdr = res.category()->renderer_template().data();
-            }
-            if (catname_catptr.find(scope->keyword_scope_shared_cat_name()) == catname_catptr.end())
-            {
-                if (categoryId_linkToChildSpecified.find(scope->category_id()) != categoryId_linkToChildSpecified.end())
-                {
-                    if (!upstream_reply->lookup_category(cat_id))
-                    {
-                        catname_catptr[scope->keyword_scope_shared_cat_name()] = upstream_reply->register_category
-                        (
-                            cat_id,
-                            cat_title,
-                             "",
-                            us::CannedQuery(categoryId_linkToChildSpecified[scope->category_id()]),
-                            us::CategoryRenderer(rdr)
-                        );
-                    }
-                    else
-                    {
-                        res.set_category(upstream_reply->lookup_category(cat_id));
-                    }
-                }
-                else if (!upstream_reply->lookup_category(cat_id))
-                {
-                    catname_catptr[scope->keyword_scope_shared_cat_name()] = upstream_reply->register_category
-                    (
-                        cat_id,
-                        cat_title,
-                         "",
-                        us::CategoryRenderer(rdr)
-                    );
-                    res.set_category(upstream_reply->lookup_category(cat_id));
-                }
-                else
-                {
-                    res.set_category(upstream_reply->lookup_category(cat_id));
-                }
-            }
-            else
-            {
-                res.set_category(upstream_reply->lookup_category(cat_id));
-                qDebug() << "==== KW SHAREDCAT not uses first result. cat_id: " << client.qstr(cat_id);
-            }
-        }
-    }
-    else // keyword scope does not use a shared category
-    {
-        qDebug() << "==== KW not SHAREDCAT";
-        qDebug() << "==== KW not SHAREDCAT. first result for scope: " << client.qstr(scope->local_id());
-        scope->set_is_first_result(false);
-        //cat_title = inc_res_cat_title;
-        //if (cat_title.empty()){
-            cat_title = registry_->get_metadata(scope->id()).display_name();
-        //}
-        qDebug() << "==== KW not SHAREDCAT. local_id: " << client.qstr(scope->local_id());
-        qDebug() << "==== KW not SHAREDCAT. cat_ttile: " << client.qstr(cat_title);
-        //if (keyword_catname_renderer.find(keyword) != keyword_catname_renderer.end())// has a decared surface template
-        if (!keyword_catname_renderer[keyword].empty())
-        {
-            qDebug() << "==== KW not SHAREDCAT.  declared renderer ";
-            qDebug() << "==== KW not SHAREDCAR. keyword: " << client.qstr(scope->keyword());
-            cat_id = scope->keyword() + ":keyword:not_shared_category:declared_renderer:surfacing:"  + cat_title;
-            rdr = keyword_catname_renderer[keyword];
-        }
-        else // use result template
-        {
-            qDebug() << "==== KW not SHAREDCAT. incoming renderer";
-            cat_id = scope->keyword() + ":keyword:not_shared_category:incoming_renderer:surfacing:" + cat_title;
-            rdr = res.category()->renderer_template().data();
-        }
-        qDebug() << "==== KW not SHAREDCAT. cat_id: " << client.qstr(cat_id);
-        if (scope->category_link_to_child()) 
-        {
-            if (!upstream_reply->lookup_category(cat_id))
-            {
-                upstream_reply->register_category
-                (
-                    cat_id,
-                    cat_title,
-                    "",
-                    us::CannedQuery(scope->id(), query().query_string(), scope->child_department()),
-                    us::CategoryRenderer(rdr)
-                );
-            }
-                res.set_category(upstream_reply->lookup_category(cat_id));
-         }
-         else
-         {
-             if (!upstream_reply->lookup_category(cat_id))
-             {
-                 upstream_reply->register_category
-                 (
-                     cat_id,
-                     cat_title,
-                     "",
-                     us::CategoryRenderer(rdr)
-                 );
-             }
-             res.set_category(upstream_reply->lookup_category(cat_id));
-         }
-    }
-}
-
-void Query::handle_category_child(unity::scopes::SearchReplyProxy const& upstream_reply,
-                                 std::shared_ptr<AggChildScope> scope,
-                                 us::CategorisedResult & res){
-
-    // for use in category registration
-    std::string cat_id;
-    std::string cat_title;
-    std::string rdr;
-
-    std::string category_id = scope->category_id();
-    qDebug() << "==== CATREG RESULT scope: " << client.qstr(scope->id()) << "  title: " <<client.qstr(cat_title);
-
-    if (!categoryId_titleMsgid[category_id].empty())
-        cat_title = _(categoryId_titleMsgid[category_id].c_str());
-    else
-        cat_title = "";
-
-    bool uses_first_result_rdr = categoryId_first_result_renderers.find(category_id) != categoryId_first_result_renderers.end();
-
-    if (!query().query_string().empty())
-    {
-        qDebug()<<client.qstr("==== CATREG scope's (%1) search template: %2").arg(client.qstr(scope->local_id()), client.qstr(scope->search_template()).replace("\n", " "));
-        qDebug() << "==== CATREG search renderer:" << client.qstr(scope->search_template()).replace("\n", "");
-        if (!scope->search_template().empty())
-        {
-            qDebug() << "==== CATREG using search renderer";
-            cat_id = scope->local_id() + ":category:search-renderer:searching:" + cat_title;
-            rdr = scope->search_template();
-        }
-        else
-        {
-            qDebug() << "==== CATREG using incoming eesult renderer";
-            cat_id = scope->local_id() + ":category:incoming-renderer:searching:" + cat_title;
-            rdr = res.category()->renderer_template().data();
-        }
-        if (!upstream_reply->lookup_category(cat_id))
-        {
-            upstream_reply->register_category
-            (
-                cat_id,
-                cat_title,
-                 "",
-                us::CategoryRenderer(rdr)
-            );
-            res.set_category(upstream_reply->lookup_category(cat_id));
-        }
-        else
-            res.set_category(upstream_reply->lookup_category(cat_id));
-        qDebug() << "==== CATREG search cat_id: " << client.qstr(cat_id);
-    }
-    else if (uses_first_result_rdr ) 
-    {
-        qDebug() << "==== CATREG uses first result. scope category_id: " << client.qstr(category_id);
-
-        if ((first_result_owner.empty()) || (first_result_owner == category_id))
-        {
-            // perform fallbacks, if any
-            if(!scope->first_common_template_id().empty())
-            {
-                qDebug() << "==== first check FALLB. scope->first_common_template_id():" << client.qstr(scope->first_common_template_id());
-                std::string res_str = us::Variant(res.serialize()).serialize_json(); 
-                auto change = this->client.check_result_fallbacks(res_str,
-                                                                  scope->first_common_template_id(),
-                                                                  this->get_common_templates_fallbacks());
-                if (!std::get<0>(change).empty())
-                {
-                    res[std::get<0>(change)] = std::get<1>(change);
-                }
-           }
-            if (categoryId_isFirstResult[category_id])
-            {
-                first_result_owner = category_id;
-                cat_id = category_id + ":category:uses-first-result:first-result-rdr:surfacing";
-                qDebug() << "==== CATREG. uses FIRST result. FIRST result. cat_id: " << client.qstr(cat_id);
-                rdr = categoryId_first_result_renderers[category_id];
-                categoryId_isFirstResult[category_id] = false;
-                categoryId_isSecondResult[category_id] = true;
-                if (categoryId_linkToChildSpecified.find(scope->category_id()) != categoryId_linkToChildSpecified.end())
-                {
-                    qDebug() << "==== CATREG. uses FIRST result. FIRST result. LINK to child ";
-                    if (!upstream_reply->lookup_category(cat_id))
-                    {
-                        catname_catptr[category_id] = upstream_reply->register_category
-                        (
-                            cat_id,
-                            cat_title,
-                             "",
-                            us::CannedQuery(categoryId_linkToChildSpecified[scope->category_id()]),
-                            us::CategoryRenderer(rdr)
-                        );
-                        scope->set_category(catname_catptr[category_id]);
-                    }
-                    res.set_category(upstream_reply->lookup_category(cat_id));
-                }
-                else
-                {
-                    qDebug() << "==== CATREG. uses FIRST result. FIRST result. NO LINK to child ";
-                    if (!upstream_reply->lookup_category(cat_id))
-                    {
-                        catname_catptr[category_id] = upstream_reply->register_category
-                        (
-                            cat_id,
-                            cat_title,
-                             "",
-                            us::CategoryRenderer(rdr)
-                        );
-                        scope->set_category(catname_catptr[category_id]);
-                    }
-                    res.set_category(upstream_reply->lookup_category(cat_id));
-                    }
-            }
-            else if ( categoryId_isSecondResult[category_id] )// second result
-            {
-                //categoryId_isSecondResult[category_id] = false;
-                qDebug() << "==== CATREG RESULT uses FIRST result is SECOND result: " << client.qstr(category_id);
-                // perform fallbacks, if any
-                if(!scope->surface_common_template_id().empty())
-                {
-                    std::string res_str = us::Variant(res.serialize()).serialize_json(); 
-                    auto change = this->client.check_result_fallbacks(res_str,
-                                                                      scope->surface_common_template_id(),
-                                                                      this->get_common_templates_fallbacks());
-
-                    if (!std::get<0>(change).empty())
-                    {
-                        res[std::get<0>(change)] = std::get<1>(change);
-                    }
-                }
-                if (!scope->surface_template().empty()) // keyword has declared cat renderer
-                {
-                    qDebug() << "==== CATREG RESULT uses FIRST result. is SECOND result. uses surface_renderer ";
-                    cat_id = category_id + ":category:uses-first-result:second-or-later-result:surface-rdr:surfacing:" + cat_title;
-                    rdr = scope->surface_template();
-                }
-                else // use result template
-                {
-                    qDebug() << "==== CATREG RESULT uses FIRST result. is SECOND result. NOT uses surface_template ";
-                    cat_id = category_id + ":category:uses-first-result:second-or-later-result:incoming-rdr:surfacing:" + cat_title;
-                    rdr = res.category()->renderer_template().data();
-                }
-                qDebug() << "==== CATREG. uses FIRST result. SECOND result. cat_id: " << client.qstr(cat_id);
-                if (!upstream_reply->lookup_category(cat_id))
-                {
-                    catname_catptr[category_id] = upstream_reply->register_category
-                    (
-                        cat_id,
-                        cat_title,
-                         "",
-                        us::CategoryRenderer(rdr)
-                    );
-                    scope->set_category(catname_catptr[category_id]);
-                }
-                res.set_category(upstream_reply->lookup_category(cat_id));
-            }
-        }
-    }
-    else // not search and does not use first result rdr
-    {
-        qDebug() << "==== CATREG RESULT not uses first result. res title: " << client.qstr(res["title"].get_string());
-        // if uses common template, perform fallbacks, if any
-        qDebug () << "==== CATREG RESULT not uses first result: common id" << client.qstr(scope->surface_common_template_id());
-        if(!scope->surface_common_template_id().empty())
-        {
-            qDebug() << "==== surface check FALLB. scope->surface_common_template_id():" << client.qstr(scope->surface_common_template_id());
-            std::string res_str = us::Variant(res.serialize()).serialize_json(); 
-            auto change = this->client.check_result_fallbacks(res_str,
-                                                              scope->surface_common_template_id(),
-                                                              this->get_common_templates_fallbacks());
-            if (!std::get<0>(change).empty())
-            {
-                res[std::get<0>(change)] = std::get<1>(change);
-            }
-        }
-        if (!scope->surface_template().empty())// has a decared surface template
-        {
-            qDebug() << "==== CATREG RESULT not uses first result. uses surface template";
-            cat_id = scope->category_id() + ":category:not-uses-first-result:surface-rdr:surfacing:" + cat_title;
-            rdr = scope->surface_template();
-        }
-        else // use result template
-        {
-            qDebug() << "==== CATREG RESULT not uses first result. NOT uses result template";
-            cat_id = scope->category_id() + ":category:not-uses-first-result:incoming-rdr:surfacing:" + cat_title;
-            rdr = res.category()->renderer_template().data();
-        }
-        qDebug() << "== rdr: " << client.qstr(rdr);
-        if (catname_catptr.find(category_id) == catname_catptr.end())
-        {
-            qDebug() << "==== CATREG RESULT not uses first result. category not found in catname_catptr";
-            if (categoryId_linkToChildSpecified.find(scope->category_id()) != categoryId_linkToChildSpecified.end())
-            {
-                qDebug() << "==== CATREG RESULT not uses first result. category not found in catname_catptr. is link to child";
-                if (!upstream_reply->lookup_category(cat_id))
-                {
-                    qDebug() << "==== CATREG RESULT not uses first result. category not found in catname_catptr. is link to child. category not found on lookup";
-                    catname_catptr[category_id] = upstream_reply->register_category
-                    (
-                        cat_id,
-                        cat_title,
-                         "",
-                        us::CannedQuery(categoryId_linkToChildSpecified[scope->category_id()]),
-                        us::CategoryRenderer(rdr)
-                    );
-                }
-                res.set_category(upstream_reply->lookup_category(cat_id));
-            }
-            else
-            {
-                qDebug() << "==== CATREG RESULT not uses first result. category not found in catname_catptr. not link to child";
-                if (!upstream_reply->lookup_category(cat_id))
-                {
-                    qDebug() << "==== CATREG RESULT not uses first result. category not found in catname_catptr.  not link to child. category not found on lookup";
-                    catname_catptr[category_id] = upstream_reply->register_category
-                    (
-                        cat_id,
-                        cat_title,
-                         "",
-                        us::CategoryRenderer(rdr)
-                    );
-                }
-                res.set_category(upstream_reply->lookup_category(cat_id));
-            }
-        }
-        else // category is found so use it
-            res.set_category(catname_catptr[category_id]);
-        qDebug() << "==== CATREG RESULT not uses first result. cat_id" << client.qstr(cat_id);
-    }
-}
-
-void Query::handle_declared_child(unity::scopes::SearchReplyProxy const& upstream_reply,
-                                 std::shared_ptr<AggChildScope> scope,
-                                 us::CategorisedResult & res,
-                                 std::string const& inc_res_cat_id,
-                                 std::string const& inc_res_cat_title) {
-
-    // for use in category registration
-    std::string cat_id;
-    std::string cat_title;
-    std::string rdr;
-
-    qDebug() << "==== DECLARED. scope is declared: " << client.qstr(scope->local_id());
-    bool set_declared_category = false;
-
-    // if child_category set, filter out others by adding "dont_use" key to result
-    // also impose max category results if set
-    qDebug() << QString("=== DECLARED: child_categpry: %1").arg(client.qstr(scope->child_category()));
-    qDebug() << QString("=== DECLARED: inc_res_cat_id: %1").arg(client.qstr(inc_res_cat_id));
-    if (!scope->child_category().empty())
-    {
-        if (client.qstr(inc_res_cat_id) != client.qstr(scope->child_category()))
-        {
-            res["dont_use"] = "true";
-        }
-        else if (scope->using_child_category_max_results())
-        {
-            scope->inc_result_idx(); // allows constraining num results to child_category_max_results declaration
-            if (scope->result_idx() > scope->child_category_max_results() )
-            {
-                res["dont_use"] = "true";
-            }
-        }
-    }
-
-    // set the category tiile
-    if (scope->using_category_title_incoming() )
-    {
-        scope->set_category_title(inc_res_cat_title);
-    }
-    else if (scope->using_category_title_display_name() )
-    {
-        scope->set_category_title(scope->metadata()->display_name());
-    }
-
-    cat_title = scope->category_title();
-
-    // dont search of incoming renderer when searching
-    if (!query().query_string().empty())
-    {
-        set_declared_category = true;
-        if (!scope->search_template().empty())
-        {
-            qDebug() << "==== DECLARED FIRST RESULT: SEARCH using search renderer";
-            cat_id = scope->local_id() + ":declared:search-rdr:searching:" + cat_title;
-            rdr = scope->search_template();
-        }
-        else
-        {
-            qDebug() << "==== DECLARED FIRST RESULT: SEARCH using incoming result renderer";
-            cat_id = scope->local_id() + ":declared:incomiing_rdr:searching:" + cat_title;
-            rdr = res.category()->renderer_template().data();
-        }
-        scope->set_category_id(cat_id);
-    }
-    else if (scope->is_first_result())
-    {
-        qDebug() << "==== DECLARED FIRST RESULT for scope: " << client.qstr(scope->local_id());
-        scope->set_is_first_result(false);
-        scope->set_is_second_result(true);
-        set_declared_category = true;
-
-        cat_id = scope->id() + ":declared_default" + cat_title;
-        if (first_result_owner.empty() || first_result_owner == scope->id())
-        {
-            first_result_owner = scope->id();
-            if (!scope->first_result_template().empty())
-            {
-                qDebug() << "==== DECLARED FIRST RESULT: using first result template";
-                cat_id = scope->local_id() + ":declared:first-result:first-result-rdr:surfacing:" + cat_title;
-                rdr = scope->first_result_template();
-            }
-            else if (!scope->surface_template().empty())
-            {
-                cat_id = scope->local_id() + ":declared:first-result:surface-rdr:surfacing:" + cat_title;
-                rdr = scope->surface_template();
-                qDebug() << "==== DECLARED FIRST RESULT: using surface template";
-            }
-            else
-            {
-                cat_id = scope->local_id() + ":declared:first-result:incoming-rdr:surfacing:" + cat_title;
-                rdr = res.category()->renderer_template().data();
-                qDebug() << "==== DECLARED FIRST RESULT: using incoming template";
-            }
-        }
-        else if (!scope->surface_template().empty())
-        {
-            cat_id = scope->local_id() + ":declared:first-result:first-result-owner:surface-rdr:surfacing:" + cat_title;
-            rdr = scope->surface_template();
-            qDebug() << "==== DECLARED FIRST RESULT: first-result-ownwer. using surface template";
-        }
-        else
-        {
-            cat_id = scope->local_id() + ":declared:first-result:first-result-owner:incoming-rdr:surfacing:" + cat_title;
-            rdr = res.category()->renderer_template().data();
-        }
-        scope->set_category_id(cat_id);
-    }
-    else if( //second result but not using different renders for first result vs rest of the results
-        scope->is_second_result()
-        && scope->first_result_template().empty()
-        )
-    {
-        qDebug() << "==== DECLARED SECOND RESULT (not using first/rest renderers) for scope: " << client.qstr(scope->local_id());
-        scope->set_is_first_result(false);
-        scope->set_is_second_result(false);
-        set_declared_category = false;
-    }
-    else if( //second result and using different renderers for first result vs rest of the results
-        scope->is_second_result()
-        && !scope->first_result_template().empty()
-        )
-    {
-        qDebug() << "==== DECLARED SECOND RESULT (using first/rest renderers) for scope: " << client.qstr(scope->local_id());
-        scope->set_is_first_result(false);
-        scope->set_is_second_result(false);
-        set_declared_category = true;
-
-        if (scope->using_category_title_incoming() )
-        {
-            scope->set_category_title(inc_res_cat_title);
-        }
-        else if (scope->using_category_title_display_name() )
-        {
-            scope->set_category_title(scope->metadata()->display_name());
-        }
-
-        cat_title = scope->category_title();
-
-        if (scope->category_link_to_child())
-        {
-            if (query().query_string().empty()) // surfacing
-            {
-                if (scope->override_surface_template()) // use declared renderer
-                {
-                    cat_id = scope->local_id() + ":declared:not-first-result:link:surface-rdr:surfacing:" + cat_title;
-                    rdr = scope->surface_template();
-                    qDebug() << "=== rdr: " << QString::fromStdString(rdr);
-                }
-                else // use incoming renderer
-                {
-                    cat_id = scope->local_id() + ":declared:not-first-result:link:incoming-rdr:surfacing:" + cat_title;
-                    rdr = res.category()->renderer_template().data();
-                }
-            }
-            else // user is searching
-            {
-                if (scope->override_search_template())
-                {
-                    cat_id = scope->local_id() + ":declared:not-first-result:link:search-rdr:searching:" + cat_title;
-                    rdr = scope->search_template().data();
-                }
-                else
-                {
-                    cat_id = scope->local_id() + ":declared:not-first-result:link:incoming-rdr:searching:" + cat_title;
-                    rdr = res.category()->renderer_template().data();
-                }
-            }
-        }
-        else // no category link to child
-        {
-            if (query().query_string().empty())
-            {
-                if (scope->override_surface_template())
-                {
-                    cat_id = scope->local_id() + ":declared:nolink:surface-rdr:surfacing:" + cat_title;
-                    rdr = scope->surface_template().data();
-                    qDebug() << QString("=== rdr: %1").arg(client.qstr(rdr));
-                }
-                else if (!scope->first_result_template().empty())
-                {
-                    cat_id = scope->local_id() + ":declared:nolink:incoming-rdr:surfacing:" + cat_title;
-                    rdr = res.category()->renderer_template().data();
-                }
-            }
-            else
-            {
-                if (scope->override_search_template())
-                {
-                    cat_id = scope->local_id() + "declared:nolink:search-rdr:searching:" + cat_title;
-                    rdr = scope->search_template().data();
-                }
-                else
-                {
-                    cat_id = scope->local_id() + "declared:nolink:incoming-rdr:searching:" + cat_title;
-                    rdr = res.category()->renderer_template().data();
-                }
-            }
-        }
-    }
-    if (set_declared_category)
-    { //category needs to be registered
-        qDebug() << "==== DECLARED. set_declared_category";
-        // if needed, get renderer from result_category_to_common_template
-        if (common_templates.find(child_scopes_m[scope->local_id()]->result_category_id_to_common_template[res.category()->id()]) != common_templates.end())
-        {
-            qDebug() << "==== DECLARED. current category:" << client.qstr(res.category()->id());
-            std::string common_template_id = child_scopes_m[scope->local_id()]->result_category_id_to_common_template[res.category()->id()];
-            qDebug() << "==== DECLARED. using common_template_id: " << client.qstr(common_template_id);
-            std::string cat_id = common_template_id + ":" + scope->local_id() + cat_title;
-
-            // if the common category has not yet been registered, register it
-            if (!upstream_reply->lookup_category(cat_id))
-            {
-                std::string template_to_use = common_templates[child_scopes_m[scope->local_id()]->result_category_id_to_common_template[res.category()->id()]];
-                std::string res_str = us::Variant(res.serialize()).serialize_json(); 
-                auto change = this->client.check_result_fallbacks(res_str,
-                                                                  scope->surface_common_template_id(),
-                                                                  this->get_common_templates_fallbacks());
-                if (!std::get<0>(change).empty())
-                {
-                    res[std::get<0>(change)] = std::get<1>(change);
-                }
-                if (scope->category_link_to_child())
-                {
-                    if (!upstream_reply->lookup_category(cat_id))
-                    {           
-                        registered_common_categories[cat_id] = upstream_reply->register_category(cat_id, scope->category_title(), "",
-                                                   us::CannedQuery(scope->id(), query().query_string(), scope->child_department()),
-                                                   us::CategoryRenderer(template_to_use));
-                    }
-                    res.set_category(upstream_reply->lookup_category(cat_id));
-                }
-                else
-                {
-                    if (!upstream_reply->lookup_category(cat_id))
-                    {           
-                        registered_common_categories[cat_id] = upstream_reply->register_category(cat_id, scope->category_title(), "", us::CategoryRenderer(template_to_use));
-                    }
-                    res.set_category(upstream_reply->lookup_category(cat_id));
-                }
-            }
-        }
-        else
-        {
-            qDebug() << "=== DECLARED set_declared_category is TRUE. cat_id: " << client.qstr(cat_id);
-            if (!rdr.empty()) // should not ever be empty!
-            {
-                if (!upstream_reply->lookup_category(cat_id))
-                {
-                    qDebug() << "=== DECLARED set_declared_category is TRUE -- lookup cat not found: " << client.qstr(cat_id);
-                    if (scope->category_link_to_child())
-                    {
-                        qDebug() << "=== DECLARED set_declared_category is TRUE -- link to child ";
-                        auto cat = upstream_reply->register_category
-                        (
-                           cat_id,
-                           cat_title,
-                           "",
-                           us::CannedQuery(scope->id(), query().query_string(), scope->child_department()),
-                           us::CategoryRenderer(rdr)
-                        );
-                        scope->set_category(cat);
-                        scope->set_category_id(cat_id);
-                    } 
-                    else
-                    {
-                        qDebug() << "=== DECLARED set_declared_category is TRUE -- NOT link to child . RDR:" << client.qstr(rdr);
-                        auto cat = upstream_reply->register_category
-                        (
-                           cat_id,
-                           cat_title,
-                           "",
-                           us::CategoryRenderer(rdr)
-                        );
-                        scope->set_category(cat);
-                        scope->set_category_id(cat_id);
-                   }
-                }
-                res.set_category(upstream_reply->lookup_category(cat_id));
-            }
-        }
-    }
-    else // category already registered, so get it and set remember its id
-    {
-        res.set_category(upstream_reply->lookup_category(scope->category_id()));
-        scope->set_category_id(scope->category_id());
-    }
-
-    //for child scopes that declare attribute swaps, do them
-    for (std::shared_ptr<std::pair<std::string,std::string>> swap : this->child_scopes_m[scope->local_id()]->swap_result_attributes)
-    {
-        qDebug() << "==== trying to swap attributes";
-        try
-        {
-            if (!res[swap->first].get_string().empty())
-            {
-                qDebug() << "==== swap first: " << client.qstr(swap->first);
-                res[swap->second] = res[swap->first];
-            }
-        }
-        catch (unity::LogicException)
-        {
-            qDebug() << "==== failed to swap attributes";
-            qWarning() << QString("Scope %1 result does not contain attribute 2").arg(client.qstr(scope->local_id()), client.qstr(swap->second));
-        }
-    }
-}