Rating system + how to pass rating callback from nodejs/config to browser

[artemkovalyov]

Hi there, I'm developing a voting component and need to pass a callback to my component which will serve as an adapter for different backends which users can be leveraging for recording votes (Google Tags, API Hook, etc).

I tried passing it via a themeConfig like myCollabc: value => { makeCallToMyAPI(value)} but that doesn't work. I can see properties that I pass but the callback is not there:

I assume some sanitizing is going on? What would be the best practice to allow the user to develop their own adapter for recording the votes and then pass it to be invoked via the component?

Or am I doing something wrong and that's why I don't see the callback on the component side? I checked and destructuring and all the types are correct.

[Josh-Cena]

The theme config must be entirely serializable, because docusaurus.config.js is ultimately run on server-side and we can't guarantee that you won't reference server-side variables. https://docusaurus.io/docs/next/advanced/architecture

If you want to pass callbacks on the client side, you have to inject it through as a client-side file (e.g. in src/components or src/theme). But I wonder, if everything is your custom component, why do you still want to extract it to the theme config? Why don't you just hard-code it in your component?

[artemkovalyov]

@Josh-Cena, I'm working on a PR to contribute this feature as we developed it some time ago and it proved useful. It's somewhat painful to support it swizzled.

My frontend and rendering logic already works. Now I'm looking for a reasonable way to let other users configure this component of they'd like to use it.

Letting them pass their implantation for external API calls via a callback function was a natural choice but I suffer to find good pattern in Docusaurus API.

Should it be then done via getCustomModules()? Or special plugin?
Id be thankful for a very simple example or at least a suggestion on how to allow users leverage own implementation for sending data to desired backend.

[Josh-Cena]

Oh, if you want to contribute—it's not the first time that this happened. A very common strategy is to design a UI-only component, and have a dummy theme component that exports a no-op function. Users are asked to swizzle this theme component to implement whatever function they want.

If you want to design a voting system though, I'm not sure if a PR would be accepted. Our idea is that this should always be done in userland since both the UI and the UX would probably be provided by whatever widget you adopted, and there's little that Docusaurus needs to do.

[artemkovalyov]

Oh, I see... It's generally a feature to give feedback about the usefulness of the docs, that's what I mean by a rating of doc pages. Would be a pity if I coded all of that in vain. My motivation was the fact that many developer documentation sited implement this feature. In that sense, announcementBar, latestUpdated, and Author are not much different.

You can of course configure it to show this UI component or not. Having such a component in a theme out of the box seems pretty useful and you're right that you can swizzle it easily for further customization to provide that API callback. I'm happy to document it.

Here's what it looks like at the moment in my dev env:

Top of the page

Bottom of the page

I made it configurable through the themeConfig as most of the other UI components.
@Josh-Cena, let me know if I should continue with a PR, or is it doomed?

[Josh-Cena]

I can't say if you should continue or not, that would be @slorber's call, but my answer is this is best done in userland because I'm aware of many third-party services that offer both the UI and the UX. See also #5380 where "feedback widget" is listed as one propelling use-case of theme-wrapping.

[artemkovalyov]

@Josh-Cena, I haven't found plenty of services that would provide smth useful. The sites I've checked mostly had their own implementation like even react docs. The issues with 3rd party services are:

• They do not provide a uniform look and feel for such a simple component that has to be integrated throughout the docs.
• In many environments, like a corp-backed open source you can't use 3rd party services due to compliance.
• The implementation of 3rd party services is highly opinionated and not customizable. It also doesn't usually integrate with your preferred analytics system like Google Analytics, Plausible, etc.
• Most of the analytics systems provide custom events or tags that are usually leveraged to collect this kind of feedback.
• After working some time in marketing and analytics - that's the default way to collect data about user interactions, I mean tags and events, not a 3rd party services.
• Docs are often a part of something bigger and the data collected from there has to be collated with other sources.
• Lastly, for intranet deployments, only internal services would work:)

This page rating pattern with +1/-1 or true/false logic is very widespread. React, Google Support, and many others use it. That's why I think having a native Docusaurus component for it makes sense at least with theme-classic. The component provides a super simplistic API of sending that 1/0 to a callback provided to it - that's it. So it's a pure frontend thing.

What belongs to the user land is implementation of that callback and here I agree it's a userland part. I think it can be solved with the swizzling pattern if no other way exists. At the end of the day even if the internals of the UI component change but API stays the same - the upgrade path should be rather easy.

@slorber, before I commit to the tests and docs, do you think this can make it in? We've prototyped it in our docs and use Docusaurus from its early alfa. Now, I had trouble upgrading the theme and core because of some swizzled components and decided to contribute this for good.

If that's not worth it, we'll probably just kill that rating snippet as the maintenance effort would not justify having it. That's actually why I think many docs' owners won't implement it. With styling, stateful logic, context wrapping, and all - it's time-consuming. Whereas if you need only a function that triggers your GA tags or Plausible endpoint - that's a no-brainer.

Looking forward to hearing what you think.

p.s.: examples from Google Cloud and React, or check our docs

[slorber]

@artemkovalyov I don't know, maybe we'll add this later but for now the best we want to do is to enable users to add this rating system themselves

I don't have a unique best solution to suggest for providing a callback through config, and I don't know how such core feature would interact with plugins like Google Analytics, which can provide a way to save ratings to a backend (RN website uses this).

Maybe we need extra core APIs to be able us to build a generic solution to solve this problem.

Until we figure this out correctly and assess if it's worth implementing in core, I'd rather see a solid userland solution solving first, even if the integration is slightly more complex.

---

Now, I had trouble upgrading the theme and core because of some swizzled components and decided to contribute this for good.

We are actually trying to make this much easier. You shouldn't need to swizzle too many components to handle that in the future. Have you tried "wrapping"? https://docusaurus.io/docs/advanced/swizzling#wrapping-theme-components

That's actually why I think many docs' owners won't implement it. With styling, stateful logic, context wrapping, and all - it's time-consuming.

We should make this easier in the first place. Is styling really the complex part here?

Which stateful logic?
Which context wrapping?

Note the implementation of Rating on the RN website is as simple as that:

https://github.com/facebook/react-native-website/blob/main/website/src/theme/DocItemFooter/index.js

import React from 'react';
import DocItemFooterOriginal from '@theme-original/DocItemFooter';
import DocsRating from '../../../core/DocsRating';

const DocsRating = ({label}) => {
  if (!ExecutionEnvironment.canUseDOM) {
    return null;
  }

  const [haveVoted, setHaveVoted] = useState(false);
  const giveFeedback = value => {
    if (window.ga) {
      window.ga('send', {
        hitType: 'event',
        eventCategory: 'button',
        eventAction: 'feedback',
        eventLabel: label,
        eventValue: value,
      });
    }
    setHaveVoted(true);
  };

  return (
    <div className="docsRating">
      {haveVoted ? (
        'Thanks for letting us know!'
      ) : (
        <>
          Is this page useful?
          <svg
            className="i_thumbsup"
            alt="Like"
            onClick={() => giveFeedback(1)}
            xmlns="http://www.w3.org/2000/svg"
            viewBox="0 0 81.13 89.76">
            <path d="..." />
          </svg>
          <svg
            className="i_thumbsdown"
            alt="Dislike"
            onClick={() => giveFeedback(0)}
            xmlns="http://www.w3.org/2000/svg"
            viewBox="0 0 81.13 89.76">
            <path d="..." />
          </svg>
        </>
      )}
    </div>
  );
};


export default function DocItemFooter(props) {
  return (
    <>
      <DocsRating label={props.content.metadata.unversionedId} />
      <DocItemFooterOriginal {...props} />
    </>
  );
}

[artemkovalyov]

@slorber, I see your points and you seem to be decisive to keep this out for now.

I don't have a unique best solution to suggest for providing a callback through config, and I don't know how such core feature would interact with plugins like Google Analytics, which can provide a way to save ratings to a backend (RN website uses this).

I planned to provide some default Gtag based implementation where you fire those tags.

Until we figure this out correctly and assess if it's worth implementing in the core, I'd rather see a solid userland solution
solving first, even if the integration is slightly more complex.

I think ours is a solid userland solution. I went onto a contribution path to make sure integration with the theme is consistent and doesn't break way too often thanks to tests and theme being maintained:) I admit that wrapping is a good solution with an easier upgrade path. This pattern wasn't documented when we developed our snippet.

We should make this easier in the first place. Is styling really the complex part here?

Most smaller projects will never implement it regardless of complexity. As this feedback pattern seems widespread, having an out-of-the-box component and default styling makes sense. Docs are mostly deployed not by developers. Those folks usually will have trouble with even swizzling.

Which stateful logic? Which context wrapping?

We have the snippet in two locations and synced the state through the context. So we sizzled a Root component as well.
When coding a contribution PR, I took a TAB component as an example and implemented storing things to localStore for keeping state thought the running session and some other goodies like memorization, etc.
We were inspired by RN by the way:) I think the first implementation I suggested to my dev team was via useState. I don't know why syncing the components didn't work that way. Might be also needless complexity.

The component is still rather simple: https://github.com/artemkovalyov/docusaurus/blob/master/packages/docusaurus-theme-classic/src/theme/DocPageRating/index.tsx
Here's the complementary part in theme-common: https://github.com/artemkovalyov/docusaurus/blob/master/packages/docusaurus-theme-common/src/utils/ratedPagesListUtils.tsx

Having a way to pass a function to FE in some way (via config or not would have been nice). Maybe could be a plugin exposing those:)

It was fun making Docusaurus dev env up and running, learning the APIs, and brushing up my React skills;)
If you change your mind at some point I'll also write some tests and finalize the PR:)

Thanks again for coming back and all the details about your decision-making process.

[slorber]

Thanks for understanding

It's not a definitive no from my side, it's just a timing issue: we are focusing on 2.0 and easier swizzling experience.

Once we have that we'd be able to explore adding useful new features and shortcuts for things that our community usually do: rating, comments etc...

Until then I think we should have a "recipe" section somewhere in our docs to explain how this can be done in userland