Living Style Guide for Neos

But it's not just the people involved who need to be agile - the technology used must also support our workflow.

One area that presents many challenges in this respect is Content Management Systems.

The classic workflow, which is used to transfer the graphic design of a website into a maintainable system, usually requires 3 phases. First, of course, the creation of the design. This is followed by the technical implementation of a static HTML document by one or more Frontenddevelopers. In the final step, integration, this document is converted into a so-called template, which replaces the previously static texts, images and other content with the data maintained in CMS.

This procedure is so well established in the Internet industry that it is practically never questioned. It is the perfect complement within a project that is carried out according to the waterfall model. From the requirements specification to the design to the maintainable result, the project goes through plannable phases that can be optimized and accepted in a self-contained manner.

The disadvantages only begin when subsequent changes to the requirements occur. In such a case, the phases described above actually have to be run through again in order to maintain the flow of information between the departments, synchronize the changes in the various code bases and enable regulated acceptance. Obviously, this approach tries to avoid a lot of expensive overhead.

In reality, therefore, quick and supposedly small changes are often made at the integration level, which makes the work of the Frontenddepartment more difficult, as the change does not find its way into their part of the codebase. Friction arises between the different trades, which often disrupts the integrity of the project to such an extent that after a while even the smallest changes cause immense costs and lead to more and more errors.

Subsequent changes are not an exotic phenomenon, however. It can be said that every project, without exception, has to react to changes in requirements. Isn't it therefore much more logical to pursue a workflow that not only allows for changes, but even sees them as the norm?

With RE.A.L., sitegeist took a path some time ago that offers a flexible alternative to the classic waterfall model. Through a rough estimate of the total effort, project planning that can move over time and a specification at sight, the dependencies between the previously rigid project phases are dissolved and a workflow is created that can handle changes much better.

But how can the same effect be achieved in the technical implementation? The layout from the graphics department is still a monolith - and it has to be, because it should ultimately represent the desired website as a whole. The implementation from the frontend department is also a monolith that needs to be broken up during integration. The waterfall phases during implementation are still present.

The +sitegeist Neos stack offers unique solutions to run projects from start to finish RE.A.L

The most important step of our innovation is to avoid template creation during the integration step. Instead, our Frontend developers create directly usable components that can be used in the integration without being changed. Later changes can be made by the Frontend developers at any time without any problems, as their part of the code base remains untouched.

To make this possible smoothly, we had to create a set of Neos-specific tools, which we would like to share with others as an open source project and present below.

To enable Frontend developers to create and maintain components independently, they must be able to test them in different browsers. The Sitegeist.Monocle neos-styleguide fulfills this task. Components can be created and tested without any further input from the integration. The data for the styleguide is versioned directly with the source code. The finished Sitegeist.Monocle uses the production code and therefore cannot deviate from the code base, which otherwise happens to most style guides during the course of the project.

No additional effort is required to maintain the Sitegeist.Monocle style guide, as the sample data that was already used when the component was created is still available for this purpose.

An essential part of reusable components, which another trade uses unchanged, is an explicit and documented interface as well as the isolation of the internal processes of the components. Atomic.Fusion defines such a structure for Neos and even allows to define which parts should be editable by the editors only when the components are used later by the CMS integration.

The original Fusion syntax was too powerful and a little too text-heavy for the efficient creation of Frontend components. This was an obstacle to the training of Frontend developers and also stood in the way of acceptance of the technology.

With the invention of the AFX language, we also solved this problem. Since the full scope of the Fusion language was not required to create Frontend components, we were able to define a sublanguage with AFX that optimizes precisely for the following tasks

• Defining HTML structures
• Using the data transferred via the API in the display
• Internal use of other Frontend components and passing on data
  

The structure of AFX adopts elements of the JSX language, which many Frontend developers are already familiar with from the ReactJS world.
The advantages for our customers Neos together with our specific tools also enable us to work on CMS projects in an agile manner and without fear of later changes. We avoid planning later enhancements in advance in the interest of our customers as we know from experience that we cannot really predict which customizations are really needed. However, we also know that with our Neos project structure we can adapt to almost all future requirements.

Overall, this allows us to be effective and innovative today in the interest of our customers without having to make assumptions about the future that will not survive contact with reality anyway.