Props

This section describes how to work with the `props` type.

With the props type, we're able to pass props to the component that we wrap with our Cast from our Typecast platform (app.typecast.dev). These props are passed to the component wrapped in the Cast prior to them rendering, and allow for dynamic content generation based on user data stored on our Typecast platform.

Note: props should be defined in the Action Payload of our UX Change in app.typecast.dev. More details can be found in our Typecast Platform documentation.

Creating a Callout component with dynamic content

In this example we're going to be making an existing component named Callout manageable through the Typecast platform.

Our goal is to have the Callout dynamically open and show text for specific users to let them know about a new feature we're releasing.

Note: the following example does not cover creating a UX Change in the Typecast platform that correspond to this Cast.

To accomplish this, we need to complete the following:

1. Wrap our Callout component where we'd like to effect a UX Change

2. Update our Callout component to support typecastProps

The two files we'll be editing are Dashboard.js and Callout.js

Dashboard.js:

// other imports are made here
...
import Callout from './Callout.js';
import * as Typecast from '@typecastdev/react-lib'

// `currentUser` is being passed to the Dashboard page from somewhere in the code
const Dashboard = ({ currentUser }) => {
  useEffect(() => {
    // initialized typecast for our Dashboard component
    // note that currentUser is a string.
    Typecast.initializeTypecast({
      orgKey: "c318a807-a6b6-4b6b-9b22-4641f505556a",
      userId: currentUser
    });
  });

  // our not so special Dashboard
  return (
    <div>
      <h1>This dashboard is from 2001!</h1>
      <p>Hopefully your dashboard is better than ours...</p>
      // Here our callout is called with no Cast
      <Callout colour="green"/>
    <div/>
  )
}

Callout.js:

// other imports are made here
...
import Popup from '@someUILibrary/Popup';

const Callout = ({ colour }) => {
  return (
    <Popup colour={colour} open={true}> I am a callout!</Popup>
  )
}

export default Callout;

Now let's wrap our Callout component with a Cast in Dashboard.js.

Note [best practices]: we recommend wrapping the components you'd like to manage in the files that you'd like to view UX Changes in rather than wrapping the component in its declaration file (wrapping our Callout component in Dashboard.js rather than Callout.js). This makes it easier to keep track of your Casts and ensures that they are explicit and maintainable.

Dashboard.js:

...
const Dashboard = ({ currentUser }) => {
  ...
  // our not so special Dashboard
  return (
    <div>
      <h1>This dashboard is from 2001!</h1>
      <p>Hopefully your dashboard is better than ours...</p>

      // Typecast.Cast will pass props to children components through the `typecastProps` prop. This needs to be handled inside the wrapped component.
      // We do not need to add any additional props below to our Callout component.
      <Typecast.Cast name="DashboardCallout">
        <Callout colour="green"/>
      </Typecast.Cast>
    <div/>
  )
}

Finally, let's modify our Callout component to accept typecastProps.

For this example, we'll be expecting typecastProps to have two attributes (defined in our Typecast platform), typecastProps.text and typecastProps.open.

Callout.js:

// other imports are made here
...
import Popup from '@someUILibrary/Popup';

// Notice the addition of `typecastProps` to our component's props.
// This is an object that contains attributes that are defined in the `Action Payload` of a UX Change in the Typecast platform.
// Any component wrapped in a `Cast` that has `typecastProps` as a prop has access to the props sent from the Typecast platform.

const Callout = ({ colour, typecastProps }) => {
  // getting props from `typecastProps`
  const text = typecastProps?.text ?? "I am a callout"
  const open = typecastProps?.open ?? true;

  return (
    <Popup colour={colour} open={open}>{text}</Popup>
  )
}

And there we have it. Now our Callout component on the Dashboard should open and render text dynamically based on the data passed by the Cast. In this case we have some default values for text and open. It is recommended to have default values for all typecastProps to ensure at runtime our components have fallback values if Typecast doesn't render, or our component is used without a Cast.

It is important that we define DashboardCallout as a UX Change on the Typecast platform, and ensure that text and open are in the Action Payload. More details can be found in our Typecast Platform documentation.