Merge branch 'develop'

docs/getting_started/sample_scenarios.md

@@ -1,27 +1,13 @@
 # Sample scenarios
 
-Wondering what you can do with this solution? Here are some demo videos of common usage scenarios for the Data Visualizer solution. 
+Wondering what you can do with this solution? Here are some demo videos and tutorials of common usage scenarios for the Data Visualizer solution. 
 
-## Build a complete search center
-
-In this demo video, we show you how to create a complete search center in a SharePoint page using the full solution Web Parts set (Search Box, Data Filters, Data Visualizer and Data Verticals). This is a typical scenario when you want to bypass the OOTB SharePoint search page limitations and integrate with your own information architecture.
-
-<iframe width="560" height="315" src="https://www.youtube.com/embed/EECqOBWq3wo" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-
-## Build a people directory using the Microsoft Graph data source
-
-A classic use case in a SharePoint portal. This time, instead using the SharePoint search, we use the Microsoft Graph and the [People API](https://docs.microsoft.com/en-us/graph/people-example#search-people) to lookup relevant people based on search box Web Part input keywords.
-
-<iframe width="560" height="315" src="https://www.youtube.com/embed/yKkMavHAMHs" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-
-## Use static taxonomy filters with the SharePoint search data source
-
-Static filters don't necessarily need to be connected to a Data Visualizer Web Part. They are different from ['Refinement' filters](https://aequos-solutions.github.io/modern-data-visualizer/usage/data-filters/#filter-types-static-filter-versus-refiner-filter) and they just send abitrary filter values to consumer Web Parts ignoring received values from the data source. In this demo, we show you a practical use case and how to use them, for instance retrieve data from the SharePoint search according to a specific taxonomy term in a specific terms set **without any prior results fetched** (meaning filter values will be available at page load for initial filtering).
-
-<iframe width="560" height="315" src="https://www.youtube.com/embed/udEq2n9bqlo" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-
-> Static filters can be used in [tokens](../usage/data-visualizer/tokens.md) as well for other data sources. 
+- [Build a complete search center](./tutorials/build_complete_search_center.md)
+- [Build a people directory using the Microsoft Graph data source](./tutorials/build_people_directory_graph.md)
+- [Build a people directory using alphabetical verticals and SharePoint Search data source](./tutorials/build_people_directory_sharepoint_search.md)
+- [Use static taxonomy filters with the SharePoint search data source](./tutorials/static_taxonomy_filters_sharepoint_search.md)
 
+> You can see all these videos on our [official Youtube channel](https://www.youtube.com/channel/UCzwqxmUUKF6dv-f0YhdiIsg/)!
 
 
 

docs/getting_started/tutorials/build_complete_search_center.md

@@ -0,0 +1,7 @@
+# Build a complete search center
+
+In this tutorial video, we show you how to create a complete search center in a SharePoint page using the full solution Web Parts set (Search Box, Data Filters, Data Visualizer and Data Verticals). This is a typical scenario when you want to bypass the OOTB SharePoint search page limitations and integrate with your own information architecture.
+
+## Video tutorial
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/EECqOBWq3wo" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

docs/getting_started/tutorials/build_people_directory_graph.md

@@ -0,0 +1,7 @@
+# Build a people directory using alphabetical verticals and SharePoint Search data source
+
+A classic use case in a SharePoint portal. This time, instead using the SharePoint search, we use the Microsoft Graph and the [People API](https://docs.microsoft.com/en-us/graph/people-example#search-people) to lookup relevant people based on search box Web Part input keywords.
+
+## Video tutorial
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/yKkMavHAMHs" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

docs/getting_started/tutorials/build_people_directory_sharepoint_search.md

@@ -0,0 +1,49 @@
+# Build a people directory using alphabetical verticals and SharePoint Search data source
+
+This tutorial gives you basic steps to achieve a people directoy using alphabetical letters and the SharePoint search data source:
+
+## Video tutorial
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/SLbXneP3b6I" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+## Step-by-step tutorial
+
+1. Add the _'Data Verticals'_ Web Part on the page.
+
+    !["Data Verticals - Add"](../../assets/scenarios/people_directory1.png){: .center} 
+
+1. For each alphabetical letter, add and configure a new vertical. As the value use `<Letter> + *`. Example `A*` for letter **'A'**. You can also add an **'All'** tab by specifying `*` as value.
+
+    !["Data Verticals - Configuration"](../../assets/scenarios/people_directory2.png){: .center} 
+
+1. Add a new _'Data Visualizer'_ Web Part on the page.
+
+    !["Data Visualizer - Add"](../../assets/scenarios/people_directory3.png){: .center} 
+
+1. Select the _'SharePoint Search'_ data source.
+
+    !["Data Visualizer - Select Data Source"](../../assets/scenarios/people_directory4.png){: .center} 
+
+1. In the _'Connections'_ property pane configuration page, connect the _'Data Verticals'_ Web Part previously added. Select **all** the available tabs (i.e. letters). Basically it tells the Data Visualizer Web Part to be or remain visible when user clicks on any of these letters.
+
+    !["Data Visualizer - Configure Verticals"](../../assets/scenarios/people_directory5.png){: .center} 
+
+1. In _'Layouts'_ property pane configuration page, select the 'People' layout.
+
+    !["Data Visualizer - Select Layout"](../../assets/scenarios/people_directory6.png){: .center}
+
+    > Optionally, in the layout options, you can check _'Show persona card on hover'_ option. To get it work, [an administrator needs to approve required API permissions](../../installation).
+
+    !["Data Visualizer - Show persona card"](../../assets/scenarios/people_directory8.png){: .center}
+
+1. In the _'Data source'_ property pane configuration page, select the _'LocalPeopleResults'_ **Result Source** and update the **Query Template** property with the `{searchTerms} FirstName:{verticals.value}` expression. 
+
+    !["Data Visualizer - Configure data source"](../../assets/scenarios/people_directory7.png){: .center}
+
+    > This expression is given as an example. You can use the `{verticals.value}` token anywhere in the query according to your requirements. The value will be simply replaced dynamically.
+
+1. Save your page. You can now filter people based on alphabetical letters using their first name.
+
+    !["Data Visualizer - Final result"](../../assets/scenarios/people_directory9.png){: .center}
+
+    > You can then add a _'Search Box'_ or _'Data Filters'_ Web Parts to complete the experience.

docs/getting_started/tutorials/static_taxonomy_filters_sharepoint_search.md

@@ -0,0 +1,9 @@
+# Use static taxonomy filters with the SharePoint search data source
+
+Static filters don't necessarily need to be connected to a Data Visualizer Web Part. They are different from ['Refinement' filters](https://aequos-solutions.github.io/modern-data-visualizer/usage/data-filters/#filter-types-static-filter-versus-refiner-filter) and they just send abitrary filter values to consumer Web Parts ignoring received values from the data source. In this demo, we show you a practical use case and how to use them, for instance retrieve data from the SharePoint search according to a specific taxonomy term in a specific terms set **without any prior results fetched** (meaning filter values will be available at page load for initial filtering).
+
+## Video tutorial
+
+<iframe width="560" height="315" src="https://www.youtube.com/embed/udEq2n9bqlo" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+> Static filters can be used in [tokens](../usage/data-visualizer/tokens.md) as well for other data sources. 

docs/usage/data-verticals/index.md

@@ -12,15 +12,20 @@ The configuration of the 'Data Verticals' Web Part is fairly simple.
 
 !["Verticals configuration"](../../assets/webparts/data_verticals/configure_verticals.png){: .center} 
 
+
+### Configure verticals
+
 The options for a vertical are as follow:
 
 | **Setting** | **Description** |
 |------------|-----------------|
-| **Tab Name** | The vertical name (i.e. tab) 
-| **Office UI Fabric icon name** | The optional Office UI fabric icon to display for the tab. Refer to [Office UI Fabric documentation](https://developer.microsoft.com/en-us/fluentui#/styles/web/icons) to see all available icons.
+| **Tab name** | The vertical name (i.e. tab) 
+| **Tab value** | The vertical value that will be sent to connected 'Data Visualizer' Web Parts. You can use this value using the `{verticals.value}` token. See [tokens](../data-visualizer/tokens.md) for more info.
+| **Fluent UIFabric icon name** | The optional Fluent UI icon to display for the tab. Refer to [Office UI Fabric documentation](https://developer.microsoft.com/en-us/fluentui#/styles/web/icons) to see all available icons.
 | **Is hyperlink** | If checked, the tab will behave as an hyperlink meaning it won't trigger any selected event.
 | **Link URL** | If the tab is an hyperlink, the link URL to use. Tokens `{<TokenName>}` are supported here. See [tokens](../data-visualizer/tokens.md) for more info.
 | **Open behavior** | If the tab is an hyperlink, the opening behavior (new tab or current tab).
+| **Show link icon** |  If the tab is an hyperlink, display or hide an icon next to the tab name indicating the tab is a link (same page or external).
 
 > The 'Data Verticals' Web Part does not need to be connected to any Web Part. However, it is meant to be used by a 'Data Visualizer' Web Part to get it work. More info about configuration [here](../data-visualizer/connections/index.md).
 

docs/usage/data-visualizer/layouts/details-list.md

@@ -4,6 +4,6 @@ The 'details list' layout allows you to display items as a structured list, the
 
 | Setting | Description | Default value 
 | ------- |---------------- | ---------- |
-| **Manage columns** | Allows you to build you own table view by adding or removing columns dynamically. For each column, you get the following options:<br><p align="center">[!["Manage columns"](../../../assets/webparts/data_visualizer/layouts/details_list_fields.png)](../../../assets/webparts/data_visualizer/layouts/details_list_fields.png)</p><ul><li>**Sort order**: the order of the column in the table.</li><li>**Column name**: the column friendly name to display.</li><li>**Column value**: you can choose here either a field from the data source current results set (from the list or as free text) without any transformation or use an Handlebars expression by clicking on the checkbox next to it. In this case, all Handlebars helpers from the main template are available and you can also add you own HTML markup in the column value. For HTML fields you can use the special variable `@root.theme` to use theme colors (ex: `@root.theme.palette.themePrimary`).<br>![Handlebars Expression](../../../assets/webparts/data_visualizer/layouts/details_list_hb_expr.png)<br><br>![Handlebars Expression 2](../../../assets/webparts/data_visualizer/layouts/details_list_hb_expr2.png)</li><li>**Minimum width in px**: the minimum width of the column in pixels.</li><li>**Maximum width in px**: the maximum width of the column in pixels.</li><li>**Sortable**: allows you to sort column values alphabetically when the column header is clicked (ascending or descending). The sort is done statically on the current page results set.</li><li>**Resizable**: allows you to resize the column dynamically in display mode.</li><li>**Multiline**: if the column column should be multiline. By default only ellipsis (...) will be display for larger text.</li></ul>
+| **Manage columns** | Allows you to build you own table view by adding or removing columns dynamically. For each column, you get the following options:<br><p align="center">[!["Manage columns"](../../../assets/webparts/data_visualizer/layouts/details_list_fields.png)](../../../assets/webparts/data_visualizer/layouts/details_list_fields.png)</p><ul><li>**Sort order**: the order of the column in the table.</li><li>**Column name**: the column friendly name to display.</li><li>**Column value**: you can choose here either a field from the data source current results set (from the list or as free text) without any transformation or use an Handlebars expression by clicking on the checkbox next to it. In this case, all Handlebars helpers from the main template are available and you can also add you own HTML markup in the column value. For HTML fields you can use the special variable `@root.theme` to use theme colors (ex: `@root.theme.palette.themePrimary`).<br>![Handlebars Expression](../../../assets/webparts/data_visualizer/layouts/details_list_hb_expr.png)<br><br>![Handlebars Expression 2](../../../assets/webparts/data_visualizer/layouts/details_list_hb_expr2.png)</li><li>**Minimum width in px**: the minimum width of the column in pixels.</li><li>**Maximum width in px**: the maximum width of the column in pixels.</li><li>**Sortable**: allows you to sort column values alphabetically when the column header is clicked (ascending or descending). The sort is done statically on the current page results set and works only when the column value is not an Handlebars expression.</li><li>**Resizable**: allows you to resize the column dynamically in display mode.</li><li>**Multiline**: if the column column should be multiline. By default only ellipsis (...) will be display for larger text.</li></ul>
 | **Show file icon** | Hide or display the file icon in the first column.
 | **Compact mode** | Display the details list in compact mode.

docs/usage/data-visualizer/tokens.md

@@ -20,6 +20,7 @@ You can use tokens in the following locations:
 
 - **Data Verticals Web Part**
     - In the link URL when the vertical item is a link.
+    - In the vertical tab value.
 
 #### Supported tokens (all data sources)
 
@@ -33,14 +34,17 @@ You can use tokens in the following locations:
 
 ##### Connections tokens
 
-Tokens related to connected Web Parts in the Data Visualizer.
+Tokens related to connected Web Parts in the Data Visualizer. 
+
+> These tokens can only be used in the 'Data Visualizer' Web Part.
 
 |**Token**|**Definition**|
 |:-----|:-----|
 |**{inputQueryText}**<br/> | The query value entered into a search box on a page. The value depends on the configuration of input text connection of the Data Visualizer Web Part. <br/> |
 |**{filters.&lt;FilterName&gt;}** | The current selected filters. You can use deep paths here to access properties. _'FilterName'_ corresponds to the filter name specified in the Data Filters Web Part (not the display name). Only single value taxonomy filters and data range filters are supported. For date range filters you can access start/end date values (as ISO8601 strings) using `{filters.MyDateRangeFilter.startDate}` or `{filters.MyDateRangeFilter.endDate}`. For taxonomy filters, the token `{filters.MyTaxonomyFilter}` will return the taxonomy item ID currently selected.
-|**{itemsCountPerPage}** | The number of items count per page configured in teh Web Part. Useful for the OData source to specify a `$top={itemsCountPerPage}` parameter.
+|**{itemsCountPerPage}** | The number of items count per page configured in the 'Data Visualizer' Web Part. Useful for the OData source to specify a `$top={itemsCountPerPage}` parameter.
 |**{startRow}** | The next start row number according to current paging. Useful for the OData source to specify a `$skipToken={startRow}` or `$skip={startRow}` parameters.
+|**{verticals.&lt;value\|name&gt;}** | If connected, get the current selected vertical tab name or associated value.
 
 ##### Context tokens
 
@@ -103,3 +107,14 @@ To deal with mutli valued properties (like taxonomy multi or choices SharePoint
 - Using a page multi values choice property: `{|RefinableStringXX:{Page.myChoiceMultiColumn}}`
 
 At any time, you can see the resolved query using the 'Debug' layout an inspecting the `data.queryModification` property.
+
+
+#### OData Data Source default URL syntax
+
+The OData Data source supports a special URL syntax allowing to execute a specifc part of that URL only during the first execution by using `{{` and `}}` enclosing characters sequence. This could be convenient for an URL containing dynamic OData filter conditions like `$filter=startswith(MyField,'{inputQueryText'}` that may be invalid due to incorrect or unavailable values during first load resulting of API error.
+
+Example:
+
+!["Default URL for OData data source"](../../assets/webparts/data_visualizer/odata/default_url.png){: .center}
+
+In this example, `{{/me/people}}` means only `/me/people` part of the URL will be executed during the first load,, retrieving the all list of users without any condition. However, on subsequent requests, the complete URL `/me/people?search={inputQueryText}}` will be executed with the correct token values.

extensibility-library-demo/.yo-rc.json

@@ -3,8 +3,8 @@
     "packageManager": "pnpm",
     "isCreatingSolution": true,
     "environment": "spo",
-    "version": "1.9.1",
-    "libraryName": "aequos-extensibility-starter",
+    "version": "1.11.0",
+    "libraryName": "aequos-extensibility-demo",
     "libraryId": "4896309f-54bc-48f2-a7ee-0785e019d195",
     "isDomainIsolated": false,
     "componentType": "library"

extensibility-library-demo/config/package-solution.json

@@ -1,14 +1,21 @@
 {
-  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
-  "solution": {
-    "name": "aequos - Extensibility Library Demo",
-    "id": "4896309f-54bc-48f2-a7ee-0785e019d195",
-    "version": "1.0.0.0",
-    "includeClientSideAssets": true,
-    "skipFeatureDeployment": true,
-    "isDomainIsolated": false
-  },
-  "paths": {
-    "zippedPackage": "solution/aequos-extensibility-demo.sppkg"
-  }
-}
+    "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
+    "solution": {
+        "name": "aequos - Extensibility Library Demo",
+        "id": "4896309f-54bc-48f2-a7ee-0785e019d195",
+        "version": "1.2.0.0",
+        "includeClientSideAssets": true,
+        "skipFeatureDeployment": true,
+        "isDomainIsolated": false,
+        "developer": {
+            "mpnId": "",
+            "name": "Franck Cornu",
+            "privacyUrl": "",
+            "termsOfUseUrl": "",
+            "websiteUrl": "www.aequos.ca"
+        }
+    },
+    "paths": {
+        "zippedPackage": "solution/aequos-extensibility-demo.sppkg"
+    }
+}