Overview

The @glue42/feedback-ui-react library enables you to create your own Feedback App for Glue42 Enterprise. The library allows complete customization of the Feedback Form. The provided default components can be replaced or extended with your custom ones.

The default Glue42 Feedback Form:

Prerequisites

For a Glue42 Enterprise project, you must have Glue42 Enterprise 3.18 or later.

Install

To use the library in your project, execute the following command:

npm install @glue42/feedback-ui-react

Configuration

To use your custom Feedback App built with the @glue42/feedback-ui-react library, modify (or add) the "form" property to the "issueReporting" top-level key in the system.json file of Glue42 Enterprise located in %LocalAppData%\Tick42\GlueDesktop\config. Set the "url" property of the "form" object to the URL of your custom Feedback App:

{
    "issueReporting": {
        "form": {
            "url": "http://localhost:3000"
        }
    }
}

The "form" object has the following properties:

| Property | Type | Description | |----------|------|-------------| | "url" | string | URL pointing to the location of the Feedback App. Defaults to "file://%GDDIR%/assets/issue-reporting/index.html". | | "width" | number | Width in pixels for the Feedback Form. | | "height" | number | Height in pixels for the Feedback Form. | | "showEnvironmentInfo" | boolean | If true, the Feedback Form will show a field with details about the Glue42 environment. |

For more available customizations of the Feedback App through configuration, see the Issue Reporting > Configuration documentation.

Usage

The @glue42/feedback-ui-react library enables you to create your own Feedback App for Glue42 Enterprise. The library provides hooks and default components which you can use to build your own Feedback App by using, modifying or replacing the available components and functionalities.

Hooks

The useIssueReportingContext() hook provides context information about the Feedback App, as well as methods for the default Feedback functionalities which you can use directly in your custom components:

const {
    close,
    config,
    onThemeChanged,
    openUrl,
    setBounds,
    submit,
    submitCompleted,
} = useIssueReportingContext();

| Property | Type | Description | |----------|------|-------------| | close() | function | Closes the Feedback App. | | config | object | Object describing the configuration for the Feedback Form. | | onThemeChanged() | (callback: (theme: string) => void) => void | Method that can be used to track theme changes. The callback parameter is invoked every time the theme changes and receives as an argument the name of the new theme. | | openUrl() | (url: string) => void | Opens a URL in the default browser. Can be used to open the URL of the newly created Jira ticket after the issue report has been submitted. | | setBounds() | (left: number, top: number, width: number, height: number) => void | Sets the bounds of the Feedback Form. | | submit() | function | Submits an issue report. | | submitCompleted | boolean | Boolean flag indicating whether the issue report submit process has been completed. |

The config object has the following properties:

| Property | Type | Description | |----------|------|-------------| | allowEditRecipients | boolean | Flag indicating whether the user is allowed to manually add or remove email recipients. | | applicationTitle | string | Title of the Feedback App. | | attachments | object[] | Array of objects each with id, name and category properties describing the available attachments. | | attachmentsViewMode | "file" | "category" | Describes how the attachments are displayed in the Feedback App. | | buildVersion | string | Platform build version as specified in the "build" top-level key of the system.json file of Glue42 Enterprise. | | createJiraTicket | boolean | Flag indicating whether a Jira ticket will be created when the issue report has been submitted. | | env | string | Platform environment as specified in the "env" top-level key of the system.json configuration file of Glue42 Enterprise. | | environmentInfo | string | Platform environment details. | | errorMessage | string | Error message sent by the platform. | | isError | boolean | Flag indicating whether the submitted feedback is about a platform error. | | mailingList | string | List of default email recipients. | | region | string | Platform region as specified in the "region" top-level key of the system.json configuration file of Glue42 Enterprise. | | selectedCategories | string[] | List of selected attachments or attachment categories. | | sendEmail | boolean | Flag indicating whether an email with the issue report will be sent to the specified recipients. | | showEnvironmentInfo | boolean | Flag indicating whether the Feedback App will show a field with environment details about the platform. | | theme | string | The name of the current theme. | | version | string | Platform version. |

Components

All default components can be reused and composed with custom code. If usage of such component has been detected, its default behavior will be applied. For instance, if you use the <SubmitButton /> component, it will automatically submit the issue report when the button is clicked, without the need of custom code to induce this behavior. If you pass the same component more than once, an error will be thrown.

To remove a component, pass a <Fragment /> component. If you want to use a default functionality (e.g., for closing the Feedback Form) in your custom components, use the useIssueReportingContext() hook to acquire it and pass it to your component.

In your custom Feedback App, you should place the <Feedback /> components in the <IssueReportingProvider /> component. This component is a React context provider component that provides feedback-related data and functionality accessible through the useIssueReportingContext() hook.

The following example demonstrates a basic usage of the library:

import React from "react";
import { IssueReportingProvider } from "@glue42/feedback-ui-react";
import CustomFeedback from "./CustomFeedback";

const App = () => {
    return (
        <IssueReportingProvider>
            <CustomFeedback />
        </IssueReportingProvider>
    );
};

export default App;

The <Header /> component holds the <Title /> and the <CloseButton /> button components. The following example demonstrates creating a header for the Feedback App with a custom title and an additional custom header button. The default <CloseButton /> component is used with its default functionality for closing the Feedback App:

import React from "react";
import {
    Title,
    CloseButton,
    ButtonGroup,
    useIssueReportingContext
} from "@glue42/feedback-ui-react";
import CustomButton from "./CustomButton";

// Custom header title.
const CustomTitle = () => {
    const { config } = useIssueReportingContext();
    const { applicationTitle } = config;
    const title = applicationTitle ? `My ${applicationTitle}` : "My Custom Feedback App";

    return <Title className="draggable" text={title} />;
};

// This component holds the header buttons.
const CustomHeaderButtons = () => {
    // Get the deafult funactionality for closing the Feedback App.
    const { close } = useIssueReportingContext();

    return (
        <ButtonGroup>
            <CustomButton />
            <CloseButton onClick={close} />
        </ButtonGroup>
    );
};

// Custom header for the Feedback App.
const CustomHeader = () => {
    return (
        <div>
            <CustomTitle />
            <CustomHeaderButtons />
        </div>
    );
};

export default CustomHeader;

To use the custom header for the Feedback App, pass it to the <Feedback /> component:

import React from "react";
import { Feedback, IssueReportingProvider } from "@glue42/feedback-ui-react";
import CustomHeader from "./CustomHeader";

const App = () => {
    return (
        <IssueReportingProvider>
            <Feedback
                components={{
                    Header: CustomHeader
                }}
            />
        </IssueReportingProvider>
    );
};

export default App;

You can use the <Body /> component to create a body for the Feedback App containing the desired issue reporting options - e.g., issue description field, attachments, Jira ticket and email options. The @glue42/feedback-ui-react library provides various components to choose from when constructing the view of your custom form: <TextArea />, <Checkbox />, <Block />, <Input />, <Select /> and more.

The following example demonstrates creating a body for the Feedback App containing custom text informing the user what will happen when they click the "Submit" button, a text area for describing the issue, and a "Settings" section containing only a single restricted option for creating a Jira ticket:

import React from "react";
import {
    Block,
    Textarea,
    Checkbox,
    useIssueReportingContext
} from "@glue42/feedback-ui-react";

// Custom body for the Feedback App.
const CustomBody = ({ handleSubmit, submitting }) => {
    const { config } = useIssueReportingContext();
    const { buildVersion, createJiraTicket } = config;
    const customText = `Your feedback will be submitted to the ${buildVersion} team`
        + (createJiraTicket ? " and a Jira ticket will be created." : ".")

    // The body contains the custom text, a text area for describing the issue, and a "Settings" section.
    return (
        <div>
            <form onSubmit={event => handleSubmit(event)}>
                <Block text={customText} />

                <Block text="Description">
                    <Textarea disabled={submitting} />
                </Block>

                {createJiraTicket &&
                <Block text="Settings">
                    <Checkbox
                        disabled={true}
                        defaultChecked={createJiraTicket}
                        label="Create Jira Ticket"
                    />
                </Block>}
            </form>
        </div>
    );
};

export default CustomBody;

To use the custom body for the Feedback App, pass it to the <Feedback /> component:

import React from "react";
import { Feedback, IssueReportingProvider } from "@glue42/feedback-ui-react";
import CustomHeader from "./CustomFooter";
import CustomBody from "./CustomFooter";

const App = () => {
    return (
        <IssueReportingProvider>
            <Feedback
                components={{
                    Header: CustomHeader,
                    Body: CustomBody
                }}
            />
        </IssueReportingProvider>
    );
};

export default App;

By default, the <Footer /> component holds the <FooterButtons /> component that renders conditionally either the <SubmitButton /> and the <CancelButton /> components, or a "Close" button based on whether submitting the issue report has been completed. During submission, the <Footer /> component renders the <Progress /> component showing the submission progress. When the submission is completed, the <Footer /> component renders an <Alert /> component showing the status of the submission, and if creating a Jira ticket has been enabled in the system configuration, a URL pointing to the created Jira ticket is also shown to the user.

The following example demonstrates adding a custom footer button:

import React from "react";
import {
    SubmitButton,
    CancelButton,
    ButtonGroup,
    useIssueReportingContext
} from "@glue42/feedback-ui-react";
import CallSupportButton from "./CallSupportButton";

// This component holds the footer buttons.
const CustomFooterButtons = () => {
    const { close } = useIssueReportingContext();

    return (
        <ButtonGroup>
            <SubmitButton form="feedback" type="submit" />
            <CallSupportButton />
            <CancelButton onClick={close} />
        </ButtonGroup>
    );
};

// Custom footer for the Feedback App.
const CustomFooter = () => {
    return (
        <div>
            <CustomFooterButtons />
        </div>
    );
};

export default CustomFooter;

To use the custom footer for the Feedback App, pass it to the <Feedback /> component:

import React from "react";
import { Feedback, IssueReportingProvider } from "@glue42/feedback-ui-react";
import CustomHeader from "./CustomFooter";
import CustomBody from "./CustomFooter";
import CustomFooter from "./CustomFooter";

const App = () => {
    return (
        <IssueReportingProvider>
            <Feedback
                components={{
                    Header: CustomHeader,
                    Body: CustomBody,
                    Footer: CustomFooter
                }}
            />
        </IssueReportingProvider>
    );
};

export default App;

License

MIT ©