Skip to content

Commit

Permalink
fix(masthead): new property for custom nav links (#10986)
Browse files Browse the repository at this point in the history 
### Related Ticket(s)

Closes #10984

### Description

The navigation data fetched from the translation files automatically replaces any custom navigation data passed in. This PR creates a new property `customNavLinks` that adopters will set the custom nav data to. 

### Changelog

**New**

- `customNavLinks` property to pass in custom nav links

**Changed**

- add checks to `masthead-composite` that will render the custom nav links over the default fetched data

<!-- React and Web Component deploy previews are enabled by default. -->
<!-- To enable additional available deploy previews, apply the following -->
<!-- labels for the corresponding package: -->
<!-- *** "test: e2e": Codesandbox examples and e2e integration tests -->
<!-- *** "package: services": Services -->
<!-- *** "package: utilities": Utilities -->
<!-- *** "RTL": React / Web Components (RTL) -->
<!-- *** "feature flag": React / Web Components (experimental) -->
  • Loading branch information
@annawen1
annawen1 authored Sep 30, 2023
1 parent 4dc0f91 commit b512715
Show file tree
Hide file tree
Showing 3 changed files with 146 additions and 89 deletions.
217 changes: 132 additions & 85 deletions packages/web-components/src/components/masthead/__stories__/README.stories.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
import { Preview, Props, Description, Story } from '@storybook/addon-docs/blocks';
import {
Preview,
Props,
Description,
Story,
} from '@storybook/addon-docs/blocks';
import contributing from '../../../../../../docs/contributing-license.md';
import { cdnJs, cdnCss } from '../../../globals/internal/storybook-cdn';



# Masthead

> The masthead component is a required navigational pattern for IBM.com that
Expand All @@ -23,6 +26,7 @@ import { cdnJs, cdnCss } from '../../../globals/internal/storybook-cdn';
[![Edit @carbon/ibmdotcom-web-components](https://codesandbox.io/static/img/play-codesandbox.svg)](https://githubbox.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/examples/codesandbox/components/masthead-l1)

## Getting Started

##### Note: Masthead uses the Carbon White theme by design. Using other themes will not change the Masthead color scheme.

### JS (via import)
Expand All @@ -49,19 +53,21 @@ import '@carbon/ibmdotcom-web-components/es/components/masthead/masthead-contain

#### Setting Platform URL

The `platformUrl` property accepts a single URL as string or an object with a specific URL for each locale.
This property has to be set via javascript.
The `platformUrl` property accepts a single URL as string or an object with a
specific URL for each locale. This property has to be set via javascript.

###### Setting a single platform URL:

```html
<dds-masthead-container platform="Lorem Ipsum" id="masthead-container"></dds-masthead-container>
<dds-masthead-container
platform="Lorem Ipsum"
id="masthead-container"></dds-masthead-container>
```

```javascript
const singleUrl = "https://www.example.com";
const singleUrl = 'https://www.example.com';

document.getElementById("masthead-container").platformUrl = singleUrl;
document.getElementById('masthead-container').platformUrl = singleUrl;
```

###### Setting multiple platform URLs with an object:
Expand All @@ -81,24 +87,29 @@ const urlObject = {
},
};

document.getElementById("masthead-container").platformUrl = urlObject;
document.getElementById('masthead-container').platformUrl = urlObject;
```

```html
<dds-masthead-container platform="Lorem Ipsum" id="masthead-container"></dds-masthead-container>
<dds-masthead-container
platform="Lorem Ipsum"
id="masthead-container"></dds-masthead-container>
```

#### Custom Navigation

In order to set custom navigation for the masthead, set the custom navigation
data to the `customNavLinks` property of the masthead-container component.

```javascript
const links = [...menu items...];
document.getElementById('masthead-container').navLinks = links;
document.getElementById('masthead-container').customNavLinks = links;
```

#### Using L1 nav

To use L1 nav, set `l1Data` prop. `l1Data` prop should be an
object that contains the navigation data of L1 nav:
To use L1 nav, set `l1Data` prop. `l1Data` prop should be an object that
contains the navigation data of L1 nav:

```javascipt
const l1Data = {
Expand All @@ -114,97 +125,116 @@ const l1Data = {
<dds-masthead-container id="masthead-container"></dds-masthead-container>
```

To set a custom endpoint for the translation service to fetch from, set either the `data-endpoint` attribute like below or `DDS_TRANSLATION_ENDPOINT` environment variable.
To set a custom endpoint for the translation service to fetch from, set either
the `data-endpoint` attribute like below or `DDS_TRANSLATION_ENDPOINT`
environment variable.

```html
<dds-masthead-container data-endpoint="/custom-endpoint"></dds-masthead-container>
<dds-masthead-container
data-endpoint="/custom-endpoint"></dds-masthead-container>
```

### Setting the active menu item
The active menu item receives a unique style treatment to indicate where the current page is within the navigation hierarchy.

The active menu item receives a unique style treatment to indicate where the
current page is within the navigation hierarchy.

##### Manually
Manually set the active item by using the `selected-menu-item` property. See [the Props table](#props).

Manually set the active item by using the `selected-menu-item` property. See
[the Props table](#props).

##### Automatically
The first menu item whose `href` value matches the browser window's current URL will automatically be marked active if the `selected-menu-item` property has not been set.

If no other menu items are marked active and the optional `platformUrl` property has been set, the platform link will be marked active.
The first menu item whose `href` value matches the browser window's current URL
will automatically be marked active if the `selected-menu-item` property has not
been set.

If no other menu items are marked active and the optional `platformUrl` property
has been set, the platform link will be marked active.

## Using custom search with typeahead API

Using a search API other than the default provided from IBM Search is supported.

First, add the `custom-typeahead-api` attribute into the masthead and set it to `true`.
First, add the `custom-typeahead-api` attribute into the masthead and set it to
`true`.

```html
<dds-masthead-container custom-typeahead-api="true"></dds-masthead-container>
```

As an example, we will be using the IBM Docs API to fetch the data, retrieving an array of result suggestions.
As an example, we will be using the IBM Docs API to fetch the data, retrieving
an array of result suggestions.

```javascript
async function customTypeaheadApiFunction(searchVal) {
return fetch(
`https://ibmdocs-dev.mybluemix.net/docs/api/v1/suggest?query=${searchVal}&lang=en&categories=&limit=6`
)
.then((response) => response.json())
.then((data) => {
let searchResults = [
data.hints,
];
return searchResults;
});
}
async function customTypeaheadApiFunction(searchVal) {
return fetch(
`https://ibmdocs-dev.mybluemix.net/docs/api/v1/suggest?query=${searchVal}&lang=en&categories=&limit=6`
)
.then((response) => response.json())
.then((data) => {
let searchResults = [data.hints];
return searchResults;
});
}
```

To query the current masthead search input, we need to create an event listener to listen for the `dds-search-with-typeahead-input` event.
Once captured, we need to call our asynchronous function to fetch the custom API results based on the query. Once the results are retrieved,
a new custom event `dds-custom-typeahead-api-results` needs to be dispatched containing the results for the component to render the search suggestions.
To query the current masthead search input, we need to create an event listener
to listen for the `dds-search-with-typeahead-input` event. Once captured, we
need to call our asynchronous function to fetch the custom API results based on
the query. Once the results are retrieved, a new custom event
`dds-custom-typeahead-api-results` needs to be dispatched containing the results
for the component to render the search suggestions.

```javascript
document.addEventListener('dds-search-with-typeahead-input', async (e) => {
const results = await customTypeaheadApiFunction(e.detail.value);
document.dispatchEvent(new CustomEvent('dds-custom-typeahead-api-results', { detail: results}));
})
document.addEventListener('dds-search-with-typeahead-input', async (e) => {
const results = await customTypeaheadApiFunction(e.detail.value);
document.dispatchEvent(
new CustomEvent('dds-custom-typeahead-api-results', { detail: results })
);
});
```

### Grouped Search

Some APIs contain grouped results in addition to regular search suggestions, which can also be displayed upon search.

As before, create a function that fetches the query and make sure to include a JSON object containing the section's `title`
and the array of retrieved section suggestions in `items`. In the example below, the section `Product pages` is added to the
results array.
Some APIs contain grouped results in addition to regular search suggestions,
which can also be displayed upon search.

As before, create a function that fetches the query and make sure to include a
JSON object containing the section's `title` and the array of retrieved section
suggestions in `items`. In the example below, the section `Product pages` is
added to the results array.

```javascript
async function customTypeaheadApiFunction(searchVal) {
return fetch(
`https://ibmdocs-dev.mybluemix.net/docs/api/v1/suggest?query=${searchVal}&lang=en&categories=&limit=6`
)
.then((response) => response.json())
.then((data) => {
let searchResults = [
data.hints,

// optional category results fetched from API
{
title: "Product pages",
items: data.products
}
];
return searchResults;
});
}
async function customTypeaheadApiFunction(searchVal) {
return fetch(
`https://ibmdocs-dev.mybluemix.net/docs/api/v1/suggest?query=${searchVal}&lang=en&categories=&limit=6`
)
.then((response) => response.json())
.then((data) => {
let searchResults = [
data.hints,

// optional category results fetched from API
{
title: 'Product pages',
items: data.products,
},
];
return searchResults;
});
}
```

As mentioned above, the two events `dds-search-with-typeahead-input` and `dds-custom-typeahead-api-results` must be handled for
suggestions to be rendered -- the same code for the event listener can be reused.
As mentioned above, the two events `dds-search-with-typeahead-input` and
`dds-custom-typeahead-api-results` must be handled for suggestions to be
rendered -- the same code for the event listener can be reused.

#### Note

The API results must match the following structure:

```javascript
[
['result 1', 'result 2', 'result 3'],
Expand All @@ -218,14 +248,18 @@ The API results must match the following structure:
}
]
```
Note that only the first array element is necessary to render the basic search suggestions, the following JSON objects are optional Grouped sections.

Note that only the first array element is necessary to render the basic search
suggestions, the following JSON objects are optional Grouped sections.

## Scoped search
Scoped searches are also supported, returning results from specifically targeted IBM pages and products.

First, prepare the desired categories to use when scoping the search. In this example, we will be creating an array with
four categories, which must follow the structure below:
Scoped searches are also supported, returning results from specifically targeted
IBM pages and products.

First, prepare the desired categories to use when scoping the search. In this
example, we will be creating an array with four categories, which must follow
the structure below:

```javascript
const scopeParameters = [
Expand All @@ -248,7 +282,7 @@ const scopeParameters = [
name: 'Developer',
appId: 'dw',
value: ['dw', 'dwaspera'],
},
},
{
name: 'IBM Docs',
appId: 'ibmdocs',
Expand All @@ -257,30 +291,38 @@ const scopeParameters = [
}
];
```

#### Note
A list of the available scoped categories can be found [here](https://github.ibm.com/digital-marketplace/columbus/blob/master/docs/SCOPED.MD).

A list of the available scoped categories can be found
[here](https://github.ibm.com/digital-marketplace/columbus/blob/master/docs/SCOPED.MD).

The `value` property can either be a single string, or an array of strings.

This array will be passed into the `scopeParameters` property. If using `lit-html` to render your page, this can be added
using `.scopeParameters` (note the `.`), in order for the array to be processed properly in the component.
This array will be passed into the `scopeParameters` property. If using
`lit-html` to render your page, this can be added using `.scopeParameters` (note
the `.`), in order for the array to be processed properly in the component.

```html
<dds-masthead-composite .scopeParameters="${scopeParameters}"></dds-masthead-composite>
<dds-masthead-composite
.scopeParameters="${scopeParameters}"></dds-masthead-composite>
```

Alternatively, JavaScript can be used to insert it into the component.

```javascript
document.querySelector('dds-masthead-composite').scopeParameters = scopeParameters;
document.querySelector('dds-masthead-composite').scopeParameters =
scopeParameters;
```

If a different locale is used, it will be necessary to use a formatter function to localize the placeholder text that
will be rendered depending on the selected scope.
If a different locale is used, it will be necessary to use a formatter function
to localize the placeholder text that will be rendered depending on the selected
scope.

```javascript
const placeholderFormatter = ({scopeValue}) => `Buscar en ${scopeValue}`;
document.querySelector('dds-search-with-typeahead').placeholderFormatter = placeholderFormatter;
const placeholderFormatter = ({ scopeValue }) => `Buscar en ${scopeValue}`;
document.querySelector('dds-search-with-typeahead').placeholderFormatter =
placeholderFormatter;
```

## Props
Expand All @@ -289,27 +331,32 @@ document.querySelector('dds-search-with-typeahead').placeholderFormatter = place

<Props of="dds-masthead-composite" />

For Cloud-specific version of masthead-container, `<dds-cloud-masthead-container>`, we support two user authentication methods, via cookie or api. To select between the two, provide the `auth-method` prop with a value of either 'cookie' or 'api'.
For Cloud-specific version of masthead-container,
`<dds-cloud-masthead-container>`, we support two user authentication methods,
via cookie or api. To select between the two, provide the `auth-method` prop
with a value of either 'cookie' or 'api'.

```html
<dds-cloud-masthead-container auth-method="cookie"></dds-cloud-masthead-container>
<dds-cloud-masthead-container
auth-method="cookie"></dds-cloud-masthead-container>
```

## Stable selectors

See [our README](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components#stable-selectors-for-analytics-and-integratione2e-testing-in-web-components) to see how Web Components selector and `data-autoid` should be used.
See
[our README](https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components#stable-selectors-for-analytics-and-integratione2e-testing-in-web-components)
to see how Web Components selector and `data-autoid` should be used.

| Web Components selector | Compatibility selector | Description |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------- |
| `<dds-masthead>` | `data-autoid="dds--masthead"` | Component |
| `<dds-masthead-menu-button>` | `data-autoid="dds--masthead__hamburger"` | Interactive |
| `<dds-top-nav-name>` | `data-autoid="dds--masthead__platform-name"` | Interactive |
| `<dds-top-nav>` | `data-autoid="dds--masthead__l0-nav"` | Component |
| `<dds-top-nav-menu trigger-content="${item}">` and `<dds-top-nav-item title="${item}">` | `data-autoid="dds--masthead__l0-nav--nav${item}"` | Interactive |
| `<dds-top-nav-menu trigger-content="${item}">` and `<dds-top-nav-item title="${item}">` | `data-autoid="dds--masthead__l0-nav--nav${item}"` | Interactive |
| `<dds-top-nav-menu-item title="${item}">` | `data-autoid="dds--masthead__l0-nav--subnav-col${item}-item${item}"` | Interactive |
| `<dds-left-nav>` | `data-autoid="dds--masthead__l0-sidenav"` | Component |
| `<dds-left-nav-menu trigger-content="${item}">` and `<dds-left-nav-item title="${item}">` | `data-autoid="dds--masthead__l0-sidenav--nav${item}"` | Interactive |
| `<dds-left-nav-menu trigger-content="${item}">` and `<dds-left-nav-item title="${item}">` | `data-autoid="dds--masthead__l0-sidenav--nav${item}"` | Interactive |
| `<dds-left-nav-menu-item title="${item}">` | `data-autoid="dds--masthead__l0-sidenav--subnav-col${item}-item${item}"` | Interactive |


<Description markdown={contributing} />
5 changes: 4 additions & 1 deletion ...ges/web-components/src/components/masthead/__stories__/README.stories.react.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -102,9 +102,12 @@ function App() {

#### Custom Navigation

In order to set custom navigation for the masthead, set the custom navigation
data to the `customNavLinks` property of the masthead-container component.

```javascript
const links = [...menu items...];
document.getElementById('masthead-container').navLinks = links;
document.getElementById('masthead-container').customNavLinks = links;
```

#### Using L1 nav
Expand Down
Loading

0 comments on commit b512715

Please sign in to comment.