Reactor 1.3.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. Paris or later: 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 documented for the DevTools application.
  7. Fork the repository https://github.com/saschawildgrube/servicenow-reactor.
  8. Go to Studio and import the Reactor application from source control.
  9. The x_snc_reactor.AppInstall() function must be executed.
    Run the following script as a background script in scope x_snc_reactor:
  10. x_snc_reactor.AppInstall();

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

API

ReactorAPI

A base class for React components and some useful utilities.

App

ReactorDemoApp

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

ReactorDemoAppCSS

Styles for the ReactorDemoApp.

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.

Clock

A react component that renders a simple clock.

FontawesomeCSS

Includes the Fontawesome css hosted from the same instance

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.

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.

Waiting

A react component that displays a spinning waiting icon.

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.log.active

    Controls if the Reactor application produces log output.

  • 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 functions (yes, JavaScript is broken).

    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 };
    		this.onClick = this.onClick.bind(this);
    	}
    	
    	onClick()
    	{
    		this.setState( {clicked: true} );
    		if (typeof this.props.callbackOnClick == 'function')
    		{
    			this.props.callbackOnClick();
    		}
    	}
    	
    	render()
    	{
    		return e('button',
    			{
    				onClick: this.onClick
    			},
    			this.props.text);	
    	}	
    }

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.

  • DevToolsGetFormatConfig

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

  • 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.

  • 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.

  • Render

    Renders the specified React component using the given properties.

License

Copyright 2022 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.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