reactium init can create Web or API projects
reactium init can create Web or API projects
This is the Home page.
/
This is the About page.
/about
This is the Home page.
This is the About page.
Front-end Routed Single Page Application
Create this file in any of the following:
Create this file in any of the following:
Override: .core/gulp.config.js
Create this file in any of the following:
Override: .core/gulp.tasks.js
Override: .core/reactium-config.js
Create this file in any of the following:
Override: .core/webpack.config.js
Create this file in any of the following:
Override: .core/webpack.config.umd.js
Create this file in any of the following:
Override: .core/babel.config.js
Object describing what caused the last routing state change (Boolean flags):
routeChanged - true when active route object changes
pathChanged - true when URL path has just changed
searchChanged - true when search params have just changed
notFound - true when no matching route was found for current route
transitionStateChanged - true when Reactium.Routing.nextState() was called from last routing state
| Reactium.Routing will wait to progress to each transition state (including rendering your routed component), until your application calls`Reactium.Routing.nextState()`. You can also subscribe to the routing state by registering a route listener, which will get calls whenever the routing state changes. {% code title="reactium-hooks.js" %} ```javascript import op from 'object-path'; const routingStateHandler = async updates => { if (['LOADING', 'READY'].includes(op.get(updates, 'transitionState'))) { // unless LOADING or READY, waiting 1 second and then go to next state await new Promise(resolve => setTimeout(resolve, 1000)); Reactium.Routing.nextState(); } }; Reactium.Routing.routeListeners.register('my-routing-observer', { handler: routingStateHandler, order: Reactium.Enums.priority.low, }); ``` {% endcode %} Ok, now when clicking the links in one of our components, you'll see them EXITING, and then stop at LOADING. Let's add a hypothetical loading function to each component, and then progress the transition after loading is complete. {% tabs %} {% tab title="Article.js" %} {% code title="Article.js (version 2)" %} ```jsx import React, { useState } from 'react'; import { Link } from 'react-router-dom'; import Reactium, { useAsyncEffect } from 'reactium-core/sdk'; import op from 'object-path'; const Article = ({ active, currentRoute, previousRoute, transitionState, transitionStates, changes, }) => { const [ article, setArticle ] = useState(); useAsyncEffect(async mounted => { // this component is current and we need to load the content if (active === 'current' && transitionState === 'LOADING') { // load the article content const article = await Reactium.Cloud.run('content-retrieve', { type: { machineName: 'article' }, objectId: currentRoute.params.id, }); // set the component state and then progress the routing transition if (mounted()) { setArticle(article); Reactium.Routing.nextState(); } } }, [active, transitionState]); if (transitionState === 'LOADING') return__webpack_public_path__ = window.resourceBaseUrl || '/assets/js/';
Configuring Heroku to Deploy Reactium
export REACTIUM_TLS_MODE=on
export REACTIUM_TLS_KEY=/path/to/server.key
export REACTIUM_TLS_CERT=/path/to/server.crt
export PORT=80 # port 80 requires root
export TLS_PORT=443 # port 443 requires root
export REACTIUM_RUN_AS=webapp # or your desired user
export REACTIUM_RUN_AS_GROUP=webapp # or your desired group
npm start
User
|Cloud
| Replace the **define** function where you have to specify the plugin associated with the cloud function | {% hint style="info" %} **See:** [Actinium SDK API Docs](https://reactiumcore.github.io/Actinium) for available functions and definitions {% endhint %} {% content-ref url="/pages/-M5ZF5ZJLk6D3X6MBBa2" %} [Broken mention](broken://pages/-M5ZF5ZJLk6D3X6MBBa2) {% endcontent-ref %} # Actinium Domain Model ## Artifacts | File | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **middleware.js** | Express middleware file for [registering middleware.](https://atomic-reactor.github.io/Actinium/#api-Actinium-Middleware) | | **plugin.js** | Actinium plugin file for [registering a plugin.](https://atomic-reactor.github.io/Actinium/#api-Actinium-Plugin.register) | | **sdk.js** | File in a plugin directory that defines an extension to the Actinium SDK. (optional) | | **route.js** | File in a plugin directory that defines data driven routes for dynamic routes in the admin or another UI application. (optional) | | **blueprints.js** | File in a plugin directory that defines UI layouts for the Admin. (optional) | | **schema.js** | File in a plugin directory that defines DB schema information for [registering Parse Collections](https://atomic-reactor.github.io/Actinium/#api-Actinium-Collection) | ### plugin.js Actinium will attempt to add any file within the **/src/app** directory with a file name that ends with **plugin.js** and execute in the file scope. A typical **plugin.js** file may look like: {% code title="/src/app/MyPlugin/plugin.js" %} ```javascript const PLUGIN = { ID: 'MyPlugin', description: 'My plugin is here!', name: 'My Plugin', }; const COLLECTION = 'MyPluginCollection'; // Register plugin Actinium.Plugin.register(PLUGIN); // Define a cloud function Actinium.Cloud.define(PLUGIN.ID, 'my-plugin-log', req => { console.log(req.params); return { message: 'OK', status: 200, ...req.params }; }); // Define an after save function that will run an after-save hook Actinium.Cloud.afterSave(COLLECTION, async req => { // run this code if MyPlugin is active if (!Actinium.Plugin.isActive(PLUGIN.ID)) return; await Actinium.Hook.run(`${COLLECTION}-after-save`, req); console.log(`Saved a ${COLLECTION} object!`); }); // Register a start hook Actinium.Hook.register('start', () => { // run this code if MyPlugin is active if (!Actinium.Plugin.isActive(PLUGIN.ID)) return; console.log(PLUGIN.ID, 'Yo!'); }); ``` {% endcode %} ### middleware.js Actinium will attempt to add any file within the **/src/app** directory with a file name that ends with **middleware.js** and execute it in the file scope. A typical **middleware.js** file may look like: {% code title="/src/app/MyPlugin/middleware.js" %} ```javascript const express = require('express'); const request = require('request'); const op = require('object-path'); const _ = require('underscore'); // Add an Express route hanlder for /media/* // and serve an Actinium.File object if a matching route is found Actinium.Middleware.register( 'media', app => { const router = express.Router(); router.use('/media/*', (req, res) => { const p = [80, 443].includes(PORT) ? '' : `:${PORT}`; const files = Object.values(Actinium.Cache.get('Media.files', {})); const rec = _.findWhere(files, { url: req.baseUrl }); const fileURL = String(op.get(rec, 'file.url', '')) .replace('undefined/', `${ENV.ACTINIUM_MOUNT}/`) .substr(1); const url = `${req.protocol}://${req.hostname}${p}/${fileURL}`; request(url).pipe(res); }); app.use(router); return Promise.resolve(); }, 0, ); ``` {% endcode %} {% hint style="info" %} Actinium will traverse **node\_modules/\*\*/actinium** directories for **plugin.js** and **middleware.js** artifacts. {% endhint %} # Extending Actinium is easy to extend and much of its bootstrapping is hook-able. {% hint style="info" %} **For more information on the available hooks see:** \ [Actinium Hooks](https://atomic-reactor.github.io/Actinium/#api-Hooks) {% endhint %} ### Actinium SDK Suppose you're creating a plugin and you want to share the functionality with other plugins. You can opt to extend the Actinium SDK by creating a namespace on the Actinium global. {% tabs %} {% tab title="Plugin" %} {% code title="/src/app/MyPlugin/plugin.js" %} ```javascript // Extend Actinium SDK Actinium.MyPlugin = require('./sdk'); ``` {% endcode %} {% endtab %} {% tab title="MyPlugin SDK" %} {% code title="/src/app/MyPlugin/sdk.js" %} ```javascript const COLLECTION = 'SomeCollection'; const MyPluginSDK = {}; MyPluginSDK.create = async (req, options) => { // Get params from request object let { params } = req; // Run a hook so other plugins can do some thangs to the params await Actinium.Hook.run('some-collection-before-create', params, req, options); // Create the new object const obj = new Actinium.Object(COLLECTION); // Save the object let savedObj = await obj.save(params, options); if (!savedObj) { return new Error('Unable to save SomeCollection object'); } // Convert the Actinium.Object into a JavaScript Object. savedObj = saveObj.toJSON(); // Run a hook so other plugins can do some thangs await Actinium.Hook.run('some-collection-created', savedObj, req, options); return savedObj; }; module.exports = MyPluginSDK; ``` {% endcode %} {% endtab %} {% endtabs %} In the above example your Actinium extension will be available regardless of your plugin's active status. If you want your extension to only be available if your plugin is active you'll want to register a **plugin-load** hook and define it after validating that your plugin is active using [**Actinium.Plugin.isActive**](https://atomic-reactor.github.io/Actinium/#api-Actinium-Plugin_isActive)**.** {% code title="/src/app/MyPlugin/plugin.js" %} ```javascript const SDK = require('./sdk'); const PLUGIN = { ID: 'MyPlugin', name: 'My Awesome Plugin', description: 'The name says it all bro', version: { actinium: '>=3.0.5', plugin: '0.0.1', }, }; Actinium.Plugin.register(PLUGIN); Actinium.Hook.register('plugin-load', async ({ ID }) => { if (ID !== PLUGIN.ID) return; if (!Actinium.Plugin.isActive(ID)) return; Actinium.MyPlugin = SDK; }); ``` {% endcode %} {% hint style="warning" %} **Note:** In the above example your extension will not be available in the file scope. {% endhint %} ### Cloud Functions Cloud functions are another way to extend Actinium functionality. Cloud functions are accessible to other plugins and the Actinium client SDK via **Actinium.Cloud.run**. You can define a cloud function in a **plugin.js** file. A typical cloud function may look like: {% code title="/src/app/MyPlugin/plugin.js" %} ```javascript const SDK = require('./sdk'); const { CloudRunOptions } = require(`${ACTINIUM_DIR}/lib/utils`); const PLUGIN = { ID: 'MyPlugin', name: 'My Awesome Plugin', description: 'The name says it all bro', version: { actinium: '>=3.0.5', plugin: '0.0.1', }, }; Actinium.Plugin.register(PLUGIN); Actinium.Cloud.define('my-plugin-create', req => { const options = CloudRunOptions(req); return SDK.create(req, options); }); ``` {% endcode %} {% hint style="info" %} If your cloud function requires capabilities or roles be sure to create the **options** object via the **CloudRunOptions** helper. {% endhint %} {% tabs %} {% tab title="Client Side Usage" %} {% code title="Usage: Reactium \~ services.js" %} ```javascript import Actinium from 'appdir/api'; const create = params => Actinium.Cloud.run('my-plugin-create', params); export default { create, }; ``` {% endcode %} {% endtab %} {% tab title="Other Plugin Usage" %} {% code title="Usage: Actinium \~ plugin.js" %} ```javascript const { CloudRunOptions } = require(`${ACTINIUM_DIR}/lib/utils`); Actinium.Cloud.define('some-other-plugin', async req => { const options = CloudRunOptions(req); const params = { someparam: 'somevalue' }; const newObj = await Actinium.Cloud.run('my-plugin-create', params, options); // do something else like transform the newObj with a hook await Actinium.Hook.run('some-other-plugin-hook', newObj, req, options); return newObj; }; ``` {% endcode %} {% endtab %} {% endtabs %} ### Express Middleware You can extend the underlying Express app by registering middleware that will be loaded on start-up. Register middleware using the **Actinium.Middleware.register** function. ```javascript const express = require('express'); const { myPluginMiddleware } = require('./sdk'); Actinium.Middleware.register('my-plugin-mw', app => { // custom middleware app.use(myPluginMiddleware()); // custom route handler const router = express.Router(); router.use('/some/route/*', (req, res, next) => { console.log('Log something'); res.send('Send something to browser'); }); // mount the router on app app.use(router); }); ``` {% hint style="info" %} **For more information on middleware see:** \ [Express Middleware](https://expressjs.com/en/guide/using-middleware.html) {% endhint %} # Updating One of the greatest features of Actinium is the ability to update to the latest version with minimal worrying about your current project being disrupted. {% hint style="warning" %} *Updating is usually non-invasive, but It's always a good idea to commit your current project before updating.* {% endhint %} ``` $ arcli actinium update ``` After updating, ensure that you have the updated dependencies by running: ``` $ arcli install -s ``` Under the hood, the latest version of Actinium Core is pulled down, extracted, and an update script makes necessary edits to your config files. # Live Query Live Query allows you to subscribe to a **Parse.Query** you are interested in. Once subscribed, the server will notify clients whenever a **Parse.Object** that matches the **Parse.Query** is created or updated, in real-time. Suppose you're building a To Do app and multiple users can make edits to the list. **Parse.Query** would require you to constantly poll the server for status. That's not an ideal situation. A Live Query solves this and makes it to where the client can subscribe to a **Parse.Query** and when updates are made, the subscriber will be notified. ## Setup Live Query requires you to configure which collections can be subscribed to. There are two ways to configure collections, [**env.json**](/actinium/live-query#env-json) and [**live-query-classnames**](/actinium/live-query#live-query-classnames-hook) hook. ### env.json Open the **/src/env.json** file and update the **LIVE\_QUERY\_SETTINGS.classNames** array with the collection name you wish to include. {% code title="/src/env.json" %} ```css { ... "LIVE_QUERY_SERVER": true, "LIVE_QUERY_SETTINGS": { "classNames": ["Changelog", "YourCollection"] }, ... } ``` {% endcode %} {% hint style="info" %} If you have multiple **env.json** files be sure to update them accordingly {% endhint %} ### live-query-classnames hook {% code title="/src/app/MyPlugin/plugin.js" %} ```javascript Actinium.Hook.register('live-query-classnames', classNames => { classNames.push('MyPluginCollection'); }); ``` {% endcode %} {% hint style="warning" %} Using the **live-query-classnames** hook will execute regardless of your plugin's active status due to the fact that this hook is run before the server starts. {% endhint %} # Overview Before getting started with the Toolkit, it's a good idea to understand what you can create with it ## Reactium Toolkit Plugin You can use the Reactium Toolkit Plugin to create [**Style Guides**](/reactium-toolkit/overview#style-guides), [**UI Component Libraries**](/reactium-toolkit/overview#ui-component-libraries), and [**Prototypes**](/reactium-toolkit/overview#prototypes).  ## Style Guides  A style guide is a document that provides guidelines for the way your brand should be presented from both a graphic and language perspective. The purpose of a style guide is to make sure that multiple contributors create in a clear and cohesive way that reflects the brand style and ensures consistency with everything from design to writing. A style guide should provide all of the necessary details for consistent branding with context as to when and where to use components. Style guides help create a shared vocabulary and reinforce design consistency. By keeping a tight rein on brand consistency, brands can drive user perception and expectations. ## UI Component Libraries  A UI component library is a wide range of building blocks available to developers and consists of all the styles and components used in an app, website, or software. Design systems use components as the building blocks for creating a user interface. Building a UI component library is an optimized way to reduce the overhead that comes with maintaining multiple repositories for multiple components. ## Prototypes  Combine UI Components and realize design concepts and features quickly and with extreme agility. Good candidates for prototyping include complex interactions, new functionality and changes in workflow, technology or design. # Installation From the Reactium root directory: ```bash npx reactium @atomic-reactor/toolkit ``` {% hint style="success" %} After the plugin has been downloaded you will be prompted to add the Toolkit styles to your project. {% endhint %} ```bash [ARCLI] > Inject Toolkit styles?: (Y/n) ``` # Configuration You can modify the default behavior of the Toolkit by overriding the configuration object: {% tabs %} {% tab title="Properties" %} | Property | Type | Description | | --------------------- | --------- | ------------------------------------------------------ | | **brand** | `Node` | String or component used to display the brand name | | **info** | `Node` | String or component used to display version info | | **titlebar** | `String` | Text used in the Titlebar of the browser | | **sidebar** | `Object` | Sidebar configuration object | | **sidebar.collapsed** | `Boolean` | Collapsed state of the Sidebar. **Default:** `true` | | **sidebar.position** | `String` | Position of the Sidebar. **Default:** `left` | | **sidebar.width** | `Number` | Width of the Sidebar when expanded. **Default:** `320` | | {% endtab %} | | | {% tab title="Default" %} ```javascript { brand: 'Reactium', info: 'Toolkit version %ver', titlebar: 'Reactium | Toolkit', sidebar: { collapsed: true, position: Reactium.Toolkit.Sidebar.position.left, width: 320, }, }; ``` {% endtab %} {% endtabs %} {% hint style="info" %} **Note:** The initial Sidebar configuration is overridden by user preferences. {% endhint %} {% code title="/MyPlugin/reactium-hooks.js" %} ```jsx import Reactium from 'reactium-core/sdk'; Reactium.Plugin.register('MyPlugin').then(() => { // Ensure the toolkit plugin is available if (!Reactium.Toolkit) return; // Override sidebar width Reactium.Toolkit.setConfig('sidebar.width', 480); }); ``` {% endcode %} The [Toolkit SDK](/reactium-toolkit/sdk) exposes a read-only property for the configuration object: ```javascript Reactium.Toolkit.config ``` ```jsx import React from 'react'; import Reactium from 'reactium-core/sdk'; const MyComponent = () => { const config = Reactium.Toolkit.config; console.log(config); returnElement to render inside the component
Required: true
When determining the active state, use an exact match
Default: false
Determines the default expanded state
Default: false
Unique ID of the component
Required: true
Grid size when the viewport is xs
Default: 12
Grid size when the viewport is sm
Default: null
Grid size when the viewport is md
Default: null
Grid size when the viewport is lg
Default: null
The Class name to apply to the component
Default: rtk-code
Enable folding
Default: true
Hide/show the line numbers.
Default: true
Wrap long lines of code.
Default: false
ID value used for action Zone.
Default: code
Number of spaces used when indenting.
Default: 4
Disable live editing.
Default: false
The size of the icon.
Default: 24
Reference to the Toolkit configuration object
Read-only
Whether the Toolkit is in debug mode
Default: false
The current operating system
Read-only
Reference to the Toolkit enum object
Read-only
Prettier options object
Optional
{markup}Unique id assigned to the subscription
Optional