Reactor 1.6.0

Welcome to Reactor - created and maintained by Sascha Wildgrube.

Features

Use Reactor to create React based applications in ServiceNow. Check out the Demo!

In React its all about React components. With Reactor its all about Reactor components.

A Reactor component may contain a React component class, but its more than that. Reactor components manage the dependencies between the components. Stylesheets are also Reactor components. Think of them as an umbrella of everything you want to make part of your app on the client side.

Reactor components have a "role" - a category that gives a hint about what it really is. Since React does not dictate any sort of separation of concerns - we have to make up for it. We are well advised to create React components not as a mix of logic and html footprint, but to create components that are for user interaction, others for application logic, etc. Reactor helps you getting there.

Please note: Currently the JavaScript libraries for React (and Babel for JSX support) are loaded from a CDN. This may NOT be compliant with GDPR requirements - so watch out for a future version that supports locally stored libraries.

Disclaimer

Reactor is NOT an officially supported ServiceNow product.

Reactor does NOT come with any kind of warranty. If you use it, you own it!

System Requirements

Installation

  1. Create an account on GitHub - if not done already.
  2. Create a personal access token for your GitHub account.
  3. Add credentials to access GitHub - use "Basic Auth".
  4. Fork the repository https://github.com/saschawildgrube/servicenow-devtools.
  5. Go to Studio and import the DevTools application from source control.
  6. Perform all installation steps for the DevTools application documented here: https://www.wildgrube.com/servicenow-devtools 
  7. Fork the repository https://github.com/saschawildgrube/servicenow-reactor.
  8. Go to Studio and import the Reactor application from source control.
  9. The InstallApp() function must be executed.
    Run the following script as a background script in scope x_snc_reactor:
  10. x_snc_devtools.InstallApp("x_snc_reactor");

Setting up a new React app

  1. Create a new UI Script to contain the main React component.
  2. Use the syntax editor macro "react" to get started.
  3. Create a Reactor Component and refer to the UI Script. The component name and the class name of the React component must be identical.
  4. Create a UI Page and add the following code into the html body:
    <g2:no_escape>$[
    x_snc_reactor.Render('ReactorDemoApp',{ text: 'Hello World!' });
    ]</g2:no_escape>
  5. Ajust the code for your new React component.
  6. Test the UI page.

Additional Documentation

React(or) Components

App

ReactorDemoApp

Demonstrates the capability of Reactor to embedd React components into a ServiceNow UI Page.

ReactorDemoAppCSS

Styles for the ReactorDemoApp.

Controller

AllTablesController

The React component loads information on all tables in the instance and displays the tables.

UI Element

Button

A React component that creates a button that can be clicked.

callbackOnClickfunctionA callback function that is invoked when the button is clicked.
textstringThe text that is displayed in the button. The button label however can also be passed as children.
valuestringThe value string that is sent back as a parameter to the callbackOnClick function.

Centered

This React component renders the containing elements in its vertical and horizontal center.

Clock

A react component that renders a simple clock.

ErrorMessage

A react component displaying an error message.

textstringmandatoryThe error message text to be displayed.

Fullscreen

Produces a container that spans over the complete available canvas.

HeaderMenu

A react component that renders a header menu.

callbackOnClickfunctionA callback function that is invoked when a menu item is clicked. The callback function receives the selected option as a string parameter.
itemsarrayAn array of objects, that specify the menu option. Each object should contain the keys "option" and "label". "label" is the screen text used for the menu items. "option" is a string value passed to the callback function when the menu item is clicked.

HeaderMenuCSS

The styles for the HeaderMenu component.

Icon

A react component that displays an icon.

iconstringmandatorySpecifies the (Fontawesome 4) icon name.
sizeintegerSpecifies the size multiplier: 2 to 5.
spinningboolSpecifies if the icon should be spinning or not.

IFrame

A react component that renders an iframe.

callbackOnLoadfunctionA callback function that is invoked when a new page is loaded within the iFrame. The current url is passed as the first parameter to the function.
urlstringmandatoryThe URL to be loaded in the iFrame.

InfoMessage

A react component displaying an info message.

textstringmandatoryThe info message text to be displayed.

ReactorJSXDemo

A demo component that uses JSX syntax.

Ruler

A react component that displays a ruler element.

callbackOnChangefunctionA callback function that is called whenever the value of the ruler changes. The function receives the new value as a parameter.
maxintegerMaximum value for the ruler. Default is 100.
minintegerMinimal value for the ruler. Default is 0.
stepintegerValue by which the ruler can be changed. Default is 1.
valueintegerThe initial value set to the ruler.

TableComponent

Renders a table.

cellsarraymandatoryThe "cells" property is an array of arrays containing objects or strings representing the cell contents. The object can contain the "content", "horizontal" and "header" fields. "content" conatins the contents of the cell. "horizontal" defines the horizontal text alignment. Options are "left" and "right". "left" is the default. "header" is either true or false.
classnamestringThe css class name to be assigned to all html elements of the table.

TableComponentCSS

The default css style sheet for the table component.

ToolBar

The ToolBar component renders a series of buttons with icons and/or text and returns the clicked button via a callback function.

callbackOnClickfunctionmandatoryThe callback functon to be called when a tool has been clicked. It receives the tool's value as a parameter.
toolsarraymandatoryAn array of objects describing the tools of the toolbar. Each "tool" object should have the following properties: "text" is the text in a button (optional) "icon" refers to an icon id for the button (optional) At least one of "text" and "icon" should be provided. "value" is a string which is passed to the callback function.

TreeNavigation

The React component renders a collapsable and expandable tree of navigation options.

callbackOnClickfunctionmandatoryThe callback function that receives a message once an item has been clicked.
collapse_all_levelintegerDefines the level up to which navigation items remain expanded if the user selects to collapse all. Default is 0.
collapse_modestringThe mode string identifier to start with. "none" will expand all navigation items, "all" will collapse all navigation items, "user" will respect the "collapse" field as provided in the items in the navigationtree property. Default is "all".
filterstringThe string by which the filter is initialized. Default is "".
filter_showboolDefine if the text filter input should be visible.
treenavigationobjectmandatoryThe treenavigation object contains the fields "label", "value" and "items". "label" is the visible text to be displayed. "value" is the parameter passed back to the callback function defined by callbackOnClick. "items" is an array of treenavigation objects that represent the next level of the tree.

Waiting

A react component that displays a spinning waiting icon.

textstringText to be displayed while waiting.

WarningMessage

A react component displaying a warning message.

textstringmandatoryThe warning message text to be displayed.

Workspace

A UI Element component that provides a framework for a typical workspace with a menu, toolbar, tabbed content, tree navigation, a multi-purpose side bar, output/result area on the bottom and a status bar at the bottom of the screen.

contentcomponentThe main content area of the workspace.
leftbarheadercomponentThe top area in the left bar.
logocomponentThe logo area on the top left of the workspace.
menucomponentThe main menu on the top of the workspace.
sidebarcomponentThe additional multi-purpose side bar on the right side of the screen.
statuscomponentThe status bar on the bottom of the screen.
toolbarcomponentThe tool bar below the menu above the content and navigation area.
treenavigationcomponentThe tree navigation pane on the left side of the workspace.
usercomponentThe user profile area on the top right corner of the workspace.

API

ReactorAPI

Contains ReactorComponent - a base class for React components and the "e" shorthand for "React.createElement".

Theme / Fonts / CSS

Fontawesome

Includes the Fontawesome css hosted on the same instance

Reference

Roles

Configuration Options

  • x_snc_reactor.active

    Controls if the Reactor application is active.

  • x_snc_reactor.jsx

    Specifies if jsx support is enabled or not. For the time being the only way to support JSX is to use the browser based Babel "standalone" compiler (Refer to https://babeljs.io/docs/en/babel-standalone).

  • x_snc_reactor.logging.verbosity

    Controls the verbosity of log output produced by the Reactor application.

Editor Macros

  • bind

    Creates the pattern "this.onClick = this.onClick.bind(this);" which is to be used in the constructor in a React component class to access the "this" object in a member function (yes, JavaScript is broken).
    However, the use of this pattern should no longer be required as the BindAllFunctionsToThis() function is used in the constructor of the ReactorComponent class.

    this.onClick = this.onClick.bind(this);

  • react

    Creates the biolerplate code for a new React(or) component.

    class NewComponent extends ReactorComponent
    {
    	constructor(props)
    	{
    		super(props);
    		this.state = { clicked: false };
    	}
    
    	componentDidMount()
    	{
    	}
    
    	componentWillUnmount()
    	{
    	}
    
    	onClick()
    	{
    		this.setState( {clicked: true} );
    		if (typeof this.props.callbackOnClick == 'function')
    		{
    			this.props.callbackOnClick();
    		}
    		else if (this.props.text != '')
    		{
    			DoModalMessage('New Reactor component',this.props.text);
    		}
    		else
    		{
    			DoModalMessage('New Reactor component','The button was clicked!');
    		}
    	}
    
    	render()
    	{
    		return e('button',
    			{
    				onClick: this.onClick
    			},
    			'Click me!');	
    	}	
    }

Script Includes

  • AppGetDependencies

    Retrieves information about the app's dependencies to other apps and required versions.

  • AppGetProperty

    Gets a system property of this application.

  • AppInstall

    This script installs Reactor.

  • AppSetDefaults

    Sets all system properties to default values.

  • AppSetProperty

    Sets a system property of this application.

  • Debug

    Produces a log output in the application log using the DevTools Debug function.

  • DevTools

    Implements the extension point for DevTools.

  • DevToolsGetApplicationStatus

    The function DevToolsGetApplicationStatus is called by the DevTools extension point instance class and returns the application status object with additional status information to be displayed on the "DevTools Application Overview" page.

  • DevToolsGetFormatConfig

    The DevToolsGetFormatConfig function is called by the DevTools extension point instance class and returns an object with field formatting information.

  • DevToolsGetInstancePipelineName

    The function DevToolsGetInstancePipelineName is called by the DevTools extension point instance class and returns the pipeline name of an instance based on the given actual name.

  • DevToolsGetLinkDirectory

    The DevToolsGetLinkDirectory function is called by the DevTools extension point instance class and returns an extended (or modified) link directory object that serves as the basis for the DevTools Link page.

  • DevToolsGetParentRecord

    The DevToolsGetParentRecord function is called by the DevTools extension point instance class and returns a parent record for the given record if it can be determined.

  • DevToolsRenderDebugDump

    The function DevToolsRenderDebugDump is called by the DevTools extension point instance class and returns additional debug information provided by the application.

  • GetComponentDependencies

    Returns the an array of component names of components the given component depends on.

  • GetComponentRecord

    Returns the record of a component.

  • GetComponentScript

    Returns the script of a component.

  • HtmlRenderReactorComponents

    Renders descriptions of React components contained in an app.

  • IsActive

    Returns true if the application is active, otherwise false.

  • IsValidReactComponentName

    Returns true if the given string is a valid react component class name.

  • Log

    Produces a log output in the application log.

  • LogError

    Produces an error log output in the application log.

  • LogWarning

    Produces a warning log output in the application log.

  • Render

    Renders the specified React component using the given properties.

License

Copyright 2022-2023 by Sascha Wildgrube

Licensed under the Apache License, Version 2.0 (the "License")

You may not use Reactor except in compliance with the License.

You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Release Notes

1.6.0 - 2023-11-29

  1. Tokyo is no longer actively supported.
  2. Reactor has been fully tested in Vancouver.
  3. DevTools 1.71.0 is now required because of the use of BindAllFunctionsToThis() (introduced in 1.67.0) and the additional parameter support in GetValue() and SetValue(). BindAllFunctionsToThis() is now used in the constructor of ReactorComponent.
  4. Now using React 18.
  5. Added a new Reactor Component role: "Theme / Fonts / CSS" and assigned the "Fontawesome" component to that new role.
  6. The TreeNavigation component now supports text filtering.
  7. The TreeNavigation component now supports menu collapse and expand.
  8. The TreeNavigation component also supports to collapse all and expand all menu items and to return to the last user selection.
  9. The Workspace component now supports an additional left bar header area - e.g. to place a text filter for the tree navigation.
  10. If the system property x_snc_reactor.logging.verbosity is set to "debug" the development version of React is imported.
  11. On the Reactor Component form for a script component loaded from a url, the script section was displayed. This has been fixed.
  12. The Centered component caused content to be cut off on top if the screen size did not fit. This has been fixed.
  13. HtmlRenderReactorComponents() now enumerates all available roles and renders the contained components dynamically.

1.5.0 - 2023-08-18

  1. DevTools 1.66.0 is now required.
  2. Reactor has been fully tested on Utah.
  3. San Diego is no longer actively supported.
  4. Reactor components can now contain "module" scripts.
  5. Added component ToolBar.
  6. Added component TreeNavigation.
  7. Added component InfoMessage.
  8. Added component WarningMessage.
  9. Added component Fullscreen.
  10. Added component Workspace.
  11. Added component Centered.
  12. Renamed AllTables to AllTablesController but AllTables is still available for backward compatibility.

1.4.0 - 2023-03-24

  1. DevTools 1.59.0 is now required.
  2. Added component ErrorMessage.
  3. Added component AllTables.
  4. Added property "text" to the Waiting component.
  5. Added link to "Demo" page to the application menu.
  6. The "react" macro boilerplate class now also contains componentDidMount() and componentWillUnmount() member functions.

1.3.0 - 2022-10-09

  1. Added new entity "Component Properties" to properly document the input properties of each Reactor component.
  2. Added component IFrame.
  3. Added component Waiting.
  4. Added component Icon.
  5. Added component FontawesomeCSS.
  6. Introduced the Reactor component which contains the ReactorComponent class (derived from React.Component) that serves as a base class for all other React(or) component classes.
  7. Added ability to load stylesheets from a URL.
  8. Reactor components are now grouped by their role in the manual.

1.2.0 - 2022-09-18

  1. DevTools 1.44.0 is now required.
  2. Reactor Components now also cover stylesheets.
  3. Added component HeaderMenu.
  4. Improved and renamed component ReactorDemoApp.
  5. Added support to include scripts from a URL.

1.1.0 - 2022-09-17

  1. Added JSX support.
  2. The system property x_snc_reactor.active is now used to switch the Reactor app on or off as a whole.
  3. All navigation modules are now requiring the x_snc_reactor.developer role.
  4. Fixed Render() html output structure.

1.0.0 - 2022-09-17

First baselined version