Merge pull request #2127 from NCEAS/feature-#1720-cesium-data-catalog

New CatalogSearchView with configurable filters & Cesium map

docs/_includes/nav.html

@@ -16,6 +16,7 @@ <h2>API</h2>
   <h2>Guides</h2>
   <a href="{{ site.url }}/guides/accesspolicy.html">Access Policies</a>
   <a href="{{ site.url }}/guides/filters/configuring-filters.html">Search Filters</a>
+  <a href="{{ site.url }}/guides/catalog-view-config">Catalog Search View</a>
   <a href="{{ site.url }}/guides/maps/cesium.html">Cesium Map</a>
 
   <h2>Help</h2>

docs/guides/catalog-view-config.md

@@ -0,0 +1,32 @@
+---
+layout: guide
+title: Configuring the Catalog Search View
+id: catalog-view-config
+toc: true
+---
+
+This page provides instructions on how to customize a the main search page for a MetacatUI repository. This page is rendered by the Catalog Search View and includes a 3D map and a set of search filters. The map and filters can be set to suit the needs of the repository.
+
+The 3D map uses the `cesium.js` library. For more information about Cesium and how to configure a Cesium Map model in general, see the general [Cesium guide](/guides/maps/cesium.html).
+
+With the x.x.x release, MetacatUI introduced a new [`CatalogSearchView`](/docs/CatalogSearchView.html) that renders the main search page. This new view replaces the `DataCatalogView` that used Google Maps. The `DataCatalogView` will be deprecated in a future release, but to give time for repositories to migrate to the new `CatalogSearchView`, the `DataCatalogView` will remain the default view for the time being.
+
+To enable the new `CatalogSearchView`, set the following properties in your [configuration file](/docs/AppConfig.html):
+
+```js
+{
+  "useDeprecatedDataCatalogView": false,
+  "enableCesium": true,
+  "cesiumToken": "YOUR-CESIUM-ION-TOKEN"
+}
+```
+
+The `cesiumToken` only needs to be set in order to enable access to layers and assets from [Cesium Ion](https://cesium.com/learn/ion/global-base-layers/). See the general [Cesium guide](/docs/guides/maps/cesium) for more information.
+
+## Customizing the search filters
+
+The default filters to use on the left hand side of the Catalog Search View are set in the [`defaultFilterGroups`](/docs/AppConfig.html#defaultFilterGroups) property of the [configuration file](/docs/AppConfig.html). This property is an array of objects that define the filters to use. See the guide about [customizing search filters](/guides/filters/configuring-filters.html) for more information.
+
+## Map config
+
+Options for Search View's map are set in the [`catalogSearchMapOptions`](docs/AppConfig.html#catalogSearchMapOptions) property of the [configuration file](/docs/AppConfig.html). This property is the same object used to define any `Map` model in MetacatUI. See the API docs for [`Map`](/docs/MapConfig.html) for complete documentation of the options.

docs/guides/filters/configuring-filters.md

@@ -1,15 +1,39 @@
 ---
 layout: guide
-title: Configuring custom filters
+title: 🔎 Configuring Search Filters
 id: configuring-filters
 ---
 
-## How to hide a field from the custom filter builder
+## Search Filters
+
+In MetacatUI, search filters are models that define a Solr field, values to use in a query for that field, and options for how to display the filter in the UI. Filters are used in the [`CatalogSearchView`](/docs/CatalogSearchView.html) and the [`PortalDataView`](/docs/PortalDataView.html).
+
+Filters which are combined to create a collection of data for a Portal can be built interactively using the [`QueryBuilderView`](/docs/QueryBuilderView.html) in the Portal Editor.
+
+Custom search filters which users can use to subset a collection of portal data further can be designed and added to the portal in [`FilterEditorView`](/docs/FilterEditorView.html) in the Portal Editor.
+
+Filters that are displayed in the repository-level `CatalogSearchView` are configured in the repository's [`config`](/docs/AppModel.html) file. See the [`Catalog Search View`](/guides/catalog-view-config.html) guide for more information.
+
+## The parts of a filter model
+
+Filters are defined in the [collections and portals XML schema repo](https://github.com/DataONEorg/collections-portals-schemas). See the [`FilterType`](https://github.com/DataONEorg/collections-portals-schemas/blob/48db8394506f5523597def6c9212aea3bfdee103/schemas/collections.xsd#L152-L210) to learn about the most essential parts of a filter model.
+
+Filters are represented in MetacatUI by the [`Filter`](/docs/Filter.html) model and all of it's extended types.
+
+### Filter groups
+
+Filters can be grouped to create nested queries such as `((field1:value1 OR field1:value2) AND field2:value3)`. They can also be grouped to display related filters together in the UI. See the [`FilterGroup`](/docs/FilterGroup.html) model for more information.
+
+## Custom Search Filters in Portals
+
+This section gives information on how to configure the options that are available for users to create custom search filters in the [`CustomFilterBuilderView`](/docs/CustomFilterBuilderView.html) in the Portal Editor.
+
+### How to hide a field from the custom filter builder
 
 Add the Solr field name to [`AppConfig.collectionQueryExcludeFields`](https://nceas.github.io/metacatui/docs/AppConfig.html#collectionQueryExcludeFields). This will also hide the field from the Query Builder.
 
 
-## Adding a new Solr field to the custom filter builder
+### Adding a new Solr field to the custom filter builder
 
 When a new Solr field is added to the Solr schema, it will automatically get added to the `General`, or default, category in the custom filter builder and it can be used with any filter type (free text, dropdown, year slider, etc). There are several places to configure the Solr field so that it works as intended:
 

docs/guides/index.md

@@ -1,8 +1,12 @@
 # MetacatUI Guides
 
 The following is a list of How To guides for customizing the display and functionality
-of your MetacatUI application. Is something missing? [Email us](mailto:[email protected]) or join us on [Slack](https://slack.dataone.org/) and we'll add it.
+of your MetacatUI application.
 
-- <a href="{{ site.url }}/guides/accesspolicy.html">Access Policies</a>
-- <a href="{{ site.url }}/guides/filters/configuring-filters.html">Search Filters</a>
-- <a href="{{ site.url }}/guides/maps/cesium.html">Cesium Map</a>
+- <a href="{{ site.url }}/guides/accesspolicy.html">👥 Access Policies</a>
+- <a href="{{ site.url }}/guides/filters/configuring-filters.html">🔎 Search Filters</a>
+- <a href="{{ site.url }}/guides/catalog-view-config.html">📑 Catalog Search View</a>
+- <a href="{{ site.url }}/guides/maps/cesium.html">🌎 Cesium Map</a>
+- <a href="{{ site.url }}/guides/maps/cesium-for-portals.html">📍 Cesium Map for Portals</a>
+
+<b>ℹ️ Is something missing? [Email us](mailto:[email protected]) or join us on [Slack](https://slack.dataone.org/) and we'll add it!</b>

docs/guides/maps/cesium-for-portals.md

@@ -0,0 +1,41 @@
+---
+layout: guide
+title: Configuring Cesium Maps for Portals
+id: cesium-for-portals
+toc: true
+---
+
+This page outlines the process of integrating a Cesium Map into a [Portal document](https://github.com/DataONEorg/collections-portals-schemas/blob/master/schemas/portals.xsd).
+
+For background on Cesium, as well as detailed guidelines on how to customize a Cesium Map model, please refer to our [Cesium guide](cesium).
+
+## How to Configure a Cesium Map Section within a Portal Document
+
+To integrate a Cesium map visualization into a portal XML document, you need to define the map's appearance and layering structure using JSON. This JSON configuration is then embedded into an `<option>` element which lies within a `<section>` element. The `<option>` element requires two distinct components: an `<optionName>` set as `mapConfig` and an `<optionValue>` that encompasses the aforementioned JSON configuration. Please ensure that the JSON is enclosed within `CDATA` tags.
+
+Here's an example:
+
+```xml
+<section>
+  <label>My Cesium Map</label>
+  <title>My Cesium Map</title>
+  <option>
+    <optionName>sectionType</optionName>
+    <optionValue>visualization</optionValue>
+  </option>
+  <option>
+    <optionName>visualizationType</optionName>
+    <optionValue>cesium</optionValue>
+  </option>
+  <option>
+    <optionName>mapConfig</optionName>
+    <optionValue>
+<![CDATA[{
+  "homePosition": {...},
+  ... 
+  "showFeatureInfo": false
+}]]>
+      </optionValue>
+    </option>
+  </section>
+```

docs/guides/maps/cesium.md

@@ -8,44 +8,22 @@ toc: true
 <div style="display:grid; grid-template-columns:1fr 2fr">
 
   <div>
-    MetacatUI uses <a src="https://github.com/CesiumGS/cesium">CesiumJS</a> to create map visualization sections in Portals. Eventually, Cesium will also be used to optionally replace Google Maps in other parts of MetacatUI (follow progress in <a src="https://github.com/NCEAS/metacatui/issues/1720">GitHub issue #1720</a>). This guide summarizes the models, views, and collections that create and control the Cesium widget and the surrounding UI. This page also includes instructions on how to configure a Cesium Map in a Portal document.
+  <p>MetacatUI uses <a href="https://github.com/CesiumGS/cesium">CesiumJS</a> to create map visualization sections in <a href="https://www.dataone.org/plus/">Portals</a> and in the <a href="/docs/CatalogSearchView.html">Catalog Search</a>. This guide summarizes the models, views, and collections that create and control the Cesium widget and the surrounding UI.</p>
+
+  <p>For information on how to configure the Cesium map in portals, see <a href="{{site.url}}/guides/maps/cesium-for-portals">Cesium map for Portals</a>.</p>
+
+  <p>For information on how to configure the Cesium map in the Catalog Search, see <a href="{{site.url}}/guides/catalog-view-config">Catalog Search View Guide</a>.</p>
   </div>
-
-  <figure style="margin-top:-50px;">
+  <figure style="margin-top:-50px; ">
     <img src="{{site.url}}/screenshots/views/maps/MapView.png" style="width:100%; max-width:800px;"/>
     <figcaption>A screenshot of the <code>MapView</code>, which uses the <code>CesiumJS</code> library</figcaption>
   </figure>
 
 </div>
 
-## Views, models & collections
-
-In the [API Docs]({{site.url}}/docs/), views, models, and collections for the map are categorized under `Views/Maps`, `Models/Maps`, `Collections/Maps`, respectively. Models that contain information about map layers and terrain data are further grouped under `Models/Maps/Assets`.
-
-### Views
-
-Generally, the Map views are organized such that the `CesiumWidgetView` could be easily interchanged with some other map widget: The UI views like the `LayerDetailsView`, `ScalebarView`, etc., receive data from and send updates to the Map models independent of the `CesiumWidgetView`. For example, rather than `Cesium` directly updating the longitude and latitude in the `scaleBarView`, it instead updates the `Map` model's `currentPosition` attribute. The `MapView` listens to changes in `Map`'s `currentPosition` and then updates the `ScaleBarView` accordingly. If in the future the `CesiumWidgetView` is replaced with a new map widget, it would simply need to update the `Map.currentPosition` attribute and the `ScaleBarView` would work as it did before.
-
-<figure>
-  <a href="https://github.com/NCEAS/metacatui-design/raw/main/cesium/images/cesium-view.png"><img src="https://github.com/NCEAS/metacatui-design/raw/main/cesium/images/cesium-view.png" style="width:100%; max-width:1300px"/></a>
-  <figcaption>The views that build the CesiumWidget and the the UI surrounding it. From the <a href="https://github.com/NCEAS/metacatui-design">MetacatUI Design repo</a>.</figcaption>
-</figure>
-
+## Enabling Cesium
 
-### Models & collections
-
-All layer and and terrain models are extensions of the more generic `MapAsset` model, which comprises attributes that are common to most of the layer/terrain models. As with the views, models and collections are designed to be as independent from the `Cesium` widget as possible, with the exception of some of the terrain and layer models.
-
-#### Cesium asset models
-
-The [`Cesium3DTileset`]({{site.url}}/docs/Cesium3DTileset), [`CesiumVectorData`]({{site.url}}/docs/CesiumVectorData), [`CesiumImagery`]({{site.url}}/docs/CesiumImagery), and [`CesiumTerrain`]({{site.url}}/docs/CesiumTerrain) asset models are very closely tied to the `Cesium` architecture. Separating these `Cesium` assets from the `CesiumWidgetView` makes it easier to write new assets in the future, and keeps the `CesiumWidgetView` from becoming too expansive.
-
-All three of these Cesium asset models have the common `createCesiumModel()` function, which constructs the appropriate `cesiumModel` for the type, given the `cesiumOptions` set on the model. The `cesiumModel` is then used by the `CesiumWidgetView` to render the data on the map. In addition, the `type` attribute used in each of these asset models directly corresponds to the Cesium constructor function that creates the `cesiumModel`.
-
-<figure>
-  <a href="https://github.com/NCEAS/metacatui-design/raw/main/cesium/images/cesium-model.png"><img src="https://github.com/NCEAS/metacatui-design/raw/main/cesium/images/cesium-model.png" style="width:100%; max-width:1300px"/></a>
-  <figcaption>The models and collections that control the cesium map. From the <a href="https://github.com/NCEAS/metacatui-design">MetacatUI Design repo</a>.</figcaption>
-</figure>
+To enable Cesium for portals and/or for the data catalog, set the `enableCesium` property to true in your configuration file. To enable displaying [layers from Cesium Ion](https://cesium.com/learn/ion/global-base-layers/) in maps, the `cesiumToken` property must also be set to a Cesium Ion token. Sign up for a token [here](https://ion.cesium.com/signup/). This is optional, and by default, `NaturalEarthII` imagery will be displayed, even without a Cesium token.
 
 ## Configuration
 
@@ -267,42 +245,41 @@ Below is an example of a detailed map configuration (descriptions have been shor
 }
 ```
 
-### Configuring a Cesium Map section in a portal document
+## Views, models & collections
 
-To add a Cesium map visualization section to a portal document, cesium config json is added as an `option` within a `cesium` visualization section. Note that the JSON should be wrapped in `CDATA` tags.
+In the [API Docs]({{site.url}}/docs/), views, models, and collections for the map are categorized under `Views/Maps` , `Models/Maps` , `Collections/Maps` , respectively. Models that contain information about map layers and terrain data are further grouped under `Models/Maps/Assets` .
+
+### Views
+
+Generally, the Map views are organized such that the `CesiumWidgetView` could be easily interchanged with some other map widget: The UI views like the `LayerDetailsView` , `ScalebarView` , etc., receive data from and send updates to the Map models independent of the `CesiumWidgetView` . For example, rather than `Cesium` directly updating the longitude and latitude in the `scaleBarView`, it instead updates the `Map` model's `currentPosition` attribute. The `MapView` listens to changes in `Map` 's `currentPosition` and then updates the `ScaleBarView` accordingly. If in the future the `CesiumWidgetView` is replaced with a new map widget, it would simply need to update the `Map.currentPosition` attribute and the `ScaleBarView` would work as it did before.
+
+<figure>
+  <a href="https://github.com/NCEAS/metacatui-design/raw/main/cesium/images/cesium-view.png"><img src="https://github.com/NCEAS/metacatui-design/raw/main/cesium/images/cesium-view.png" style="width:100%; max-width:1300px"/></a>
+  <figcaption>The views that build the CesiumWidget and the the UI surrounding it. From the <a href="https://github.com/NCEAS/metacatui-design">MetacatUI Design repo</a>.</figcaption>
+</figure>
+
+### Models & collections
+
+All layer and and terrain models are extensions of the more generic `MapAsset` model, which comprises attributes that are common to most of the layer/terrain models. As with the views, models and collections are designed to be as independent from the `Cesium` widget as possible, with the exception of some of the terrain and layer models.
+
+#### Cesium asset models
+
+The [ `Cesium3DTileset` ]({{site.url}}/docs/Cesium3DTileset), [ `CesiumVectorData` ]({{site.url}}/docs/CesiumVectorData), [ `CesiumImagery` ]({{site.url}}/docs/CesiumImagery), and [ `CesiumTerrain` ]({{site.url}}/docs/CesiumTerrain) asset models are very closely tied to the `Cesium` architecture. Separating these `Cesium` assets from the `CesiumWidgetView` makes it easier to write new assets in the future, and keeps the `CesiumWidgetView` from becoming too expansive.
+
+All three of these Cesium asset models have the common `createCesiumModel()` function, which constructs the appropriate `cesiumModel` for the type, given the `cesiumOptions` set on the model. The `cesiumModel` is then used by the `CesiumWidgetView` to render the data on the map. In addition, the `type` attribute used in each of these asset models directly corresponds to the Cesium constructor function that creates the `cesiumModel` .
+
+<figure>
+  <a href="https://github.com/NCEAS/metacatui-design/raw/main/cesium/images/cesium-model.png"><img src="https://github.com/NCEAS/metacatui-design/raw/main/cesium/images/cesium-model.png" style="width:100%; max-width:1300px"/></a>
+  <figcaption>The models and collections that control the cesium map. From the <a href="https://github.com/NCEAS/metacatui-design">MetacatUI Design repo</a>.</figcaption>
+</figure>
 
-Example:
 
-```xml
-<section>
-  <label>My Cesium Map</label>
-  <title>My Cesium Map</title>
-  <option>
-    <optionName>sectionType</optionName>
-    <optionValue>visualization</optionValue>
-  </option>
-  <option>
-    <optionName>visualizationType</optionName>
-    <optionValue>cesium</optionValue>
-  </option>
-  <option>
-    <optionName>mapConfig</optionName>
-    <optionValue>
-<![CDATA[{
-  "homePosition": {...}
-      ..... 
-  "showFeatureInfo": false
-}]]>
-      </optionValue>
-    </option>
-  </section>
-```
 
 ## Useful links
 
-- [CesiumJS on GitHub](https://github.com/CesiumGS/cesium)
-- [CesiumJS website](https://cesium.com/platform/cesiumjs/) - Overview of Cesium, including information about Cesium Ion
-- [Cesium documentation](https://cesium.com/learn/cesiumjs/ref-doc/)
-- [Cesium sandcastle](https://sandcastle.cesium.com/) - For experimenting with Cesium, includes helpful examples and demos
-- [TerriaJS on GitHub](https://github.com/TerriaJS/terriajs) - a large application that also uses the CesiumWidget. Although Terria uses a customized and older version of Cesium, it can serve as a good reference.
-- [Planned features & known issues related to the Cesium Map in MetacatUI](https://github.com/NCEAS/metacatui/issues?q=is%3Aopen+is%3Aissue+label%3Acesium)
+* [CesiumJS on GitHub](https://github.com/CesiumGS/cesium)
+* [CesiumJS website](https://cesium.com/platform/cesiumjs/) - Overview of Cesium, including information about Cesium Ion
+* [Cesium documentation](https://cesium.com/learn/cesiumjs/ref-doc/)
+* [Cesium sandcastle](https://sandcastle.cesium.com/) - For experimenting with Cesium, includes helpful examples and demos
+* [TerriaJS on GitHub](https://github.com/TerriaJS/terriajs) - a large application that also uses the CesiumWidget. Although Terria uses a customized and older version of Cesium, it can serve as a good reference.
+* [Planned features & known issues related to the Cesium Map in MetacatUI](https://github.com/NCEAS/metacatui/issues?q=is%3Aopen+is%3Aissue+label%3Acesium)