sibyl-button v4.1.4

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:

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>

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.

Creating an Announcement object

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

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

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.

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.