UI-Extensions contains the building blocks for the SCM-Manager ui extension system.
\nExtension points are spots in the ui, where the ui could be extended or modified.\nAn extension point requires a unique name and is represented as React component.
\nExample:
\n<div>\n <h2>Repository</h2>\n <ExtensionPoint name=\"repo.details\" />\n</div>We can register an extension, in the form of a React component, to the \"repo.details\" extension point, by using the binder:
\nimport { binder } from \"@scm-manager/ui-extensions\";\n\nconst Rtfm = () => {\n return <strong>Read the f*** manual</strong>;\n};\n\nbinder.bind(\"repo.details\", Rtfm);The ExtensionPoint will now find and render the Rtfm component.
\nAn extension point can render multiple extensions at one. This can be done with the renderAll parameter:
\n<div>\n <h2>Repository</h2>\n <ExtensionPoint name=\"repo.details\" renderAll={true} />\n</div>Now we can bind multiple components to the same extension point.
\nconst Rtfm = () => {\n return <strong>Read the f*** manual</strong>;\n};\n\nconst RealyRtfm = () => {\n return <h1>Read the f*** manual</h1>;\n};\n\nbinder.bind(\"repo.details\", Rtfm);\nbinder.bind(\"repo.details\", RealyRtfm);An extension point author can pass React properties to the extensions. This can be done with the props property:
<div>\n <ExtensionPoint name=\"repo.title\" props={{name: \"myrepo\"}} />\n</div>The extension becomes now the defined react properties as input:
\nconst Title = (props) => {\n return <h1>Repository {props.name}</h1>;\n};\n\nbinder.bind(\"repo.title\", Title);An ExtensionPoint is able to render a default, if no extension is bound to the ExtensionPoint.\nThe default can be passed as React children:
\n<ExtensionPoint name=\"repo.title\">\n <h1>Default Title</h1>\n</ExtensionPoint>An extension can specify a predicate function to the binder.\nThis function becomes the props of the ExtensionPoint as input and only if the predicate returns true the extension will be rendered:
\nconst GitAvatar = () => {\n return <img src=\"/git/avatar.png\" alt=\"git avatar\" />;\n};\n\nbinder.bind(\"repo.avatar\", GitAvatar, (props) => props.type === \"git\");<ExtensionPoint name=\"repo.avatar\" props={{type: \"git\"}} />Both extension points and extensions can share a common typescript type to define the contract between them.\nThis includes the name, the type of props passed to the predicate and what type the extensions themselves can be.
Example:
\n type CalculatorExtensionPoint = ExtensionPointDefinition<\"extension.calculator\", (input: number[]) => number, undefined>;\n \n const sum = (a: number, b: number) => a + b;\n binder.bind<CalculatorExtensionPoint>(\"extension.calculator\", (input: number[]) => input.reduce(sum, 0));\n const calculator = binder.getExtension<CalculatorExtensionPoint>(\"extension.calculator\");\n const result = calculator([1, 2, 3]);In this example, we use the base type ExtensionPointDefinition<name, type, props> to declare a new extension point.
As we do not need a predicate, we can define the props type parameter as undefined. This allows us to skip the props parameter in the\ngetExtension method and the predicate parameter in the bind method.
When using bind to define an extension or getExtension to retrieve an extension, we can pass the new type as a type parameter.\nBy doing this, we allow typescript to help us with type-checks and offer us type-completion.
Negative Example:
\n type CalculatorExtensionPoint = ExtensionPointDefinition<\"extension.calculator\", (input: number[]) => number, undefined>;\n \n const sum = (a: number, b: number) => a + b;\n binder.bind<CalculatorExtensionPoint>(\"extension.calculato\", (input: number[]) => input.reduce(sum, 0));This code for example, would lead to a compile time type error because we made a typo in the name of the extension when binding it.\nIf we had used the bind method without the type parameter, we would not have gotten an error but run into problems at runtime.
If an extension point defines children those children are propagated to the extensions as children prop e.g:
\nconst MyExtension:FC = ({children}) => (\n <div className=\"fancy-box\">{children}</div>\n)\nconst App = () => {\n binder.bind(\"box\", MyExtension);\n return (\n <ExtensionPoint name=\"box\">\n <p>Box Content</p>\n </ExtensionPoint>\n );\n}The example above renders the following html code:
\n<div class=\"fancy-box\">\n <p>Box Content</p>\n</div>An exception is when the extension already has a children property, this could be the case if jsx is directly bind.\nThis exception applies not only to the children property it applies to every property.\nThe example below renders Ahoi, because the property of the jsx overwrites the one from the extension point.
type Props = {\n greeting: string;\n}\n\nconst GreetingExtension:FC<Props> = ({greeting}) => (\n <>{greeting}</>\n);\n\nconst App = () => {\n binder.bind(\"greet\", <GreetingExtension greeting=\"Ahoi\" />);\n return <ExtensionPoint name=\"greet\" props={{greeting: \"Moin\"}} />;\n};Sometimes it can be useful to allow plugin developers to wrap an existing component.\nThe wrapper property is exactly for this case, it allows to wrap an existing component with multiple extensions e.g.:
const Outer: FC = ({ children }) => (\n <>Outer -> {children}</>\n);\n\nconst Inner: FC = ({ children }) => (\n <>Outer -> {children}</>\n);\n\nconst App = () => {\n binder.bind(\"wrapped\", Outer);\n binder.bind(\"wrapped\", Inner);\n return (\n <ExtensionPoint name=\"wrapped\" renderAll={true} wrapper={true}>\n Children\n </ExtensionPoint>\n );\n}The example above renders Outer -> Inner -> Children, because each extension is passed as children to the parent extension.
Extensions are automatically sorted on retrieval based on either their extensionName (ASC) and/or their priority (DESC),\nwhich can be passed upon binding an extension.
Example:
\n binder.bind(\"extension.point.example\", <div>Hello World the fourth</div>, { priority: 10, extensionName: \"ignore\" });\n binder.bind(\"extension.point.example\", <div>Hello World the third</div>, { priority: 50 });\n binder.bind(\"extension.point.example\", <div>Hello World the first</div>, { priority: 100, extensionName: \"me\" });\n binder.bind(\"extension.point.example\", <div>Hello World the second</div>, { priority: 75 });\n\n const extensions = binder.getExtensions(\"extension.point.example\");\n \n /**\n * Output =>\n * \n * Hello World the first\n * Hello World the second\n * Hello World the third\n * Hello World the fourth\n */