Skip to content

Latest commit

 

History

History
163 lines (112 loc) · 6.89 KB

README.md

File metadata and controls

163 lines (112 loc) · 6.89 KB

Ng-EnjoyHint

EnjoyHint is a web-tool that provides the simplest way to create interactive tutorials and hints for your site or web-application. It can also be used to highlight and sign application elements.

Ng-EnjoyHint is an rewrite of EnjoyHint that removes jQuery and brings a native Angular experience.

Installation

npm install ng-enjoyhint

Usage

  • Inject the NgEnjoyHintService into your component.
    private readonly enjoyHintService = inject(NgEnjoyHintService);
  • Call runTutorial() to run the tutorial.
    await this.enjoyHintService.runTutorial(
      [
        {
          selector: ".my-element",
          event: "click",
          description: "Click on this element",
        },
        {
          selector: ".my-other-element",
          event: "click",
          description: "Now click over here",
        },
      ]
    );

How it works

When running a tutorial, an overlay is added to the page. Four semi-transparent elements, one on each side of the target element, de-emphasize the rest of the page and block user input. A description is shown on the side of the target element. The user can complete the configured event (normally a click) on the target element to advance to the next step of the tutorial. When the last step is completed, the overlay is removed.

License

MIT

API

EnjoyHintService

Methods

runTutorial()

runTutorial(steps, options?): Promise<boolean>

Run an interactive tutorial

Parameters
Parameter Type Description
steps ITutorialStep[] the tutorial steps to run
options? Partial<IEnjoyHintOptions> optional object to override the default behavior
Returns

Promise<boolean>

a promise resolving when the tutorial is closed; resolves to true if the tutorial was completed, false if it was skipped

Source

lib/enjoyhint.service.ts:35


IButtonOptions

Custom settings for a tutorial button

Properties

Property Type Description
className? string Custom CSS class to apply to the button
text string Text to display on the button

IEnjoyHintOptions

Properties

Property Type Description
backdropColor string Color of the backdrop overlay. Accepts any valid CSS color value.

Default
'black'
backdropOpacity number Opacity of the backdrop overlay. Higher values makes text more readable.

Default
0.75
fontFamily string Font family to use for the tutorial text and buttons.

Default
'sans-serif'
foregroundColor string Color of text and arrow elements.

Default
'white'
nextButton IButtonOptions Custom settings for the "Next" button.

Default
{ text: 'Next' }
overlayZIndex? number Z-index of the backdrop.

Default
1000 (from @angular/cdk/overlay)
padding number Amount of space between the edge of the current step's target element and the backdrop (in pixels)

Default
5
previousButton IButtonOptions Custom settings for the "Previous" button.

Default
{ text: 'Previous' }
skipButton IButtonOptions Custom settings for the "Skip" button.

Default
{ text: 'Skip' }

ITemplateWithContext<T>

Type parameters

Type parameter Value
T unknown

Properties

Property Type
context T
template TemplateRef<T>

ITutorialStep

Properties

Property Type Description
description string | TemplateRef<any> The main instructions for the step. Keep this short.
details? string | TemplateRef<any> | ITemplateWithContext<unknown> Additional text displayed in a smaller font under the description.
May be longer (but not too long).
event string The event to listen for on the element to move onto the next step.
Accepts any valid DOM event name, or 'next' to move on when the "Next" button is clicked.
hidePrevious? boolean Whether or not to hide the "Previous" button.

Default
false
hideSkip? boolean Whether or not to hide the "Skip" button.

Default
false
nextButton? IButtonOptions Custom settings for the "Next" button.
previousButton? IButtonOptions Custom settings for the "Previous" button.
selector? string The CSS selector for the element to focus on. If not specified, the
provided instructions will display in the center of the screen.
skipButton? IButtonOptions Custom settings for the "Skip" button.
stepEnd? () => void | Promise<void> Callback to execute when the step is ended.
stepStart? () => void | Promise<void> Callback to execute when the step is started.