CarbonReact
CarbonReact is a part of the CarbonORM series. It is a React MySQL ORM that is designed to generate all your boilerplate code.
Installation
CarbonReact is available on NPM. You'll need to have NodeJS installed which comes prepackaged with npm (node package manager).
npm install @carbonorm/carbonreact
Generate Models
The command below generates a single C6.ts file containing your tables, types, and REST bindings. Keep the output in
version control and import from it on both server and client. All arguments are optional. If you do not provide them the
defaults will be used. The example arguments below are the defaults.
npx generateRestBindings --user root --pass password --host 127.0.0.1 --port 3306 --dbname carbonPHP --prefix carbon_ --output ./shared/rest/C6.ts
The generated file exports C6, GLOBAL_REST_PARAMETERS, and per-table bindings (e.g. Users):
import { C6, GLOBAL_REST_PARAMETERS, Users } from "./shared/rest/C6";
You can view the generator source in CarbonNode. We use Handlebars templates to generate the code.
For more information on CarbonNode and the generations please see the CarbonNode.
QuickStart Implementation
CarbonReact is designed to be the Bootstrap of your application. It is in charge of managing the state of your application.
ideally once it has mounted it never gets unmounted. In application where this is not possible, you can provide the
shouldStatePersist property to the CarbonReact React Component. This will allow you to persist the state of your
application even if the component is unmounted. The behavior of accessing or updating state while the component is
unknown (undefined) and should be avoided. The example below shows a simple implementation of CarbonReact. Our user
defined component is in CarbonORM which is written to extend the CarbonReact class. Your implementation must also
extend CarbonReact. The name CarbonORM is arbitrary and can be changed to your application's name.
import 'react-toastify/dist/ReactToastify.min.css'; // This is required for alerts to work and not break styling
const container = document.getElementById('root');
const root = createRoot(container!);
root.render(
<React.StrictMode>
<CarbonORM />
</React.StrictMode>
);
CarbonReact should be loaded as soon as the page loads. There are plans to allow other alerting systems to be used, but for now we use React Toastify. It must be required in one of your files and typically can be done the root of your project.
export const initialCarbonORMState: typeof initialRestfulObjectsState
& typeof initialRequiredCarbonORMState
& iAuthenticate
& iVersions
& iUi
& {} = {
...initialVersionsState,
...initialRestfulObjectsState,
...initialRequiredCarbonORMState,
...initialAuthenticateState,
...initialUiState,
}
export default class CarbonORM extends CarbonReact<{ browserRouter?: boolean }, typeof initialCarbonORMState> {
static instance: CarbonORM;
state = initialCarbonORMState;
constructor(props) {
super(props);
CarbonORM.instance = this;
CarbonReact.instance = this;
}
componentDidMount() {
Carbons.Get()
authenticateUser()
}
render() {
console.log("CarbonORM TSX RENDER");
const {isLoaded, backendThrowable} = this.state;
if (backendThrowable.length > 0) {
return <BackendThrowable />
}
const reactRouterContext = (children: any) => {
if (isTest) {
return <MemoryRouter initialEntries={['/']}>{children}</MemoryRouter>
}
return <HashRouter>{children}</HashRouter>
}
return reactRouterContext(<>
<Routes>
<Route path={UI + "*"}>
<Route path={MATERIAL_DASHBOARD + "*"} element={ppr(Dashboard, {})}>
<Route path={DASHBOARD + '*'} element={ppr(DashboardPage, {})}/>
<Route path={USER_PROFILE + '*'} element={ppr(UserProfile, {})}/>
<Route path={TABLES + '*'} element={ppr(TableList, {})}/>
<Route path={TYPOGRAPHY + '*'} element={ppr(Typography, {})}/>
<Route path={ICONS + '*'} element={ppr(Icons, {})}/>
<Route path={MAPS + '*'} element={ppr(Maps, {})}/>
<Route path={NOTIFICATIONS + '*'} element={ppr(Notifications, {})}/>
<Route path={UPGRADE_TO_PRO + '*'} element={ppr(UpgradeToPro, {})}/>
<Route path={'*'} element={<Navigate to={'/' + UI + MATERIAL_DASHBOARD + DASHBOARD}/>}/>
</Route>
<Route path={MATERIAL_KIT + "*"} element={ppr(MaterialKit, {})}>
<Route path={SECTION_NAVBARS + '*'} element={ppr(SectionNavbars, {})}/>
<Route path={SECTION_BASICS + '*'} element={ppr(SectionBasics, {})}/>
<Route path={SECTION_TABS + '*'} element={ppr(SectionTabs, {})}/>
<Route path={SECTION_PILLS + '*'} element={ppr(SectionPills, {})}/>
<Route path={SECTION_NOTIFICATIONS + '*'} element={ppr(SectionNotifications, {})}/>
<Route path={SECTION_TYPOGRAPHY + '*'} element={ppr(SectionTypography, {})}/>
<Route path={SECTION_JAVASCRIPT + '*'} element={ppr(SectionJavascript, {})}/>
<Route path={SECTION_COMPLETED_EXAMPLES + '*'} element={ppr(SectionCompletedExamples, {})}/>
<Route path={SECTION_LOGIN + '*'} element={ppr(SectionLogin, {})}/>
<Route path={LANDING_PAGE + '*'} element={ppr(LandingPage, {})}/>
<Route path={SECTION_DOWNLOAD + '*'} element={ppr(SectionDownload, {})}/>
<Route path={'*'} element={<Navigate to={'/' + UI + MATERIAL_KIT + SECTION_NAVBARS}/>}/>
</Route>
<Route path={'*'} element={<Navigate to={'/' + UI + MATERIAL_DASHBOARD}/>}/>
</Route>
<Route path={DOCUMENTATION + '*'} element={ppr(Documentation, {})}>
<Route path={CARBON_ORM_INTRODUCTION + '*'} element={ppr(CarbonORMIntroduction, {})}/>
<Route path={SUPPORT + '*'} element={ppr(Support, {})}/>
<Route path={CARBONPHP + '*'} element={ppr(CarbonPHP, {})}/>
<Route path={DEPENDENCIES + '*'} element={ppr(Dependencies, {})}/>
<Route path={CHANGELOG + "*"} element={ppr(Changelog, {})}/>
<Route path={IMPLEMENTATIONS + "*"} element={ppr(Implementations, {})}/>
<Route path={LICENSE + "*"} element={ppr(License, {})}/>
<Route path={'*'} element={<Navigate to={'/' + DOCUMENTATION + CARBON_ORM_INTRODUCTION}/>}/>
</Route>
<Route path="/landing-page" element={ppr(LandingPage, {})}/>
<Route path={'*'} element={<Navigate to={'/documentation'}/>}/>
</Routes>
<ToastContainer
autoClose={3000}
draggable={false}
position="top-right"
hideProgressBar={false}
newestOnTop
closeOnClick
rtl={false}
pauseOnHover
/>
</>)
}
}
Websocket Updates (Optional)
Backend: broadcast the payload generated by CarbonNode on every write (POST/PUT/DELETE).
import { GLOBAL_REST_PARAMETERS } from "./shared/rest/C6";
GLOBAL_REST_PARAMETERS.websocketBroadcast = (payload) => {
wsServer.broadcast(JSON.stringify(payload));
};
Frontend: pass C6 into CarbonReact so the websocket client can normalize updates and only apply them when the row is
already in local state. Debug logs only appear when VERBOSE is enabled.
import { C6 } from "./shared/rest/C6";
root.render(
<React.StrictMode>
<CarbonORM websocket={{ C6, url: "ws://localhost:8888/carbonorm/websocket" }} />
</React.StrictMode>
);
Our testing tool Jest requires React Router Dom
to be in MemoryRouter mode. This is because Jest does not have a DOM and therefore cannot render the HashRouter or
BrowserRouter component. CarbonReact does not require React Router Dom to be installed. You can use any router you
like. The example above uses HashRouter which is necessary as this website
hosted for free using GitHub Pages.
A folder named state in the root of your project
src/state/ should contain all your state files. These files should be written with the intention of being imported
into your CarbonReact extended component. The example below shows a simple state file that is implemented above. Helper
functions are also included in the state files. These functions are designed to be used in your React Components. React
stateful operations must be wrapped in a function and thus must not be run during the initial page load.
Updating state is as simple as calling CarbonORM.instance.setState({}). The class name CarbonORM can be replaced with
any name of your liking. Typically, you will want to use the name of your project.
import CarbonORM from "CarbonORM";
export interface iUi {
pureWordpressPluginConfigured?: boolean,
documentationVersionURI: string,
isLoaded: boolean,
darkMode: boolean,
}
export const initialUiState: iUi = {
pureWordpressPluginConfigured: false,
documentationVersionURI: '0.0.0',
isLoaded: false,
darkMode: true,
}
export const switchDarkAndLightTheme = () => {
CarbonORM.instance.setState({
darkMode: !CarbonORM.instance.state.darkMode
});
};