Sibyl Button - Docs

Welcome

Welcome to the documentation for Sibyl Button for Angular! This library provides a component that allows users to submit bug reports for the application they are using. Additionally, Sibyl can handle the display of announcements notifying the user of any critical events or updates worth keeping tabs on. This README file provides an overview of the component's features, its available inputs, and how to use them.

The library, when handling the delivery of forms and/or announcements, can operate in either automatic or manual mode:

• Automatic mode uses the passed API Endpoint and makes a call from within the library. Sibyl will POST a feedback form and/or GET announcements from the server.
• Manual mode will push the object with the form data (+ additional body config key-value pairs) as an object back to the consumer and/or receive hard-coded announcement objects specified in the consumer app.

The library also supports integration with your error detection mechanism (e.g. ErrorInterceptor's). In case of an error within the consumer application, the library can be configured to respond to that error with an animation attracting the user's attention to the button and inviting them to submit a feedback report. The same can be leveraged to dynamically append additional information to the body of the request (e.g. the type of error or location of occurrence). As the appended information is an object, values associated with a key will can be easily overridden by providing another value paired to the same key.

Installation

This tutorial assumes you’ll be using a .tgz archive containing the library files.

1. Copy the .tgz archive to your location. You might consider keeping it alongside other files within your workspace, so that it comes within the scope of your repository.

2. Open a terminal window and navigate to the root directory of the destination project.

3. Install the library in the terminal with the command:

   npm  install  /path/to/sibyl-button.tgz

4. Sibyl Button (as sibyl-button) package will be installed and added to the dependencies section of the package.json file in your project.

5. In the consumer app’s AppModule, import the library’s module at the top and include it in the imports array:

   import { SibylModule } from 'sibyl-button';
   
   //...
   
   imports: [
   	/...
   	SibylModule,
   ],
   

6. In the consumer app’s AppComponent.ts file, create a new SibylConfig instance and provide the configuration for the library.

   The most minimal, workable SibylConfig looks like this:

   mySibylConfig = new SibylConfig(
     {}, // Appearance Config
     [], // Custom Fields for Form conforming to type ```SibylCustomFields```
     {
       serviceName: "My App", // Required property naming the consumer app to identify the source of request.
       announcements: {
         type: "manual", // Required property specifying the preference for the manual mode strategy.
       },
       form: {
         type: "manual", // Required property specifying the preference for the manual mode strategy.
       },
     }
   );

7. In the consumer app’s AppComponent HTML Template, add the sibyl-button component. Remember to include your SibylConfig instance in the [sibylConfigInstance] input.

   <sibyl-button [sibylConfigInstance]="mySibylConfig"></sibyl-button>
   
      <div>
         <app-toolbar></app-toolbar>
         <router-outlet ></router-outlet>
         /...
      </div>

8. You may use SibylService across your app to interact with the library outside of the static configuration. It comes with a number of useful functions and works just like any other Angular service - just include it in your component's constructor:

   constructor(private sibylService: SibylService) {}

Custom Form Fields

Sibyl does not include any fields by default. You may include four types of form fields: an <input> field, a <textarea>, a dropdown as <select> and a checkbox. The fields configuration should be provided as an array.

Constructing an object representing an form field

SibylCustomFields - This type represents an array of custom fields. It includes the following properties:

| Property | Notes | | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | type: 'input' or 'textarea' or 'checkbox' or 'dropdown' | Required: Specifies the type of the field. It can be 'input', 'textarea', 'checkbox' and 'dropdown'. | | required: boolean | Required: Indicates whether the field is required or not. | | fieldName: string | Required: Represents the name of the field. | | fieldLabel: string | Optional: Represents the label of the field. | | fieldPlaceholder: string | Optional: Represents the placeholder text to show in the field. | | options: string[] | Required if Dropdown: Represents the list of options for the dropdown. Only applicable if the type is 'dropdown'. |

Configuring Delivery of Forms and Announcements

Sibyl needs hard-coded delivery instructions contained in an object. There are three required keys:

{
   serviceName: "My App", // Required property naming the consumer app to identify the source of request.
   form: {
      /// *** More below
   },
   announcements: {
      /// *** More below
   },
}

Configuring Form Delivery

• Automatic mode uses the passed API Endpoint and makes a POST call from within the library.

• Manual mode will push the object with the form data via the formOutput output back to the consumer upon clicking Submit.

  • In manual mode, to confirm delivery as successful or failed by displaying the relevant screen to the user, use the notifySibylOfApiCall method from SibylService.
  • Consider implementing them inside of the method making the call under .then() or next: () => {} / .catch() or error: () => {}
  • this.sibylService.notifySibylOfApiCall('success');
  • this.sibylService.notifySibylOfApiCall('error');
  • this.sibylService.notifySibylOfApiCall('idle');

  <sibyl-button
  //...
  (formOutput)="receiveFormOutput($event)" >
  </sibyl-button>

| Property | Notes | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | type: 'manual' or 'automatic' | Required: Specifies the type of operation. It can be either 'manual' or 'automatic'. | | body: ReqBody | Optional: Append hard-coded properties to the body of the request. Properties can be expanded and overridden by dynamically supplying additional body content with a method from SibylService. | | endpoint: string | Required if Automatic: Specifies the endpoint for sending (with POST method) the form to. This is required if the strategy type is 'automatic'. |

Configuring Announcement Delivery

• The received object must conform to the specific structure of a single Announcement object.
• Announcements are displayed the announcements alongside the form. The one with the most recent value in displayProminentUntil will also be displayed as a small toast popup next to the button.
• Automatic mode uses the passed API Endpoint and makes a GET call from within the library.
• Manual mode will receive the array with the form data via SibylConfig or accept it via SibylService.

| Property | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | type: 'manual' | Required Specifies the type of operation. It can be either 'manual' or 'automatic'. | | announcements: Announcement[] | Available and Optional if Manual: The announcements to be shown. This is optional and can be omitted. | | endpoint: string | Required if Automatic: Specifies the endpoint for fetching the announcements from. This is required if the type is 'automatic' or OperationType.automatic. | | body: ReqBody | Available and Optional if Automatic: The body of the GET request. This is optional and should be used only if needed. |

Creating an Announcement object

Announcement - This type represents an announcement. It includes the following properties:

| Property | Notes | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id: number | Required: Represents the unique identifier of the announcement. | | title: string | Required: Represents the title of the announcement. | | message: string | Required: Represents the message of the announcement. | | type: AnnouncementType | Required: Specifies the type of the announcement. It can be either 'new', 'info', or 'critical'. | | displayUntil: number | Optional: Represents the timestamp until which the announcement should be displayed in the library. | | displayProminentUntil: number | Optional: Represents the timestamp until which the announcement should be prominently displayed as a toast popup. The library, by design, seeks out the announcement with the most recent timestamp counting from the current date and time. |

AnnouncementType - This type represents the type of an announcement. It can be one of the following values:

| Value | Notes | | ------------ | ----------------------------------------- | | 'new' | Represents a new announcement. | | 'info' | Represents an informational announcement. | | 'critical' | Represents a critical announcement. |

Receiving Announcements via GET Request

The response body with your announcements must contain a key data with the value of an array conforming to the type Announcement[]. Sibyl, by design, is associating the location of fetched values from GET requests to that key.

res.body = {
  data: [
    /// *** Your Announcements
  ];
}

Receiving Announcements manually

Pass the announcements as an array as part of your SibylConfig instance. Alternatively use the refreshAnnouncements method from SibylService.

Configuring Appearance

The library comes with default styling based on css tokens (e.g. --some-colour-one).

If your consumer app uses an Angular Material version injecting tokens as part of the app's theming (tested with AM ver. 16+), Sibyl will integrate those Material colour values and adjust its own theming accordingly. Alternatively, you can always take advantage of the AppearanceConfig and granularly customise the look of the library.

AppearanceConfig accepts the following values:

• Colours as you'd define them in your stylesheet (e.g. HEX values, CSS colour names, etc.)
• Font-family names for typography as you'd define them in your stylesheet.
• Your own tokens for colours or font-family names available across your app (e.g. --my-primary-colour).
• Strings of text to be shown in critical places across the library.
• Strings of text representing a determinate configuration value (e.g. 'bottom-right' for positioning).
• Number of milliseconds for durations and delays.

The SibylAppearanceOptions type combines the following properties. Each one is optional and can be used to adjust a specific aspect of the library's appearance.

| Property | Notes | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | prominentTypography: string | Optional: Specifies the font to be applied to headers in components. Accepts tokens (--my-token) or 'font-family' value/s. | | typography: string | Optional: Specifies the font to be applied to ordinary text blocks and paragraphs. Accepts tokens (--my-token) or 'font-family' value/s. | | buttonIcon: string | Optional: Specifies the icon for the button. Uses Material Icons. | | buttonPosition: Positioning | Optional: Specifies the position of the button. Accepts 'bottom-left', 'bottom-right', 'top-right', or 'top-left'. | | materialColourVariant: MaterialVariants | Optional: If the project is using Angular Material, the library can adjust the colour scheme to match that of the core app. Accepts 'primary', 'accent', or 'warn'. | | primaryColourToken: string | Optional: Specifies the primary colour. Accepts tokens (--my-token) or colours. | | primaryLighterColourToken: string | Optional: Specifies a lighter variant of the primary colour. Accepts tokens (--my-token) or colours. | | errorColourToken: string | Optional: Specifies the colour for error accents. Accepts tokens (--my-token) or colours. | | errorLighterColourToken: string | Optional: Specifies a lighter colour variant of the error accents. Accepts tokens (--my-token) or colours. | | formHeading: string | Optional: Specifies the heading text for the form. | | formGuidanceShort: string | Optional: Specifies the shorter version of the guidance memo text for the form. | | formGuidanceLong: string | Optional: Specifies the longer version of the guidance memo text for the form. | | notificationDuration: number | Optional: Specifies the duration over which the notification with prominent announcements will be shown on first run - in milliseconds. | | shortDelay: number | Optional: Defines the minimum time interval between button reactions to prevent overzealous, repeated responses when several errors occur in quick succession - in milliseconds. | | longDelay: number | Optional: Specifies the delay time before the long animation (with floating 'REPORT IT HERE' memo) can be shown again - in milliseconds. |

Leveraging Error Interception Mechanism in Consumer App

Use the method notifySibylOfError() included as part of SibylService. Being a member of a service class, it can be leveraged across your entire app. It can be used to notify Sibyl of an error: upon calling, it triggers an animation on the button to attract the user's attention.

Dynamically Adjusting Form Request Body Content

Use the method appendToFormBody() included as part of SibylService. It may be used to update and append the body of the form POST request. Consider combining this solution with the one handling error occurrences (as above) or leverage it in some other as you see fit.

The body of the request is constructed by attaching the spread operator to the following properties. As such, the dynamic body context will override pre-existing keys in the hard-coded body content in your SibylConfig instance.

Sequentially:

• Form values,
• Hard-coded body content,
• Appended, dynamic body content.

You can clear the appended body content by using clearAppendedFormBodyContent() from SibylService. Considering the foregoing, the hard-coded body content provided in SibylConfig will not be affected.

Packaging of New Builds

1. In the main directory of the canvas workspace type in ng build sibyl-button which will create a build folder with the library.

2. Navigate to the dist folder where the contents of the build are located and open it in terminal.

3. Type in npm pack which will generate a .tgz package (without publishing it online).

4. The .tgz package is fully portable and you can place it wherever you might need it.

Troubleshooting

NodeJS.Timeout - Wrong namespace?

1. Navigate to tsconfig.app.json within your destination app.

2. Add node to your types array:

   /* To learn more about this file see: https://angular.io/config/tsconfig. */
   
   {
   	"extends": "./tsconfig.json",
   	"compilerOptions": {
   		"outDir": "./out-tsc/app",
   
   		// *** THIS ONE ***
   		"types": ["node"]
   	},
   	"files": ["src/main.ts", "src/polyfills.ts"],
   	"include": ["src/**/*.d.ts"]
   }

3. Restart your app to apply the new changes.