Skip to content

Commit f4b4b81

Browse files
topicustopicus
committed
Improve dkan_dash documentation
1 parent 7e1f0a3 commit f4b4b81

File tree

1 file changed

+101
-20
lines changed

1 file changed

+101
-20
lines changed

‎README.md

+101-20
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,103 @@ As an example of what you might get from wiring it all up, here is a screenshot
1616

1717
Changing the filter values at the top will reload the data -- and, in some cases, change the layout -- of the visualizations below them.
1818

19+
## Anatomy of a dashboard
20+
- Settings file: it holds all the configuration required to instantiate a dashboard.
21+
- Data Handlers: a set of functions to adapt the raw data for each component.
22+
- State handlers: a set of functions to manipulate the application state base on conditions.
23+
- Custom components: components that are not included in the react-dash library and you need to create ad hoc for your project.
24+
25+
## Settings object
26+
Dashboard are just javascript objects. Concretely a settings object that stores all the required information to built a dashboard. Namely: layouts, components, data sources, data handlers, etc.
27+
28+
You have two options to start a DKAN Dash project:
29+
30+
1. Use the module as it is without any custom component.
31+
2. Add customizations like components and data handlers.
32+
33+
The second option is by far the most common scenario.
34+
35+
Just remember that all the customizations needs to happen inside the `custom_dash` module. Don't hack dkan_dash.
36+
37+
This setting object can be placed either in a file or in the database.
38+
39+
**IMPORTANT: Database stored settings always takes precedent over file stored settings**
40+
41+
### Database stored settings
42+
This option is ideal when you need to perform updates in your dashboard without push any code. For example, if you need to change the dashboard title, chart colors, field names, etc.
43+
44+
### File stored settings
45+
For developers it's easy to work with files. Files can be tracked by a control version system so it's easy to rollback when something wrong happens.
46+
47+
By convention, the settings files should be placed in `custom_dash/js/src` and with the suffix `Settings` named like `dashboardNameSettings.js`.
48+
49+
**In order to use an object stored in a file you will need to follow some conventions:**
50+
51+
- All the dashboard settings should be stored at `Drupal.settings.dkanDash.devSettings.some__uri`
52+
- Each devSettings key is a dashboard setting object
53+
- Dashboard settings are pick base on the path. For example, for the path `dashboard/people` you need a key `dashboard__people` in the `Drupal.settings.dkanDash.devSettings` object.
54+
- Setting objects should not contain functions. To transform data, data handlers are the way to go. Remember you can create and use your own components.
55+
56+
## Quick start
57+
58+
### Requirements
59+
- DKAN
60+
- react-dash
61+
- npm or yarn
62+
63+
### Steps
64+
1. Make sure you have JSONEditor and react-dash libraries in the libraries directory.
65+
2. Download and enable dkan_dash.
66+
3. Go to `/node/add/react-dashboard`
67+
4. Set a title
68+
5. Switch the JSONEditor to code mode.
69+
6. Copy and paste the following JSON object and save
70+
71+
```
72+
{
73+
"title": "A dashboard title",
74+
"regions": [
75+
{
76+
"id": "some-region",
77+
"children": [
78+
{
79+
"id": "hello",
80+
"type": "Markup",
81+
"content": "<h1>Hello</h1>"
82+
}
83+
]
84+
}
85+
]
86+
}
87+
```
88+
89+
## Customizations
90+
By default react-dash was created to be customized. These may include data handlers, custom components, state handlers, etc.
91+
92+
### Before start
93+
Because all the custom code is transpiled all the files must reside inside the directory `custom_dash/src/js`. Files outside that folder will be ignored.
94+
Beside this, you also need import your files within `custom_dash/src/js/index.js`. By doing this, babel (the tranpiler) knows which files should be transpiled and which ignored.
95+
96+
## How to transpile your custom code
97+
```
98+
> yarn
99+
> yarn run dev
100+
```
101+
102+
## Extended workflow
103+
104+
Sometimes it's useful to develop react-dash features while you are working in a project. Without the extended workflow if you need to add a new feature to react-dash and test that in your project you will need to rebuild react-dash, copy distribution files, rebuild dkan_dash, etc.
105+
106+
Custom Dash build process allow you to define some environment variables indicating where `react-dash` and `dkan_dash` repositories are located and thus perform the build steps automatically.
107+
108+
```
109+
> yarn
110+
> export REACT_DASH_PATH=/path/to/react/dash
111+
> export REACT_DASH_PATH=/path/to/dkan_dash
112+
> yarn run dev
113+
```
114+
115+
19116
## Who DKAN Dash is for
20117
We built DKAN Dash as a way to do complex custom data visualization dashboards in a repeatable way using DKAN's [Datastore API](http://docs.getdkan.com/en/stable/apis/datastore-api.html) as a data backend. DKAN Dash and its supporting ecosystem are really a development framework that allows for highly customizable data visualizations while minimizing boilerplate code and unnecessary repetition.
21118

@@ -74,24 +171,8 @@ The react-dash library [ships with an example project](https://github.com/NuCivi
74171
## Further reading
75172

76173
1. The [React Dash](https://react-dashboard.readthedocs.io) documentation is a complete resource for information on the standalone library.
77-
2. Take a look at the files in the [custom_dash](https://github.com/NuCivic/custom_dash) repo to see how a specific implementation would be structured.
78-
3. Look for news and updates on the [DKAN blog](http://getdkan.com/blog/)
79-
4. Join the `#dashboards` channel on the [DKAN Community Slack](https://dkansignup.herokuapp.com/)
174+
3. Take a look at the [Dkan documentation](http://dkan.readthedocs.io/en/latest/)
175+
4. Take a look at the files in the [custom_dash](https://github.com/NuCivic/custom_dash) repo to see how a specific implementation would be structured.
176+
5. Look for news and updates on the [DKAN blog](http://getdkan.com/blog/)
177+
6. Join the `#dashboards` channel on the [DKAN Community Slack](https://dkansignup.herokuapp.com/)
80178

81-
## Development
82-
83-
## Normal workflow
84-
```
85-
> yarn
86-
> npm run dev
87-
```
88-
89-
## Extended workflow
90-
The extended workflow includes changes in react-dash library. Sometimes it's useful to work with dkan_dash and react-dash at the same time. For such cases you might want to compile react-dash, copy the files to dkan_dash and then compile dkan_dash.
91-
However this is not very straight forward so dkan_dash build grab from the environment variable REACT_DASH_PATH the path to the react-dash library in order to do this process automatically.
92-
93-
```
94-
> yarn
95-
> export REACT_DASH_PATH=/path/to/react/dash
96-
> yarn run dev
97-
```

0 commit comments

Comments
 (0)