Webex Components

Library of React components to easily embed into your web applications!

Webex Components is a set of React components following Webex standard styling, aimed at react developers that want to embed the components into their applications.

Project Status

The Webex Component System is considered to be in beta stage and it's not a generally available product from Webex at this time. This means that the Webex Component System is available for everyone to use but breaking changes may occur as we develop it. We try our best to minimize any breaking changes but they may occur.

While the Webex Component System is not a GA product, we still offer support through all regular channels. However, bug priority is given to products already generally available. We would love for you to use the Webex Component System and be part of the feedback process!

Demo
Install
Webex Components vs Webex Widgets
Usage
Contributing
License
Support

Demo

We use Storybook to showcase all supported components. Our Storybook can be found at https://webex.github.io/components/storybook.

Install

npx install-peerdeps @webex/components

Webex Components vs Webex Widgets

In addition to the Webex Component System, we also offer the Webex Widgets. The Webex Component System (sometimes shortened as Webex Components) is a set of React components that, while following Webex styling, allow for more granularity in terms of layout and source of data. See usage section.

Webex Widgets are based on Webex Components but include the adapter that uses our Javascript SDK to talk to Webex services for you. This means that the Webex Widgets use the SDK Component Adapter to inject the Webex data. All you need is a valid access token and a few parameters based on the widget you want to use.

You have to take the Widget layout as-is, but the benefit is that there are no configurations needed. Install, copy-paste and you have the power of Webex in your application!

To learn more on the Webex Widgets head to its Github repository at https://github.com/webex/widgets.

Usage

Styles

In order to properly style Webex Components, we need to import all the fonts, icons, images and core CSS manually. You will need to add Momentum UI styles in addition to the components' styles. Momentum UI is Webex design system.

Momentum UI Styles

Momentum UI should be installed in your application as a peer dependency of the Webex Components. If you followed the command in the install section it should already be your dependencies. There are two ways to include Momentum UI in your application:

CSS

Copy @momentum-ui/core/fonts directory to the fonts or assets directory of your app. If you don't have a directory, create a public directory from which the fonts to be served
Copy @momentum-ui/core/css/momentum-ui.min.css to the styles or assets directory of your app

In the <head> of your HTML, reference the location of your momentum-ui.min.css

<link rel="stylesheet" type="text/css" href="<path to>/momentum-ui.min.css">

Sass

Copy @momentum-ui/icons/fonts directory to the fonts or assets directory of your app

Add $brand-font-folder, $icon-font-path, and $images-path variables to your app's "variables.scss" file

$brand-font-folder: '<path to fonts directory>';
$icon-font-path: '<path to fonts directory>';
$images-path: '<path to images directory>';

Import @momentum-ui/core/scss/momentum-ui-components.scss into your main entry Sass file after the variables
```
...

@import '@momentum-ui/core/scss/momentum-ui-components';
```
Compile your Sass using your static compiler or bundler

For more on Momentum UI, you can visit Momentum UI's repository

Webex Components Styles

There are two ways to do this:

JavaScript

In your index.js, add the following import:

import '@webex/components/dist/css/webex-components.css';

...

Important: Import Momentum UI styles before importing the Webex Component ones. Webex Components may override certain Momentum UI styles

HTML

In the <head> of your index.html, add the following imports:

<head>
  ...

  <!-- If you added Momentum UI via standard CSS -->
  <link rel="stylesheet" type="text/css" href="<path to>/@momentum-ui/core/css/momentum-ui.min.css" />

  <link rel="stylesheet" type="text/css" href="node_modules/@webex/components/dist/css/webex-components.css" />
</head>

Important: Import Momentum UI styles before importing the Webex Component ones. Webex Components may override certain Momentum UI styles

Adapters

Webex Components are self-updating, meaning, they know how to fetch the data they need. Data is passed to components via adapter classes (see adapters). Adapters are an uniform interface for the Webex Components to consume. They also know how to map the data from their data source to the data the components need.

To use a Webex Component, start by creating a Webex Adapter:

import {WebexJSONAdapter} from '@webex/components';

const adapter = new WebexJSONAdapter(jsonData);

Adapters may interact with different data source types. For instance, as part of the Webex Component repository we distribute a JSON adapter that reads data from JSON files. We also are working on offering an adapter for the Webex browser SDK.

Components

Putting everything together - styles, adapters and components - this is a simple example of how using a component would look like:

import '@webex/components/dist/css/webex-components.css';

import React from 'react';
import ReactDOM from 'react-dom';
import {WebexAvatar, WebexDataProvider, WebexJSONAdapter} from '@webex/components';

// jsonData represents an JSON object with the data to feed components
const adapter = new WebexJSONAdapter(jsonData);

ReactDOM.render(
  <WebexDataProvider adapter={adapter}>
    <WebexAvatar personID="XYZ" />
  </WebexDataProvider>,
  document.getElementById('root')
);

Happy Coding!

Contributing

We'd love for you to contribute to our source code and to make Webex Components even better than it is today! Here are some guidelines that we'd like you to follow.

Issues

Please open an issue and we will get to it in an orderly manner. Please leave as much as information as possible for a better understanding.

License

MIT License

Support

For more developer resources, tutorials and support, visit the Webex developer portal, https://developer.webex.com.

alinasuciu / components