Build a Timeline Generator using amCharts and Kintone

Learn how to make an amCharts Timeline chart within a React Project with a Kintone Database!

Thank you for attending our Kintone x Timeline workshop!

Our free, live workshop will walk you through creating a Web Database App, setting up a React project, and using amCharts to generate a dynamic Timeline chart!

Completed Project

Get Started

First, clone the kintone-workshops/timeline-generator-amcharts repo! 🚀
Then go inside the folder.

cd Downloads

git clone https://github.com/kintone-workshops/timeline-generator-amcharts

cd timeline-generator-amcharts

npm install

npm install -g @kintone/customize-uploader

⚡ Notes ⚡

React requires Node >= 14.0.0 & npm >= 5.6
Check the versions inside the timeline-generator-amcharts folder:
- node -v
- npm -v
Not the correct versions or confused? 🤔 → Check out the Guide on Installing Node.js & npm Doc

⚡ Note: Please ignore the package deprecation warnings ⚡

🔎 The npm install command installs the required dependencies defined in the package.json files and generates a node_modules folder with the installed modules.

Open the timeline-generator-amcharts folder in VS Code as well:

code .

Get Your Free Kintone Database

bit.ly/KDP_NEW

⚡ Only use lowercase, numbers, & hyphens in your subdomain
⚠ Do not use uppercase or special characters

Workshop Slides

Check out the slides.pdf file for the workshop slides!

Workshop Steps

Create a Kintone App using the presidents.csv file
Setup a Custom View
Grab the Login Credentials, View ID, and App ID
Create a .env File
Update customize-manifest.json with the App ID
Edit index.js - Input Kintone data into the chart
Compile and upload the code to Kintone with npm run build && npm run upload
Play with the Timeline chart on your Kintone App 🎉

Create a Kintone Web Database App

Step 1 - Create a Kintone App using the `presidents.csv` file

Step 01	Step 02
Step 03	Step 04
Step 05	Step 06
Step 07	Step 08
Step 09	Step 10
Step 11	Step 12
Step 13	Step 14
Step 15	Step 16
Step 17

Set Field Codes

How to set the Field Codes for the Kintone App?

Hover over the field
Click the top right gear icon ⚙️
Select Settings from the drop-down menu
Click the edit button
Enter the new field code
Click the Save button

⚠️ Field Codes are case-sensitive ⚠️

Set the following Field Codes

Field Name	Field Code
Start_Date	`start`
End_Date	`end`
First_name	`first`
Last_Name	`last`
Party	`party`
Wiki_URL	`wiki`
Image_URL	`image`

Step 2 - Setup a Custom View

From App Settings, Click the Views tab
Click the Plus Button ⊕ to create a View
Select Custom view under Visible Fields and Column Order section
Get the View ID! (Required in the .env file)
Under HTML Code, input:
```
<div id="root"></div>
```
Save!

Be sure to click the Save and Activate App buttons! 💪

Step 23	Step 24
Step 25	Step 26
Step 27	Step 28
Step 29	Step 30

Connecting the Project to Kintone

Step 3 - Grab the Login Credentials, View ID, and App ID

Where to get the Subdomain, View ID, and App ID?

Go to your Kintone App's custom view & grab the URL
Kintone App's URL follows this template:
- https://<SUBDOMAIN>.kintone.com/k/<App ID>/?view=<View ID>

Example:

https://example.kintone.com/k/1/?view=1234
Subdomain = example
KINTONE_BASE_URL = https://example.kintone.com
App ID = 1
View ID = 1234

Step 4 - Create a `.env` File

Using the .env.example file as a template, create a .env file.
This file will contain your login credentials and the Kintone App's View ID.

Here is what your .env might look like:

KINTONE_BASE_URL="https://example.kintone.com"
KINTONE_USERNAME="your_username"
KINTONE_PASSWORD="your_password"
VIEW_ID="1234"

⚠️ DO NOT DELETE THE .env.example FILE!

.env.example is used by env-cmd to verify that the .env file is correctly configured.

Step 5 - Update customize-manifest.json with the App ID

The Kintone Customize Uploader uses customize-manifest.json to determine where to upload the JavaScript file (which Kintone App).

{
    "app": "1",
    "scope": "ALL",
    ...

If this is NOT your first Kintone App, update the app value to your App ID.

Coding Time

Step 6 - Edit index.js - Input Kintone data into the chart

File: /src/index.js

We access the database records from Kintone's event.records object.
We will map the event.records object into an object for amCharts to parse.
Below is a basic mapping function, with Kintone's records designated as the rec object.
Kintone's records follow a structure of objectName.fieldCode.value
Example: To access the First Name value of a Kintone record, we will write it as:
- rec.first.value => George (Washington)

Solution to Step 6 ↯

// TODO: Input Kintone data into the chart
chart.data = event.records.map((rec, index) => {
  return {
    // TODO: Text above the PinBullet; President's name
    'text': rec.first.value,
    // TODO: PinBullet's & time period's color; Party color
    'color': partyColor[rec.party.value],
    // TODO: Time period's start; Term's start
    'start': rec.start.value,
    // TODO: Time period's end; Term's end
    'end': rec.end.value,
    // TODO: Icon inside the PinBullet; President's icon
    'icon': rec.image.value,
    'category': '' // Timeline category; leave as empty string
  }
});

Notice anything interesting about the color property? 👋
We're using a slightly unusual method of object notation here.
The reason is that the partyColor object we defined on line 29 depends on the variable from our Kintone records. Because the color is a variable, standard JavaScript object notation such as partyColor.rec.party.value would not evaluate correctly. We use bracket notation here to have the partyColor property depend on our app's rec.party.color value. In short, if you want to use a variable to access an object property, use square brackets!

Finish the Project

Step 7 - Compile and upload the code to Kintone

Run the following command to compile the code and upload it to Kintone.

npm run build && npm run upload

Before Code Upload	After Code Upload

Step 8 - Play with the Timeline chart on your Kintone App 🎉

Debugging

Let's Fix Those Problems 💪

Here is a rundown of common problems that may occur & their solutions!

Errors related to .env

If you get one of the following error messages, please verify that your .env file has been correctly configured and that you have not modified the .env.example.

Failed to find .env file at default paths: [./.env,./.env.js,./.env.json]
[webpack-cli] Error: Missing environment variable: KINTONE_BASE_URL
[webpack-cli] Error: Missing environment variable: KINTONE_USERNAME
[webpack-cli] Error: Missing environment variable: KINTONE_PASSWORD
[webpack-cli] Error: Missing environment variable: VIEW_ID
[webpack-cli] TypeError: Cannot convert undefined or null to object

Errors related to kintone-customize-uploader

If you get the following error message, please verify that you have installed the kintone-customize-uploader package.

Error Message:

Options: {"command":"kintone-customize-uploader","commandArgs":["customize-manifest.json"],"options":{"expandEnvs":false,"noOverride":false,"silent":false,"useShell":false,"verbose":true}}
Found .env file at default path: ./.env
spawn kintone-customize-uploader ENOENT
Parent process exited with signal: 1. Terminating child process...

Solution:

npm install -g kintone-customize-uploader

`npm install` command is not working

Verify the Node.js & npm versions inside the timeline-generator-amcharts folder
Just installed Node.js? Verify you configured Node.js versions inside the timeline-generator-amcharts folder

Mac: nodenv local 14.5.0
Windows: nvm use 14.5.0

Not the correct versions or confused? 🤔 → Check out the Guide on Installing Node.js & npm Doc

`npm run upload` failed?

@kintone/customize-uploader not working? Let's try the following:

(1) Verify that customize uploader was installed globally

npm install -g @kintone/customize-uploader

(2) Verify that the .env login info is correct (including the password)

⚠️ Make sure your login info is inside the .env file & NOT the .env.example file!
⚠️ Verify that KINTONE_BASE_URL input is correctly formatted:
- ✅ Correct Format: https://example.kintone.com
- ❌ Incorrect Format: https://example.kintone.com/ or example.kintone.com
⚠️ Re-run the npm commands after saving the .env file
⚙️ Details: Step 4 - Create a .env File

(3) Verify your customize-manifest.json was updated with the correct App ID

⚙️ Details: Step 5 - Update customize-manifest.json with the App ID

(4) Verify that the npm run build command was run before the npm run upload

Uncaught Error: Target container is not a DOM element

Verify that the Custom View (Gallery View) has the following HTML Code:

<div id="root"></div>

Not seeing all the presidents?

Verify that the # per page setting is set to 100 for the amCharts Timeline to display all the presidents.

Not seeing a highlighted `TODO:`?

Click the Install button on the VS Code pop-up message to install TODO Highlight extension.

Completed Code

If you want the completed code for the index.js file, you can find it here:
completed-index.js

amCharts + Kintone References

Here are some references we used to create the Timeline Chart x Kintone customization.

Kintone Customize Uploader

What is @kintone/customize-uploader?

Kintone Events

amCharts Getting Started Tutorials

amCharts Animation

Animation & animated.js

Timeline

Plugin: Bullets

Plugin: Bullets

Name		Name	Last commit message	Last commit date
Latest commit History 75 Commits
.vscode		.vscode
docs		docs
src		src
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
customize-manifest.json		customize-manifest.json
package-lock.json		package-lock.json
package.json		package.json
presidents.csv		presidents.csv
slides.pdf		slides.pdf
webpack.config.js		webpack.config.js

License

kintone-workshops/timeline-generator-amcharts

Folders and files

Latest commit

History

Repository files navigation