hyperoslo / hyper_admin

Admin solution for Ruby on Rails.

HyperAdmin

HyperAdmin is an admin interface solution for Ruby on Rails. It works pretty much as a mountable engine, except it always mounts under /admin. This is currently not configurable.

Installation

Simply put the gem in your Rails application's Gemfile:

gem 'hyper_admin'

Then, install the bundle as usual:

$ bundle install

Finally, mount HyperAdmin into your application. Put this in your config/routes.rb file:

HyperAdmin.routes self
mount HyperAdmin::Engine, at: '/admin'

As mentioned above, you must mount it under /admin for the time being. In a later version, this will be configurable.

Usage

To register models that should be accessible through the admin, all you need to do is register them with a single line of code. Do this in any Ruby file(s) you want under app/admin/, such as app/admin/article.rb or app/admin/person.rb. When the application boots, HyperAdmin will check each file under the app/admin/. To register a resource:

HyperAdmin.register NameOfYourResource

For instance:

HyperAdmin.register Article

With this in place, you can now visit /admin/articles in your application and start managing your articles.

Configuring views

When registering resources, it is also possible to customize what fields should show up where and (to some degree) how they should be displayed. For instance, we might want to only show the ID, title and publication date of an article in the index view. For that, we would pass in a block to register and specify which columns to display on the index view, like this:

HyperAdmin.register Article do
  index do
    column :id
    column :title
    column :published_at
  end
end

Note that the order matters here, so this could also be used to force an order of attributes to be displayed. In the example above, HyperAdmin would know the types of the attributes because of how it is registered in the database. However, some types cannot be determined from the database alone. URL fields and e-mail fields, for instance, are stored as text, so they will be treated as text by default. It is possible to tell HyperAdmin what type of field you're specifying by using the type keyword:

HyperAdmin.register Article do
  index do
    column :id
    column :title
    column :published_at
    column :author_email, type: :email
  end
end

The “email” type will create a “mailto”-style link in the index and show views, and an <input type="email"> in the form. Likewise, the “url” type will create a regular link in index/show and an <input type="url"> in forms.

Lastly, it is also possible to customize the labeling of the attributes in each view using the human keyword:

HyperAdmin.register Article do
  index do
    column :id
    column :title
    column :published_at, human: "Publication date"
    column :author_email, type: :email
  end
end

Note that if human is not specified, HyperAdmin will fetch the attribute name from the currently active locale, which is recommended most of the time. human is available for special cases where you want a label other than the localized name of the attribute.

Customizing the show and form pages work the same way as the index pages, but using the row and field methods instead, respectively. A fully customized resource registration might look something like this:

HyperAdmin.register Article do
  index do
    column :id
    column :title
    column :published_at, human: "Publication date"
  end

  show do
    row :id, human: "Article ID"
    row :title
    row :body
    row :published_at, human: "Publication date"

    column :author_email, type: :email
  end

  form do
    field :title
    field :body
    field :published_at
    field :author_email, type: :email
  end
end

Contributing

1. Fork it
2. Check out the develop branch (git checkout develop)
3. Create your feature branch (git checkout -b feature/my-new-feature)
4. Commit your changes (git commit -am 'Add my new feature')
5. Push to the branch (git push origin my-new-feature)
6. Create a new Pull Request

Credits

Hyper made this. We're a digital communications agency with a passion for good code, and if you're using HyperAdmin we probably want to hire you.

License

HyperAdmin is available under the MIT license. See LICENSE.md for more details.

hyper_admin's Issues

Convert all the things to Angular

Write an awesome README

Get rid of that annoying window.stateProvider

In order to specify the routes (states) after the config phase, the $stateProvider has been put on the window scope. It's not particularly pretty, though, but I found no other way of configuring the states using the UI Router. ngNewRouter, however, would fix this, but it would probably require a lot of refactoring to get it implemented. That would be kinda neat, though.

Include an HTML base tag in the layout

This is required for $location to work properly, and is a good practice per the HTML5 specs. Without it, and with newer versions of Angular, the following error will occur and navigation will not work: https://docs.angularjs.org/error/$location/nobase

Flash messages are coming from Rails, not Angular

No feedback is given to the user in forms of flash messages (e.g. after deleting records), as Angular is handling everything. Rails sets flash messages, but they only show up after refreshing the page. That's not all too useful.

Fix issues with respond_with in Rails 4.2+

Since Rails is following semantic versioning and removing a kinda huge feature is totally backwards compatible so it can be done in a minor release, this thing is now breaking. To fix it, we now need to either (1) depend on the responders gem, (2) refactor away the respond_with stuff from our controllers or (3) depend on a Rails version less than 4.2. That last one is not gonna happen and, while (1) is probably the simplest fix, (2) would require less dependencies and shouldn't be that difficult to accomplish, so I think I'm kinda leaning towards that one.

Allow user to specify attributes in index table

Create form for editing new records

The action buttons are misaligned in the form page

The submit and cancel buttons on the form page are misaligned. It looks like this happens because one button is a <button> and the other is a <a>, even if both are originally <md-button>s.

The order of the attributes displayed should not be alphabetical

When looping through the attributes for a resource (or resource class), the attributes are ordered alphabetically. This is not the way they are sent from the server. This is probably due to Angular ordering them for some reason. Should find a way to avoid that.

README mentions Knowledge Base

Allow for fields that are not columns

For example, if a Person model has a name method that joins together a first name and a last name, it should be possible to view this field in the admin, even though it's not a direct column.

Sortable table columns

We need a way to sort rows in the index page. By default, columns that display direct attributes on the model (i.e. attributes directly accessible through the database) should be sortable automatically. It should also be possible to specify a way to sorting algorithm (by lambda?) for non-standard attributes like associations and virtual attributes.

Allow user to specify attributes in detail view

List each record of a resource in a table

Create form for making new records

List attributes for a record in detail view

Set up pagination

Once datasets get very large, pagination is a must-have.

Add support for batch deleting from list

Use a stable version of Angular

We now depend on an unstable version of Angular due to features that was there before the official release. This is no longer necessary and should be changed.

Allow user to specify form fields to display

Validations aren't known to Angular

It would be neat to have Angular know about how each field is validated, so that we could do some actual client-side validation. The way it is know, Rails will return a set of error messages which Angular will display in and above the form. If the form is invalid, we shouldn't even need to bother Rails with trying to validate anything.

Display appropriate input fields depending on attribute type

The inputs are always displayed as simple one-line text fields. Depending on the attribute type, different types of inputs should be displayed. For instance, a textarea for text inputs, an e-mail input for e-mail fields, etc.

Dates aren't filled in when editing resources

Dates look horrible in index and show

Refactor the whole state registration stuff

States are being registered when the application first loads through the Resource.registerStates function. It's quite a mess and it relies on the state provider ($stateProvider from UI Router) to be available on the global window object, which is even more messy. However, I have found no sane way to build up the states dynamically based on which resources are available.

Maybe we don't have to, though. Maybe we can do some clever URL matching and get away with predefined states for each view, regardless of the name of the resource? Something like this:

$stateProvider
  .state "index",
    url: "/admin/:pluralName"
    templateUrl: (params) ->
      "/admin/#{params.pluralName}.html"
    controller: "IndexCtrl as indexCtrl"
    data:
      resource: resource
  .state "index.new",
    url: "/new"
    templateUrl: (params) ->
      "/admin/#{params.pluralName}/new.html"
    controller: "NewCtrl as newCtrl"
    data:
      resource: resource
      mode: "new"
  .state "index.show",
    url: "/:id"
    templateUrl: (params) ->
      "/admin/#{params.pluralName}/#{params.id}.html"
    controller: "ShowCtrl as showCtrl"
    data:
      resource: resource
  .state "index.edit",
    url: "/:id/edit"
    templateUrl: (params) ->
      "/admin/#{params.pluralName}/#{params.id}/edit.html"
    controller: "EditCtrl as editCtrl"
    data:
      resource: resource
      mode: "edit"

That might totally work. I think. I'll have to give it a try.

Forms display id, created_at and updated_at fields