README
Spark Base Widget (@ciscospark/spark-widget-base)
This base React component does the initial React, Spark authentication, and Redux setup for all Spark widgets.
Usage
There are a number of ways to use our spark-widget-base
repo to begin developing your own widget on the Cisco Spark platform.
IMPORTANT NOTE: In order to authenticate to Spark, the resulting components require an
accessToken
orguestToken
prop that you must provide when instantiating your widget. Please see the Authentication Section
Quick Start
To automatically setup Cisco Spark connections, and register your widget into the global browser store, you can use the sparkWidgetBase
enhancer like so:
import sparkWidgetBase from '@ciscospark/spark-widget-base';
function MyWidget(props) {
return <div>My Widget</div>;
}
export default sparkWidgetBase('myWidget', MyWidget);
Widgets using Redux
If you are also using redux
for state management and want to provide your own reducers, import and use the constructSparkEnhancer
higher order component instead:
import React, {Component} from 'react';
import {constructSparkEnhancer} from '@ciscospark/spark-widget-base';
import reducers from './reducer';
class MyWidget extends Component {
render() {
return <div>My Widget's name is {this.props.displayName}</div>
}
}
export default constructSparkEnhancer({
name: 'myWidget',
reducers
})(MyWidget);
By constructing your component like this, the constructor will combine your reducers with internal spark reducers and update your store with a react-redux
<Provider />
. This will allow you to connect()
any child components and gain access to the store.
Authentication
In order to authenticate to Spark, you must provide the resulting React Components with an accessToken
prop.
This can be done programatically like so:
import MyWidget from './MyWidget';
class MyApp extends Component {
render() {
return <MyWidget accessToken={this.getState().accessToken} />;
}
}
The widgets also support guest tokens in the form of JWT. To provide a guest token to authenticate, use the guestToken
prop.
SDK Instance
In addition to accessToken
or guestToken
, the widgets can accept the property sdkInstance
.
This is a Webex SDK instance that has already been created and authenticated.
The SDK requires certain plugins to be loaded in order for the widgets to function properly:
- authorization
- logger
- meetings
- people
- phone
- rooms
- internal.conversation
- internal.feature
- internal.flag
- internal.mercury
- internal.presence
- internal.search
- internal.team
Advance Usage
When your widget instantiates, it will get receive props from our main store. Some of the data and functions you will have access to:
sparkState
: an object that will provide you with device registration and authentication statessparkInstance
: thespark
object that is provided by the Webex JS SDK. You can use this object to interact with Webex APIs as the authenticated user.
Additional Enhancers
This package also provides some additional enhancers to make your widget setup a bit easier:
withInitialState
(default): Establishes widget initial states with Redux and injects the React-Redux storeProvider
componentwithBrowserGlobals
(default): Enables widgets to be instantiated globally usingwindow.ciscospark.widget(el).widgetName
(usage example)withDataAPI
(default): Enables widgets to be instantiated using a data API (usage example)withIntl
: A helper for enabling react-intl in your widget. You can pass a config object that will make intl available to you:{locale: 'en', messages}
To use any of these enhancers you can apply them directly to a Component: withIntl(MyComponent)
.
Or you can compose them using a libary like recompose:
import {compose} from 'recompose';
import {
withIntl
} from '@ciscospark/spark-widget-base';
import {MyWidget} from './MyWidget';
const MyWrappedWidget = compose(
withIntl()
)(MyWidget);