Office-js-docs-pr: In the Outlook roaming section a lot of jQuery is used - is that best practice?

[DennisGaida]

In the section How to save settings in the user's mailbox for Outlook add-ins as roaming settings most of the code examples start with $(document).ready(function () and also with the comment // After the DOM is loaded, add-in-specific code can run..

• Are roaming settings really only available after the DOM is loaded? This isn't documented anywhere on this page besides the code examples.
• Why rely on the third party jQuery library in this case? Why not have a document ready event handler within Office.js or use plain JavaScript (i.e. document.addEventListener("DOMContentLoaded", function(){)?

I think reliance on a specific third party library (jQuery) should be minimized if not completely removed. Developers shall use whatever library they prefer (or don't use any library).

[ElizabethSamuel-MSFT 11/13/2020 edit] Updated referenced page from persisting-add-in-state-and-settings to manage-state-and-settings-outlook.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: b683480b-a4fe-97ba-64f9-45ecfe829bf4
• Version Independent ID: 55687f2c-7649-5ca7-d090-aface4cd8a7e
• Content: Manage state and settings for an Outlook add-in - Office Add-ins
• Content Source: docs/outlook/manage-state-and-settings-outlook.md
• Product: non-product-specific
• Technology: add-ins
• GitHub Login: @o365devx
• Microsoft Alias: o365devx

[AlexJerabek]

Thanks @DennisGaida for the request to clarify this documentation. @ElizabethSamuel-MSFT, can you investigate?

[ElizabethSamuel-MSFT]

@DennisGaida Thanks for making this request. I've added this to our internal backlog.

Thanks.

[ElizabethSamuel-MSFT]

@DennisGaida The RoamingSettings may provide some more information about how it behaves. Can you take a look?

Developers can certainly use plain JS or any framework of their choosing. Our including jQuery or other frameworks is usually meant to show how to incorporate frameworks, simplify the code example, or for convenience.

[DennisGaida]

@ElizabethSamuel-MSFT thank you for linking the RoamingSettings documentation, great information!

I'm not sure whether the documentations match because RoamingSettings says "_The RoamingSettings object is initialized from the persisted storage only when the add-in is first loaded_" and the code example does not use jQuery's $(document).ready, it actually just uses Office.context.roamingSettings.get(settingName); without waiting for document ready. I'm seeing a mismatch between RoamingSettings and the documentation this issue is about and I am not sure whether waiting for document ready is necessary / best practice or just there "for good measure" in the example.
RoamingSettings does not document that settings are only available after the document ready event.

On frameworks or plain JS I understand your thinking, thanks for clarifying!

[ElizabethSamuel-MSFT]

@DennisGaida Thanks for your response. I'll ask the product team to take a look.

@exextoc Can you take a look here?

Thanks.

[ElizabethSamuel-MSFT]

@ElizabethSamuel-MSFT thank you for linking the RoamingSettings documentation, great information!

I'm not sure whether the documentations match because RoamingSettings says "_The RoamingSettings object is initialized from the persisted storage only when the add-in is first loaded_" and the code example does not use jQuery's $(document).ready, it actually just uses Office.context.roamingSettings.get(settingName); without waiting for document ready. I'm seeing a mismatch between RoamingSettings and the documentation this issue is about and I am not sure whether waiting for document ready is necessary / best practice or just there "for good measure" in the example.
RoamingSettings does not document that settings are only available after the document ready event.

On frameworks or plain JS I understand your thinking, thanks for clarifying!

@exextoc Can you provide your thoughts on this comment? Thx.

[exextoc]

You do not need to wait for the document to be loaded to use Roaming Settings.

The documentation you are referring to (_The RoamingSettings object is initialized from the persisted storage only when the add-in is first loaded_) is meant to specify that the value of the RoamingSettings object is from the first load (not including persisted changes) if the taskpane is reloaded/page change.

[DennisGaida]

You do not need to wait for the document to be loaded to use Roaming Settings.

Hence the documentation this issue is about should be changed. I would opt for removing any jQuery dependency and document load events - otherwise you will have many apps that use this exact unnecessary code.

[ElizabethSamuel-MSFT]

@DennisGaida I'm removing the add-in initialization code from the example. If someone is interested in learning more about how to initialize an add-in, they can see our article on the topic.

Thanks again for raising this issue. The change should be merged and published today.