React-gadgets NPM

react-gadgets

React Gadgets

Summary

React-Gadgets is a React library speficailly intended for use in a SharePoint Framework (SPFx) webpart. These react components are built using the best practice of lifting state up. A component can be a functional or class component. It is also possible that a component has its own state. However, most of the time compoonents lift state up to the parent (SPFx webpart). The parent SPFX webpart has a parent 'wrapper' component that handles the over all state inclduing data, crud operations, and component interactions.

Install

If you are also developing the SharePoint Framework web part at the same time, using the NPM module can be inconvenient as you might be making changes in both project simultaneously. To support this, use npm link.

Clone this project.
From your source project (this), run the following:
Run npm install
Run npm link to create a global symlink for this project to be used in other projects.
Next, from your SPFx project directory (spfx-gadget-extensions OR spfx-gadget-webparts), run the following:
npm link react-gadgets
1. You only need to do this if you are working on the SPFx solution as well.

This will link the NPM module via a global symlink that allows you to see your react-gadget changes in your SPFX project live without having to hassle with an NPM publish. When you run a build in your other project it will include this package.

Usage

Your can use the following starter code to create a new functional (stateless) component

/**
 * @class Functional component template
 */

import * as React from 'react';
import IProp from '../../interfaces/IProp';
import cStyles from './MenuGroupItem.scss';
import Skeleton from 'react-loading-skeleton';
import defaultTheme from '../../theme/DefaultTheme';


interface Props extends IProp {

}

export function SampleFunctionalComponent(props: Props) {

    const { theme } = props;
    const themeConfig = !theme ? defaultTheme : theme;
    const themeStyles = {
        sample: {
            color: themeConfig.color.primary
        }
    }

    return (
        <div className={cStyles.container} style={themeStyles.sample}>
            Sample Gadget
        </div>
    )

}

export default SampleFunctionalComponent;

You can use the following starter code to create a new class (stateful) component

/**
 * @class Class component template
 */

import * as React from 'react';
import IProp from '../../interfaces/IProp';
import cStyles from './MenuGroupItem.scss';
import Skeleton from 'react-loading-skeleton';
import defaultTheme from '../../theme/DefaultTheme';


interface Props extends IProp {

}

class SampleClassComponent extends React.Component<Props, State> {

    constructor(props: Props) {
        super(props)

        // initialize your state
    }

    public render(): JSX.Element {

        const { theme } = this.props;
        const themeConfig = !theme ? defaultTheme : theme;
        const themeStyles = {
            sample: {
                backgroundColor: themeConfig.color.primary
            }
        }


        return (
            <div className={cStyles.container} style={themeStyles.sample}>
                Sample Class Component
            </div>
        )
    }

}

export default SampleClassComponent;

Development/Debugging

This project contains two seperate projects. The root project is the React component library. There is also a sub-project called gadgets. This project is based on create-react-app and allows for a live realoading/debugging environment.

Start debugging

From the root project run npm start.
Open a new terminal and change into the gadgets project.
Run npm start from this directory.

At this point both projects will be running and you should have a browser window http://localhost:3000 open. As you make changes to your project it will reload and refresh after each change.

Note: Make sure you have VSCode setup for auto-save via File > Auto Save for the project to auto-rebuild upon change.

How to use

React-Gadget components are setup to be used a specific way to allow for proper styling/themeing.

Themeing

Each component should have the import IProp from '../../interfaces/IProp'; statement. This imports the default IProp interface:

import ITheme from '../interfaces/ITheme';

export default interface IProp {
    theme?: ITheme;
}

This interface has a optional prop called theme that can be passed into any component. Each component you build has its own Prop interface:

interface Props extends IProp {

}

That extends the IProp interface. This way, you always get the theme object imported into all of your components.

Theme styles can be used in two different ways: CSS in JS OR styled-components . The default and preffered method is CSS in JS. Let's take a look at that first.

CSS in JS

Looking at the started code above, you can see that a component has the following code within its render method.

const { theme } = this.props;
const themeConfig = !theme ? defaultTheme : theme;
const themeStyles = {
    sample: {
        backgroundColor: themeConfig.color.primary
  }
}

const { theme } = this.props; imports the theme object from props.
const themeConfig = !theme ? defaultTheme : theme; checks tom see if the theme was passed in from the parent component (SPFx)/ If it not found it uses the defaultTheme that is include in the project.
- Note: The default theme and SPFx theme are based on the ITheme interface. Changes the overall structure of this interface must be kept in sync between projects to ensure proper intellsiense and validation.
The sample object below creates a single CSS class in JS called sample and assigns the background-color to the primary color from the theme object.
- This is convert to normal css as .sample { background-color: #someColor}. Notice how CSS properties are defined using CAML case.
  - css:background-color
  - react:backgroundColor

const themeStyles = {
    sample: {
        backgroundColor: themeConfig.color.primary
  }
}

SCSS

Normal scss can be used for styles that are specific to the component and do not include colors that are part of the overall theme.
The import cStyles from './MenuGroupItem.scss'; statement imports the local scss file into the component. You can then reference the css via cStyles.sample. SCSS styles should always be applied via the className attribute.

Styled components

Styled-components allows you to write actual CSS code to style your components. You used the styled component to create a stlyed HTML element that uses traditional css. Styled components generate an actual react component with the defined styles. In the example below a <li> element is created tha applies styles to the child a tag.

  const ListIem = styled.li`
      a {
          color: ${themeConfig.color.accent4};
      }
      & a:hover {
          color: ${themeConfig.color.accent1};
      }
  `;

Use the styled component like this:

<ListItem>
  <a href="">Sample text</a>
</ListItem>

The output will be:

<li>
  <a href="">Sample text</a>
</li>

With styles applied dynbamically via the styled-components module.

What should I use and where do In use it

In a react gadget component we use styles differently, depending on where they origin from.

SCSS styles (no theming): Used via the className={} attribute via cStyles.
CSS in JS (supports theme values): Used via the style={} attribute by refering the appropriate themeStyles object.
Styled-Component (supports theme values): Used when psuedo styles are needed. Creates wrapper component for your content.

<div className={SCSS Styles go here} style={CSS in JS goes here}>

Get Started

I want to...

Build a component that has internal properties that will change during the component lifecycle
- Use a stateful component.
Build a component that will receive its data from another component.
- Use a functional component.
Use a theme attribute in my component.
- Use CSS in JS or a styled component.
Created basic css for my component
- Use the SCSS file created with each component.

react-gadgets v0.0.2