/timeline-generator-amcharts

Build a timeline generator using amCharts 4 and Kintone

Primary LanguageJavaScriptMIT LicenseMIT

Build a Timeline Generator using amCharts and Kintone

Banner

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!

Outline

Completed Project

Result.gif

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
Step 1: Fill out the Kintone Developer license sign-up form Step 2: Email address will be the login name & the subdomain will be your unique link

Workshop Slides

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


Workshop Steps

  1. Create a Kintone App using the presidents.csv file
  2. Setup a Custom View
  3. Grab the Login Credentials, View ID, and App ID
  4. Create a .env File
  5. Update customize-manifest.json with the App ID
  6. Edit index.js - Input Kintone data into the chart
  7. Compile and upload the code to Kintone with npm run build && npm run upload
  8. 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 Create_CSV_App_01 Step 02 Create_CSV_App_02
Step 03 Create_CSV_App_03 Step 04 Create_CSV_App_04
Step 05 Create_CSV_App_05 Step 06 Create_CSV_App_06
Step 07 Create_CSV_App_07 Step 08 Create_CSV_App_08
Step 09 Create_CSV_App_09 Step 10 Create_CSV_App_10
Step 11 Create_CSV_App_11 Step 12 Create_CSV_App_12
Step 13 Create_CSV_App_13 Step 14 Create_CSV_App_14
Step 15 Create_CSV_App_15 Step 16 Create_CSV_App_16
Step 17 Create_CSV_App_17

Set Field Codes

How to set the Field Codes for the Kintone App?

  1. Hover over the field
  2. Click the top right gear icon ⚙️
  3. Select Settings from the drop-down menu
  4. Click the edit button Edit Button
  5. Enter the new field code
  6. Click the Save button

⚠️ Field Codes are case-sensitive ⚠️

Field_Code_Settings

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 Create_CSV_App_23 Step 24 Create_CSV_App_24
Step 25 Create_CSV_App_25 Step 26 Create_CSV_App_26
Step 27 Create_CSV_App_27 Step 28 Create_CSV_App_28
Step 29 Create_CSV_App_29 Step 30 Create_CSV_App_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
Step7_Before.png Step7_After.png

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

  1. Verify the Node.js & npm versions inside the timeline-generator-amcharts folder
  2. 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

(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.

  • Kintone-View-Setting-Record-Count.png

Not seeing a highlighted TODO:?

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

  • vscode-setting-extension.png

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

Timeline

Plugin: Bullets

To have the PinBullets linkable to their Wiki_URL, take a look at the following docs

Other Parts