Hello Magnolia - SPA
Overview
In this Tutorial we will learn how to use the Visual Single Page Application (SPA) Editor to build stunning websites with ReactJS and Angular.
Basic Form-based headless CMS systems are good for constrained and predefined content types. But to give marketers the ability to create articles, page structure or create their own custom landing pages or micro-sites, the Magnolia SPA Editor will accelerate your Marketer and free up your development capacity.
The Visual SPA Editor is bridging the gap between enterprise-level content management systems and SPA frontend development.
New to Headless CMS?
Checkout our Hello Magnolia Headless Tutorial to get started with some basics.
What are we going to build?
We are going to build a Travel Website SPA promoting travel packages.
In the previous tutorial we have built a basic Headless CMS Website. In this tutorial we will create an application, but enable the Marketer to visually change the SPA.
- Marketers can add new navigation items
- They can create new pages and arrange the content freely with a pre-defined list of Components.
Prerequisites
- Magnolia CLI and required development tools. The instructions are here
Install the demo project
To jumpstart our Project we will install our demo Project. The easiest way to do this is to clone our git repository.
Create a directory named "hello-magnolia-headless" (if this directory is alredy existing you can reuse it):
Clone the git repository:
Install Magnolia for the project
Switch to the cloned project:
Next, choose number 2 (magnolia-community-webapp)
Once the installation is finished you will see an output similar to this on your console:
Before starting, get some handy configuration and sample images. From the magnolia
directory, run:
- Mac or Linux
- Windows
Start Magnolia
Open a new terminal window, and from within your minimal-headless-spa-demos/magnolia
directory execute following command to start your Magnolia Headless CMS:
- When the terminal shows
Server startup in [...] milliseconds
, magnolia is up and running- Open http://localhost:8080
- Click 'Run the web update on the author instance'
- Login with username:
superuser
and password:superuser
Configure CORS
Magnolia is an enterprise-level CMS system, therefore security is taken very serously. To be able to access website content from our headless application we will need to enable CORS in the system.
- Open the Configuration app
- Find
/server/filters
and scroll to the end. - Move
addCORSHeaders
directly afteruriSecurity
(a few items up.)
Install the SPA
We include both a React and an Angular example, just choose which one you want to use.
In your terminal, go to the actual frontend app directory (for React or Angular). Install the dependencies either with npm or yarn, and do your first build.
- React
- Angular
- Vue
See It In Action
Let's have a look at the running demo containing the starter content before we are going to inspect the Starter Code. We have started Magnolia and built and deployed the project in the chapter before.
Install demo content
We have prepared Demo Content to start with. To install the Demo Content follow these steps:
- Open the Pages App in your browser.
- Click
Import
action (You might need to scroll down in the action bar.) - For React: Select the file
./magnolia/_dev/content-to-import/website.react-minimal.yaml
- For Angular: Select the file
./magnolia/_dev/content-to-import/website.angular-minimal.yaml
- For Vue: Select the file
./magnolia/_dev/content-to-import/website.vue-minimal.yaml
Page Builder
In the Pages App, open the SPA Project by double clicking on react-minimal
, angular-minimal
or vue-minimal
depending on which project you have installed.
Now you can see the React, Angular or Vue app rendered in the Magnolia Page Builder. Go-ahead and try to change the title or add an image.
Note: You are editing a SPA!
Inspect the Code
Let's have a look how our demo project is structured:
The blue and green components are fixed components, the developer controls them and their position. The magenta components inside the Area Component are controlled and freely arranged (added, moved, deleted, etc.) by the marketer. The marketer uses the Page Editor to edit the SPA with components built and defined by the developer.
You can look at it as the developer putting 'handles' and 'knobs' on frontend components, so that marketers and content authors can move them around and tune them with custom content.
The green Page Component and Area Component are provided by Magnolia.
- The Page Component is responsible for rendering the 'top' frontend component, and preparing the Magnolia Page Editor.
- The Area Component is mapping the content created by the marketer , to the components defined by the developer, in order to render them. You can define multiple area components on the same Page Component, and a component can have one or more areas of its own.
Light Modules
You can share code and components in multiple light modules.
Shared Light Module: spa-lm
The Magnolia templates and dialogs are the same no matter the front-end framework, so the demo project puts all the shared content in the "spa-lm" module.
Templates
Template definitions register the component with the Magnolia system. They also point to the Dialog definition.
- headline.yaml
- image.yaml
- paragraph.yaml
Dialogs
Dialog definitions provision the form that Marketers will use to tune and enter content. They define the fields and the names of the properties to be persisted.
- headline.yaml
- image.yaml
- paragraph.yaml
Application Light Module
The actual SPA will be deployed to a front-end framework specific module.
We have defined two Page Templates, which the marketer will be able to include in our SPA in the page builder. In the page template you can define Areas and which components which will be available in that area.
- React
- Angular
- Vue
Have a look at
- basic.yaml
- contact.yaml
Frontend App Structure
- React
- Angular
- Vue
Open your project in
We have two categories of templates. Page and Components.
In our source directory we have two sub directories. Page (containing Layout Components) and Components.
- Pages
- Basic
- Contact
- Components
- Navigation
- Headline
- Image
- Text
magnolia.config.js
The componentMappings
in this file are what the Magnolia JS libraries use to determine which SPA component to instantiate, based on the templateID
(for example: spa-lm:components/paragraph
) which is received in the JSON from the Magnolia endpoint.
- React
- Angular
- Vue
Frontend Components
Root Component / Bootstrap Component
The Root Component (App.js
in React, root.component.ts
/ root.component.html
in Angular, App.vue
in Vue) is the main entry point of our app. it defines the page structure and routing.
Note the imports of the Magnolia JS lib: @magnolia/react-editor
or @magnolia/angular-editor
.
- React
- Angular
- Vue
From /helpers/PageLoader.js
Page Component
The Page Component is defining the layout and the placement of the Area components.
Let's have a look at the Basic Page. The EditableArea
is defining which conntent should be displayed. In our case we have defined main
and extras
in our page template.
- React
- Angular
- Vue
Component Components 🤔
We learned earlier that the Magnolia SPA editor framework is helping to map the content structure created in Magnolia to frontend components. Let's have a look at the Headline Component as an example.
- React
- Angular
- Vue
src/components/Headline.js
You can see how the fields defined in the dialog is passed through to the component, directly as props
!
Build a Component
In the "Headless CMS" tutorial we have created a headless app to show tour packages. Using the Visual SPA Editor and the basic Form-Centric approach is not mutually exclusive. On the contrary, both approaches complement each other.
What are we going to build?
We will build a Tour List Component. Our Marketers will be able to choose and add the component anywhere they want.
- Create a new component using light modules.
- Create a dialog for Marketers to add a headline.
Create Tour List Component
Let's create a new Component in Magnolia CMS first. Go to:
Edit the component file tourList.yaml
and paste in:
Dialog
Next we will define a simple dialog for our Marketers.
Edit the dialog file tourList.yaml
and paste in:
Make the Component available
Next we want to define where the component can be used. We will add our tourList Component to the available components of our Basic Page
- React
- Angular
- Vue
Edit the file basic.yaml
and add following text to the availableComponents from the main Area:
The full file will look like this:
Now we can already select the component in the Page Editor.
Open the Pages App and add your component.
But of course before we can see anything displayed, we have to implement the frontend component.
The Frontend Component
Our new component is now provisioned in Magnolia, and an instance of it is saved to the content repository. First, we want the component to display the Header entered by the Marketer. Once this is running and we have seen how to add and edit the component in the SPA Editor, we will extend the component to read and display our Tour List data.
Now, let's build out our component in React, Angular or Vue.
- React
- Angular
- Vue
Switch to our React SPA directory:
Go to the components directory:
Create a new file for our component:
Edit the Component:
We will just print the headline surrounded by a div.
Next, open the Magnolia Config file to add our component to the mapping.
Import the new component:
Add to mapping:
The full file looks like this:
Build the SPA (in the /spa/react-minimal
directory.)
Try your Component
Now that you implemented your component and re-built (and deployed) your SPA, open up the Page Editor again and view your page.
Your component is displayed.
Nice work!
You've just gone through the complete cycle of building a component (with handles and knobs on it) that a marketer can place in a visual SPA Editor.
Next, keep going with your new component. Bring in the tour listing logic you implemented in the 'Hello Magnolia - Headless' section into your new component.
Displaying List of Tours
Our Component is up and running. Next we want to:
- Upload some Demo Content
- Define the REST API endpoint
- Extend our Frontend Component to display the list of tours
Add Tours Content Type
In the folder spa-lm switch to contentTypes
directory:
Create a file named tours.yaml
and copy following content into it:
Create a Magnolia App
Change to the spa-lm/apps
directory.
Create a file named tours.yaml
with following content:
To see your new Tours app, log out and log back in, and press the grid icon.
Install content
We have prepared Demo Content to start with. To install the Demo Content follow these steps:
- Open Tours app
- Click
Import
action (You might need to scroll down in the action bar.) - Select the file
./magnolia/_dev/content-to-import/tours.magnolia-travels.xml
Add Tours REST API Endpoint
In the folder spa-lm switch to restEndpoints/delivery
directory:
Create a file named tours.yaml
and copy following content into it:
This creates our new REST endpoint. Give it a try:
Finish the Frontend Component
Finally, we can extend our TourList Component to fetch and display the imported data.
- React
- Angular
- Vue
Add some more styling
In /spa/react-minimal/src/components
create a file TourList.css
in the same directory as TourList.js
and copy in this stylesheet:
Open your TourList.js
file, and replace the code with this:
Build the SPA (in the /spa/react-minimal
directory.)
You have upgraded your component and re-built (and deployed) your SPA. Now open up the Page Editor again and view your page.
You will see the new tour list.
Next Steps
Congratulations!
You've fully upgraded a simple headless SPA into one marketers can fully manage, including placing a sophisticated listing component.
Next, take a well earned break. :)
Then, after this nitty-gritty hands-on practical work, learn more about the Visual SPA Editor & frontend libraries
Or get big-picture theoretical with the topics in the 'Concepts' section.