This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.
Custom Widgets¶
Custom widgets are independent applications, tocco-apps, that can be embedded on external websites.
Widget package¶
Create a new package for your widget in the widgets
folder:
yarn plop Package
Add the widget to a bundle:
yarn plop Bundle app
The src/main.js
is the entry point of the widget.
Env¶
Define the env
inside the initApp
of the main.js
. There is a helper function env.setInputEnvs(input)
which sets the env vars from the input automatically.
Without the correct envs the core component will not behave properly for widgets (e.g. entity-detail
should not render the meta-information inside the footer).
import {env} from 'tocco-util'
...
const initApp = (id, input, events, publicPath) => {
const content = <MyWidget />
// set env from input
env.setInputEnvs(input)
const store = appFactory.createStore(reducers, sagas, input, packageName)
...
return appFactory.createApp(packageName, content, store, {...})
}
Input / PropTypes¶
The widgets receives the config from the Widget Config entity as input object with some additional meta information:
appContext
object containing thewidgetConfigKey
backendUrl
locale
Note
The selection
prop type, which has been added automatically, can be removed for widgets.
Example:
import PropTypes from 'prop-types'
import {appContext} from 'tocco-util'
const initApp = (...) => {
...
}
...
const ExampleWidgetApp = props => {
...
}
ExampleWidgetApp.propTypes = {
appContext: appContext.propTypes.isRequired,
backendUrl: PropTypes.string,
locale: PropTypes.string,
...
}
Name |
Description |
Example |
---|---|---|
appContext |
Meta information about the embedded widget.
Available |
{
"embedType": "widget",
"widgetConfigKey": "123",
}
|
backendUrl |
The base url of the nice2 backend. |
|
locale |
The locale of the widget. If the |
|
Visibility status integration¶
Your widget app will get a function onVisibilityStatusChange
as an input property. This can be used to communicate to the system running the widget
that some state, in which it might want to display some content, was reached. An example are the status list
and detail
in the entity-browser
app
that get triggered when the user navigates to one of the corresponding sites, or the success
status in the event-registration
app that gets triggered
when the registration is successfully created.
See Visibility status configuration on how to configure visibility status to be available on a widget config.
When implementing your own visibility status, we recommend creating a visibilityStatus.js
status file in the root of your src
folder, containing an
object of all your implemented visibility status and then only using the values defined in there. This ensures no typo is made when changing visibilty status
which would create hard to debug errors, as well as serving as a common way to document all available status in code.
Instead of passing onVisibilityStatusChange
through your app and calling it by hand, use the action creator
externalEvents.fireVisibilityStatusChangeEvent
.
visibilityStatus.js
¶export const VisibilityStatus = {
list: 'list',
detail: 'detail',
success: 'success'
}
fireVisibilityStatusChangeEvent
to change to success
state¶// ExampleAppContainer.js
import {connect} from 'react-redux'
import {externalEvents} from 'tocco-app-extensions'
const mapActionCreators = {
fireVisibilityStatusChangeEvent: externalEvents.fireVisibilityStatusChangeEvent
}
const mapStateToProps = state => ({})
export default connect(mapStateToProps, mapActionCreators)(ExampleApp)
// ExampleApp.js
import {VisibilityStatus} from './visibilityStatus'
const ExampleApp = ({fireVisibilityStatusChangeEvent}) => {
fireVisibilityStatusChangeEvent([VisibilityStatus.success])
}
For externalEvents.fireVisibilityStatusChangeEvent
to work you’ll have to make sure that externalEvents
has been added to your apps store
with the correct events.
main.js
that adds externalEvents
to the store¶const EXTERNAL_EVENTS = ['onVisibilityStatusChange']
const initApp = (id, input, events, publicPath) => {
const store = appFactory.createStore(reducers, sagas, input, packageName)
externalEvents.addToStore(store, state => appFactory.getEvents(EXTERNAL_EVENTS, state.input))
}