You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
### Bug Fixes
- Fix Google chart rendering condition for Classic Plugin
- Changes the speed and position of the loading bar
### Improvements
- Add a Live Preview button for the plugin page on wordpress.org
- Added NPS survey
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+112-4Lines changed: 112 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,10 +7,118 @@ How to release a new version:
7
7
- Clone the master branch
8
8
- Do your changes
9
9
- Send a PR to master and merge it using the following subject message
10
-
-`release: <release short description>` - for patch release
11
-
-`release(minor): <release short description>` - for minor release
12
-
-`release(major): <release short description>` - for major release
13
-
The release notes will inherit the body of the commit message which triggered the release. For more details check the [simple-preset](https://github.com/Codeinwp/conventional-changelog-simple-preset) that we use.
10
+
-`release: <release short description>` - for patch release
11
+
-`release(minor): <release short description>` - for minor release
12
+
-`release(major): <release short description>` - for major release
13
+
The release notes will inherit the body of the commit message which triggered the release. For more details check the [simple-preset](https://github.com/Codeinwp/conventional-changelog-simple-preset) that we use.
14
+
15
+
## Architecture
16
+
17
+
### Introduction
18
+
19
+
The two main features are:
20
+
21
+
- data importing
22
+
- chart rendering
23
+
24
+
Those two options are present in the plugin dashboard and as Gutenberg blocks.
25
+
26
+
All the charts are saved as custom post type (`post_type=visualizer`), and the data is saved as post meta (with the prefix `visualizer-`). (Check plugin settings in `classes/Visualizer/Plugin.php`)
27
+
28
+
The charts can be embedded in page via shortcode or Gutenberg blocks.
29
+
30
+
### Data Importing
31
+
32
+
For data importing, the most basic usage is using a CSV or JSON file. The source can be an uploaded file or a URL. The data is then parsed and stored in a format that can be used by the chart rendering feature.
33
+
34
+
For parsing the CSV and JSON files, we use built-in PHP functions.
35
+
36
+
> [!NOTE]
37
+
> The `samples` folder contains some sample data files that can be used for testing.
38
+
39
+
Advanced data importing features include data from:
40
+
41
+
- a database using a query;
42
+
- post meta values withing a desired `post_type`;
43
+
- WooCommerce Report API;
44
+
- from other charts;
45
+
- manually inputted data with the build-in editor.
46
+
47
+
Related code is in `classes/Visualizer/Source`. Pro Features like database import are in `visualizer-pro` plugin on `inc/addon.php`.
48
+
The rendering for Import dashboard is done in `classes/Visualizer/Render/Layout.php`; for Gutenberg Blocks check `classes/Visualizer/Gutenberg/src/Components/Import`.
49
+
50
+
### Chart Rendering
51
+
52
+
The chart rendering is done with the help of the [Chart.js](https://www.chartjs.org/) library. The plugin uses the `chartjs` library to render the charts.
53
+
54
+
The workflow for rendering a chart is:
55
+
56
+
- We add markup for the chart in the page; ( `[visualizer id="5295" lazy="no" class=""]` can be rendered via shortcode or Gutenberg block with function `gutenberg_block_callback` in `Block.php`);
57
+
- We load the data into the global object `window.visualizer`. (Beside the object, and endpoint is also created for fetching the data, available with `rest_url` property);
58
+
- Using js (with `render-facade.js`), we search the markup in the page, and using the stored ID, we pull the data from the global object and initiate the chart rendering.
59
+
60
+
Check the class `Visualizer_Module_Frontend` to see all the hooks and filters that are used to render the charts.
61
+
62
+
### Data handling
63
+
64
+
While the data importing and rendering are the main selling points, the most of work is done in the data handling which includes interface rendering, storing, and fetching the data.
65
+
66
+
The Charts menu settings are available in `Chart Library` page in the admin dashboard, but also in the block `Inspector` as part of the Gutenberg block. The first is done via PHP and jQuery, and the second is done via React. Any design changes should be done in both places.
67
+
68
+
Same thing for chart library visualization, it can be either from admin dashboard or from Gutenberg block.
69
+
70
+
> [!NOTE]
71
+
> The plugin tries to offer seamless experience for both classic and Gutenberg editor. But the bugs resulted might be different, especially in the Gutenberg editor where changes are happening frequently.
72
+
73
+
> [!NOTE]
74
+
> Unlike the jQeury, the Gutenberg block require a build step, you will need to install all the NPM dependencies and run `npm run dev` or `npm run build` to see the changes.
75
+
76
+
### Setup Wizard
77
+
78
+
The `Setup Wizard` is an onboarding process that helps the user to set up its first chart. When the plugin is installed for the first time, the user is redirected to the wizard.
79
+
80
+
The steps includes:
81
+
82
+
1. Choosing the chart type;
83
+
2. Importing the sample data;
84
+
3. Asking the user if he wants a draft page to show the chart;
85
+
4. Promotion (optional);
86
+
5. Email subscription;
87
+
6. Redirect to draft page if the user marked the option at step 3. Otherwise, redirect to the plugin dashboard.
88
+
89
+
The page rendering is done using the `setup-wizard.php` file, and the server logic is in the `Visualizer_Module_Wizard` class. A jQuery script (`setup-wizard`) is used to handle the interactions.
90
+
91
+
> [!NOTE]
92
+
> The usual process include showing the promotion and email collection form. Those are hidden when the `preview` query parameter is present in the URL. The Preview is used as demo presentation for the `Live Preview` feature of the WordPress store.
93
+
94
+
### Quirks
95
+
96
+
#### Number Formatting
97
+
98
+
The workflow for adding a chart with number formatting is:
99
+
100
+
1. Select the chart;
101
+
2. Add the data without any other specific sign (`$`, `%`, `.`, etc.) -- `2.5` will be added as `25`;
102
+
3. Generate the chart;
103
+
4. Add number formatting (`#.#` for `2.5`).
104
+
105
+
For displaying data mentioning a percentage (%), amount, or any other specific signs ($, €, etc.); you need to specify the correct number formatting.
106
+
107
+
Percentage:
108
+
109
+
1. When manually inputting the data, if you want to display 80%, you need to add it as `0.8`.
110
+
2. Then you go trough the number formatting box and input `#%`.
111
+
112
+
Amounts:
113
+
114
+
1. For inputting amounts like `2,345`, you need to input it as `2345`.
115
+
2. Then you go to number formatting and input `#,###`.
116
+
3. Same thing for `2.5`, you need add the format as `#.#`.
117
+
118
+
For specific signs:
119
+
120
+
1. For displaying a sign like `$` (like `$2.345`), you need to follow the same steps as for the amount.
0 commit comments