Skip to content

Commit f2134cf

Browse files
author
Jill Grant
authored
Merge pull request #267297 from cdpark/howto-html-userpref
User Story 201187: Q&M: Freshness pass for Immersive Reader -- "How to" html and user preferences
2 parents 2466da7 + c9611c2 commit f2134cf

File tree

3 files changed

+47
-44
lines changed

3 files changed

+47
-44
lines changed
Lines changed: 21 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,80 @@
11
---
22
title: "Edit the Immersive Reader launch button"
33
titleSuffix: Azure AI services
4-
description: This article will show you how to customize the button that launches the Immersive Reader.
4+
description: Learn how to customize the button that launches the Immersive Reader app.
55
#services: cognitive-services
6-
author: rwallerms
6+
author: sharmas
77
manager: nitinme
88

99
ms.service: azure-ai-immersive-reader
1010
ms.topic: how-to
11-
ms.date: 03/08/2021
12-
ms.author: rwaller
11+
ms.date: 02/23/2024
12+
ms.author: sharmas
1313
---
1414

1515
# How to customize the Immersive Reader button
1616

17-
This article demonstrates how to customize the button that launches the Immersive Reader to fit the needs of your application.
17+
This article demonstrates how to customize the button that launches the Immersive Reader, to fit the needs of your application.
1818

1919
## Add the Immersive Reader button
2020

21-
The Immersive Reader SDK provides default styling for the button that launches the Immersive Reader. Use the `immersive-reader-button` class attribute to enable this styling.
21+
The [Immersive Reader SDK](https://github.com/microsoft/immersive-reader-sdk) provides default styling for the button that launches the Immersive Reader. To enable this styling, use the `immersive-reader-button` class attribute.
2222

2323
```html
2424
<div class='immersive-reader-button'></div>
2525
```
2626

2727
## Customize the button style
2828

29-
Use the `data-button-style` attribute to set the style of the button. The allowed values are `icon`, `text`, and `iconAndText`. The default value is `icon`.
29+
To set the style of the button, use the `data-button-style` attribute. The allowed values are `icon`, `text`, and `iconAndText`. The default value is `icon`.
3030

3131
### Icon button
3232

33+
Use the following code to render the icon button.
34+
3335
```html
3436
<div class='immersive-reader-button' data-button-style='icon'></div>
3537
```
3638

37-
This renders the following:
38-
39-
![This is the rendered Text button](./media/button-icon.png)
39+
:::image type="content" source="media/button-icon.png" alt-text="Screenshot of the rendered button icon.":::
4040

4141
### Text button
4242

43+
Use the following code to render the button text.
44+
4345
```html
4446
<div class='immersive-reader-button' data-button-style='text'></div>
4547
```
4648

47-
This renders the following:
48-
49-
![This is the rendered Immersive Reader button.](./media/button-text.png)
49+
:::image type="content" source="media/button-text.png" alt-text="Screenshot of the text in the button.":::
5050

5151
### Icon and text button
5252

53+
Use the following code to render both the button and the text.
54+
5355
```html
5456
<div class='immersive-reader-button' data-button-style='iconAndText'></div>
5557
```
5658

57-
This renders the following:
58-
59-
![Icon button](./media/button-icon-and-text.png)
59+
:::image type="content" source="media/button-icon-and-text.png" alt-text="Screenshot of the icon and text together.":::
6060

6161
## Customize the button text
6262

63-
Configure the language and the alt text for the button using the `data-locale` attribute. The default language is English.
63+
To configure the language and the alt text for the button, use the `data-locale` attribute. The default language is English.
6464

6565
```html
6666
<div class='immersive-reader-button' data-locale='fr-FR'></div>
6767
```
6868

6969
## Customize the size of the icon
7070

71-
The size of the Immersive Reader icon can be configured using the `data-icon-px-size` attribute. This sets the size of the icon in pixels. The default size is 20px.
71+
To configure the size of the Immersive Reader icon, use the `data-icon-px-size` attribute. This sets the size of the icon in pixels. The default size is 20 px.
7272

7373
```html
7474
<div class='immersive-reader-button' data-icon-px-size='50'></div>
7575
```
7676

77-
## Next steps
77+
## Next step
7878

79-
* Explore the [Immersive Reader SDK Reference](./reference.md)
79+
> [!div class="nextstepaction"]
80+
> [Explore the Immersive Reader SDK reference](reference.md)

articles/ai-services/immersive-reader/how-to-prepare-html.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,23 @@
11
---
22
title: "How to prepare HTML content for Immersive Reader"
33
titleSuffix: Azure AI services
4-
description: Learn how to launch the Immersive reader using HTML, JavaScript, Python, Android, or iOS. Immersive Reader uses proven techniques to improve reading comprehension for language learners, emerging readers, and students with learning differences.
5-
author: rwallerms
4+
description: Learn how to structure HTML and retrieve your content for use with Immersive Reader.
5+
author: sharmas
66
manager: nitinme
77
ms.service: azure-ai-immersive-reader
88
ms.custom: devx-track-js, devx-track-python
99
ms.topic: how-to
10-
ms.date: 03/04/2021
11-
ms.author: rwaller
10+
ms.date: 02/23/2024
11+
ms.author: sharmas
1212
---
1313

1414
# How to prepare HTML content for Immersive Reader
1515

16-
This article shows you how to structure your HTML and retrieve the content, so that it can be used by Immersive Reader.
16+
This article shows you how to structure your HTML and retrieve the content, so that your Immersive Reader application can use it.
1717

1818
## Prepare the HTML content
1919

20-
Place the content that you want to render in the Immersive Reader inside of a container element. Be sure that the container element has a unique `id`. The Immersive Reader provides support for basic HTML elements, see the [reference](reference.md#html-support) for more information.
20+
Place the content that you want to render in the Immersive Reader inside of a container element. Be sure that the container element has a unique `id`. To learn more about how the Immersive Reader provides support for basic HTML elements, see the [SDK reference](reference.md#html-support).
2121

2222
```html
2323
<div id='immersive-reader-content'>
@@ -56,6 +56,7 @@ const data = {
5656
ImmersiveReader.launchAsync(YOUR_TOKEN, YOUR_SUBDOMAIN, data, YOUR_OPTIONS);
5757
```
5858

59-
## Next steps
59+
## Next step
6060

61-
* Explore the [Immersive Reader SDK Reference](reference.md)
61+
> [!div class="nextstepaction"]
62+
> [Explore the Immersive Reader SDK reference](reference.md)
Lines changed: 17 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,32 @@
11
---
2-
title: "Store user preferences"
2+
title: Store user preferences for Immersive Reader
33
titleSuffix: Azure AI services
4-
description: This article will show you how to store the user's preferences.
5-
author: rwallerms
4+
description: Learn how to store user preferences via the Immersive Reader SDK options.
5+
author: sharmas
66
manager: nitinme
77

88
ms.service: azure-ai-immersive-reader
99
ms.topic: how-to
10-
ms.date: 06/29/2020
11-
ms.author: rwaller
10+
ms.date: 02/23/2024
11+
ms.author: sharmas
1212
---
1313

1414
# How to store user preferences
1515

16-
This article demonstrates how to store the user's UI settings, formally known as **user preferences**, via the [-preferences](./reference.md#options) and [-onPreferencesChanged](./reference.md#options) Immersive Reader SDK options.
16+
This article demonstrates how to store the user's UI settings, or *user preferences*, via the [-preferences](./reference.md#options) and [-onPreferencesChanged](./reference.md#options) Immersive Reader SDK options.
1717

18-
When the [CookiePolicy](./reference.md#cookiepolicy-options) SDK option is set to *Enabled*, the Immersive Reader application stores the **user preferences** (text size, theme color, font, and so on) in cookies, which are local to a specific browser and device. Each time the user launches the Immersive Reader on the same browser and device, it will open with the user's preferences from their last session on that device. However, if the user opens the Immersive Reader on a different browser or device, the settings will initially be configured with the Immersive Reader's default settings, and the user will have to set their preferences again, and so on for each device they use. The `-preferences` and `-onPreferencesChanged` Immersive Reader SDK options provide a way for applications to roam a user's preferences across various browsers and devices, so that the user has a consistent experience wherever they use the application.
18+
When the [CookiePolicy](./reference.md#cookiepolicy-options) SDK option is set to *Enabled*, the Immersive Reader application stores user preferences, such as text size, theme color, and font, by using cookies. These cookies are local to a specific browser and device. Each time the user launches the Immersive Reader on the same browser and device, it opens with the user's preferences from their last session on that device. However, if the user opens the Immersive Reader app on a different browser or device, the settings are initially configured with the Immersive Reader's default settings, and the user needs to set their preferences again for each device they use. The `-preferences` and `-onPreferencesChanged` Immersive Reader SDK options provide a way for applications to roam a user's preferences across various browsers and devices, so that the user has a consistent experience wherever they use the application.
1919

20-
First, by supplying the `-onPreferencesChanged` callback SDK option when launching the Immersive Reader application, the Immersive Reader will send a `-preferences` string back to the host application each time the user changes their preferences during the Immersive Reader session. The host application is then responsible for storing the user preferences in their own system. Then, when that same user launches the Immersive Reader again, the host application can retrieve that user's preferences from storage, and supply them as the `-preferences` string SDK option when launching the Immersive Reader application, so that the user's preferences are restored.
20+
First, by supplying the `-onPreferencesChanged` callback SDK option when launching the Immersive Reader application, the Immersive Reader sends a `-preferences` string back to the host application each time the user changes their preferences during the Immersive Reader session. The host application is then responsible for storing the user preferences in their own system. Then, when that same user launches the Immersive Reader again, the host application can retrieve that user's preferences from storage, and supply them as the `-preferences` string SDK option when launching the Immersive Reader application, so that the user's preferences are restored.
2121

22-
This functionality may be used as an alternate means to storing **user preferences** in the case where using cookies is not desirable or feasible.
22+
This functionality can be used as an alternate means to storing user preferences when using cookies isn't desirable or feasible.
2323

2424
> [!CAUTION]
25-
> **IMPORTANT** Do not attempt to programmatically change the values of the `-preferences` string sent to and from the Immersive Reader application as this may cause unexpected behavior resulting in a degraded user experience for your customers. Host applications should never assign a custom value to or manipulate the `-preferences` string. When using the `-preferences` string option, use only the exact value that was returned from the `-onPreferencesChanged` callback option.
25+
> Don't attempt to programmatically change the values of the `-preferences` string sent to and from the Immersive Reader application because this might cause unexpected behavior resulting in a degraded user experience. Host applications should never assign a custom value to or manipulate the `-preferences` string. When using the `-preferences` string option, use only the exact value that was returned from the `-onPreferencesChanged` callback option.
2626
27-
## How to enable storing user preferences
27+
## Enable storing user preferences
2828

29-
the Immersive Reader SDK [launchAsync](./reference.md#launchasync) `options` parameter contains the `-onPreferencesChanged` callback. This function will be called anytime the user changes their preferences. The `value` parameter contains a string, which represents the user's current preferences. This string is then stored, for that user, by the host application.
29+
The Immersive Reader SDK [launchAsync](./reference.md#launchasync) `options` parameter contains the `-onPreferencesChanged` callback. This function is called anytime the user changes their preferences. The `value` parameter contains a string, which represents the user's current preferences. This string is then stored, for that user, by the host application.
3030

3131
```typescript
3232
const options = {
@@ -38,9 +38,9 @@ const options = {
3838
ImmersiveReader.launchAsync(YOUR_TOKEN, YOUR_SUBDOMAIN, YOUR_DATA, options);
3939
```
4040

41-
## How to load user preferences into the Immersive Reader
41+
## Load user preferences
4242

43-
Pass in the user's preferences to the Immersive Reader using the `-preferences` option. A trivial example to store and load the user's preferences is as follows:
43+
Pass in the user's preferences to the Immersive Reader app by using the `-preferences` option. A trivial example to store and load the user's preferences is as follows:
4444

4545
```typescript
4646
const storedUserPreferences = localStorage.getItem("USER_PREFERENCES");
@@ -54,6 +54,7 @@ const options = {
5454
};
5555
```
5656

57-
## Next steps
57+
## Next step
5858

59-
* Explore the [Immersive Reader SDK Reference](./reference.md)
59+
> [!div class="nextstepaction"]
60+
> [Explore the Immersive Reader SDK reference](reference.md)

0 commit comments

Comments
 (0)