diff --git a/docs/_includes/nav.html b/docs/_includes/nav.html index 1baeea757..f3bc2a142 100644 --- a/docs/_includes/nav.html +++ b/docs/_includes/nav.html @@ -16,6 +16,7 @@

API

Guides

Access Policies Search Filters + Catalog Search View Cesium Map

Help

diff --git a/docs/guides/catalog-view-config.md b/docs/guides/catalog-view-config.md new file mode 100644 index 000000000..78ffdb65e --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/guides/filters/configuring-filters.md b/docs/guides/filters/configuring-filters.md index ee3c0152f..65b54a00d 100644 --- a/docs/guides/filters/configuring-filters.md +++ b/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: diff --git a/docs/guides/index.md b/docs/guides/index.md index 34772f12a..868e856a5 100644 --- a/docs/guides/index.md +++ b/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:metacat-dev@ecoinformatics.org) or join us on [Slack](https://slack.dataone.org/) and we'll add it. +of your MetacatUI application. -- Access Policies -- Search Filters -- Cesium Map +- đŸ‘Ĩ Access Policies +- 🔎 Search Filters +- 📑 Catalog Search View +- 🌎 Cesium Map +- 📍 Cesium Map for Portals + +ℹī¸ Is something missing? [Email us](mailto:metacat-dev@ecoinformatics.org) or join us on [Slack](https://slack.dataone.org/) and we'll add it! \ No newline at end of file diff --git a/docs/guides/maps/cesium-for-portals.md b/docs/guides/maps/cesium-for-portals.md new file mode 100644 index 000000000..53f6c4e60 --- /dev/null +++ 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 `