neos / neos-ui

Neos CMS UI written in ReactJS with Immutable data structures.

@neos/neos-ui

The Neos CMS interface written in ReactJS and a ton of other fun technology.

Versioning

This repository follows the same versioning scheme as Neos itself. Release roadmap is available here

That means:

• All bugfixes go to the lowest maintained branch
• All new features go only to the 8.4 and 9.0 branch
• New minor and major releases are made in sync with Neos/Flow. Bugfix releases may be available independently

Currently maintained versions

• NeosCMS version 8.3: branch 8.3
• NeosCMS version 8.3: branch 8.4
• NeosCMS version 9.0: branch 9.0
• latest development happens currently in the 8.4 and 9.0 branch

Releases with just security updates

• NeosCMS version 7.3: branch 7.3
• NeosCMS version 8.0: branch 8.0
• NeosCMS version 8.1: branch 8.1
• NeosCMS version 8.2: branch 8.2

Browser support

The new interface supports all evergreen (i.e. self-updating) browsers, including: Chrome, Firefox, Safari, Edge, Opera and other webkit-based browsers.

If you discover bugs in any of the supported browsers, please report them!

Features

• Blazingly fast Yarn 3 + ESbuild stack
• https://www.neos.io/features/editing-content.html
• https://www.neos.io/features/inline-editing-true-wysiwyg.html

Installation and usage

The UI is already included in the base Neos distribution. And on Packagist available via: neos/neos-ui

Updating

composer update neos/neos-ui

Installing latest development

For trying out the new UI, we recommend you to run the regularly released beta releases. However, if you want to stay on bleeding-edge, or want to help out developing, you'll need the 9.0.x-dev release. You can install the latest release using:

composer require neos/neos-ui-compiled:9.0.x-dev neos/neos-ui:9.0.x-dev

Contributing

Please follow the respective guides for contributing on OSX and on Linux.

on Windows

1. Ensure you have the relevant version installed (see above).

2. Please install Docker for Windows.

3. Run docker-compose up.

4. Inside Configuration/Settings.yaml, set the following property for disabling the pre-compiled files:

Neos:
  Neos:
    Ui:
      frontendDevelopmentMode: true

6. Get an overview about the codebase. We've recorded an introduction on YouTube which gets you acquainted with the basics. Additionally, please get in touch with us on Slack in the channel #project-ui-rewrite. We're eager to help you get started!

on OSX / Linux

In order to start contributing on OSX / Linux, follow the following steps:

1. Ensure you have the relevant version installed (see above).

2. We require Chrome as well as the yarn(https://yarnpkg.com/en/) command and GNU Make(https://www.gnu.org/software/make/) to be installed on your system.

3. The currently supported version of node is defined in .nvmrc file. If you have nvm installed, you can just run nvm install && nvm use from the project directory.

4. Inside Configuration/Settings.yaml, set the following property for disabling the pre-compiled files:

Neos:
  Neos:
    Ui:
      frontendDevelopmentMode: true

5. Run the initialization script:

make setup

6. Get an overview about the codebase. We've recorded an introduction on YouTube which gets you acquainted with the basics. Additionally, please get in touch with us on Slack in the channel #project-ui-rewrite. We're eager to help you get started!

Guideline for PR and commit messages

Please see our guideline on how to write meaningful descriptions for your contributions.

Doing upmerges

To do the upmerge run the following commands

# review and `git commit`
git checkout 8.0 && git fetch && git reset --hard origin/8.0 && git merge --no-ff --no-commit origin/7.3
# review and `git commit`
git checkout 8.1 && git fetch && git reset --hard origin/8.1 && git merge --no-ff --no-commit origin/8.0
# review and `git commit`
git checkout 8.2 && git fetch && git reset --hard origin/8.2 && git merge --no-ff --no-commit origin/8.1
# review and `git commit`
git checkout 8.3 && git fetch && git reset --hard origin/8.3 && git merge --no-ff --no-commit origin/8.2
# review and `git commit`
git checkout 8.4 && git fetch && git reset --hard origin/8.4 && git merge --no-ff --no-commit origin/8.3
# review and `git commit`
git checkout 9.0 && git fetch && git reset --hard origin/9.0 && git merge --no-ff --no-commit origin/8.4
# review and `git commit`

Development commands

Command	Description
make clean	delete all node_modules in every subdirectory.
make build	Runs the development build.
make build-watch	Watches the source files for changes and runs a build in case.
make lint	Executes make lint-js and make lint-editorconfig.
make lint-js	Runs test in all subpackages.
make lint-editorconfig	Tests if all files respect the .editorconfig.
make test	Executes the test on all source files.
make test-e2e	Executes integration tests.

Writing unit tests

The unit tests are executed with jest. To run the unit tests, execute make test in your shell.

Adding unit tests is fairly simple, just create a file on the same tree level as your changed/new feature, named [filename].spec.js and karma will execute all tests found within the spec file, other than that, just orient yourself on the existing tests.

Use it.only(() => {}) and describe.only(() => {}) if you want to run a specific test and not the whole test suite.

Integration tests

To setup end-to-end tests locally you have got to do the same things described in CircleCI workflow, namely take the test disribution and composer install in it, put the right branch into Neos.Neos.Ui folder and run webserver and mysql server with the same config as described in the test distribution's Settings.yaml (or adjust it).

For executing the end to end tests on a Mac with catalina or higher you need to permit screen recording. Open 'System Preferences > Security & Privacy > Privacy > Screen Recording' and check 'TestCafe Browser Tools' in the application list.

Local Development with e2e-tests & docker

To speed up the e2e-test workflow/feedback loop you can start the system under test in a docker setup and run the tests against that:

• make start-neos-dev-instance (starts a docker setup with the system under test)
• The neos dev instance is available at localhost:8081
• To enter the container run docker compose -f Tests/IntegrationTests/docker-compose.neos-dev-instance.yaml exec php bash
• yarn run testcafe <browser> <testFile> <optional flags>
  • for example, this runs all tests in chrome: yarn run testcafe chrome Tests/IntegrationTests/Fixtures
  • some helpful optional flags are
    • -T 'sidebars' - grep tests by pattern and only execute those
    • --selector-timeout=10000 - if you work on async pieces of the UI then this might help to prevent race conditions
    • --assertion-timeout=30000 - see above
    • --debug-on-fail - you can debug the state of the app at the moment an assertion failed

Debugging integration tests

• View the recording via Sauce Labs. You can find the url in the beginning of the test output.
• Observe Flow exceptions and logs in build artifacts.
• You can trigger a SSH enabled build via the CircleCI interface and then login.

Releasing

You only need to trigger the jenkins release with the version you want to release. After jenkins has finished you need release a new version on github.

License

see LICENSE

neos-ui's Issues

Render correct contents in the OffCanvas navigation

Currently we only render fixtures, this needs to be changed.

Allow pasting copied element as a reference

Jira issue originally created by user soee:

Neos offers option to reuse the same element across website by using Reference NodeType. At the moment to use it we have to insert Reference element and search for target content. This works pretty good when target element has some property like 'title' that can be used to search for it. But if target content has no such property it simply can't be found by Reference object.

To make it a lot easier it would be good to have option to paste element as a reference. This could work like this:

1. Copy any content element as usual
   2.1 You can paste this element as usual to create copy
   2.2 You can paste this element as a reference - create reference to copied element

This would require probably some extra button in content element controls - next to "paste" controls or by extending it.

Atachements:

Jira-URL: https://jira.neos.io/browse/NEOS-1487

Reduce the relative path hassle with webpacks `root` feature

Render endpoint urls via uri-ViewHelper

Integrate unit & behavior tests for the JavaScript-Applications

The stack will contain at least mocha, chai and sinon, either cheerio or JSDom and maybe even the React testing utilities.

Add functionality to the OpenInNewTab Button in the ContextBar

Inspector: should warn also when page is closed

Jira issue originally created by user @liwo:

The inspector should show a warning if the window is closed if there's still unsaved data.

Jira-URL: https://jira.neos.io/browse/NEOS-534

Enhance the UX for the Tabs

This might be of help, when used in the guest frame:

window.onbeforeunload = (e) => {
    console.log(document.activeElement.href);
};

Include all source files while generating the coverage data

Currently only files which are imported through the .spec.jsfiles are included in the coverage metrics, thus, the data is not correct.

Integrate greenkeeper for automatically updated depdencies

We could do this as soon as possible, but I would feel far more comfortable if we actually prioritize #18 ahead so we are 100% sure that the greenkeeper PR`s are tested and everything still works like a charm.

http://greenkeeper.io/#signup

Update to babel <= 6.0.0

Since the newest babel version stalled the implementation of decorators, we currently use the older version "6.4.0". This issue is just a reminder to update babelify as soon as possible.

Related issue: http://phabricator.babeljs.io/T2645

Save a subset of the store in session storage

e.g. ui.tabs and user.settings

Exit codes of the TravisCI shell scripts aren't propagated

Thus, builds aren't breaking correctly as seen with https://travis-ci.org/PackageFactory/PackageFactory.Guevara/jobs/112261030

This will be solved by adding set -eat the top of each shell script.

Clicking escape should deselect element selected element

Jira issue originally created by user @aertmann:

When a content element is selected it should be unselected when clicking the Escape key. However if it's the uppermost element (page) selected, nothing should happen.

Jira-URL: https://jira.neos.io/browse/NEOS-601

Create the Neos JS Content-API / Separation of Core UI from API logic

Hey guys!

So today I had a phonecall with @skurfuerst and we both agreed that we need to move fast from the current separation into folder to a standardized API which will in future be shipped with the Neos core package.

For example, currently the service layer and all of the logic for communicating with the Neos Backend endpoints is placed directly in the Host/ folder. @grebaldi already stated in several places that he wants to refactor most of this (f.e. the ChangeManager service).

I think we should take this opportunity seriously and go straight into the process of moving most of the logic into a separate API bundle which will always be loaded in the <head> before every other tag. Afterwards we might want to create an abstraction layer for the current UI, which binds the Neos Content API to the redux-actions.

Note that the API itself should not use redux, so we have a clear separation of UI logic/actions and the API itself. A stream based API for the NodeService, which is accessing the unified node model(which also needs to be created ASAP), and a PublishingService which uses Promises/Generators(?) may be an appropriate solution, but this is only a rough idea in the back of my head.

Anyway, looking forward to thoughts of all of 'ya
CC: @grebaldi @dimaip @skurfuerst

Add the Edit/Preview Panel

Remember auto-publishing state between sessions

Jira issue originally created by user @aertmann:

When an editor changes to using auto-publishing the state should be remembered across sessions for that user.

Jira-URL: https://jira.neos.io/browse/NEOS-350

Re-Enable the `no-use-before-define` ESLint rule

Since #44, the no-use-before-define ESLint rule was removed, this is due to an incorrect parser behavior of babel-eslint which is already reported.

We also postponed the update of ESLint to version 2.3.0 since of babel/babel-eslint#267.

Integrate static typechecking via babel / flow

I've just discovered this plugin: https://github.com/codemix/babel-plugin-typecheck

It kind of enables static typechecking for functions, in ES7 there may be Trademarks and Guards, which kind of strive into the same direction.

The question is, do we want to integrate such a plugin, even though its syntax may heavily change in the upcoming months?

I think static typechecking in functions would enhance the code quality greatly, though I am aware that this may be a to unstable feature of the next ES version.

What do you think @dimaip @skurfuerst @grebaldi

Add functionality for the UserDropDown items

The User Settings item is a simple link, but the logout button is a form with values which Flow requires to complete the logout handler.

ToDo: Implement the generated IDs/values which Flowrequires.

Enhance the handling of runtime errors in both the Host and Guest frame

Handle each error via window.onerror in the guest frame.

Collapsible Document tree to make room for the Content tree

Jira issue originally created by user @aertmann:

STUB: The Document tree should be collapsible in order to make more room for the Content tree in cases of pages with lots of content

Jira-URL: https://jira.neos.io/browse/NEOS-781

Keep state of which document nodes were expanded between views

Jira issue originally created by user @aertmann:

STUB: The tree should remember which branches were opened/closed during the last time

This should be possible with dynatree's cookie functionality

Jira-URL: https://jira.neos.io/browse/NEOS-780

Login dialog should be shown across tabs

Jira issue originally created by user @aertmann:

When multiple tabs on the same domain are open and one of them notices being logged out, all of the tabs should show the login dialog synchronously as well as hiding it synchronously.

Jira-URL: https://jira.neos.io/browse/NEOS-816

Create git-hooks for a better development expirience

The plan is, to create the following hooks:
prepare-commit-msg -> Validates the commit message against the Neos commit guidelines
post-merge -> updates npm dependencies after a rebase, merge, checkout and pull
pre-commit -> lints all source files, currently I am not sure if we should also run karma as well (Boot time of karma is pretty long tbh)

Integrate redux-actions, Move all redux stuff into one folder `redux`

As suggested by @dimaip and me. We both think this makes sense. Maybe we can integrate this on the same step as moving all the redux stuff into one folder named redux?

https://github.com/acdlite/redux-actions

What do you think @grebaldi

Shortcuts for Edit/Preview modes

Jira issue originally created by user rasmusskjoldan:

Jira-URL: https://jira.neos.io/browse/NEOS-334

Create a migration for the FontAwesome 3.2.1 > v4.5.0

Icons such as resize-full or ban-circle have been renamed and need to be remapped to the new names.

Avoid build errors on TravisCI by adding a GitHub oAuth token to composer

Some builds are currently failing because of composer/composer#1314. This should be fixed ASAP.

Enhance accessibility in all Components & Containers

We are better of to integrate ARIA-Attributes and voice labels as soon as possible so we all embrace accessibility while developing new features in the coming months.

Improve experience using small screens by collapsing panels automatically

Jira issue originally created by user @aertmann:

• when clicking (focussing) a content element, the inspector panel is automatically shown, the node tree is automatically hidden
• when clicking somewhere else (unfocus), the inspector panel is hidden, the node tree is shown

this mode could be active at a specific horizontal screen size only.

Jira-URL: https://jira.neos.io/browse/NEOS-614

Editor: side-by-side view

Jira issue originally created by user daniel:

In order to translate content elements of a document, the editor wants to see a side-by-side view (split screen) of the original content and translated content. The editor may choose to defer from a 1-1 translation and remove specific elements in the second language version or add content elements which don't exist in the original language. The side-by-side view will show which content elements correlate with others in the respective language.

Jira-URL: https://jira.neos.io/browse/NEOS-631

Add functionality for the Toggle-UI Button in the ContextBar

Complete the Tree handler logic

Currently the Tree Component only passes the correct arguments for the Enter and ArrowRight keys when pressing a key while the component is focused.

On the following lines we need to pass the new focused node data(prev/next of the current active node) to the handler.
https://github.com/PackageFactory/PackageFactory.Guevara/blob/develop/Resources/Private/JavaScript/Host/Components/Tree/index.js#L88-L93

Integrate stylelint

Implement linting of JavaScript files via `xo`

Insert new panels should support keyboard navigation

Jira issue originally created by user @aertmann:

When opening the insert new panel from either the navigate component or inline handles, the panels options should be navigable with tab, arrow keys and hitting enter/space should select the focussed element.

Jira-URL: https://jira.neos.io/browse/NEOS-340

BUG: Language selector gets stucks after re-login

Jira issue originally created by user soee:

We can interact with backend interface after session expired, but before any action will be processed we need to authenticate first in login window.

The problem:

If our session expired and we click on the language selector and try to change to different language, target language gets selected and we will see login screen. After filling the form and getting authenticated again, our action (language change) is not processed further. - But the UI is stuck in the new state alreasy: The target language is set. (So we have to change currently selected item (target language) to different one to make the page reload and than switch to targen language.)

Would be good to have the language change action processed after relogin.

Jira-URL: https://jira.neos.io/browse/NEOS-924

Show filename of image in inspector

Jira issue originally created by user kapale:

The preview of the image in the inspector should show the filename of the image to make it easier to identify which image was chosen.

Jira-URL: https://jira.neos.io/browse/NEOS-1370

Do not nest elements in BEM class names

E.g. this is not correct BEM notation: treeWrapper__tree__children.
See: bem-site/bem-method#110

Also we should agree on BEM style: bloclName__elementName--modifier vs block-name__element-name--modifier (original notation) vs BlockName-elementName--modifier (Nicolas Galagher's notation, my favourite).

Create a .nvmrc file with the node version constraints

Thanks to @dimaip and @skurfuerst for the hint

Memorize the prop functions which get passed down into child-components

Currently we often got a pattern like this:

<Button onClick={() => this.props.onClick()} />

which is insufficient since it breaks the component life-cycle, especially shouldComponentUpdate(). Instead we should memorize the passed functions to prevent unnecessary re-render calls and function creations.

Clicking editable block in preview mode after editing throws error

Jira issue originally created by user @aertmann:

How to reproduce:

1. Use a editing mode to edit an inline editable property.
2. Switch to a preview mode
3. Click the inline editable property.

Uncaught TypeError: Cannot read property 'element' of undefined (create.js:577)

Jira-URL: https://jira.neos.io/browse/NEOS-583

Finalize the Auto-Publishing mode

Currently, only the UI get's updated (checkbox is checked, duh!), but the functionality of Neos itself isn't replicated, this still needs to be done.

Make it possible to highlight protected pages/content in tree or in the page

Jira issue originally created by user @Sebobo:

This could maybe be resolved by stacking more icons or changing the text
color like the "hidden" property does.

Jira-URL: https://jira.neos.io/browse/NEOS-1680

Don't `dispatch` directly from components

If we use react-redux, it's considered a best practice to not to couple React components with Redux state logic like dispatch, React component should not be aware of the existence of Redux at all.

connect method from react-redux package receives second argument that maps array of callbacks to Redux action creators. So the component just exposes some callback and react-redux does the rest.
See https://github.com/rackt/react-redux/blob/master/docs/api.md#connectmapstatetoprops-mapdispatchtoprops-mergeprops-options

Finalize the DimensionSwitcher Component/Functionality

Currently we embedded a data-fixture for the DimensionSwitcher in the ContextBar Container. Real data needs to be rendered and the functionality for the switch needs to be implemented.

Revisit the end to end tests with selenium

In e2f14ab I've removed all selenium related user stories and the build setup, since it was unreliable. This issue is just a reminder to re-visit this whole topic again later on. Maybe a switch to nightwatch.js or nightmare.js could give us the expected stability?

Decouple the development of the UI package from the Neos backend services

We should strive into a development workflow where we just run a simple Node.js based server for development purposes.

The benefits for this will not only be an server we could actually use in our testing stack, but it would also increase the standalone nature of the UI package, basically we are 100% independent while developing.

The server itself should at least provide the basic endpoints for saving/fetch data, as well as the initial rendering of the app. I don't want to replicate the whole service, but we definitely need a dummy server for testing the UI anyway, so why not also use the server as a development tool too? :)

Stateless function components?

I think most of React components here could be simplified to use the new stateless function component way. Wdyt?