Customise React components through injection

[unclecheese]

As a SilverStripe developer, I want to be able to add, remove, or modify behaviour, state, or UI
in the React-powered areas of admin so that I can customise the application via a module or
my project.

Acceptance Criteria:

• Thirdparty developers have an accessible, easily-understood API for injecting their own components into the CMS UI
• CMS UI components can be overriden with customised replacements
• CMS UI components can be wrapped with Higher Order Components
• Clear, informative errors are thrown if a developer tries to modify behaviour after boot.
• The order in which customisations are applied is predictable and configurable
• The API for extending the UI, state, and functionality of the admin as it pertains to React components is well-documented, and the steps required to do so are explained in detail.
• Existing CMS React components use the DI solution
• The following use cases are made possible through the API. This can be demonstrated by sample code and recipes rather than full implementations.
  • Show the "last edited" date on a gallery tile (component composition)
  • Block opening the detail form of a gallery tile if the file is in draft mode (event overrides)

Tasks:

• Implement context-based DI layer described here
• Replace all existing calls to Injector.js with new context-based solution.
• Apply BottleJS DI library to context-based solution
• Draft an API for an SS-specific wrapper around the DI layer, and get reviewed internally by at least two frontend developers
• Create SS-specific wrapper for DI layer based on agreed-upon API
• Develop several PoC implementations for injected components:
  • Customise the title field of a GalleryItem
  • Create two modules that customise TextField behaviour. One to log character count, and one to check password strength
  • A core UI button that is customised to throw a window.confirm that if denied will kill its original action
• Write documentation on how to use the aforementioned APIs.

Related

• RFC-9: UI Extensibility

Pull Requests

• WIP: Pulls/4/react dependency injection silverstripe-admin#70
• Use new Injector API silverstripe-asset-admin#487
• Docs for React DI #6957

POCs

• https://github.com/open-sausages/experimental-react-di (Depends on experimental asset-admin)

Documentation

#6957

[chillu]

Unsetting estimate, that should be done in backlog grooming by the whole team.

[chillu]

Trying to figure out how much language expressiveness we give up by going to a DI container. Same issue as Injector in SilverStripe PHP really. While we don't need to implement Flow or Typescript right now, DI is going to be a big factor in how useful these language extensions will be to us going forward. In the screenshot above, you can see a component injected through BottleJS, which is explicitly typed to its original implementation (MyComponent). The downside here is that we need to use import MyComponent in addition to calling bottle.container.MyComponent wherever an injected service is used. I think that's an acceptable tradeoff for retaining expressiveness.

[chillu]

@steve-silverstripe As a core contributor with a lot of React experience, I'd be keen to hear your thoughts on this as well. There's "customise frontend" related cards which are linked in the sections of the main RFC at #4887. This one is the basis for lots of this work: Customisation through dependency injection. Aaron is working on a PoC at the moment, which will go towards solidifying an API.

[unclecheese]

I've written up some documentation. https://github.com/open-sausages/experimental-react-di