Skip to content

Commit 64cc0db

Browse files
CookiezaursCookiezaurs
authored
Merge pull request #5725 from Countly/guides-readme
readme file for guides plugin
2 parents afd822c + f5a51d4 commit 64cc0db

File tree

1 file changed

+187
-0
lines changed

1 file changed

+187
-0
lines changed

‎plugins/guides/README.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Guides plugin
2+
3+
## Overall behaviour
4+
5+
The guides plugin is a core plugin that provides interactive, in-app walkthroughs and articles for users to help them navigate and utilise features within the Countly application.
6+
7+
Guides are enabled if **enableGuides** is set to true in the CMS OR in the API config file (this allows us to enable them for a specific server). If Guides are disabled or no data is available for a specific plugin, we display the tooltip instead of the Guides button.
8+
9+
The Guides plugin data comes from the Countly CMS. When fetched, it is stored in **Countly DB** under the **cms_cache** collection and is refreshed periodically based on the **UPDATE_INTERVAL** variable set in the backend:
10+
If cms_cache is empty or the UPDATE_INTERVAL has passed, the data is fetched from the CMS. We can also force a refresh by calling the **clearCache** endpoint which clears the cms_cache collection.
11+
12+
## File structure
13+
14+
File structure follows usual Countly plugin structure
15+
16+
```
17+
plugins/guides
18+
├── api
19+
├── frontend/public
20+
│ ├── javascripts
21+
│ │ ├── countly.models.js # Guides model code; transforms backend data
22+
│ │ └── countly.views.js # Views code: handles all views/components
23+
│ ├── localization # Contains localization files
24+
│ ├── stylesheets # Contains stylesheets
25+
│ └── templates
26+
│ ├── guides.html # Main guides page template, covering all plugins
27+
│ ├── dialog.html # Template for the dialog that displays guides for each plugin
28+
│ ├── search.html # Template for the search bar within the guides section
29+
│ ├── search-result-tab.html # Template for the tab that shows search results in guides
30+
│ ├── tab.html # Generic tab template for organising walkthroughs/articles by section
31+
│ ├── articles-component.html # Component template for a list of articles
32+
│ ├── article-component.html # Component template for an individual article
33+
│ ├── walkthroughs-component.html # Component template for a list of walkthroughs
34+
│ ├── walkthrough-component.html # Component template for an individual walkthrough
35+
│ ├── overview-component.html # Component template for the overview section of guides
36+
│ └── overview-tab.html # Template for the tab that displays an overview of guides
37+
│
38+
├── install.js
39+
├── build.js
40+
├── package.json
41+
├── tests.js
42+
└── README.md
43+
```
44+
45+
Other relevant files:
46+
47+
```
48+
frontend
49+
│ ├── express/public/javascripts/countly
50+
│ └── countly.cms.js # Frontend file where requests to the backend are made
51+
│
52+
api
53+
├── parts/mgmt
54+
│ └── cms.js # Backend file where requests to the CMS are made
55+
└── config.js # API config file where we can enable guides
56+
57+
```
58+
59+
## Data structure
60+
61+
The guides data is stored in the **Countly CMS** with the following structure:
62+
```
63+
{
64+
"data": [
65+
{
66+
"id": 1,
67+
"attributes": {
68+
"sectionID": "/section",
69+
"sectionTitle": "Section",
70+
"createdAt": "date",
71+
"updatedAt": "date",
72+
"publishedAt": "date",
73+
"locale": "en",
74+
"walkthroughTitle": "Custom title for walkthroughs",
75+
"walkthroughDescription": "Custom description for walkthroughs",
76+
"articleTitle": "Custom title for articles",
77+
"articleDescription": "Custom description for articles",
78+
"articles": [
79+
{
80+
"id": 18,
81+
"title": "title",
82+
"url": "https://support.count.ly/path/to/article"
83+
}
84+
],
85+
"walkthroughs": [
86+
{
87+
"id": 17,
88+
"title": "title",
89+
"url": "https://demo.arcade.software/walkthrough"
90+
},
91+
{
92+
"id": 5,
93+
"title": "title",
94+
"url": "https://demo.arcade.software/walkthrough"
95+
}
96+
],
97+
"localizations": {
98+
"data":[]
99+
}
100+
}
101+
}
102+
....other sections
103+
],
104+
"meta": {
105+
"pagination": {
106+
"page": 1,
107+
"pageSize": 100,
108+
"pageCount": 1,
109+
"total": 1
110+
}
111+
}
112+
}
113+
114+
```
115+
116+
When fetched, the data is transformed and stored in the **Countly DB (cms_cache collection)**. The data for each section is stored in a separate document with the _id: "server-guides_{sectionID}"
117+
118+
The document has the following structure:
119+
```
120+
{
121+
"_id": "server-guides_1",
122+
"lu": timestamp,
123+
"sectionID": "/section",
124+
"sectionTitle": "Section",
125+
"createdAt": "date",
126+
"publishedAt": "date",
127+
"updatedAt": "date",
128+
"locale": "en",
129+
"articleDescription": "Custom description for articles",
130+
"articleTitle": "Custom title for articles",
131+
"walkthroughDescription": null,
132+
"walkthroughTitle": null,
133+
"articles": [
134+
{
135+
"id": 18,
136+
"title": "title",
137+
"url": "https://support.count.ly/path/to/article"
138+
}
139+
],
140+
"walkthroughs": [
141+
{
142+
"id": 17,
143+
"title": "title",
144+
"url": "https://demo.arcade.software/walkthrough"
145+
},
146+
{
147+
"id": 5,
148+
"title": "title",
149+
"url": "https://demo.arcade.software/walkthrough"
150+
}
151+
],
152+
"localizations": {
153+
"data": []
154+
}
155+
}
156+
157+
```
158+
In cms_cache, we also store the Guides configurations (such as whether the plugin is enabled, titles, descriptions etc) with the following structure:
159+
```
160+
{
161+
"_id": "server-guide-config_1",
162+
"enableGuides": true,
163+
"lu": timestamp,
164+
"createdAt": "date",
165+
"publishedAt": "date",
166+
"updatedAt": "date",
167+
"articleDescription": "Description",
168+
"articleTitle": "Title",
169+
"walkthroughDescription": "Description",
170+
"walkthroughTitle": "Title"
171+
}
172+
```
173+
174+
Lastly, in cms_cache, we store metadata for guides and guides configurations with the following structure:
175+
The lu (last updated) field lets us know when it is time to refresh the data from the CMS
176+
```
177+
{
178+
"_id": "server-guides_meta",
179+
"lu": timestamp
180+
}
181+
```
182+
```
183+
{
184+
"_id": "server-guide-config_meta",
185+
"lu": timestamp
186+
}
187+
```

0 commit comments

Comments
 (0)