@dci-edtech/formica NPM

formica-ui

A UI-Framework driven by ant-design for DCI-EdTech micro-services.

formica?

Formica is a genus of ants, commonly known as wood ants or field ants.

What is formica-ui?

formica-ui is a collection of react UI components, for faster and easier creation of new services. It is implemented into the service template, and makes it possible to create pages, components or other react elements inside of services using the newest version of our UI.

Using ant-design (https://ant.design/) and our own component wrappers, we can be sure to have a very professional and customizable layout for our UI components, that can be reused for any service, on any platform.

How to's

How to check component usage?

formica-ui supplies storybook (https://storybook.js.org/) a react framework for easily testing react components, each component of formica-ui can be checked out with storybook and can be tested, including all its props and settings.

Testing out formica-ui components online:

The storybook environment for formica-ui is availible at https://dci-edtech.github.io/formica-ui/

Testing out formica-ui components locally:

To start storybook locally, go to the /docs directory and open the index.html file in your browser.

How to create components for formica-ui?

First, start storybook in watch mode by typing npm run storybook in the terminal and open a browser window at http://localhost:6006/. For your convenience, you will see what you are working on updating in real time.

Creating new components for formica-ui, and storybook support, works almost the same as creating any other react component, there are only a few things needed to be taken into consideration.

Any component sits in the src/Components directory in its own folder (eg /Button), the component contains a .jsx file, containing the component code, a .scss file, containing the components specific custom styles, overwriting ant-designs default styles and a .stories.jsx file, containing the stories of the component.

The following section will show a Button component and its stories, with comments explaining the specific sections of the code:

Important: When you created a new component including stories, run npm run build to add the component to the storybook library before you push your changes.

Component Layout

// src/Components/Button/Button.jsx

// import react and prop-types:
import React from 'react';
import PropTypes from 'prop-types';

// import external component dependencies, like npm modules or an original ant-design component, to be customized or reused:
import { Button as ButtonAnt } from 'antd';

// import the custom style-sheet to overwrite ant-designs defaults:
import './button.scss';

// export the component on creation, and supply all props that belong to the component + any other prop that could be supplied (...props)
export const Button = ({ type, size, label, danger, ...props }) =>
{
    // work on the component, like you are used to, and use the props for their respective settings:
    return (
        <ButtonAnt
            size={ size }
            type={ type }
            danger={ danger }
            {...props}
        >
            { label }
        </ButtonAnt>
    );
};

// create the propTypes for every prop, so storybook knows what kind of type a prop is. JSDoc style comments will be shown as descriptions in the storybook documentation of the component:
Button.propTypes = {
  /**
   * Is this the principal call to action on the page?
   */
  type: PropTypes.string,
  /**
   * For dangerous operations
   */
  danger: PropTypes.bool,
  /**
   * How large should the button be?
   */
  size: PropTypes.oneOf(['small', 'default', 'large']),
  /**
   * Button contents
   */
  label: PropTypes.string.isRequired,
  onClick: PropTypes.func,
};

// set up a few default prop values:
Button.defaultProps =
{
    danger: false,
    type: 'primary',
    size: 'default',
    onClick: undefined,
};

Story layout

// src/Components/Button/Button.stories.jsx

// import react
import React from 'react';

// import the ant-stylesheet from the module here, on microservice level, it is pre-imported into the main application file.
import 'antd/dist/antd.css';

// import the component
import { Button } from './Button';

// export story settings
export default
{
    // The title and section of the component, this defines where to find the component in the storybook overview:
    title: 'Components/Button',
    // The used component:
    component: Button,
    // custom arguments, for setting up the component explorer:
    argTypes:
    {
        // for example, the button size can be changed by using a select-box, that has 3 options:
        size:
        {
            control:
            {
                type: "select", 
                options: [ 'small', 'default', 'large' ]
            }
        }
    }
};

// create a template utilizing the components and handing over the arguments, that will be set up in the following lines:
const Template = (args) => <Button {...args} />;

//...

// create stories, that can be selected in the component explorer, by binding the arguments to the Template:
export const Large = Template.bind({});

// change settings to your liking to have visible changes in the component setup:
Large.args =
{
    size: 'large', // notice how the size is different on each of the following stories, this will be reflected in the component explorer:
    type: "default",
    danger: false,
    label: 'Button'
};

export const Default = Template.bind({});
Default.args =
{
    size: 'default',
    type: "default",
    danger: false,
    label: 'Button'
};

export const Small = Template.bind({});
Small.args =
{
    size: 'small',
    type: "default",
    danger: false,
    label: 'Button'
};

How to use formica-ui components with a service?

In the future, formica-ui will be a dependency of the service-template, and all its components can be used inside of it in any way you see fit, a detailed documentation this topic will follow