This boilerplate has been designed to help you get started to create your own elements that can be used in the ALX Catalyst application.
The boilerplate handles getting the access token allowing API access for development on your localhost it uses the redux-toolkit to handle the api calls with some basic endpoints added.
The boilerplate posts the messageData into the rect application from the index.html file allowing you to simulate Catalyst passing in the parameters, this is then saved into the redux store allowing access from any react component using the useAppSelector hook.
There is a useTheme that is used to handle the basic theme colors and this mirrors the theme within Catalyst so you can copy the #colors over or use your own theme colors.
The first thing I suggest doing is adding in the parameters that you will be using for the app. these will need to be added to the config.json file. These parameters will be displayed in the side panel for users to enter the data into the input fields.
{
"version": "2.0.0",
"logo": "https://www.autologyx.com/wp-content/uploads/2020/09/favicon.png",
"publisher": "ALX",
"publisher_url": "https://www.autologyx.com/",
"parameters": [
{
"parameter_name": "primary_color",
"parameter_description": "Enter a hex color.",
"parameter_type": "string"
},
{
"parameter_name": "secondary_color",
"parameter_description": "Enter a hex color.",
"parameter_type": "string"
},
{
"parameter_name": "tertiary_color",
"parameter_description": "Enter a hex color.",
"parameter_type": "string"
},
{
"parameter_name": "nav_and_background_colors",
"parameter_description": "Enter a hex color.",
"parameter_type": "string"
},
{
"parameter_name": "background_colors",
"parameter_description": "Enter a hex color.",
"parameter_type": "string"
}
]
}
Screen shot for how the config is used to construct parameter input fields in Catalyst
Key Name | is required | valid type | options |
---|---|---|---|
version | true | str | |
parameters | false | object | |
logo | false | str | |
publisher | false | str | |
publisher_url | false | str | |
parameter_name | true | str | |
parameter_description | false | str | |
parameter_type | true | enum | ("string" , "integer", "float" , "boolean", "enum") |
parameter_limit | false | int | |
parameter_options | false | list | ["yes","No"] (used when parameter_type is set to enum) |
After the config.json has been updated with the parameters that your app will be using you then need to add these into the index.html file so that you can use them in your application for testing and development.
The parameters will be an object where the key is the value given to the parameter_name in the config.json, the value will be what the user enters into the parameter fields when setting up the element in Catalyst.
<body class="scrollbar-none">
<div id="root" class="scrollbar-none"></div>
<script type="module" src="/src/main.tsx"></script>
<!-- Uncomment the below for testing with the parameters passed in to the messageData -->
<script>
setTimeout(() => {
console.log("Running post message script.");
const messageData = {
user_details: {
access_token: "",
first_name: "",
last_name: "",
user_id: "5",
user_name: "",
},
object_record_meta: {
class_id: "464",
record_id: "",
},
endpoint: "http://localhost:3001", //same port as the proxy
component_parameters: [],
parameters: {
primary_color: "#5A88DB",
secondary_color: "#7C8664",
tertiary_color: "#DB6D5A",
nav_and_background_colors: "#333333",
background_color: "#DEDEDE",
},
};
window.postMessage(messageData, "http://localhost:5173/");
}, 2000);
</script>
</body>
After updating the index.html I suggest adding the parameters you have setup into the interface types allowing you to work with the parameters in the app. open the file element\src\types\interfaces.ts and then add the parameters into the ParameterData interface where you will find the theme parameters already set up.
export interface ParameterData {
primary_color?: string;
secondary_color?: string;
tertiary_color?: string;
nav_and_background_colors?: string;
background_color?: string;
}
in the terminal cd into the proxy_server root folder and run the following commands to get set up.
npm i
npm run compile
Then update the .env file with the instance that you will be using so that the API calls are going to the correct place. This will be just the BASE_URL
HOST=localhost
PORT=3001
BASE_URL=PROXY_URL
Then cd back into the element root folder you will need to create a new .env.development file and then copy the code from the .env.example over. Add you own user name and password for the Catalyst instance that you are using in the proxy_server the BASE_URL that you set up, and then install the dependencies.
VITE_APP_USER_NAME=YOUR_ALX_USER_NAME
VITE_APP_USER_PASSWORD=YOUR_ALX_PASSWORD
VITE_APP_BASE_URL=http://localhost:3001
npm i
Now you are ready to run the application for testing.
npm run dev
You should see the following your browser when you go to http://localhost:5173/ you should see in the dev tools under the network setting that you get a successful login api request.
If you get the following error then you need to check that you have entered the correct user credentials for the instance of catalyst your proxy_server is connecting to.
A good starting point to in the element\src\components\Element\index.tsx.