Skip to main content

PageBuilder - Documentation

Table of Contents​

System Requirements​

Version
Strapiv4.24.4 (tested: v4.24.4)
NodeJSv18 (tested: v18.20.4)
npmv10 (tested: v10.7.0)

Quick Start Guide​

If you already have experience working inside the javascript-ecosystem and follow a "do it yourself"-approach it might be enough for you to just follow these (minimum) steps to install and start both PageBuilder services.

PageBuilder: Strapi-Plugin - @am-gmbh/pabu-strapi-plugin​

💡 If you don't have an existing Strapi project, you should follow the Part A of the official Strapi Quick Start Guide first. (Make sure to install and start a compatible strapi version by using npx create-strapi-app@4.24.4!)

  • Copy the pabu-folder to /strapi/src/plugins (you might have to create the /plugins-folder manually). (See: Strapi Project structure)

  • Create/edit the plugins-file inside of your strapi/config-directory:

    module.exports = () => ({
      // ...
      pabu: {
          enabled: true,
          resolve: "./src/plugins/pabu",
      },
      // ...
    });
    • Because the pabu-plugin uses the upload-plugin you should also add the following upload-configuration to your plugins-file.
      // ...
      upload: {
        config: {
          sizeLimit: 250 * 1024 * 1024,
        },
      },
      // ...

  • Edit your middleware-file inside of your strapi/config-directory:

      module.exports = [
        "strapi::logger",
        "strapi::errors",
        {
          name: "strapi::security",
          config: {
            contentSecurityPolicy: {
              useDefaults: true,
              directives: {
                "connect-src": ["'self'", "https:"],
                "img-src": ["'self'", "data:", "blob:"],
                "media-src": ["'self'", "data:", "blob:"],
                upgradeInsecureRequests: null,
              },
            },
          },
        },
        {
          name: "strapi::cors",
          config: {
            origin: process.env.PABU_CORS_ORIGINS.split(", "),
            expose: [
              "WWW-Authenticate",
              "Server-Authorization",
              "Access-Control-Expose-Headers",
            ],
            headers: [
              "Content-Type",
              "Authorization",
              "X-Frame-Options",
              "Cache-Control",
              "Pragma",
              "Expires",
              "Access-Control-Allow-Headers",
            ],
          },
        },
        "strapi::poweredBy",
        "strapi::query",
        {
          name: "strapi::body",
          config: {
            enabled: true,
            jsonLimit: "5mb",
            // if you use text or form body you can enable and adjust this:
            // formLimit: "5mb",
            // textLimit: "5mb",
          },
        },
        "strapi::session",
        "strapi::favicon",
        "strapi::public",
      ];

  • Run the following commands.

      cd /strapi
      npm install

  • Because the pabu-plugin comes with various content-types that should be installed correctly you should add and include the pabu-build in your strapi build script. Adjust your strapi/package.json:

...
  "build": "npm run pabu-build && strapi build",
  "pabu-build": "node src/plugins/pabu/server/components/install.js && cd src/plugins/pabu && npm install && npm run compile-and-build",
...

💡 The content-types that needs to be edited from within Strapi Admin are visually highlighted in the Strapi Admin.

  • Place the pabu license key as "pabu-license"-file in /strapi.

  • Add required environment variables.

    ### PaBu: General ###
    CMS_FEATURES=core
    # URL of your Next.js frontend
    PABU_PUBLIC_FRONTEND_URL=http://127.0.0.1:3000
    # URL of your Strapi Application and Next.js frontend
    PABU_CORS_ORIGINS="http://localhost:3000, http://127.0.0.1:3000, http://127.0.0.1:1337, http://localhost:1337"

  • optional (but recommended): Depending on your needs you might want to use another email-provider than the Strapi default: sendmail. To switch email-provider-configuration comfortably you should add the following configuration to your plugins-file.

    // ...
      email: {
        config: {
          provider: process.env.EMAIL_PROVIDER,
          providerOptions: {
            host: process.env.EMAIL_SMTP_HOST,
            port: Number(String(process.env.EMAIL_SMTP_PORT)),
            auth: {
              user: process.env.EMAIL_SMTP_USER,
              pass: process.env.EMAIL_SMTP_PASS,
            },
            secure: false,
            ignoreTLS: true,
          },
          settings: {
            defaultFrom: process.env.EMAIL_ADDRESS_FROM,
            defaultReplyTo: process.env.EMAIL_ADDRESS_REPLY,
          },
        },
      },
      // ...

  • with this plugins-file-configuration you can now switch the email-provider configuration like this:

      # By default: sendmail is used. You should not use sendmail in production (e.g. use nodemailer instead).

      # EMAIL_PROVIDER=sendmail
      # EMAIL_SMTP_HOST=localhost
      # EMAIL_SMTP_PORT=25
      # EMAIL_SMTP_USER=smtpUser
      # EMAIL_SMTP_PASS=smtpPass
      # EMAIL_ADDRESS_FROM=emailAdressFrom
      # EMAIL_ADDRESS_REPLY=emailAdressReply

    (For more informations about E-Mail-Providers in Strapi: Developer Documentation: Strapi Plugin (located in the pabu strapi-plugin directory at /pabu/README.md))

❗ Before starting the installation you need to make sure that you have created/adjusted the strapi/.env-File. (For more informationabout Environment-Variables in Strapi: Developer Documentation: Strapi Plugin (located in the pabu strapi-plugin directory at /pabu/README.md))

  • Build Strapi & start your Strapi application. 
    cd /strapi  
    npm run build 
    npm run develop

☁️ Strapi Cloud: Always make sure that you buildt (npm run build) your project locally before deploying to Strapi Cloud!

PageBuilder: Frontend - Next.js​

  • Copy the nextjs-folder into / of your project structure.

  • Edit the values in the /nextjs/.env file.

  • Navigate to the /nextjs folder and run the following npm commands in the command line tool.

    npm install

    # (optional) this step is only required if you want to modify the project and develop locally:
    npm run dev

    ❗ Make sure to edit the values in the nextjs/.env-File before building/starting.

    # if you want to build and run in production mode:
    npm run build
    npm run start

  • After that, the server should be reachable with any browser at http://127.0.0.1:3000.

💡 Use http://127.0.0.1:3000 instead of http://localhost:3000 while developing locally. This is necessary to ensure the cookie domain works correctly.

💡 With both services up and running you should test your setup by logging in with your Strapi Admin credentials on each services login mask.
Next.js: nextjs:3000/cms/login
Strapi: strapi:1337/admin

💡 If the backend service is not running, the root page (http://127.0.0.1:3000) and all other pages except the login page will result in a 404 error page.

After the succesful installation of the PageBuilder: Frontend and the PageBuilder: Backend you can jump right into adjusting the already created default-settings. With our PageBuilder: Quickquide you can greatly reduce the time until you can focus on creating the content of your site.

Features​

  • WYSIWYG Editor
  • Centralized overview of design options
  • Simple, intuitive use of the content elements
  • Good customization of the elements to your own needs
  • Content elements can be placed directly on the page
  • custom improved Media Manager
  • custom improved Draft / Publishing
  • Internationalization support
  • SEO Features
  • built in Search Function
  • Context-based sets with settings
  • Consistent branding possible
  • Role Management
  • ... and much more!
  • PageBuilder: Backend: Extend your existing Strapi application with full-fledged website-builder-capabilities by installing as plugin in addition to your existing content-types & logic.
  • PageBuilder: Frontend: Can be used as production-ready (page-router based) Next.js 14 starter.

PageBuilder: Backend (Strapi Plugin)​

What is the PageBuilder: Backend?
The PageBuilder: Backend is a strapi-plugin (@am-gmbh/pabu-strapi-plugin, shortly called pabu) that enables your Strapi application to fulfill the role as the backend for the Pagebuilder: Frontend (Next.js).

In comparison to the frontend the pabu-plugin is used to setup your environment and configure the behaviour and appearance of your site.

That means that after initial configuration, a typical content-manager does no longer have to work and edit content inside of Strapi and is only required to login to Strapi if the design or configuration of the site changes.

The pabu-plugin bundles multiple features like customFields and various specific content-types that contain the content and configuration (pages, content-elements, UI-elements) of your website buildt with the PageBuilder. The PageBuilder currently only supports these exclusive content-types.

Any existing logic inside of your Strapi application (contentTypes, controllers, ...) can be used in parallel to the features of the pabu-plugin.

💡 With exception to configuration of the store, contentElementSettings, cmsSettings and global the content of the pabu-plugin (pages, media, navigation, footer, ...) should only be used via the API by using the PageBuilder: Frontend.

❗ Manually changing data of the PageBuilder from within Strapi or directly in the database can lead to data loss and a malfunctional state of your application!

Usage​

The @am-gmbh/pabu-strapi-plugin-plugin is the backbone of the PageBuilder. While the main functionality, the backend logic and API it provides, is not visible from within Strapi Admin, the configuration for the PageBuilder: Frontend is done within the store, contentElementSettings, cmsSettings and global content-types.

💡 Content-Types that needs to be edited from within Strapi Admin are visually highlighted in the Strapi Admin.

The @am-gmbh/pabu-strapi-plugin will provide the configuration as API, .json-Files or minified CSS (that is (re)generated on every configuration change) for the PageBuilder: Frontend.

💡 Make sure to always reload the frontend if you have configured content-types inside of Strapi. Otherwise you might not see the (re)generated styles.

Developer Documentation (Strapi Plugin)​

For additional informations and more technical insights on how the different features of the pabu-plugin work, we strongly advise you to have a look into the separated Strapi Plugin Documentation (located in the pabu strapi-plugin at /pabu/README.md)

PageBuilder: Frontend (Next.js)​

What is the PageBuilder: Frontend?

The PageBuilder Frontend is a Next.js project currently using nextjs v14 and the pages router instead of the app router. If you want to learn more about how Next.js works, you can refer to the official Next.js documentation.

💡 Understanding how Next.js works is not mandatory if you do not intend to modify the code of this project.

This frontend serves as the UI for the backend service, which uses Strapi with the PageBuilder plugin installed.

The goal of the PageBuilder Frontend is to enable end users to create and configure web pages easily in a WYSIWYG (What You See Is What You Get) style, without needing to access the Strapi backend service.

💡 The PageBuilder Frontend will not function as a standalone solution. It requires the backend service to be running and connected.

Usage Frontend​

After starting the frontend, you should be able to access the login page at http://127.0.0.1:3000/cms/login. The login form will only work if the backend is also running. You can sign in with the same credentials that are used for the Strapi admin panel.

Once signed in, you will see a toolbar at the top of the page called the CmsTopBar. This top bar indicates that you are logged into the PageBuilder Frontend and contains the contentmanager main navigation (a dropdown autocomplete with all existing pages) and other action buttons like edit page or add page.

First Steps​

Here are some initial tasks you can perform:

  • Create the navigation
  • Create the footer
  • Fill the root page with content
  • Create other pages
  • And so on...

It is highly recommended to look into the content manager user documentation that was provided to you.

Features Frontend​

Pages​

  • Draft / Publish

    • Each page has two versions: a draft version and a published version. The published version is live and available at the URL, while the draft version is only visible to the content manager after clicking the edit button. This allows you to save a modified version of a page without publishing it immediately.

  • Edit Mode / Preview Mode

    • While editing a page, you can toggle to preview mode to see how the currently edited page would look to a user.

  • Content Elements

    • Content elements are various components that display content on each page. The content manager can choose what a content element should display and where it should be placed.

  • Page Settings

    • General Page Settings
      • Name, URL, show/hide navigation, show/hide footer
    • SEO Settings
      • Meta tags for configuring SEO for each page individually
  • Create and update the navigation with an easy-to-use navigation editor. The navigation is created once and displayed on every page configured to show it.
  • Edit the footer region in edit mode. The footer is created once and displayed on every page configured to show it.

Forms​

  • Create and update forms using a forms editor. Place the created forms on any page you create.

Media Manager​

  • The media manager handles all uploads. You can upload various file types and select them in content elements on the page.

Multi-Language Support​

  • Pages, navigation, footer, forms, and media files can all be localized, allowing content to be displayed in different languages for different locales.

Developer Documentation (Next.js)​

For additional informations and more technical insights, we strongly advise you to have a look into the separated Next.js Developer Documentation (located in the Next.js directory at /nextjs/README.md)

Deployment​

We strongly recommend creating a docker image for deploying your application to the web. Because deploying the PageBuilder is not different from deploying a Next.js or Strapi application, we do not provide any additional custom docker container images or Dockerfile/docker-compose.yml.
Official Next.js Documentation
Official Strapi Documentation

Strapi Cloud​

When hosting your Strapi project with Strapi Cloud you need to make sure that you adjust your environment-variables accordingly. Within Strapi those are: PABU_PUBLIC_FRONTEND_URL, PABU_CORS_ORIGINS and STRAPI_MEDIA_URL.
Inside of Next.js: NEXT_PUBLIC_STRAPI_MEDIA_URL, NEXT_PUBLIC_STRAPI_API_URL.

☁️ Strapi Cloud: STRAPI_MEDIA_URL & NEXT_PUBLIC_STRAPI_MEDIA_URL must include both the same URL. Like NEXT_PUBLIC_STRAPI_API_URL they must be defined without trailing slash!

☁️ Strapi Cloud: When developing locally you might want to add * to your PABU_CORS_ORIGINS. This should never be a permanent solution.

Glossary​

TermExplanation
pb / pabuPageBuilder (projectname)
CMS Userauthenticated content manager user
Guestnormal non-logged-in user visiting a page
CMS Area / CMS User Viewareas that only an authenticated content manager can see/use
Public Area / Guest Viewthe view for a normal guest visitor (not authenticated)
contentElementelement that can be placed on a page. Example: "Text with image" - an element with text and an image that can be added to a page.
contentElementSettingsconfiguration (in Strapi) for a specific type of contentElements.
globalConfig / globalThis configuration is done in Strapi (global) and results in a JSON file config-global.json, which is passed to the frontend.
storeVarious elements in strapi that can be (re)used when configuring contentElementSettings or global.
customCSS(often) project-specific CSS (stored in the DB via Strapi (custom)) to override styling. Appended to css-global-min.css.
css-global-min.cssglobally generated CSS from Strapi configuration (combination of global, store, contentElementSettings & custom)
nested content (element)elements that can be created within content elements. (Example: individual cards within the content element "cards").
editModeflag that determines whether content is currently being edited or not.
editViewflag that determines whether edit controls are displayed or not. editView=true can only be reached with editMode=true. editMode && !editView = preview mode. editMode && editView = edit view.
configFrameframe that appears on hover in edit mode around the content to be edited. Actions can be performed via the config frame (delete, move, config modal, etc.).
configModalconfiguration modal for a single content element. Each content element can be individually configured via the configModal.
nestedContentModalconfiguration modal for a single content element that contains nested content. This modal is only available when the nested content is not directly editable on the page. Example: gallery, carousel, etc. (Cards, for example, have nested content but do not require a nested content modal because the content can be modified directly within the cards).
addContentModalmodal for adding new content elements to a page.
SpaceX / SpaceYpadding of content elements on the X or Y axis.
ContentElementWrapperA component that wraps a single content element this component contains the background configuration, the css class selector, the animations for a whole content element and the SpaceX / SpaceY components.
API Route / API Gatewaythe Next.js API Routes - we use the Next.js API Routes as an API gateway. No request goes directly to Strapi or any other microservice. The client (browser) only communicates with the Next.js server, which then forwards the requests.
cmsSettingssingle type in Strapi important only for content managers and the content manager area. Not delivered to the guest user.
emailSettingssingle type in Strapi that contains email settings and email templates. Not passed to the frontend.

Contact​

AM GmbH
Feldstraße 34
59872 Meschede

Phone: +49 (0) 291/20256-0
E-Mail: info@am-gmbh.de
Web: https://am-gmbh.de