- Getting Started
- Integrating with Create React App
- Designing UI
- Working with code
- Structor Market
- Exporting
- Export pages
- Export application
Structor does not depend on any starter/seed/boilerplate project. It runs even in an empty folder with package.json.
But before you get familiar with Structor we suggest to run through a brief tutorial. This tutorial is using our starter project which lets you quickly try all cool features of Structor.
- Clone or download the repo
structor-starterfrom GitHub here:
- Run command from cloned or unpacked directory:
npm install
- Run command:
npm install structor
- When the prompt is appeared in the command line, choose
appas a directory where the source code will be located.
Specify a directory name where the source code of the generated components will be.
If the directory does not exist in the current project structure it will be created.
(app)
- From this point you are able to start Structor:
npm run structor
- Open the following address in the browser:
http://localhost:2222/structor
Now you should see the Structor's workspace. If not, please create an issue.
After the first opening you'll see the workspace page. We may call it a page bacause it behaves as the real page in the browser. But there are two modes in the workspace.
The first mode is an editing mode. In the editing mode we can cut, paste, duplicate, delete, replace, change style of any component on the page.
On a separate note, we should understand what is a component and component model in terms of the Structor's workspace. The page in the workspace consists of multiple React components. Although, the page is not a React component itself, as you may thought, the page is just a tree of components models which are written in JSON. See detailed explanation of what is a component model in section A component model of this guide.
The second mode is a preview mode. In the preview mode you are able to see how page looks and try how it works in the browser.
On the left vertical toolbar you may find two buttons which are responsible for switching between modes:
On this stage of the tutorial the current page should be in the edit mode. If not, please set the edit mode on.
However we can work in Structor with only those components which are shipped with Structor distribution, in this tutorial we will install a package of Material UI components from Structor Market.
Activate a library button with plus icon as it is shown on the screenshot below. The library panel shows the groups of available components in the current project. Find the Install button at the top of the left-side panel and click on it.
We are forwarded to the Structor Market gallery, here we can see what packages of component presets are avaialble to install. Let's install a mui-next-spkg package, which includes components from the next version of Material UI lib.
Installation process will take some time because Structor installs dependencies via npm. Once package is installed we will see new pages in the workspace and new groups of components. Just try to open other pages using the page selector component in the top toolbar.
Let's start to compose something interesting. Make sure that the current page is /home page and click somewhere on the text in the center of the page. You'll see that a border appeared around some area - it means that you selected a component. There is a few ways to understand what the component is selected now.
We may find it in a breadcrumbs control at the top of the workspace as it is shown on the screenshot below. Or you can take a look at the context menu which appeared at the place you clicked right mouse button.
Additionally, there is a more common method which will show us the entire structure of the page. There is a bottom panel with the components tree on the current page. Click on the button with code icon on the left vertical toolbar as it is shown on the screenshot below.
Note Moving mouse cursor around on the page will show us a boundaries of components which we are able to select.
Now let's place the some components from library onto the page.
There is a requirement in the Material UI lib to place MuiThemeProvider as a root component of any MUI components combination. So, we can find a ThemeProvider component in the MUI group (this is a wrapper of MuiThemeProvider here) and place it as a container for our future combination.
Just open the MUI group in the library panel and click on ThemeProvider item in the list. We will see that there is a sublist. The sublist in the library shows that this component has several models. Let's click on default model and see that ThemeProvider component's model was copied to clipboard.
Now we have to replace h3 component in the tree with the component from clipboard. If you do not have h3 selected, select it by clicking on it on the page or just select on the treeview (or in the breadcrumbs control).
Then find Replace button in the top toolbar, or click right mouse and hit a Replace button in the context menu.
As the result we will have the composition as it is shown on the screenshot below.
Now replace a Placeholder component on the page with raised primary model of Button component. And then place h2 component (from HTML group) before Button inside of LayoutItem component.
Placing a component before or after another component can be provided in the same manner as we were replacing components - you have to pick a component from the library and then use Before or After button in the top toolbar or context menu for selected component.
In the result we should have the following composition:
Structor ships with a couple source code generators for React component scaffolds. We are not going to discuss here how it works and how it can be customized. Although, please keep in mind that any scaffold template may be changed to fit your requirements easily.
Now we are going to generate a scaffold for simple React component which will have equal look and feel as our composition which we made above.
Select the topmost div in the hierarchy of the current page, and click Generate Component button on the top toolbar of the workspace. We will see the first page of the generators gallery, where we have to choose what component we want to generate.
Note: You may choose any component on the page as a root node to generate a new React component. But in this tutorial we will select the topmost one.
Here we will choose a react-component generator - click on Generate button to start a generation wizard.
The next step requires to enter a name of new component and/or a namespace for component.
On this note we should step aside a bit and try to understand what the source code and its structure we will have after generation. The only requirement from Structor is to use a certain type of the source code structure. We will discuss the structure and motives to use it in the The code structure guide's chapters. But on this step please keep in mind the following structure of components which is possible to use with Structor:
<APP_DIR>
components/
<COMPONENT_NAME>
index.js - React component
containers/
<CONTAINER_NAME>
index.js - Redux container
actions.js
constants.js
reducer.js
sagas.js
selectors.js
modules/
<NAMESPACE_NAME>/
components/
<COMPONENT_NAME>
index.js - React component
containers/
<CONTAINER_NAME>
index.js - Redux container
actions.js
constants.js
reducer.js
sagas.js
selectors.js
index.js - components and containers index
reducer.js - composition of containers' reducers
sagas.js - composition of containers' sagas
Enter Counter as a new name of React component, and enter Tutorial as a namespace. We are going to create a new namespace with Counter component. Although, we can create a component without any namespace and that will put it in components folder.
Next step gives us options for a few variants of the future scaffold. Let's leave the options as they are and proceed to the next step.
Here is a preview of the generated source code. After reviewing just click on Install component button.
Now we have to switch to the preview mode and try to click on the button - nothing happened. That is why we need to change the source code to make it something valuable.
Open index.js file in the directory...
<PROJECT_DIR>/app/modules/Tutorial/components/Counter
...and made chages in generated code as it is shown below. Also, please observe that your changes are applied in the preview page almost immediatelly.
/**
*
* Counter
*
*/
import React, { Component } from "react";
import PropTypes from "prop-types";
import {
ThemeProvider,
LayoutContainer,
LayoutItem,
Button
} from "modules/MUI";
const style = {
display: "flex",
justifyContent: "center",
alignItems: "center",
padding: "1em"
};
class Counter extends Component {
constructor(props) {
super(props);
++ this.handleIncrease = this.handleIncrease.bind(this);
this.state = {
-- exampleValue: ""
++ counterValue: 0,
};
}
++ handleIncrease(e) {
++ e.stopPropagation();
++ e.preventDefault();
++ this.setState({counterValue: this.state.counterValue + 1});
++ }
render() {
-- const { exampleValue } = this.state; // eslint-disable-line
-- const { exampleProp } = this.props; // eslint-disable-line
++ const {counterValue} = this.state; // eslint-disable-line
return (
<div style={style}>
<div>
<ThemeProvider>
<LayoutContainer gutter={24}>
<LayoutItem xs={12}>
-- <h2><span>Empty h2</span></h2>
++ <h2><span>Count: {counterValue}</span></h2>
-- <Button raised={true} primary={true}>
++ <Button
++ onClick={this.handleIncrease}
++ raised={true}
++ primary={true}
++ >
<span>Button</span>
</Button>
</LayoutItem>
</LayoutContainer>
</ThemeProvider>
</div>
</div>
);
}
}
-- Counter.propTypes = {
-- exampleProp: PropTypes.string
-- };
-- Counter.defaultProps = {
-- exampleProp: ""
-- };
export default Counter;Switch again to the preview mode and try to click on the button - you will see that the counter value is increasing.
This step is not necessary to the projects which have own building process and requre to add components manually into appliation pages. Structor Starter App does not have a sophisticated app building process in terms of granularity, optimisation, etc. This step is mostly for the learning purpose.
Click on the button with book icon on on the left vertical toolbar. This will show us a list of available pages.
In the top of the list we may see two buttons: Export Pages and Export App. Export Pages responsible for generating the source code for selected pages. And Export App button generates not only the pages' source code, but also the source code for entry point in terms of Webpack compiler.
As far as we are going to build application, we are choosing Export App. The modal dialog will worn us about what files will be generated.
After we will see a green message about a successful exporting. Now we can find a new <APP_DIR>/routes folder along with files for React/Redux application. Additionally, please find the compiled bundle of the application in <PROJECT_DIR>/build directory.
Finally we can run our application in the local Express server, go to the terminal and run following command:
npm run start:production
This command initiates a building process of our application and starts an Express server instance on 3000 port. After the server is started we may open http://localhost:3000 address in our browser.