adminka

Adminka

Main goal of that plugin isn't to provide an admin dashboard with huge scope of functionality and tasty features but to provided simple GUI for CRUD and ability to scale it with own features. Plugin uses awesome gem Devise for users' authentication, gem Kaminari for pagination and gem Carrierwave for file uploads.

Usage

After plugin migrations are done the next step will be mounting plugin to app routes. Insert in your routes.rb

  mount Adminka::Engine => 'admin_panel', as: "adminka"

Mounting path title is up to you(e.g. admin_panel, my_adminka etc.), the only thing should be permanent is alias 'adminka'.

Congratulations! Now you can move to yourappdomain/admin_panel and you'll see login form. Of course at first you need to register system admin. Fill in all standard fields and press Sign up. You will be redirected to root_path because newly created admin should be activated to proceed. For activation, in your database you need to change in table adminka_admins field is_active to TRUE. Only now your admin will be allowed to access main menu.

The next step will be a creation of proper resource to manage. Let it be user resource. After resource creation you should pass routes to plugin by doing like this

Rails.application.routes.draw do

  resources :cities

  mount Adminka::Engine => 'admin_panel', as: "adminka"

  Adminka::Engine.routes.draw do
    resources :users
  end
end

and now you have restful routes to manage user resource. Then move to your controllers folder, create folder adminka and and proper controller for you resource(e.g. users_controller).Don't forget that adminka controllers should be namespaced and inside each resource controller you must initialize constant MODEL which holds name of proper model. See example below

class Adminka::UsersController < Adminka::CrudController
  MODEL = 'User'
end

Now let's provide an ability to upload avatar for users. Just install Carrierwave and follow installation instructions. As a result, for example, you will have attribute avatar for User model and UserUploader. Well done! You can upload image for user. The another point is pagination, it will help to manage huge amount of entities. So, we need to install Kaminari. Just add gem to your gemfile and run bundle.That's all. The complete model should look like this:

class User < ApplicationRecord
  paginates_per 5

  belongs_to :city
  mount_uploader :avatar, AvatarUploader

  validates :first_name, :last_name, presence:  true
end

And the last step is creation model for resource. Adminka plugin uses .yml files to store models data. Thus you need to move to your models folder, create folder adminka and to create user.yml file inside it. You can see example in test/dummy/app/models/adminka directory. Below I'll provide short description of file structure:

1. Parent field user - it should be equal to model name.
2. title - left sidebar menu item title. It can be arbitrary(e.g. user, client etc).
3. attributes - contains info about model attributes, their types and separate them for each resource actions(C,R,U,D).
4. list - attributes, which will be shown by index action where resources list is present.
5. show - attributes, which will be shown by show action.
6. edit - attributes, which can be updated. Need to pay more attention to that feature. Each attribute should contain it's title and type. Type title corresponds to html field types(e.g. radio, select, text etc). For some types you need to provide more details:
   • Type radio should contain field value and nested fields in format key: value
   • Type select should have a foreign key name. For example, User belongs_to City, so the field name is city_id, then value attribute contains proper parent model name(e.g. City), attributes field contains two subfields: id(mandatory field) and field which contains parent model field value(e.g. title City title). So you have id and you want to get title of City by using relation.
7. If your field contains image url, just assign it to type: image.
8. search - list of fields you want to provide search for(e.g. first_name, last_name)

You can find model structure example in engine's root directory /test/dummy/app/models/adminka

Views

Plugin uses some defaults views and layouts and of course you can change them according to your needs. For that purpose plugin provides views generator, just run

$ rails g adminka:views

and you'll get all needed views in views/adminka directory and views/layouts/adminka.

Controllers

If you need custom behavior you can generate plugin controllers and override proper actions by running:

$ rails g adminka:controllers

I18n

To generate translation files run:

$ rails g adminka:locale

Installation

gem 'adminka'

or if you prefer latest updates

gem 'adminka', github: 'rockandruby/adminka'

And then execute:

$ bundle

Or install it yourself as:

$ gem install adminka

First of all after gem installation you need to copy migrations to your app by executing

$ rails adminka:install:migrations

and then migrate.

Demo

Demo app

Test credentials:

Login: [e-mail]

Password: 123456

Contributing

Contribution directions go here.

License

The gem is available as open source under the terms of the MIT License.