Update: Improved UNISYS LifeCycle integration with React

[daveseah]

The first working feature delivery of "persistent network database integration" #20 had a working UNISYS, but there were several areas that would have been confusing to developers coming onto the project. I've tried to clarify it further and simplify it.

There are no functional changes that end users will notice, but developers should benefit from the improvements.

Use the new UNISYS.Component instead of REACT.Component

Rather than worry about where to stick the right UDATA and UNISYS.Hook() declarations in your React component, just extend a class from UNISYS.Component and all that stuff is built-in now!

Many API methods have been renamed to more consistently reflect the "app" versus "net" nomenclature (or because I thought of a better name). See the source is in unisys/client-react-component.jsx for a complete listing. The old methods are still available, but will warn you in the console to update.

No more Hooks in UNISYS.Component. Use Special Events instead

The UNISYS.Hook() syntax is now reserved only for our pure UNISYS modules; you will get a warning if you try to use it inside of UNISYS.Component. To effectively communicate with other UNISYS modules, you need to be aware of what and when you can do certain things.

• The root REACT AppShell is now managed by UNISYS so ReactDOM.render() executes after INITIALIZE, LOADASSETS, and CONFIGURE phases have completed.
• Views (e.g. AutoCompleteDemo) render inside of the AppShell, and is what we think of when we say "app" within our system.
• The view's constructor is where you can register state and message handlers for the component. However, you SHOULD NOT USE any UNISYS message or state services that are defined in OTHER React components, because they may not yet exist. Use the constructor for constructing only. All stand-alone UNISYS service modules "should" be accessible at the end of CONFIGURE, so they can be used in your constructor.
• After the view has rendered completely, the DOM_READY, RESET, START and APP_READY phases execute in UNISYS modules. Your React components have access to these phases through new methods OnDOMReady(callback),OnReset(callback),OnStart(callback), OnAppReady(callback) and OnRun(callback). You can use these hook replacements to know when to access other React component UNISYS state or message services, since they will have all been initialized by the time OnStart() fires.
• Put your component into the default state by subscribing to OnReset(), and get it ready to run when OnStart() is fired. OnAppReady() will fire when UNISYS needs the app to register any information to the network before it will receive net messages, and finally OnRun() will fire when it's time to RUN.

Write your React handler code to RESPOND to changes in state and messages, not FORCE something procedurally. If button handlers do a lot of brute-force logic, the code will be fragile, hard to read, and error prone. Instead issue a MESSAGE that results in the transformation of APPSTATE, which then gets received by the components that have subscribed to them, which then convert them to changes via this.setState(). This will also help establish a clean interaction/data model.

Improved Route Definition

Previously, you had to update two places in init-appshell.jsx to add a new View route. Now, update the Routes data structure in a single place. You will still need to manually update the NavBar JSX to add it as a menu item, but you can also just type it directly into the browser location bar.

Sample Database Now Included

The repository now ships with runtime/sample.data.json which contains the placeholder netgraph dataset. If the runtime/netcreate.json database is not detected, the contents of the sample data will be copied into it.

As before, you can also run the #dev-db app and use the database push command ncPushDatabase('myfile.json') to overwrite the server's database. The json files should be copied to the app/assets/data directory so it is available to the command.

Other Technical Notes

With this update, the lifecycle startup and control is much better defined, and there are fewer confusing lines of magic code required to make a new view work.

Currently, there is just one requirement to make a new UNISYS-compatible View:

• The exported class must have a static UMOD property equal to module.id. For example, if your view class is AutoCompleteDemo, then you would add the line AutoCompleteDemo.UMOD=module.id before module.exports=AutoCompleteDemo
• [optional] Extend your class from UNISYS.Component instead of React.Component to gain access to UNISYS commands. You still need to add UMOD=module.id.
• [optional] Put UNISYS.ForceReloadOnNavigation() after the super() call in the class constructor to ensure that your app is the only one running. This is useful if you are not using tabbed views for the same application.

[benloh]

Approved. Some issues with adding/deleting objects that are probably related to AutoCompleteDemo's outdated use of data updates.