How to create a full-stack React Bootstrap UI in under 10 minutes
A tutorial and reference on designing a complete web application and generating it with CodeBot UX
by Matt Stephens, Parallel Agile
This article was originally published here: https://medium.com/parallel-agile-blog/create-a-full-stack-react-bootstrap-ui-in-under-10-minutes-d0eec3077618
- a React web UI
- a MongoDB database
- a Node/Express.js REST API, optionally secured using JWT
- JSON Schema
- Swagger/OpenAPI docs
We have more targets, platforms, architectures and languages on the way, but that’s plenty to get started with!
To whet your appetite, here’s a quick CodeBot video that shows a project being turned into a generated UI:
To get started designing your new application, you’ll need:
- a copy of Enterprise Architect (EA) to create the domain model and wireframes
- a CodeBot account from Parallel Agile
At the time of writing, the generated React UI isn’t in full release, but it’s available under Early Access for customers with a CodeBot license (to gain access, please email us)
There’s also a handy series of step-by-step CodeBot 101 videos that show how to get everything installed and set up — so I won’t repeat those details here:
- Creating and Activating your Account
- Installing the Parallel Agile Add In for Enterprise Architect 2
- Taking CodeBot for a Spin
In this article I’ll walk through the a much-simplified version of the “VSRADS” model shown in the above example video.
VSRADS stands for “Very Short Range Air Defence System” — it’s basically a mosquito zapper. It listens for the high-pitched whine of a mosquito flying by, calculates its position and trajectory, and zaps it with a low-frequency laser.
Our example project is a state machine simulator… given a series of states, a web page is generated to represent each one; and the state machine itself is turned into the navigation “user flow” between pages — i.e. the routes.
So let’s get started!
Step 1: Create a project with 3 top-level packages
Create a new, blank project in EA, and give it the following 3 packages (via “Add View” in the right-click menu):
This will become a familiar pattern… the “three amigos” for defining a new full-stack project
When the model is generated later, the elements in each of these packages will contribute to the generated application, as follows:
- Each wireframe is turned into a React web page
- The navigation state machine is turned into a set of routes
- Each domain class (created in the Domain Model package) is turned into a MongoDB collection and REST API create/read/update/delete endpoint
Step 2: Draw the domain model
Under “Domain Model”, create a class diagram and populate it with some domain classes.
The complete VSRADS domain model looks like this:
For this example you could just create a subset — just be sure to include Simulation Run, as we’ll be linking it to the UI and database.
Step 3: Design the UI Navigation
The idea is that you design individual screens as wireframes, and link them together via a “user flow” or navigation diagram; in this case we’ll draw the user flow as a state machine:
- Each state represents a screen or page
- Each transition (the arrows linking the states together) represents a navigation route
Navigation routes are triggered by things like clicking a link, or submitting a form — “create” or “update” actions.
To introduce the idea, here’s a “hello world” kind of example:
Each generated page will be given its own URI (/login, /view_products etc) so can be individually bookmarked. However, the “Initial” pseudo-state is used to determine which page is displayed by default— the “navigation root” or home page.
Back to VSRADS though… this is a more complex state machine:
Each transition arrow has been given a trigger, which is shown as a label in the diagram. To add a trigger, double-click on the transition:
In EA, you don’t need to select the trigger type etc, you can just enter a name, to keep it simple.
The name needs to match up with the component name in the wireframe, e.g. a button called “Target Identified” — you’ll see some examples of this in the next section.
Usually, the trigger name is also prefixed with an event type, such as on click: or on create: . However, “on click” is the default, so can be omitted.
It’s also worth noting, if the button name is the same as the target page, then CodeBot will figure it out, so you then don’t even need to give the transition a name.
The following event prefixes are supported:
- on click— e.g. “on click: Login”
- on create — e.g. “on create: Target”
- on update — e.g. “on update: Target”
The events all take place in the “source page”, i.e. the page that the transition arrow points from. The trigger will, as you’d expect, result in the app navigating to the “target page”.
The create and update events are triggered when a form is submitted in the “source page”.
Now that you have the overall website or application designed, it’s a good time to create a wireframe for each one.
Step 4: Design the wireframes
EA has a UI wireframe designer built-in. Because the wireframes are fully integrated into the UML model, you can link together wireframe elements, classes, states and other elements… so everything fits together in the generated project.
The VSRADS model has 8 wireframes in total. For this article we’ll focus on two of them, Set Up Simulation (the start page), and Listening for Mosquitoes.
Creating a Wireframe
Right-click on the Wireframes package and choose New Diagram:
In the new wireframe, you need to create a top-level frame which serves as the page-size boundary. This may seem less relevant for websites, but will become important when CodeBot also generates other platforms such as mobile apps. (New feature coming soon!!)
Always add a “Client Area” to represent the page boundary, and fit all the wireframe components inside it
Next, add some components to the page!
Currently with the Early Access release, CodeBot recognises a subset of all the available components. So for now, be sure to only add from the Controls and Website Controls tool palettes.
Position and size the components to match your page design. CodeBot will translate this into a responsive website layout; e.g. it’ll detect grids of label/textfield pairs, alignment of individual labels or buttons, etc.
You can also supply hints to influence how the page is generated. In EA, this is done via tagged values — you can find these on the Tags tab in the Properties panel:
In the above screenshot, the Set up Simulation title has been given a tag called css class, with the value h1 (“Heading 1”). To add more than one CSS class, separate them with spaces.
Another useful tag is variant. This conforms to the Bootstrap 4 colour variants:
For example, the Run Simulation button is given the “primary” variant (the exact case doesn’t matter) via a tagged value, so will be rendered in the page with a solid-blue background:
In this way, it’s possible to adhere to Bootstrap’s design language—the “primary” variant represents the main or default action, etc.
For future platforms even if they don’t use Bootstrap, CodeBot will adapt the same “Bootstrappy” tagged values to the target platform, so you’ll only have to draw the wireframes once in order to get a generated website, mobile app, desktop app etc.
Just to illustrate another page in the same UX design, here’s the Listening for Mosquitoes wireframe:
The Image component can display any image type normally supported in web browsers (jpeg, gif, png). Just include a url tag with the complete URL where the image can be loaded from.
Step 5: Define actions on UI elements
In the previous screenshot, the Run Simulation button also has a tag called action, with the value create.
As long as the button resides in a container panel with form components (text fields etc), when the button is clicked, the form will be submitted to the generated REST API. What happens next depends on the value of the action tag:
- create (create a new record in the database)
- update (update the current record)
The form elements do need to be linked to a particular domain class, though; so let’s do that next.
Step 6: Link UI elements to the domain model
There are two ways to associate UI elements with a particular domain class:
- Use the domain tag
- Draw a dependency relationship from the UI element to the domain class
Which one you use is entirely up to you; the effect on the generated code is exactly the same. It’s more of a stylistic choice, as some people appreciate the visual aspect of seeing a link on the diagram, while others prefer the detail to be tucked away.
Click on the form component you’d like to link, and add a tag as follows:
The domain tagged value uses the form:
Class Name.attribute name
e.g. Simulation Run (the domain class), a dot, then name (the attribute name).
As a time saver, you can also just add the domain class name to the parent container panel:
The “child” form components are then auto-linked to the domain attributes, by matching each component name with an attribute name.
Once this linking-up is done, then when the generated form is submitted, it’ll automatically call the correct REST API endpoint for that domain class.
As an alternative to the domain tag, simply drag the relevant domain class from the package explorer onto the wireframe. Then draw a dependency arrow from the container panel to the class:
You can also link the individual text fields to the class, if preferred.
To emphasize again, this has exactly the same effect as using the domain class; which you use is just a personal preference.
Step 7: Generate the application
If you have the CodeBot add-in installed in EA, right-click on the root (“Model”) package in the package browser. Then choose:
Specialize > Parallel Agile > Generate Project
If you can’t run the add-in for any reason (e.g. you’re on a Mac using a Windows VM), another way to run CodeBot is as follows:
- Make sure you’ve selected the root (“Model”) package, then from EA’s ribbon menu, choose:
Publish > Export-XML -> Export XML for Current Package
- Login into the CodeBot Web Console at parallelagile.net, and choose Upload XMI:
CodeBot will detect that the model contains wireframes, and automatically generate a Bootstrap-React project. You can find it in the downloaded zipfile, in the UX/React folder.
Step 8: Run the React app!
You can optionally elect the generated application to be hosted — just make sure the “Publish to our cloud service” checkbox in the above screenshot is ticked.
In this case, CodeBot will automatically build the React app, and then publish the full website, REST API and database to our secure cloud service.
To access the hosted website, click the blue Visit Website button (visible in the above screenshot).
The Set up Simulation page will load in a separate tab:
When you enter some form details and click Run Simulation, the following series of events take place:
- Due to the action tag and the linked domain class, the React app submits the form to the REST API
- The REST API validates the form data against the generated JSON Schema (based on the domain class and attributes), then creates the new record in the MongoDB database
- Due to the on create: Run Simulation trigger on the navigation state machine, the React app will detect that a “create” just happened linked to the Run Simulation button. So (as the trigger is on a transition), the browser navigates to the next page, Listening for Mosquitoes:
CodeBot UX radically shortens the iterative feedback loop when developing new software. When domain modeling, you can now quickly create a working prototype, use the prototype to elicit new or changed requirements, feed the updates back into the model, rinse and repeat…
… often several times in the same workshop session, with the customer or domain expert right there in the room (or on the same Zoom call).