-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathcompositor.json
143 lines (143 loc) · 16.6 KB
/
compositor.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
{
"name": "code-orange/telemachy",
"version": "0.1.4",
"libraries": {
"xv": "^1.1.25"
},
"title": "Telemachy",
"branch": "master",
"style": {
"name": "Default",
"componentSet": {
"nav": "nav/BasicNav",
"header": "header/BannerHeader",
"article": "article/BasicArticle",
"footer": "footer/BasicFooter"
},
"fontFamily": "-apple-system, BlinkMacSystemFont, sans-serif",
"fontWeight": 400,
"bold": 600,
"lineHeight": 1.5,
"typeScale": [
72,
48,
24,
20,
16,
14,
12
],
"monospace": "Menlo, monospace",
"heading": {
"fontFamily": null,
"fontStyle": null,
"fontWeight": 600,
"lineHeight": 1.25,
"textTransform": null,
"letterSpacing": null
},
"h0": {},
"h1": {},
"h2": {},
"h3": {},
"h4": {},
"h5": {},
"h6": {},
"alternativeText": {},
"space": [
0,
8,
16,
32,
48,
64,
96
],
"layout": {
"maxWidth": 1024,
"centered": false
},
"colors": {
"text": "#111",
"background": "#fff",
"primary": "#08e",
"secondary": "#059",
"highlight": "#e08",
"border": "#ddd",
"muted": "#eee"
},
"border": {
"width": 1,
"radius": 2
},
"link": {},
"button": {
"hover": {
"boxShadow": "inset 0 0 0 999px rgba(0, 0, 0, .125)"
}
},
"input": {},
"body": {
"margin": 0
},
"breakpoints": {
"xs": "@media screen and (max-width:40em)",
"sm": "@media screen and (min-width:40em)",
"md": "@media screen and (min-width:52em)",
"lg": "@media screen and (min-width:64em)"
}
},
"content": [
{
"component": "nav",
"links": [
{
"href": "https://github.com/code-orange/telemachy",
"text": "GitHub"
},
{
"href": "https://npmjs.com/package/telemachy",
"text": "npm"
}
]
},
{
"component": "header",
"heading": "telemachy",
"subhead": "Easy guided tours for Angular apps",
"children": [
{
"component": "ui/TweetButton",
"text": "telemachy: Easy guided tours for Angular apps",
"url": null
},
{
"component": "ui/GithubButton",
"user": "code-orange",
"repo": "telemachy"
}
],
"text": "v2.0.4"
},
{
"component": "article",
"metadata": {
"source": "github.readme"
},
"html": "<h1>Telemachy <a href=\"https://www.npmjs.com/package/telemachy\"><img src=\"https://img.shields.io/npm/v/telemachy.svg?style=flat-square\"></a> <a href=\"https://npmjs.org/package/telemachy\"><img src=\"http://img.shields.io/npm/dt/telemachy.svg?style=flat-square\"></a> <a href=\"https://www.npmjs.com/package/telemachy\"><img src=\"https://img.shields.io/npm/l/telemachy.svg?style=flat-square\"></a></h1>\n\n<p><img src=\"demo.gif\"></p>\n<h2>Table of contents</h2>\n<ul>\n<li><a href=\"#getting-started\">Getting started</a><ul>\n<li><a href=\"#installation\">Installation</a></li>\n<li><a href=\"#usage\">Usage</a><ul>\n<li><a href=\"#persistency\">Persistency</a></li>\n<li><a href=\"#restarting-a-tour\">Restarting a tour</a></li>\n<li><a href=\"#api\">API</a></li>\n</ul>\n</li>\n<li><a href=\"#telemachyservice\">TelemachyService</a></li>\n<li><a href=\"#tourpersistency\">TourPersistency</a></li>\n<li><a href=\"#youtubetourstep\">YoutubeTourStep</a></li>\n<li><a href=\"#htmltourstep\">HTMLTourStep</a></li>\n<li><a href=\"#elementtourstep\">ElementTourStep</a></li>\n</ul>\n</li>\n</ul>\n<h2>Getting started</h2>\n<h3>Installation</h3>\n<pre>yarn add telemachy\n<span class=\"hljs-comment\"># or</span>\nnpm install --save telemachy</pre><p>Import <code>TelemachyModule</code> in your root module (make sure the <code>RouterModule</code> is loaded, Telemachy uses it to automatically start the tour for any compontent that a user navigates to):</p>\n<pre><span class=\"hljs-keyword\">import</span> { NgModule } <span class=\"hljs-keyword\">from</span> <span class=\"hljs-string\">'@angular/core'</span>;\n<span class=\"hljs-keyword\">import</span> { BrowserModule } <span class=\"hljs-keyword\">from</span> <span class=\"hljs-string\">'@angular/platform-browser'</span>;\n<span class=\"hljs-keyword\">import</span> { RouterModule } <span class=\"hljs-keyword\">from</span> <span class=\"hljs-string\">'@angular/router'</span>;\n\n<span class=\"hljs-keyword\">import</span> { TelemachyModule } <span class=\"hljs-keyword\">from</span> <span class=\"hljs-string\">'telemachy'</span>;\n\n<span class=\"hljs-keyword\">import</span> { AppComponent } <span class=\"hljs-keyword\">from</span> <span class=\"hljs-string\">'./app.component'</span>;\n\n<span class=\"hljs-meta\">@NgModule</span>({\n imports: [BrowserModule, RouterModule.forRoot([]), TelemachyModule],\n declarations: [AppComponent],\n bootstrap: [AppComponent]\n})\n<span class=\"hljs-keyword\">export</span> <span class=\"hljs-keyword\">class</span> AppModule {}</pre><p>Finally, add the <code><telemachy-tour></code> component to your root app component (or one that is always loaded when you want to display a tour):</p>\n<pre><span class=\"hljs-keyword\">import</span> { Component } <span class=\"hljs-keyword\">from</span> <span class=\"hljs-string\">'@angular/core'</span>;\n\n<span class=\"hljs-meta\">@Component</span>({\n selector: <span class=\"hljs-string\">'app-root'</span>,\n template: <span class=\"hljs-string\">`<telemachy-tour></telemachy-tour><router-outlet></router-outlet>`</span>\n})\n<span class=\"hljs-keyword\">export</span> <span class=\"hljs-keyword\">class</span> RootComponent {}</pre><h3>Usage</h3>\n<p>In its easiest form, you can use Telemachy just by implementing the <code>HasGuidedTour</code> interface:</p>\n<pre><span class=\"hljs-meta\">@Component</span>({\n selector: <span class=\"hljs-string\">'app-complex-component'</span>,\n templateUrl: <span class=\"hljs-string\">'./complex-component.component.html'</span>\n})\n<span class=\"hljs-keyword\">export</span> <span class=\"hljs-keyword\">class</span> ComplexComponent <span class=\"hljs-keyword\">implements</span> HasGuidedTour {\n tourAutoStart() {<span class=\"hljs-keyword\">return</span> <span class=\"hljs-literal\">true</span>;}\n getTour():TourStep[] {\n <span class=\"hljs-keyword\">return</span> [\n <span class=\"hljs-keyword\">new</span> YoutubeTourStep(<span class=\"hljs-string\">'l9xU1WpdmVY'</span>),\n <span class=\"hljs-keyword\">new</span> ElementTourStep(<span class=\"hljs-string\">'#complex-thing'</span>, <span class=\"hljs-string\">'Here, I will explain this.'</span>),\n <span class=\"hljs-keyword\">new</span> ElementTourStep(<span class=\"hljs-string\">'#second-complex-thing'</span>, <span class=\"hljs-string\">'Then, I will explain this.'</span>),\n <span class=\"hljs-keyword\">new</span> HTMLTourStep(<span class=\"hljs-string\">`Finally, we are <em>done</em>!`</span>)\n ];\n }\n}</pre><p>By implementing the optional <code>tourAutoStart()</code> method (and having it return <code>true</code>), Telemachy will automatically start this component's tour whenever it becomes active through the angular router.\nYou can also explicitly say it should be started by calling <code>TelemachyService.startTour(this)</code>.\nIn both cases, Telemachy will only show the tour if the persistency layer says the user should see it.</p>\n<h4>Persistency</h4>\n<p>By default, Telemachy will always show a user the tour on each visit.\nIf you want to save if a user has already seen a tour, you should provide an alternate implementation for the <code>TourPersistency</code> service.</p>\n<p>Telemachy comes with an alternate implementation that uses localstorage to save this state.\nThis implementation depends on <a href=\"https://github.com/phenomnomnominal/angular-2-local-storage\">phenomnomnominal/angular-2-local-storage</a>.\nYou can use this as follows:</p>\n<pre><span class=\"hljs-keyword\">import</span> { LocalStorageModule, LocalStorageService } <span class=\"hljs-keyword\">from</span> <span class=\"hljs-string\">'angular-2-local-storage'</span>;\n<span class=\"hljs-keyword\">import</span> { TelemachyModule, TourPersistency, LocalstorageTourPersistencyFactory } <span class=\"hljs-keyword\">from</span> <span class=\"hljs-string\">'telemachy'</span>;\n\n<span class=\"hljs-meta\">@NgModule</span>({\n imports: [BrowserModule, LocalStorageModule.withConfig(), TelemachyModule],\n declarations: [AppComponent],\n bootstrap: [AppComponent],\n providers: [\n {provide: TourPersistency, useFactory: LocalstorageTourPersistencyFactory, deps: [LocalStorageService]}\n ]\n})\n<span class=\"hljs-keyword\">export</span> <span class=\"hljs-keyword\">class</span> AppModule {}</pre><p>We recommend you replace the <code>TourPersistency</code> service with an implementation that saves the user's state in a remote system, for instance through a REST API.</p>\n<h4>Restarting a tour</h4>\n<p>You can restart the tour for a currently visible component by calling <code>TelemachyService.restartTour()</code>.\nTo check if there is a currently visible component that has a tour, use <code>TelemachyService.canRestart()</code>.</p>\n<h2>API</h2>\n<h3>TelemachyService</h3>\n<pre><span class=\"hljs-keyword\">class</span> TelemachyService {\n <span class=\"hljs-comment\">/**\n * Attempt to start the tour for a component\n * @param component\n */</span>\n startTour(component: HasGuidedTour): <span class=\"hljs-built_in\">void</span>;\n <span class=\"hljs-comment\">/**\n * Indicates if there is a tour that could be restarted\n *\n * @returns {boolean}\n */</span>\n canRestart(): <span class=\"hljs-built_in\">boolean</span>;\n <span class=\"hljs-comment\">/**\n * Restarts the tour for a component (no guarantee which) that is visible right now\n */</span>\n restartTour(): <span class=\"hljs-built_in\">void</span>;\n\n <span class=\"hljs-comment\">/**\n * Adds an event listener that is called at either the start or end of the tour.\n * Types are 'start' or 'end'\n * listener can't be an anonymous function else it is not possible to remove the callback.\n * \n * @param type string\n * @param listener function\n */</span>\n addEventListener(<span class=\"hljs-keyword\">type</span>: <span class=\"hljs-built_in\">string</span>, listener:<span class=\"hljs-function\"><span class=\"hljs-params\">()</span> =></span> <span class=\"hljs-built_in\">void</span>): <span class=\"hljs-built_in\">void</span>;\n\n <span class=\"hljs-comment\">/**\n * Removes an event listener.\n * Types are 'start' or 'end'\n * listener should be the same function as the one that was added.\n * \n * @param type string\n * @param listener function\n */</span>\n removeEventListener(<span class=\"hljs-keyword\">type</span>: <span class=\"hljs-built_in\">string</span>, listener:<span class=\"hljs-function\"><span class=\"hljs-params\">()</span> =></span> <span class=\"hljs-built_in\">void</span>): <span class=\"hljs-built_in\">void</span>;\n\n canGoBack(): <span class=\"hljs-built_in\">boolean</span>;\n canFinish(): <span class=\"hljs-built_in\">boolean</span>;\n finish(): <span class=\"hljs-built_in\">void</span>;\n skip(): <span class=\"hljs-built_in\">void</span>;\n next(): <span class=\"hljs-built_in\">void</span>;\n previous(): <span class=\"hljs-built_in\">void</span>;\n <span class=\"hljs-keyword\">private</span> reset();\n <span class=\"hljs-keyword\">private</span> emit();\n subscribeStep(generatorOrNext?: <span class=\"hljs-built_in\">any</span>, error?: <span class=\"hljs-built_in\">any</span>, complete?: <span class=\"hljs-built_in\">any</span>): Subscription;\n readonly progress: <span class=\"hljs-built_in\">number</span>;\n readonly total: <span class=\"hljs-built_in\">number</span>;\n}</pre><h3>TourPersistency</h3>\n<pre><span class=\"hljs-keyword\">class</span> TourPersistency {\n <span class=\"hljs-comment\">/**\n * Whether a tour should be started\n *\n * @param componentName Name of the component that the user has arrived at\n * @returns {Observable<boolean>}\n */</span>\n shouldStart(componentName: <span class=\"hljs-built_in\">string</span>): Observable<<span class=\"hljs-built_in\">boolean</span>>;\n <span class=\"hljs-comment\">/**\n * Finish the tour for a component\n * @param componentName\n */</span>\n finish(componentName: <span class=\"hljs-built_in\">string</span>): <span class=\"hljs-built_in\">void</span>;\n <span class=\"hljs-comment\">/**\n * Skip the tour for a component\n * @param componentName\n */</span>\n skip(componentName: <span class=\"hljs-built_in\">string</span>): <span class=\"hljs-built_in\">void</span>;\n}</pre><h3>YoutubeTourStep</h3>\n<pre><span class=\"hljs-comment\">/**\n * Tour step that shows a Youtube video in the middle of the page\n */</span>\n<span class=\"hljs-keyword\">class</span> YoutubeTourStep <span class=\"hljs-keyword\">extends</span> TourStep {\n <span class=\"hljs-comment\">/**\n * Video id\n */</span>\n video: <span class=\"hljs-built_in\">string</span>;\n <span class=\"hljs-keyword\">constructor</span>(<span class=\"hljs-params\">video: <span class=\"hljs-built_in\">string</span></span>);\n}</pre><h3>HTMLTourStep</h3>\n<pre><span class=\"hljs-comment\">/**\n * Tour step that shows some HTML in the middle of the page\n */</span>\n<span class=\"hljs-keyword\">class</span> HTMLTourStep <span class=\"hljs-keyword\">extends</span> TourStep {\n <span class=\"hljs-comment\">/**\n * HTML to display in this step\n */</span>\n body: <span class=\"hljs-built_in\">string</span>;\n <span class=\"hljs-keyword\">constructor</span>(<span class=\"hljs-params\">body: <span class=\"hljs-built_in\">string</span></span>);\n}</pre><h3>ElementTourStep</h3>\n<pre><span class=\"hljs-comment\">/**\n * Tour step that highlights an element on the page with some explanation\n */</span>\n<span class=\"hljs-keyword\">class</span> ElementTourStep <span class=\"hljs-keyword\">extends</span> TourStep {\n <span class=\"hljs-comment\">/**\n * Element to highlight\n */</span>\n domElement: Element;\n <span class=\"hljs-comment\">/**\n * HTML to display in this step\n */</span>\n body: <span class=\"hljs-built_in\">string</span>;\n <span class=\"hljs-keyword\">constructor</span>(<span class=\"hljs-params\">selector: <span class=\"hljs-built_in\">string</span>, body: <span class=\"hljs-built_in\">string</span>, <span class=\"hljs-keyword\">async</span>?: <span class=\"hljs-built_in\">boolean</span></span>);\n readonly top: string;\n readonly bottom: string;\n readonly left: string;\n readonly right: string;\n readonly documentHeight: string;\n readonly documentWidth: string;\n readonly toBottom: string;\n readonly toRight: string;\n readonly fromLeft: string;\n readonly fromTop: string;\n readonly height: string;\n readonly width: string;\n}</pre><p>If <code>async</code> is <code>true</code>, the <code>ElementTourStep</code> will attempt to find the element on the page after it has been initialized.\nIf the element isn't available by the time the step should be rendered, the step will be skipped. </p>\n<h3>Event Listeners</h3>\n<p>It is possible to add event listeners that are fired add the start of the tour \nor at the end of the tour when the finished/skipped button is clicked. \nPossible types: <code>start</code> or <code>end</code></p>\n<pre> <span class=\"hljs-keyword\">let</span> doSomething = <span class=\"hljs-function\"><span class=\"hljs-params\">()</span> =></span> <span class=\"hljs-built_in\">console</span>.log(<span class=\"hljs-string\">'something'</span>);\n <span class=\"hljs-keyword\">this</span>.TelemachyService.addEventListener(<span class=\"hljs-string\">'start'</span>, doSomething);\n <span class=\"hljs-keyword\">this</span>.TelemachyService.removeEventListener(<span class=\"hljs-string\">'start'</span>, doSomething);</pre>"
},
{
"component": "footer",
"links": [
{
"href": "https://github.com/code-orange/telemachy",
"text": "GitHub"
},
{
"href": "https://github.com/code-orange",
"text": "code-orange"
}
]
}
]
}