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
@@ -15,66 +15,216 @@ This page shows you how to customize the UI of your local instance. This is step
15
15
16
16
## Overview
17
17
18
-
The default custom Data Commons image provides a bare-bones UI that you will undoubtedly want to customize to your liking. Data Commons uses the Python [Flask](https://flask.palletsprojects.com/en/3.0.x/#) web framework and [Jinja](https://jinja.palletsprojects.com/en/3.1.x/templates/) HTML templates. If you're not familiar with these, the following documents are good starting points:
<td>Sample logo file – replace with your own.</td>
52
-
</tr>
53
-
</tbody>
54
-
</table>
55
-
56
-
Note that the `custom` parent directory is customizable as the `FLASK_ENV` environment variable. You can rename the directory as desired and update the environment variable in `custom_dc/env.list`.
57
-
58
-
If you have renamed the parent `custom` directory, be sure to use that name in the flag.
59
-
60
-
> **Note:** Currently, making changes to any of the files in the `static/` directory, even if you're testing locally, requires that you rebuild a local version of the repo to pick up the changes, as described in [Build a local image](/custom_dc/build_image.html#build-repo). We plan to fix this in the near future.
61
-
62
-
## Customize HTML templates {#html-templates}
63
-
64
-
You can customize the page header and footer (by default, empty) in [base.html](https://github.com/datacommonsorg/website/blob/master/server/templates/custom_dc/custom/base.html) by adding or changing the HTML elements within the `<header></header>` and `<footer></footer>` tags, respectively.
65
-
66
-
<!--TODO: Add an example of customization e.g. different colors or text-->
67
-
68
-
## Customize Javascript and styles {#styles}
69
-
70
-
Use the [overrides.css](https://github.com/datacommonsorg/website/blob/master/static/custom_dc/custom/overrides.css) file to customize the default Data Commons styles. The file provides a default color override. You can add all style overrides to that file.
71
-
72
-
Alternatively, if you have existing CSS and Javascript files, put them under the [/static/custom_dc/custom](https://github.com/datacommonsorg/website/blob/master/static/custom_dc/custom) folder. Then include these files in the `<head>` section of the corresponding HTML files as:
See [`server/templates/custom_dc/custom/new.html`](https://github.com/datacommonsorg/website/blob/master/server/templates/custom_dc/custom/new.html) as an example.
79
-
80
-
18
+
The Custom Data Commons image provides a default site user interface that you will want to customize. The site uses the Python [Flask](https://flask.palletsprojects.com/en/3.0.x/#){: target="_blank"} web framework, [React](https://react.dev/){: target="_blank"} Javascript components and [Jinja](https://jinja.palletsprojects.com/en/3.1.x/templates/){: target="_blank"} HTML templates.
19
+
20
+
This page describes how you can reuse and modify various code and configuration files that are provided for Custom Data Commons in the `website` repo.
21
+
22
+
{: #setup}
23
+
## Before you start: Set up your environment
24
+
25
+
The files that control the Custom Data Commons UI are in the following directories in the `website` repo:
26
+
-[`server/app_env/`](https://github.com/datacommonsorg/website/tree/master/server/app_env){: target="_blank"}: Python web server configuration
27
+
-[`server/templates/custom_dc/custom/`](https://github.com/datacommonsorg/website/tree/master/server/templates/custom_dc/custom){: target="_blank"}: Jinja HTML templates
28
+
-[`server/templates/tools/`](https://github.com/datacommonsorg/website/tree/master/server/templates/tools){: target="_blank"}: JSON files for visualization tools
29
+
-[`server/config/custom_dc/custom/`](https://github.com/datacommonsorg/website/tree/master/server/config/custom_dc/custom){: target="_blank"}: JSON files for layout elements
30
+
-[`static/custom_dc/custom/`](https://github.com/datacommonsorg/website/tree/master/static/custom_dc/custom){: target="_blank"}: CSS and image files
31
+
32
+
While it's possible to edit all of the files in place, this risks causing merge conflicts or overwrites whenever you sync to the latest stable release. Instead, we recommend the following procedure.
33
+
34
+
### Step 1: Set up your Flask templates environment
35
+
36
+
1. Choose a simple name for directories that will host template and static files, e.g. `myproject`.
37
+
1. Create a new subdirectory under `server/templates/custom_dc` using the new name. For example:
38
+
```
39
+
cd website/server/templates/custom_dc
40
+
mkdir myproject
41
+
```
42
+
1. For any of the HTML template files you would like to edit directly, copy them from the `custom` subdirectory into your new directory.
43
+
```
44
+
cp custom/*.html myproject/
45
+
```
46
+
For additional HTML files, you can store them here too; be sure to set required variables as described in the comments at the top of [`base.html`](https://github.com/datacommonsorg/website/blob/master/server/templates/custom_dc/custom/base.html){: target="_blank"}.
47
+
48
+
1. If you'd like to customize the examples that appear in the visualization tools, copy any or all of the JSON files from `server/templates/tools/` into your new directory.
49
+
```
50
+
cp ../tools/*.json myproject/
51
+
```
52
+
1. If you'd like to customize the menus and menu items that appear in the header, create a new `base` subdirectory under your directory and copy [`server/config/custom_dc/custom/base/header.json`](https://github.com/datacommonsorg/website/blob/master/server/config/custom_dc/custom/base/header.json){: target="_blank"} there.
1. Create a new subdirectory under `static/custom_dc/` using the same name you created in step 1.
62
+
```
63
+
cd website/static/custom_dc
64
+
mkdir myproject
65
+
```
66
+
1. Copy [`static/custom_dc/custom/overrides.css`](https://github.com/datacommonsorg/website/blob/master/static/custom_dc/custom/overrides.css){: target="_blank"} into this directory. You can use this file to define your own styles.
67
+
```
68
+
cp custom/overrides.css myproject/
69
+
```
70
+
1. Place your logo, image files and any custom Javascript and CSS files in this directory. In the relevant HTML template files (e.g. `base.html` etc.), be sure to add `script` and `link` elements to reference them. For example:
1. In your `custom_dc/env.list` file, set the `FLASK_ENV` variable to the same name you created in step 1:
83
+
```
84
+
FLASK_ENV=myproject
85
+
```
86
+
1. Copy and rename the file [`server/app_env/custom.py`](https://github.com/datacommonsorg/website/blob/master/server/app_env/custom.py){: target="_blank"} to the same name.
87
+
```
88
+
cd website/server/app_env
89
+
cp custom.py myproject.py
90
+
```
91
+
1. In this file, set the following variables:
92
+
```
93
+
NAME = "My Data Commons" # Used for browser title bar
> Tip: The `app_env/myproject.py` file overrides default options set in `app_env/_base.py`. You can add other variables you would like to override from that file.
99
+
100
+
## Simple customizations
101
+
102
+
The following are simple customizations you can make by editing HTML, CSS, and JSON files directly.
103
+
104
+
- Logo: Replace [`logo.svg`](https://github.com/datacommonsorg/website/blob/master/static/custom_dc/custom/logo.svg){: target="_blank"} with your own logo file.
105
+
- Styles: Add new selectors and declaration blocks to [`overrides.css`](https://github.com/datacommonsorg/website/blob/master/static/custom_dc/custom/overrides.css){: target="_blank"}. (Note: The provided blocks control more than just styles, but content as well. Don't try to override them.)
106
+
- Add a site-wide footer: Add elements to the `footer` block in [`base.html`](https://github.com/datacommonsorg/website/blob/master/server/templates/custom_dc/custom/base.html){: target="_blank"}. To style the footer using `overrides.css`, create a new CSS block. For example:
107
+
```
108
+
<!--base.html-->
109
+
<footerid="my-footer">
110
+
<p>Here is my footer!</p>
111
+
</footer>
112
+
```
113
+
```
114
+
/* overrides.css */
115
+
#my-footer {
116
+
border-top: 1px solid #efefef;
117
+
background-color: green;
118
+
}
119
+
```
120
+
- Header bar menus: In [`header.json`](https://github.com/datacommonsorg/website/blob/master/server/config/custom_dc/custom/base/header.json){: target="_blank"}, add, remove, or edit the default entries to change menus, text, items, section layout, and links.
121
+
122
+
- Add a search bar to the header: In [`base.html`](https://github.com/datacommonsorg/website/blob/master/server/templates/custom_dc/custom/base.html){: target="_blank"}, set this option:
123
+
```{% raw %}
124
+
{% set is_hide_header_search_bar = 'false' %}
125
+
```{% endraw %}
126
+
- Text and links on the Knowledge Graph landing page (`/browser`): Edit or replace the content in the `content` block of [browser_landing.html](https://github.com/datacommonsorg/website/blob/master/server/templates/custom_dc/custom/browser_landing.html){: target="_blank"}.
127
+
128
+
- Visualization tools (Map Explorer, Scatter Plot Explorer, Timeline Explorer) example chips: Add, remove, or modify default entries in the [`*_examples.json`](https://github.com/datacommonsorg/website/blob/master/server/templates/tools/){: target="_blank"} files as follows:
129
+
130
+
- Set `id` to any string you want.
131
+
- Replace titleMessageId with title, and specify the text that you want to appear in the example chip. (Note: titleMessageId is only used if you are localizing your site, and is mutually exclusive with title.)
132
+
- Set `url` to the full, URL-encoded path to the chart you would like to display.
- Add more pages to the site: Add HTML templates to your `server/templates/` directory. They should extend `base.html` and set the required variables listed at the top of that file.
143
+
144
+
> **Note:** Currently, making changes to any of the files in the `static/` directory, even if you're testing locally, requires that you rebuild a local version of the repo to pick up the changes, as described in [Build a local image](/custom_dc/build_image.html#build-repo).
145
+
146
+
147
+
{: #complex}
148
+
## Complex customizations: header and homepage
149
+
150
+
The contents of the home page and site-wide header, defined in
151
+
[`homepage.html`](https://github.com/datacommonsorg/website/blob/master/server/templates/custom_dc/custom/homepage.html){: target="_blank"} and [`base.html`](https://github.com/datacommonsorg/website/blob/master/server/templates/custom_dc/custom/base.html){: target="_blank"} respectively, are entirely generated by Javascript as React "apps". The Javascript is actually compiled at build time, using [Webpack](https://webpack.js.org/){: target="_blank"}. To make changes to these elements, you have two options:
152
+
153
+
- Override the default Javascript entirely to start from scratch. With this option, you can directly modify the template HTML and/or reuse JS you are already using in other parts of your site. However, you will essentially remove all the default content and start with a blank page and/or header. For example, if you override the home page JS, you'll need to provide code to generate the search bar. For the header, this is the only available option currently.
154
+
- Modify the existing React component(s). In this way, you can mix and match the default content with your own. However, you'll need to code in Typescript and add build rules to Webpack to create your custom Javascript file(s). The Typescript is a separate Custom Data Commons component that you can copy and build. This option is only usable for the homepage.
155
+
156
+
### Option 1: Override default components
157
+
158
+
To remove the default header contents (logo, title, and menus), do the following:
159
+
160
+
1. In your copied `base.html` file, remove the header `main-header` ID (or rename to something else), and add HTML elements in the tags.
161
+
```
162
+
<headerid="my-header">
163
+
<p>Here is my header content!</p>
164
+
</header>
165
+
```
166
+
1. If you have your own JS file(s), add them to your <code>static/custom_dc/<var>PROJECT_NAME</var></code> directory and add script elements to the head section of base.html. For example:
1. To add styling for the header to `overrides.css`, add a new block for it:
176
+
```
177
+
#my-header {
178
+
...
179
+
}
180
+
```
181
+
182
+
To remove the default home page main body (text, search bar and tools), do the following:
183
+
1. In your copied `homepage.html` file, remove the `main-header` ID from the content block div (or rename it to something else), and add HTML elements in the tags.
184
+
185
+
```
186
+
<divid="my-content">
187
+
<p>Here is my home page content!</p>
188
+
</div>
189
+
```
190
+
191
+
1. If you have your own JS file(s), add them to your <code>static/custom_dc/<var>PROJECT_NAME</var></code> directory and add lines like this to the head section of `homepage.html`:
1. To add styling, add new selector blocks to `overrides.css`.
200
+
201
+
### Option 2: Modify default Javascript
202
+
203
+
> **Note**: Only use this procedure if you are familiar with React libraries and coding in Typescript.
204
+
205
+
To modify elements of the home page:
206
+
207
+
1. Copy the files [`static/js/apps/homepage/custom_dc_app.tsx`](https://github.com/datacommonsorg/website/blob/master/static/js/apps/homepage/custom_dc_app.tsx){: target="_blank"} and [`static/js/apps/homepage/main_custom_dc.ts`](https://github.com/datacommonsorg/website/blob/master/static/js/apps/homepage/main_custom_dc.ts){: target="_blank"} and give them different file names. For example:
208
+
```
209
+
cd website/static/js/apps/homepage
210
+
cp custom_dc_app.tsx my_homepage.tsx
211
+
cp main_custom_dc.ts my_main.ts
212
+
```
213
+
1. Edit [`static/webpack.config.js`](https://github.com/datacommonsorg/website/blob/master/static/webpack.config.js){: target="_blank"} to add another build entry:
214
+
```
215
+
my_homepage: [
216
+
__dirname + "/js/apps/homepage/my_main.ts",
217
+
__dirname + "/css/homepage.scss",
218
+
]
219
+
```
220
+
221
+
1. Edit the `.tsx` file to add or remove components.
222
+
223
+
1. In `base.html`, replace the `homepage_custom_dc.js` script file name with your new name. For example:
<td>Sample data and config file (`config.json`) that can be added to a Custom Data Commons. This page describes the model and format of this data and how you can load and view it. </td>
<td>Contains customizable CSS file and default logo. To modify the styles or replace the logo, see <a href="custom_ui.html#styles">Customize Javascript and styles</a>.</td>
<td>Contains <a href="https://developer.hashicorp.com/terraform" target="_blank">Terraform</a> and convenience shell scripts for setting up your instance on Google Cloud Platform. See <a href="deploy_cloud.md">Deploy your custom instance to Google Cloud</a> for complete details.</td>
119
111
</tr>
120
112
</tbody>
121
113
</table>
122
114
115
+
Additional files, that control the site user interface, are described in [Customize the site](custom_ui.md).
116
+
123
117
## Look at the sample data
124
118
125
119
Before you start up a Data Commons site, it's important to understand the basics of the data model that is expected in a custom Data Commons instance. Let's look at the sample data in the CSV files in the `custom_dc/sample/` folder. This data is from the Organisation for Economic Co-operation and Development (OECD): "per country data for annual average wages" and "gender wage gaps":
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?v=4&size=40){kind=avatar}
0 commit comments