angular-walkthrough
v0.11.0
Published
Walkthrough, an Angular library
Downloads
377
Readme
Walkthrough
This Angular model is inspired in part by ng-walkthrough for AngularJS.
Installation
npm i angular-walkthrough --save
Requirements
- Angular
16.1
and more - Angular/cdk
16.1
and more
Old versions:
- For Angular 6~11 use
0.8.2
- For Angular 11~15 use
0.9.8
Demo
Usage
ng-walkthrough
attributes
All attributes are optional.
id
: HTML id.
Output events
ready
: fired when the walkthrough is completely readyclosed
: fired when the walkthrough has been closed. It sends a boolean value set to true if the walkthrough has been closed with the "finishButton" button.finished
: fired when the walkthrough has been finished, which means : closed on last step.
Focus zone:
focusElementSelector
: CSS selector for focus a HTML element. If the selector detect more that one, the only the first will be chosen.focusElementCSSClass
: Add a class on focusElementfocusHighlightAnimation
:true
for show highlight animation on the focus element. By defaultfalse
.focusBackdrop
:true
for show a dark backdrop around the focus element. By defaultfalse
.focusGlow
:true
for show a glow on the focus element. By defaultfalse
.focusClick
: add an actionclick
on the highlight zone.typeSelector
: type of selection. Two modes possible:element
(one unique HTML element),zone
(a zone with contains the first and last element). By default :element
.radius
: apply a “borderRadius” on highlight zone. Ifnumber
the value as change in percent. Ifauto
use the focused element borderRadius. If it's a simplestring
, use it without changes. By default, no radius.marginZone
: add a margin of focus zone in px. (e.g.12 15 12 13
for CSS12px 15px 12px 13px
,12 15
for12px 15px 12px 15px
,12
for12px 12px 12px 12px
.)scrollOnTarget
: if the walkthrough detects thatfocusElementSelector
is outside of the current view, scrolls automatically. By default :true
visibilityCallback
: callback to check iffocusElementSelector
is hidden, only if the walkthrough needs specific verification. By default :optional
notScrollOnResize
: do not scroll when resizing (e.g. may be required with dynamic menu on mobile)observerOptions
: options of DOM detection changes (default:{ attributes: false, childList: true, subtree: true }
)
Content:
contentTemplate
: add ang-template
with your description.contentText
: show a simple description without formatting in content.contentStyle
: background style for content container. By default :darken
. Possible values:none
,darken
.alignContent
: align thecontentTemplate
horizontally. . By default :left
.left
: on the leftcenter
: on the center of the pageright
: on the rightcontent
: center to the target content
verticalAlignContent
: align thecontentTemplate
vertically. By default :top
. Possible values :- With target :
above
: above contenttop
: top of contentcenter
: center of contentbottom
: bottom of contentbelow
: below contenttop-screen-center
: no effect
- Without target
above
ortop
: top of the pagecenter
: center of the pagebottom
orbelow
: bottom of the pagetop-screen-center
: center on the screen with scroll on top
- With target :
contentSpacing
: The max space which separates the content to the focus zone horizontally, default is 0 (opposite of the focusZone)verticalContentSpacing
: The max space which separates the content to the focus zone vertically, default is 50rootElement
: root element on which walkthrough will scroll to after each positioning, as to avoid hidden zones
Navigation:
hidePrevious
:true
to hide the previous button. By defaultfalse
previousStep
: add a link to go to the previousng-walkthrough
.nextStep
: add a link to go to the nextng-walkthrough
.hideNext
: hide the next step link.HiveNav
: hide the navigation step links.closeButton
:true
for show the button. By defaultfalse
.closeAnywhere
:false
for click anywhere to close. By defaulttrue
.finishButton
:true
for show a link to exit. By defaultfalse
.disabled
:true
for ignoring the walkthrough based on a boolean flag. By defaultfalse
.texts
: change texts. It's an overlay ofWalkthroughText
.
Arrow:
showArrow
:true
for show the arrow. By defaultfalse
.arrowColor
: change the arrow color. By default#FFF
.
ng-walkthrough-flow
attributes
All attributes are optional and not overriding the sub-components attributes except previousStep
, nextStep
that will be ignored.
id
: HTML id.
Output events
closed
: fired when a walkthrough has been closed. It sends a boolean value set to true if the walkthrough has been closed with the "finishButton" button.finished
: fired when the last walkthrough has been closed.
Focus zone:
focusHighlightAnimation
:true
for show highlight animation on the focus element.focusBackdrop
:true
for show a dark backdrop around the focus element.focusGlow
:true
for show a glow on the focus element.radius
: apply a “borderRadius” on highlight zone. Ifnumber
the value as change in percent. Ifauto
use the focused element borderRadius. If it's a simplestring
, use it without changes.marginZone
: add a margin of focus zone in px. (e.g.12 15 12 13
for CSS12px 15px 12px 13px
,12 15
for12px 15px 12px 15px
,12
for12px 12px 12px 12px
.)notScrollOnResize
: do not scroll when resizing (e.g. may be required with dynamic menu on mobile)observerOptions
: options of DOM detection changes (default:{ attributes: false, childList: true, subtree: true }
)
Content:
contentStyle
: background style for content container. Possible values:none
,darken
.rootElement
: root element on which walkthrough will scroll to after each positioning, as to avoid hidden zones (facultative)
Navigation:
hidePrevious
:true
to hide the previous button. By defaultfalse
closeButton
:true
for show the button.closeAnywhere
:false
for for click anywhere to close.texts
: change texts. It's a overlay ofWalkthroughText
.finishButton
:true
for show a link to exit. By defaultfalse
. Alwaystrue
on the last step.
Arrow:
showArrow
:true
for show the arrow. By defaultfalse
.arrowColor
: change the arrow color. By default#FFF
.
Change texts
It's possible to change all texts. With the texts
directive attribute.
WalkthroughText {
previous = 'Previous';
next = 'Next';
close = 'Close';
}
Statics methods
WalkthroughComponent.walkthroughStop()
: hide and stop the current walkthrough (impossible to open a new walkthrough). Does not work if no walkthrough is showed.WalkthroughComponent.walkthroughContinue()
: show and continue the current walkthrough. Does not work if no walkthrough is paused.WalkthroughComponent.walkthroughHasShow()
: if the a walkthrough is currently showing.WalkthroughComponent.walkthroughNext()
: to load the next walkthrough.WalkthroughComponent.walkthroughPrevious()
: to load the previous walkthrough.
Statics observable
WalkthroughComponent.onOpen
: on openWalkthroughComponent.onRefresh
: on reshowing the current stepWalkthroughComponent.onClose
: on closeWalkthroughComponent.onFinish
: on close in the last stepWalkthroughComponent.onNavigate
: on navigateWalkthroughComponent.onNavigatePrevious
: on navigate on the previous stepWalkthroughComponent.onNavigateNext
: on navigate on the next step
Example
Highlighting #selectorId
element with example text in ng-template
.
<ng-walkthrough
id="wt-test"
focusElementSelector="#selectorId"
focusBackdrop="true"
[contentTemplate]="template"
closeButton="true"
>
<ng-template #template>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit...</p>
</ng-template>
</ng-walkthrough>
Example of scenario with ng-walkthrough-flow
:
<ng-walkthrough-flow
#walkFlow
id="wt-test-flow"
focusBackdrop="true"
focusHighlightAnimation="true"
closeButton="true"
closeAnywhere="false"
showArrow="true"
radius="auto"
[texts]="frenchText"
>
<ng-walkthrough
id="wt-test1-flow"
focusElementSelector="#test1"
[contentText]="Lorem ipsum dolor sit amet, consectetur adipiscing elit..."
>
</ng-walkthrough>
<ng-walkthrough
id="wt-test2-flow"
focusElementSelector="#test2"
[contentText]="Lorem ipsum dolor sit amet, consectetur adipiscing elit..."
>
</ng-walkthrough>
<ng-walkthrough
id="wt-test3-flow"
focusElementSelector="#test3"
closeButton="true"
[contentText]="Lorem ipsum dolor sit amet, consectetur adipiscing elit..."
>
</ng-walkthrough>
</ng-walkthrough-flow>
For more examples, see examples/example.component.html
.
Publishing the library
npm run build:lib
cd dist/angular-walkthrough
npm publish
License
Like Angular, this module is released under the permissive MIT license. Your contributions are always welcome.