admin-on-rest 0.9 is out

We've just released version 0.9 of admin-on-rest, the React admin GUI for REST APIs. It introduces much required features, such as:

• Responsive UI
• Collapsible Sidebar
• Custom Menu
• Support for HTTP PATCH

We've also worked on performance improvements throughout the library.

You can test admin-on-rest v0.9 online with the admin-on-rest demo.

But first, let's talk about the only backward compatibility break in this version. It will impact you if you upgrade, because it concerns the restClient signature.

Rest Client Change

The expected return format of the restClient has changed. Now it must systematically return an object with a data property.

 Type                 | Response format
 -------------------- | ----------------
 `GET_LIST`           | `{ data: {Record[]}, total: {int} }`
-`GET_ONE`            | `{Record}`
-`CREATE`             | `{Record}`
-`UPDATE`             | `{Record}`
-`DELETE`             | `{Record}`
-`GET_MANY`           | `{Record[]}`
-`GET_MANY_REFERENCE` | `{Record[]}`
+`GET_ONE`            | `{ data: {Record} }`
+`CREATE`             | `{ data: {Record} }`
+`UPDATE`             | `{ data: {Record} }`
+`DELETE`             | `{ data: {Record} }`
+`GET_MANY`           | `{ data: {Record[]} }`
+`GET_MANY_REFERENCE` | `{ data: {Record[]}, total: {int} }`

This removes a potential surprise for developers trying to build their own rest client.

So upgrade your restClient implementation, or your admin-on-rest 0.8 application will break. This shouldn't take more than a few minutes.

Responsive UI

Admin users often use mobile devices to follow their business activity. The usage differs from desktop, because on mobile, users tend to modify data less than on desktop. But they expect to have the same amount of information available as on desktop.

To address this need, admin-on-rest is now usable on mobile. This includes a layout with better usage of the screen real estate, a different UI for the sidebar and main buttons, and the ability to switch components based on the screen size.

You don't have to do anything to benefit from this change: the default <Layout> component is now responsive, and the UI switches to mobile on smaller screen sizes.

However, some components don't fit with the touch UX. <Datagrid>, for instance, is impracticle on small screens. That's why admin-on-rest 0.9 introduces a new list component, called <SimpleList>.

Version 0.9 also introduces a declarative way to switch from <Datagrid> to <SimpleList> according to screen size, called <Responsive>. This new component expects element props named small, medium, and large. It displays the element that matches the screen size (with breakpoints at 768 and 992 pixels).

Here is an example usage of <Responsive> and <SimpleList> in a list of posts:

// in src/posts.js
import React from "react";
import {
  List,
  Responsive,
  SimpleList,
  Datagrid,
  TextField,
  ReferenceField,
  EditButton,
} from "admin-on-rest/lib/mui";

export const PostList = props => (
  <List {...props}>
    <Responsive
      small={
        <SimpleList
          primaryText={record => record.title}
          secondaryText={record => `${record.views} views`}
          tertiaryText={record =>
            new Date(record.published_at).toLocaleDateString()
          }
        />
      }
      medium={
        <Datagrid>
          <TextField source="id" />
          <ReferenceField label="User" source="userId" reference="users">
            <TextField source="name" />
          </ReferenceField>
          <TextField source="title" />
          <TextField source="body" />
          <EditButton />
        </Datagrid>
      }
    />
  </List>
);

While this requires some work for the developer, it's the best way to provide an optimized UX depending on the device screen size.

Collapsible Sidebar

Whether on desktop or on mobile, the sidebar is now collapsible. Just click the hamburger menu to toggle the sidebar visibility.

Once again, you have nothing to do to benefit from that enhancement if you use the default layout.

Custom Menu

Up until version 0.8, if you wanted to customize the menu items, you had to override the entire layout. With the addition of the responsive logic, this became even more unbearable. Admin-on-rest 0.9 simplifies this by letting you write a custom menu component:

// in src/Menu.js
import React from "react";
import MenuItem from "material-ui/MenuItem";
import { Link } from "react-router";

export default ({ resources, onMenuTap, logout }) => (
  <div>
    <MenuItem
      containerElement={<Link to="/posts" />}
      primaryText="Posts"
      onTouchTap={onMenuTap}
    />
    <MenuItem
      containerElement={<Link to="/comments" />}
      primaryText="Comments"
      onTouchTap={onMenuTap}
    />
    <MenuItem
      containerElement={<Link to="/custom-route" />}
      primaryText="Miscellaneous"
      onTouchTap={onMenuTap}
    />
    {logout}
  </div>
);

Then, pass your Menu component to the <Admin> component as the menu prop:

// in src/App.js
import Menu from "./Menu";

const App = () => (
  <Admin menu={Menu} restClient={simpleRestClient("http://path.to.my.api")}>
    // ...
  </Admin>
);

This should facilitate the addition of custom menu entries, or the construction of complex menus (with submenus).

HTTP Patch

It's up to the developer to translate REST request from admin-on-rest to HTTP requests to your server. Admin-on-rest provides built-in restClient implementations that conform to several standards (including GraphQL!).

But if your REST server requires that updates are sent using the HTTP PATCH verb, sending a diff instead of the full record, you were stuck... until now.

REST requests with the UPDATE verb now include the previousData in the payload, in addition to the modified data. This allows you to compute and send a diff as the HTTP request body.

See more details in the REST Client documentation.

What's Next

There are many more features released in 0.9. You should check the Release notes for details.

When we released version 0.8, we thought it was the last release before a 1.0. It took us longer than expected to work on the 0.9 features, and there are still a few things we'd like to work on before a stable release. That's why today's release isn't labeled 1.0. But the next one will!

Please upgrade to 0.9 and send us your feedback about this version in the GitHub repository. And if you like it, please share the word!