Skip to content
A frontend framework for building admin SPAs on top of REST services, using React
JavaScript CSS Other
Branch: master
Clone or download
Pull request Compare This branch is 4785 commits behind marmelab:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs
example
src
.babelrc
.eslintrc
.gitignore
.travis.yml
CHANGELOG.md
LICENSE.md
Makefile
README.md
package.json

README.md

admin-on-rest Build Status

A frontend Framework for building admin applications on top of REST services, using ES6, React and Material UI.

admin-on-rest demo

Installation

Admin-on-rest is available from npm. You can install it (and its required dependencies) using:

npm install --save-dev admin-on-rest

Documentation

Head to http://marmelab.com/admin-on-rest/ for a complete documentation. If you installed the library via npm, it's also available offline, under the node_modules/admin-on-rest/docs/ directory.

Example

// in app.js
import React from 'react';
import { render } from 'react-dom';
import { simpleRestClient, Admin, Resource } from 'admin-on-rest';

import { PostList, PostEdit, PostCreate, PostIcon } from './posts';

render(
    <Admin restClient={simpleRestClient('http://localhost:3000')}>
        <Resource name="posts" list={PostList} edit={PostEdit} create={PostCreate} icon={PostIcon}/>
    </Admin>,
    document.getElementById('root')
);

The <Resource> component is a configuration component that allows to define sub components for each of the admin view: list, edit, and create. These components use Material UI and custom components from admin-on-rest:

// in posts.js
import React from 'react';
import { List, Edit, Create, Datagrid, DateField, TextField, EditButton, DisabledInput, TextInput, LongTextInput, DateInput } from 'admin-on-rest/lib/mui';
export PostIcon from 'material-ui/svg-icons/action/book';

export const PostList = (props) => (
    <List {...props}>
        <Datagrid>
            <TextField source="id" />
            <TextField source="title" />
            <DateField source="published_at" />
            <TextField source="average_note" />
            <TextField source="views" />
            <EditButton basePath="/posts" />
        </Datagrid>
    </List>
);

const PostTitle = ({ record }) => {
    return <span>Post {record ? `"${record.title}"` : ''}</span>;
};

export const PostEdit = (props) => (
    <Edit title={PostTitle} {...props}>
        <DisabledInput source="id" />
        <TextInput source="title" />
        <TextInput source="teaser" options={{ multiLine: true }} />
        <LongTextInput source="body" />
        <DateInput label="Publication date" source="published_at" />
        <TextInput source="average_note" />
        <DisabledInput label="Nb views" source="views" />
    </Edit>
);

export const PostCreate = (props) => (
    <Create title="Create a Post" {...props}>
        <TextInput source="title" />
        <TextInput source="teaser" options={{ multiLine: true }} />
        <LongTextInput source="body" />
        <TextInput label="Publication date" source="published_at" />
        <TextInput source="average_note" />
    </Create>
);

Configuring The REST Client

REST isn't a standard, so it's impossible to make a REST client library that will work for all REST backends. Admin-on-rest deals with this problem by letting you provide a REST client function. This is the place to translate REST requests to HTTP requests, and HTTP responses to REST responses.

The <Admin> component expects a restClient parameter, which is a function with the following signature:

/**
 * Execute the REST request and return a promise for a REST response
 *
 * @example
 * restClient(GET_ONE, 'posts', { id: 123 })
 *  => new Promise(resolve => resolve({ data: { id: 123, title: "hello, world" } }))
 *
 * @param {string} type Request type, e.g GET_LIST
 * @param {string} resource Resource name, e.g. "posts"
 * @param {Object} payload Request parameters. Depends on the action type
 * @returns {Promise} the Promise for a REST response
 */
const restClient = (type, resource, params) => new Promise();

The expected format for REST requests and responses is documented in src/rest/README.md; you can find an example in src/rest/simple.js;

The restClient is also the ideal place to add custom HTTP headers, authentication, etc.

Batteries Included But Removable

Although it's fast and easy to build an admin using the <Admin> and <Resource> components, it is also possible to include the admin logic into an existing React application. You are strongly encouraged to use the lower-level elements or admin-to-rest, provided you're familiar with Redux, react-router and redux-saga.

The library makes no assumption on the side effect library you want to use, but provides examples for redux-saga.

The side effects expected by admin-on-rest are AJAX calls to the REST backend(s), and redirects. They must respond to the following actions:

  • CRUD_GET_LIST => CRUD_GET_LIST_SUCCESS
  • CRUD_GET_ONE => CRUD_GET_ONE_SUCCESS
  • CRUD_UPDATE => CRUD_UPDATE_SUCCESS
  • CRUD_CREATE => CRUD_CREATE_SUCCESS
  • CRUD_DELETE => CRUD_DELETE_SUCCESS

Check sideEffect/saga.js for a detail of the inputs and outputs

Todo

  • Add more documentation
  • Improve error handling
You can’t perform that action at this time.