SDK: Develop useDotCMS React Hook

[rjvelazco]

Caution

GitHub Issue Blocked by: #30968

Parent Issue

#30943

Overview

Create a React hook to streamline interactions with dotCMS, focusing on editor mode. This hook will manage subscriptions and notify the editor of page loads and URL changes.

Background

Currently, a similar hook exists within our examples; however, this hook should be officially provided as part of the SDK. By doing so, we aim to enhance the developer experience, making it easier and more efficient for developers to integrate and set up a page with dotCMS. Providing this hook through the SDK will streamline the process, reducing setup time and complexity, and allowing developers to get up and running as quickly as possible.

Task

Tasks

Preview Give feedback

1. Receive updates for pageAsset coming from the UVE.
2. If the pageAsset is not provided, retrieve it based on the user's Page Query.
3. Ensure the hook does not subscribe when outside the editor.
4. Use only methods that are part of the public API within the hook.
5. Manage subscriptions efficiently, with proper cleanup to prevent memory leaks.
6. Fully document the hook’s usage and parameters.

Proposed Objective

Technical User Experience

Proposed Priority

Priority 3 - Average

Acceptance Criteria

• Users can edit pages and see the latest changes.
• Update the example to reflect the new hook.
• The hook should emit the user's Page Query to the UVE.

External Links... Slack Conversations, Support Tickets, Figma Designs, etc.

• Google Doc

Challenges and Considerations

1. Compatibility Across React Versions: Ensure the hook works seamlessly across different versions of React.
2. Public API Accessibility: All methods used within the hook should be part of the public API. Users might want to implement custom solutions.
3. Documentation and Developer Guidance: Provide comprehensive documentation and guidance to assist developers in using the hook effectively.

Pseudo-Code Example

function useDotCMS({initialPageAsset, params }) {
    const [pageAsset, setPageAsset] = useState(initialPageAsset);
    
   /**
     * Initializes the page asset state with content fetched from the server.
     * This effect runs once on component mount if an initial page asset is not provided.
     * It sets up the page asset state and cleans up by removing the 'changes' listener.
     */
    useEffect(() => {
        if (initialPageAsset) return;

        const { pageAsset } = client.getPageContent({
            url: pathName,
            ...params
        });

        setPageAsset(pageAsset)

        return () => uveEditor.off('changes');
    }, []);

    /**
     * Sets up a listener for changes in the UVE editor.
     * Updates the page asset state when changes occur.
     * The listener is only active when inside the editor or when onReload is defined.
     */
    useEffect(() => {
        if (!isInsideEditor() && !onReload) return;
        uveEditor.on('changes', (pageAsset) => setPageAsset(pageAsset));
        return () => uveEditor.off('changes');
    }, []);

    /**
     * Notifies the editor of URL changes.
     * This effect is only active when inside the editor.
     */
    useEffect(() => {
        if (!isInsideEditor()) return;
        notifyEditor(params);
    }, [params.url]);

    return { pageAsset };
}

[rjvelazco]

@zJaaal @KevinDavilaDotCMS Whoever is going to take this issue, once it is ready, we must create/design the error handling