Skip to content

Commit 1abedbc

Browse files
didooCopilot
didoo
and
Copilot
authored
Website - Improve clarity/accuracy of how the @isHrefExternal argument is documented across multiple components (#3025)
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 288d4cc commit 1abedbc

File tree

17 files changed

+94
-59
lines changed

17 files changed

+94
-59
lines changed

‎showcase/app/templates/page-components/app-side-nav/index.hbs

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -364,8 +364,24 @@
364364
</span>
365365
</Hds::AppSideNav::List::Link>
366366
</SG.Item>
367+
<SG.Item @label="Default link">
368+
<Hds::AppSideNav::List::Link @icon="hashicorp" @text="HashiCorp Cloud Platform" @href="#" />
369+
</SG.Item>
367370
<SG.Item @label="External link">
368-
<Hds::AppSideNav::List::Link @icon="hashicorp" @text="HashiCorp Cloud Platform" @isHrefExternal={{true}} />
371+
<Hds::AppSideNav::List::Link
372+
@icon="hashicorp"
373+
@text="HashiCorp Cloud Platform"
374+
@isHrefExternal={{true}}
375+
@href="#"
376+
/>
377+
</SG.Item>
378+
<SG.Item @label="Internal link">
379+
<Hds::AppSideNav::List::Link
380+
@icon="hashicorp"
381+
@text="HashiCorp Cloud Platform"
382+
@isHrefExternal={{false}}
383+
@href="#"
384+
/>
369385
</SG.Item>
370386
</Shw::Grid>
371387

‎showcase/app/templates/page-components/side-nav.hbs

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -834,8 +834,19 @@
834834
</span>
835835
</Hds::SideNav::List::Link>
836836
</SG.Item>
837+
<SG.Item @label="Default link">
838+
<Hds::SideNav::List::Link @icon="hashicorp" @text="HashiCorp Cloud Platform" @href="#" />
839+
</SG.Item>
837840
<SG.Item @label="External link">
838-
<Hds::SideNav::List::Link @icon="hashicorp" @text="HashiCorp Cloud Platform" @isHrefExternal={{true}} />
841+
<Hds::SideNav::List::Link @icon="hashicorp" @text="HashiCorp Cloud Platform" @href="#" @isHrefExternal={{true}} />
842+
</SG.Item>
843+
<SG.Item @label="Internal link">
844+
<Hds::SideNav::List::Link
845+
@icon="hashicorp"
846+
@text="HashiCorp Cloud Platform"
847+
@href="#"
848+
@isHrefExternal={{false}}
849+
/>
839850
</SG.Item>
840851
</Shw::Grid>
841852

‎website/docs/components/app-footer/partials/code/component-api.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -59,8 +59,8 @@ The `AppFooter::StatusLink` component, yielded as contextual component.
5959
<C.Property @name="href">
6060
Pass a custom href for the link. (URL parameter that’s passed down to the `<a>` element.)
6161
</C.Property>
62-
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
63-
Controls if the `<a>` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default.
62+
<C.Property @name="isHrefExternal" @type="boolean">
63+
Controls whether or not the `<a>` link is external. When left `undefined` or explicitly set to `true` it adds the `target="_blank"` and `rel="noopener noreferrer"` attributes to the `<a>` tag (for security reasons).
6464
</C.Property>
6565
<C.Property @name="route/models/model/query/current-when/replace">
6666
Parameters that are passed down as arguments to the `<LinkTo>`/`<LinkToExternal>` components.
@@ -115,8 +115,8 @@ The `AppFooter::Link` component, yielded as contextual component.
115115
<C.Property @name="href">
116116
URL parameter that’s passed down to the `<a>` element.
117117
</C.Property>
118-
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
119-
Controls if the `<a>` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default.
118+
<C.Property @name="isHrefExternal" @type="boolean">
119+
Controls whether or not the `<a>` link is external. When left `undefined` or explicitly set to `true` it adds the `target="_blank"` and `rel="noopener noreferrer"` attributes to the `<a>` tag (for security reasons).
120120
</C.Property>
121121
<C.Property @name="route/models/model/query/current-when/replace">
122122
Parameters that are passed down as arguments to the `<LinkTo>`/`<LinkToExternal>` components.

‎website/docs/components/app-header/partials/code/component-api.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,16 +54,16 @@ The `AppHeader::HomeLink` component uses the generic `Hds::Interactive` componen
5454
Used to display text inline with the logo. If `@isIconOnly` is set to `true`, this value will instead be passed to the `aria-label` of the `<a>` tag.
5555
</C.Property>
5656
<C.Property @name="isIconOnly" @type="boolean" @default="true">
57-
Indicates if the Home Link will only contain a icon/logo. If set to `false`, the `@text` property will be rendered adjacent to the logo.
57+
Indicates if the Home Link will only contain a icon/logo. If set to `false`, the `@text` property will be rendered adjacent to the logo.
5858
</C.Property>
5959
<C.Property @name="color" @type="string">
6060
Used to specify an optional custom color provided as any valid CSS color. For more details on acceptable values, see the [Icon color argument](/components/icon?tab=code#fill). If unspecified, it will use the App Headers’s default white text color.
6161
</C.Property>
6262
<C.Property @name="href">
6363
URL parameter that’s passed down to the `<a>` element.
6464
</C.Property>
65-
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
66-
This controls if the `<a>` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default.
65+
<C.Property @name="isHrefExternal" @type="boolean">
66+
Controls whether or not the `<a>` link is external. When left `undefined` or explicitly set to `true` it adds the `target="_blank"` and `rel="noopener noreferrer"` attributes to the `<a>` tag (for security reasons).
6767
</C.Property>
6868
<C.Property @name="route/models/model/query/current-when/replace">
6969
Parameters that are passed down as arguments to the `<LinkTo>`/`<LinkToExternal>` components.

‎website/docs/components/app-side-nav/partials/code/component-api.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -133,8 +133,8 @@ It internally uses the [`Hds::Interactive`](/utilities/interactive) utility comp
133133
<C.Property @name="href">
134134
URL parameter that’s passed down to the `<a>` element.
135135
</C.Property>
136-
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
137-
This controls if the `<a>` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default.
136+
<C.Property @name="isHrefExternal" @type="boolean">
137+
Controls whether or not the `<a>` link is external, in which case (for security reasons) we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default.
138138
</C.Property>
139139
<C.Property @name="route/models/model/query/current-when/replace">
140140
Parameters that are passed down as arguments to the `<LinkTo>`/`<LinkToExternal>` components.
@@ -190,8 +190,8 @@ It internally uses the [`Hds::Interactive`](/utilities/interactive) utility comp
190190
<C.Property @name="href">
191191
URL parameter that’s passed down to the `<a>` element.
192192
</C.Property>
193-
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
194-
This controls if the `<a>` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default. If set to `true`, displays a right aligned “external-link” icon.
193+
<C.Property @name="isHrefExternal" @type="boolean">
194+
Controls whether or not the `<a>` link is external. When left `undefined` or explicitly set to `true` it adds the `target="_blank"` and `rel="noopener noreferrer"` attributes to the `<a>` tag (for security reasons). If explicitly set to `true`, it displays also a right aligned “external-link” icon.
195195
</C.Property>
196196
<C.Property @name="route/models/model/query/current-when/replace">
197197
Parameters that are passed down as arguments to the `<LinkTo>`/`<LinkToExternal>` components.

‎website/docs/components/button/partials/code/component-api.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,8 @@
2626
<C.Property @name="href">
2727
URL parameter that is passed down to the `<a>` element.
2828
</C.Property>
29-
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
30-
Controls if the `<a>` link is external and so for security reasons we need to add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it.
29+
<C.Property @name="isHrefExternal" @type="boolean">
30+
Controls whether or not the `<a>` link is external. When left `undefined` or explicitly set to `true` it adds the `target="_blank"` and `rel="noopener noreferrer"` attributes to the `<a>` tag (for security reasons).
3131
</C.Property>
3232
<C.Property @name="route/models/model/query/current-when/replace">
3333
Parameters that are passed down as arguments to the `<LinkTo/LinkToExternal>` component.

‎website/docs/components/button/partials/code/how-to-use.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,18 +114,21 @@ If you’re passing an `@href` or a `@route` argument to the component, this wil
114114
!!! Info
115115

116116
The `Hds::Button` component uses the generic `Hds::Interactive` component. For more details about how this utility component works, please refer to [its documentation page](/utilities/interactive).
117+
117118
!!!
118119

119120
#### With @href
120121

121122
If you pass an `@href` argument, an `<a>` link will be generated.
122123

123-
`target=“_blank”` and `rel=“noopener noreferrer”` attributes are applied by default. This is the most common case, as internal links are generally handled using a `@route` argument but can be overridden. If the `href` points to an internal link, or uses a different protocol (e.g., "mailto" of "ftp"), pass `@isHrefExternal={{false}}` and it will not add the `target` and `rel` attributes.
124+
By default, the link is considered "external", which means that the `target=“_blank”` and `rel=“noopener noreferrer”` attributes are applied to the `<a>` element. This is the most common case, as internal links are generally handled using a `@route` argument.
124125

125126
```handlebars
126127
<Hds::Button @text="Visit website" @icon="external-link" @iconPosition="trailing" @href="https://hashicorp.com" />
127128
```
128129

130+
If the `@href` points to an internal link, or uses a different protocol (e.g., "mailto" or "ftp"), pass `@isHrefExternal={{false}}` to the component and it will omit the `target` and `rel` attributes.
131+
129132
#### With @route
130133

131134
If you pass a `@route` argument, an `<a>` link will be generated using a `<LinkTo>` Ember component. All of the standard arguments for the `<LinkTo/LinkToExternal>` components are supported (eg. `models/model/query/current-when/replace`).

‎website/docs/components/dropdown/partials/code/component-api.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -227,8 +227,8 @@ It internally uses the [`Hds::Interactive`](/utilities/interactive) utility comp
227227
<C.Property @name="href">
228228
URL passed to the `<a>` element.
229229
</C.Property>
230-
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
231-
Indicates whether or not the `<a>` link is external, in which case `target="_blank"` and `rel="noopener noreferrer"` attributes are added automatically.
230+
<C.Property @name="isHrefExternal" @type="boolean">
231+
Controls whether or not the `<a>` link is external. When left `undefined` or explicitly set to `true` it adds the `target="_blank"` and `rel="noopener noreferrer"` attributes to the `<a>` tag (for security reasons).
232232
</C.Property>
233233
<C.Property @name="route/models/model/query/current-when/replace">
234234
Parameters passed as arguments to the `<LinkTo/LinkToExternal>` component.
@@ -287,8 +287,8 @@ The `Dropdown::ListItem::Checkmark` component, yielded as contextual component.
287287
<C.Property @name="href">
288288
URL passed to the `<a>` element.
289289
</C.Property>
290-
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
291-
Indicates whether or not the `<a>` link is external, in which case `target="_blank"` and `rel="noopener noreferrer"` attributes are added automatically.
290+
<C.Property @name="isHrefExternal" @type="boolean">
291+
Indicates whether or not the `<a>` link is external. When left `undefined` or explicitly set to `true` it adds the `target="_blank"` and `rel="noopener noreferrer"` attributes to the `<a>` tag (for security reasons).
292292
</C.Property>
293293
<C.Property @name="route/models/model/query/current-when/replace">
294294
Parameters passed as arguments to the `<LinkTo/LinkToExternal>` component.

‎website/docs/components/dropdown/partials/code/how-to-use.md

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,13 @@ To change this behavior, you can use the `@preserveContentInDom` argument so tha
219219
### ListItem::Interactive
220220

221221
`ListItem::Interactive` renders the correct element based on the passing of a `@route`, `@href`, or the addition of a click event (e.g.,
222-
`\{{on "click" this.myAction}}`). Internally, the component uses the [Hds::Interactive](/utilities/interactive) utility component.
222+
`\{{on "click" this.myAction}}`).
223+
224+
!!! Info
225+
226+
The `ListItem::Interactive` component uses the generic `Hds::Interactive` component. For more details about how this utility component works, please refer to [its documentation page](/utilities/interactive).
227+
228+
!!!
223229

224230
#### Rendering a button
225231

@@ -245,13 +251,6 @@ You can pass an `@icon` argument to add a leading icon:
245251

246252
#### Rendering a link with `@href`
247253

248-
!!! Info
249-
250-
**Internal Link?**
251-
252-
When using the `@href` argument, you’re indicating an external link (instead of a route). So, a few relevant HTML attributes are added—`target="_blank"` and `rel="noopener noreferrer"`. However, if the `@href` really _does_ point to an internal link or uses a different protocol (e.g., `mailto` or `ftp`), pass `@isHrefExternal={{false}}` to the component and it will not add any extra HTML attributes.
253-
!!!
254-
255254
If you pass an `@href` argument, a link (`<a>` element) will be generated:
256255

257256
```handlebars
@@ -261,8 +260,9 @@ If you pass an `@href` argument, a link (`<a>` element) will be generated:
261260
</Hds::Dropdown::ListItem::Interactive>
262261
</ul>
263262
```
263+
By default, the link is considered "external", which means that the `target=“_blank”` and `rel=“noopener noreferrer”` attributes are applied to the `<a>` element. This is the most common case, as internal links are generally handled using a `@route` argument.
264264

265-
To indicate that the link points to an external resource, you can use `@trailingIcon` and assign it an icon name like `external-link`, `docs-link`, `guide-link`, or `learn-link`.
265+
To visually indicate that the link points to an external resource, you can use `@trailingIcon` and assign it an icon name like `external-link`, `docs-link`, `guide-link`, or `learn-link`.
266266

267267
```handlebars
268268
<ul class="hds-dropdown__list">
@@ -272,6 +272,8 @@ To indicate that the link points to an external resource, you can use `@trailing
272272
</ul>
273273
```
274274

275+
If the `@href` points to an internal link, or uses a different protocol (e.g., "mailto" or "ftp"), pass `@isHrefExternal={{false}}` to the component and it will omit the `target` and `rel` attributes.
276+
275277
#### Rendering a LinkTo (with `@route`)
276278

277279
Pass a `@route` to render Ember `<LinkTo>`. If the route is external to your current engine, pass `@isRouteExternal={{true}}` to use `<LinkToExternal>` instead of `<LinkTo>`. For more details see the [Hds::Interactive component](/utilities/interactive/) documentation. All the standard arguments for the `<LinkTo/LinkToExternal>` components are supported (e.g., `models/model/query/current-when/replace`).
@@ -384,4 +386,4 @@ When using the “generic” ListItem, the product team is responsible for imple
384386
<Hds::Link::Standalone @text="Watch tutorial video" @icon="film" @href="/" />
385387
</D.Generic>
386388
</Hds::Dropdown>
387-
```
389+
```

‎website/docs/components/link/inline/partials/code/component-api.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
<C.Property @name="href">
1414
URL parameter that’s passed down to the `<a>` element.
1515
</C.Property>
16-
<C.Property @name="isHrefExternal" @type="boolean" @default="false">
17-
Controls if the `<a>` link is external. For security reasons, we add the `target="_blank"` and `rel="noopener noreferrer"` attributes to it by default.
16+
<C.Property @name="isHrefExternal" @type="boolean">
17+
Controls whether or not the `<a>` link is external. When left `undefined` or explicitly set to `true` it adds the `target="_blank"` and `rel="noopener noreferrer"` attributes to the `<a>` tag (for security reasons).
1818
</C.Property>
1919
<C.Property @name="route/models/model/query/current-when/replace">
2020
Parameters that are passed down as arguments to the `<LinkTo>`/`<LinkToExternal>` components.

0 commit comments

Comments
 (0)