Home

Welcome to the PackageFactory.Guevara wiki! This page hosts developer documentation and conventions.

Getting Started

Please follow the instructions in the README for getting started! This documentation is mainly for developers of this package.

Overall folder structure

The JS frontend of this code resides in Resources/Private/JavaScript.

As this package uses a Guest iFrame for rendering the actual website, we have two JS contexts which communicate with each other. The "outer frame" which contains the Neos UI is called host, while the iFrame containing the website is called the guest.

This structure is reflected in the sub-folder/package structure:

• Host: the main application of Neos.
  • This is the React.JS/Redux application.
• Guest: the connector running inside the guest frame.
• API: the draft for the soon to be separated Neos JS API which handles the communication with the server instance.
  • The API is bootstrapped in the root of the Host application, since it relies on the csrfToken of the logged in user.
• Login: The login screen. Currently not used.
• Shared: helper functions which are necessary both inside the guest and the host.
  • Should not contain state!
  • We try to get rid of these functions!

TODO: explain how the guest and the host frame communicate.

Our Style of Writing React.js components

We embrace the usage of stateless components as much as possible with the relatively new functional stateless components from React which where introduced in v0.14. In our containers we use the ES2015 class syntax, combined with the react-redux @connect decorator. The combination of both increases the separation of rendering and glue-code for the state.

State and redux

We use redux to manage our state, and as described before we ban state from our react components. We also incorporate a bunch of packages like redux-actions for reducing the code you need to write for creating actions, redux-saga for managing complex and asynchronous actions and action collections, so called sagas.

Sagas are our main pillar of complex, asynchronous, conditional action sequences. For example, in case of the page tree we need to cover sequences like the following example:

1. UI toggle page tree item
2. Check if the children are already loaded
3. In case the items are already present in the state, just toggle the sub tree.
4. If not, load them
5. Display the loading icon in the UI
6. As soon as the data got successfully loaded, append them to the store
7. If added to the store, hide the loading icon
8. In case the loading of the data failed, display the error icon
9. Finish it all by toggling the sub tree.

You see, this is a lot of conditional logic, which is also asynchronous since we need to fetch data from the server. For this purpose we use Sagas, which rely on generators and include all of the above statements.

In our reducers we use plow.js which enforces immutable data and includes a bunch of helper functions for working with nested object structures. This library can optionally return, and we use it pretty much everywhere, curried functions.

If you don't know what a curry function is, you should read this nice interactive tutorial on functional programming. In the longer run we will also re-add immutable.js again.

Testing

TODO

Redux State Structure

TODO

Functional Programming Basics

TODO

Glossary

• Node
• StoredNode
• StoredNodeType / NodeType