blueocean-plugin/blueocean-dashboard

Dashboard plugin

This plugin provides the main Dashboard user interface for Blue Ocean. It has a bunch of GUI components and extension points for other plugins to extend. This is where the fun happens.

Running and modifying this plugin

With mvn

1. Go into blueocean-plugin and run mvn hpi:run in a terminal. (mvn clean install from the root of the project is always a good idea regularly!)
2. From this directory, run gulp bundle:watch to watch for JS changes and reload them.
3. Open browser to http://localhost:8080/jenkins/blue/ to see this
4. hack away. Refreshing the browser will pick up changes. If you add a new extension point or export a new extension you may need to restart the mvn hpi:run process.

With npm/storybook

We are supporting React Storybook https://voice.kadira.io/introducing-react-storybook-ec27f28de1e2#.8zsjledjp

npm run storybook

Then it’ll start a webserver on port 9001. Further on any change it will refresh the page for you on the browser. The design is not the same as in blueocean yet but you can fully develop the components without a running jenkins,

Writing Stories

Basically, a story is a single view of a component. It's like a test case, but you can preview it (live) from the Storybook UI.

You can write your stories anywhere you want. But keeping them close to your components is a pretty good idea.

Let's write some stories:

// src/main/js/components/stories/button.js

import React from 'react';
import { storiesOf, action } from '@kadira/storybook';

storiesOf('Button', module)
  .add('with a text', () => (
    <button onClick={action('clicked')}>My First Button</button>
  ))
  .add('with no text', () => (
    <button></button>
  ));

Here, we simply have two stories for the built-in button component. But, you can import any of your components and write stories for them instead.

Configurations for storybook

Now you need to tell Storybook where it should load the stories from. For that, you need to add the new story to the configuration file .storybook/config.js:

// .storybook/config.js
import { configure } from '@kadira/storybook';

function loadStories() {
  require('../src/main/js/components/stories/index');
  require('../components/stories/button'); // add this line
}

configure(loadStories, module);

or to the src/main/js/components/stories/index.js (this is the preferred way):

// src/main/js/components/stories/index.js
require('./pipelines');
require('./status');
require('./button'); // add this line

That's it. Now simply run “npm run storybook” and start developing your components.

Testing

We have created different test environments that you can us during development. To run the test once:

npm run test

TDD support via watch

npm run test:watch

Can be used for TDD with a rapid feedback loop (as soon you save all tests will run)

Linting with npm

ESLint with React linting options have been enabled.

npm run lint

lint:fix

You can use the command lint:fix and it will try to fix all offenses, however there maybe some more that you need to fix manually.

npm run lint:fix

lint:watch

You can use the command lint:watch and it will give rapid feedback (as soon you save, lint will run) while you try to fix all offenses.

gulp lint:watch --continueOnLint

Development hints

redux

To follow the explanations I recommend you are familiar with http://redux.js.org//docs/basics/index.html.

The basic idea behind our implementation is based on the three principles of redux http://redux.js.org/docs/introduction/ThreePrinciples.html:

1. Single source of truth - The state of your whole application is stored in an object tree within a single store.

I implemented our single source of truth in blueocean-web/src/main/js/main.jsx where we get all jenkins.main.stores extensions. If we have plugins that are implementing the redux store then we use this information (basically we chain the exposed reducer - see 3.) to configure the store.

    const stores = ExtensionPoint.getExtensions("jenkins.main.stores");
    let store;
    if (stores.length === 0) {
        store = configureStore(()=>null); // No store, dummy functions
    } else {
        store = configureStore(combineReducers(Object.assign(...stores)));
    }

    // Start React
    render(
        <Provider store={store}>
            <Router history={history}>{ makeRoutes() }</Router>
        </Provider>
      , rootElement);

2. State is read-only - The only way to mutate the state is to emit an action, an object describing what happened.

In blueocean-dashboard/src/main/js/redux/actions.js we have defined all admin related actions. We call some of this actions e.g. fetchRunsIfNeeded from the view e.g. Activity.jsx

    componentWillMount() {
        if (this.context.config && this.context.params) {
            const {
                params: {
                    pipeline,
                },
                config = {},
            } = this.context;
            config.pipeline = pipeline;
            this.props.fetchRunsIfNeeded(config);
        }
    }

3. Changes are made with pure functions - To specify how the state tree is transformed by actions, you write pure reducers.

Reducers are just pure functions that take the previous state and an action, and return the next state. Remember to return new state objects, instead of mutating the previous state.

blueocean-dashboard/src/main/js/redux/reducer.js here we define all the reducer we are currently using in the admin app and expose them. To follow along the above code snippet from Activity.jsx the fetchRunsIfNeeded looks like:

    fetchRunsIfNeeded(config) {
        return (dispatch) => {
            const baseUrl = `${config.getAppURLBase()}/rest/organizations/jenkins` +
            `/pipelines/${config.pipeline}/runs`;
            return dispatch(actions.fetchIfNeeded({
                url: baseUrl,
                id: config.pipeline,
                type: 'runs',
            }, {
                current: ACTION_TYPES.SET_CURRENT_RUN_DATA,
                general: ACTION_TYPES.SET_RUNS_DATA,
                clear: ACTION_TYPES.CLEAR_CURRENT_RUN_DATA,
            }));
        };
    },

    fetchIfNeeded(general, types) {
        return (dispatch, getState) => {
            const data = getState().adminStore[general.type];
            dispatch({ type: types.clear });

            const id = general.id;

            if (!data || !data[id]) {
                return fetch(general.url)
                    .then(response => response.json())
                    .then(json => {
                        dispatch({
                            id,
                            payload: json,
                            type: types.current,
                        });
                        return dispatch({
                            id,
                            payload: json,
                            type: types.general,
                        });
                    })
                    .catch(() => dispatch({
                        id,
                        payload: [],
                        type: types.current,
                    })
                    );
            } else if (data && data[id]) {
                dispatch({
                    id,
                    payload: data[id],
                    type: types.current,
                });
            }
            return null;
        };
    },

If you have followed a bit the admin app this code reminds a lot of the old "fetch" aka AjaxHoc aka ghettoAjax code. The basic idea is to see if we already have the data in our state const data = getState().adminStore[general.type]; and if so dispatch ACTION_TYPES.SET_CURRENT_RUN_DATA with payload: data[id], if not we go ahead and fetch(general.url) and using promises to finally dispatch first ACTION_TYPES.SET_CURRENT_RUN_DATA and then ACTION_TYPES.SET_RUNS_DATA

    [ACTION_TYPES.SET_CURRENT_RUN_DATA](state, { payload }): State {
        return state.set('currentRuns', payload);
    },
    [ACTION_TYPES.SET_RUNS_DATA](state, { payload, id }): State {
        const runs = state.get('runs') || {};
        runs[id] = payload;
        return state.set('runs', runs);
    },

Now coming back to reducers you see in the end we return a new State were we set 'currentRuns' and 'runs'. Since actions are not synchronous we are exposing the runs/currentRuns in the reducer as

export const runs = createSelector([adminStore], store => store.runs);

We use https://github.com/reactjs/reselect here to compute derived data, allowing Redux to store the minimal possible state. For example to see whether the current pipeline is a multibranch pipe:

export const isMultiBranch = createSelector(
    [pipeline], (pipe) => {
        if (pipe && pipe.organization) {
            return !!pipe.branchNames;
        }
        return null;
    }
);

In e.g. RunDetails.jsx we are using both selector like:

import {
    actions,
    currentRuns as runsSelector,
    isMultiBranch as isMultiBranchSelector,
    createSelector,
    connect,
} from '../redux';
//...
const selectors = createSelector(
    [runsSelector, isMultiBranchSelector],
    (runs, isMultiBranch) => ({ runs, isMultiBranch }));

export default connect(selectors, actions)(RunDetails);

connect injects the selectors and actions to our class via properties so we can use them in the render():

// e.g. if isMultiBranch is null this means that the "current" pipeline is not set
// early out
        if (!this.context.params
            || !this.props.runs
            || this.props.isMultiBranch === null
        ) {
            return null;
        }

//...using the runs selector:
const result = this.props.runs.filter(...);