ng-admin 0.4: Eating our own dog food

ng-admin, our AngularJS admin GUI consuming any RESTful API, has just been updated to version 0.4. Here is what's new:

• refined graphical user interface
• streamlined configuration API
• a new Show view
• configurable buttons for views and rows
• configurable title
• read-only entities

You can test ng-admin 0.4 live with the ng-admin demo.

We've been using ng-admin a lot on our own projects, and the additions and adjustments brought by 0.4 intend to make it easier to use, both for developers and end-users. We've especially focused on the first contact experience, and on the ability to customize the GUI even more.

We're sure that you'll love it, especially since it's backwards compatible with the previous version. Read on to see the changes in detail, and the deprecated method calls.

Refined Graphical User Interface

Many visual tweaks and adjustments bring a more harmonized, simple user interface. There is more content on screen, buttons are grouped logically, shapes and labels are more consistent. When our customers use ng-admin to read and edit their data, they don't ask questions anymore, and they are very pleased with the overall user experience.

Streamlined Configuration API

As we implemented more and more CRUDs for our customers, we realized how painful and repetitive the previous configuration API could be. By providing better defaults, we removed the need to configure view titles, or mapped fields. We also added a few helpers to make the developer's life easier. Here is the configuration for the two views above:

post
  .listView()
  .title("All posts") // default title is "[Entity_name] list"
  .pagination(pagination)
  .addField(new Field("id").label("ID"))
  .addField(new Field("title")) // the default list field type is "string"
  .addField(
    new ReferenceMany("tags") // a Reference is a particular type of field that references another entity
      .targetEntity(tag) // the tag entity is defined later in this file
      .targetField(new Field("name")) // the field to be displayed in this list
  )
  .listActions(["show", "edit", "delete"]);

post
  .editionView()
  .title('Edit post "{{ entry.values.title }}"') // title() accepts a template string, which has access to the entry
  .actions(["list", "show", "delete"]) // choose which buttons appear in the action bar
  .addField(new Field("title")) // a text input
  .addField(new Field("body").type("wysiwyg")) // a rich text editor
  .addField(
    new ReferenceMany("tags") // a multi-select
      .targetEntity(tag)
      .targetField(new Field("name"))
  )
  .addField(
    new ReferencedList("comments") // a datagrid of related records
      .targetEntity(comment)
      .targetReferenceField("post_id")
      .targetFields([new Field("id"), new Field("body").label("Comment")])
  );

The most notable difference is the replacement of the view adder:

// ng-admin 0.3 style
entity.addView(new EditView()
  .addField(...)
  .addField(...)
);
// replace by the following in 0.4
entity.editionView()
  .addField(...)
  .addField(...);

Entity.addView() remains available, but will log a deprecation warning.

You'll also notice that the view titles now feel natural, and in a majority of cases you won't need to override them. "Convention over configuration" is one of our mantras, and we'll continue pushing it further.

A New Show View

Sometimes you want to see the detail of a record before editing it. That's what the new Show view is about: displaying a single record on screen, without edition controls.

This Show view is not accessible by default. You'll have to add buttons to the List and / or Edit views to give access to it. Fortunately, it's now super easy thanks to configurable buttons.

Configurable Buttons for Views and Rows

Here is how you setup the set of buttons in the Edit view:

post.editionView().actions(["list", "show", "delete"]);

You can also create an Actions column in the list view by calling the listActions() helper:

post.listView().listActions(["show", "edit", "delete"]);

And if you want to add a button of your own, using a custom directive, switch to a string argument rather than an array:

var template =
  '<show-button entry="entry" entity="entity"></show-button>' +
  '<delete-button entry="entry" entity="entity"></delete-button>' +
  '<my-custom-directive entry="entry"></my-custom-directive>' +
  "<back-button></back-button>";
post.editionView().actions(template);

Each of the buttons you see in the interface can be reused as standalone directives:

• <show-button>
• <edit-button>
• <delete-button>
• <create-button>
• <list-button>
• <back-button>

Configurable title

The default title for each view is more sensible, but sometimes it's not enough:

But since the title() helper accepts an Angular template, you can customize it at will:

post.deletionView().title('Delete post "{{ entry.values.title }}"');

Read-Only Entities

Now that we have a Show view, ng-admin cen be used on top or read-only APIs. Here is, for instance, the configuration and interface for a read-only tags API endpoint:

// a readOnly entity has disabled creation, edition, and deletion views
var tag = new Entity("tags").readOnly();
tag
  .listView()
  .addField(new Field("id").label("ID"))
  .addField(new Field("name"))
  .addField(new Field("published").type("boolean"))
  .addField(
    new Field("custom")
      .type("template")
      .label("Upper name")
      .template("{{ entry.values.name.toUpperCase() }}")
  )
  .listActions(["show"]);

tag
  .showView()
  .addField(new Field("name"))
  .addField(new Field("published").type("boolean"));

app.addEntity(tag);

The List view has no more 'Create' button:

In addition, the links in the 'Id' column link to the Show view by default, where neither edition or deletion are possible:

We hope supporting read-only APIs will open new use cases for ng-admin.

Upgrade

We've deprecated a few methods, but they are still supported, with a warning. As a consequence, upgrading to ng-admin 0.4 should be painless.

Don't forget to read the upgrade guide to read about what is deprecated and will be removed in 0.5.

Send Us Your Feedback

We've been working a lot lately on ng-admin, and we don't intend to stop. We've also received a lot of feature requests ; we know that a mature administration generator must have even more than what ng-admin currently offers. But we'll implement first the features that profit our customers. So if you desperately need a new feature, feel free to send us a pull request on GitHub: ng-admin is entirely open-source.

Don't hesitate to comment here with your feedback, and please spread the word about ng-admin 0.4!