Module 1: The Foundations (Prerequisites)

38. Module 1: The Foundations (Prerequisites)#

Goal: Understand the language (TypeScript) and the engine (React) before driving the car (Experience Builder).

If you are new to Experience Builder (ExB), you are essentially learning three things at once:

  1. TypeScript: The language we write in.

  2. React: The library that builds the User Interface (UI).

  3. Jimu: The specific framework that powers ExB.

This module focuses on the first two. You cannot build a solid house (Widget) without good bricks (TypeScript) and mortar (React).

38.1. 1. TypeScript Basics for ExB#

TypeScript is just JavaScript with Types. It stops you from making silly mistakes, like trying to multiply “hello” by 5.

38.1.1. Key Concept: Types#

In normal JavaScript, variables can be anything. In TypeScript, we tell the computer what they are.

// JavaScript
let name = "John";
name = 5; // Valid in JS, but might crash your app later

// TypeScript
let name: string = "John";
name = 5; // Error! The computer catches this immediately.

Common Types in ExB:

  • string: Text (“Hello”)

  • boolean: True/False (isActive, isVisible)

  • number: Math (1, 3.14)

  • any: The “I don’t care” type (Try to avoid this!)

38.1.2. Key Concept: Interfaces#

Interfaces are blueprints for objects. They are CRITICAL in ExB, especially for config.json.

Example: Imagine you have a car.

interface Car {
    make: string;
    model: string;
    year: number;
    isElectric: boolean;
}

const myCar: Car = {
    make: "Tesla",
    model: "Model 3",
    year: 2023,
    isElectric: true
};

If you forget year, TypeScript will yell at you. This ensures your code always has the data it expects.

38.1.3. Key Concept: Generics (<Type>)#

You will see < > arrows everywhere in ExB code. This is a Generic. It tells a function exactly what type of data it’s working with.

  • Array<string>: A list of ONLY text strings.

  • useState<boolean>: A state variable that can ONLY be true/false.

38.2. 2. React Essentials#

ExB widgets are React Components. A component is just a function that returns HTML.

38.2.1. Anatomy of a Component#

import { React } from 'jimu-core';

// The Component Function
const MyButton = () => {
    // Returns "JSX" -> HTML written inside JavaScript
    return <button>Click Me</button>;
}

38.2.2. Props (Properties)#

Props are how data flows down. Think of them as function arguments. In ExB, props.config is how your settings get into the widget.

// Using the prop
const WelcomeMessage = (props) => {
    return <h1>Hello, {props.userName}</h1>;
}

// Using the component
<WelcomeMessage userName="Developer" />

38.2.3. State (useState)#

State is Memory. If you want a button to change color when clicked, or a counter to go up, you need State. Variables won’t update the screen. State will.

import { React } from 'jimu-core';
const { useState } = React;

const Counter = () => {
    // [Value, functionToUpdateValue] = useState(InitialValue)
    const [count, setCount] = useState(0);

    return (
        <div>
            <p>You clicked {count} times</p>
            <button onClick={() => setCount(count + 1)}>
                Click me
            </button>
        </div>
    );
};

38.2.4. Effects (useEffect)#

Effects run code when things change.

  • “When the map loads…”

  • “When the user selects a layer…”

import { React } from 'jimu-core';
const { useEffect } = React;

const MapListener = (props) => {
    
    // This runs every time 'props.mapId' changes
    useEffect(() => {
        console.log("The map ID changed to: " + props.mapId);
    }, [props.mapId]); // <--- The "Dependency Array"

    return <div>Checking Map...</div>;
}
Contents