Um admin para Ruby on Rails

Adicione em seu GemFile:

gem 'my_admin'

Execute o comando ‘bundle’ para atualizar o Gemfile.lock.

Após instalar a gem, é preciso copiar os arquivos do MyAdmin para sua aplicação, para isso execute o comando:

rails g my_admin:install

O comando acima irá criar os seguintes arquivos:

• config/initializers/my_admin.rb – Arquivo com as configurações do MyAdmin. Veja mais em Configurações Geral
• db/migrate/create_my_admin_*.rb – Migrações para criar as tabelas do MyAdmin.

Execute ‘rake db:migrate’ para criar as tabelas do MyAdmin.

Inicie sua aplicação ‘rails s’. Assim o MyAdmin já estará disponível em ‘https://localhost:3000/admin’

As configurações do MyAdmin ficam no arquivo ‘config/initializers/my_admin.rb’.

• Paperclip.options[:command_path] - Caminho dos executáveis do ImageMagick. (Para tratamento de imagens e arquivos)
• config.title – Título da sua aplicação
• config.url_prefix – Caminho que o MyAdmin irá responder, padrão ‘admin’.

Abaixo das configurações ficarão todos os modelos que o MyAdmin administrará.

Para adicionar um novo modelo execute o seguinte comando:

rails g my_admin:model <Nome do seu modelo>

O comando acima irá adicionar uma nova linha no arquivo ‘config/initializers/my_admin.rb’ que irá informar ao MyAdmin que seu modelo será administrado.

E será adicionado também o controller ‘controllers/my_admin/_controller.rb’ que será responsável pelas ações do MyAdmin. Portanto se precisar alterar alguma ação padrão (index, edit, update, new, create, destroy), é esse arquivo que será alterado. (Veja mais em Alterar Ações Existente)

Todas as configurações do modelo ficará dentro do próprio arquivo de modelo (app/models/*.rb), e ficará na seguinte estrutura:

config_my_admin do |admin|
    admin.application = "content"
    admin.list_display = [:name]
    admin.fieldsets = [{:fields => [:name, :content, :image]}]
    admin.permissions = [:list, :update, :export]
    admin.fields = {:name => {:type => :read_only}}
end

Ou seja todas as configurações ficam dentro da função ‘config_my_admin do |admin|‘

Veja abaixo todas opções:

• admin.application

  Define qual grupo o Modelo pertence Tipo: String

  admin.application = “content”

• admin.list_display

  Lista que define quais serão os campos exibidos no grid de visualização (Index). Os itens da lista podem ser um campo de tabela, como também pode ser um método dentro do modelo. Tipo: Array

  admin.list_display = [:name, :email, :phone]

• admin.fieldsets

  Lista de hashs que define quais serão os fieldsets e seus respectivos campos exibidos nos formulários de criação e edição. O hash podem conter os seguintes campos:

  • fields: lista dos campos que o fieldset contem. Tipo: Array

  • name: Nome do Fieldset, caso não seja definido, o nome não será exibido. Tipo: String

  Tipo: Array de Hash

  admin.fieldsets = [
  	{:fields => [:name, :email, :phone]},
  	{:fields => [:address, :number, :city, :state], :name => :location}
  ]

• admin.permissions

  Lista das ações que os usuário poderão executar no modelo. As ações permitidas são (:list, :create, :update, :destroy, :export) Tipo: Array

  admin.permissions = [:list, :update, :export]

• admin.fields

  Customização e configurações mais especifica dos campos.

  As customizações disponíveis são:

  • type:

    Descrição: Tipo do campo (Veja mais em Tipo dos Campos)

    Tipo: String ou Symbol

    admin.fields = {:name => {:type => :text}}

  • order:

    Descrição: Define se o campo poderá ser ordenado ou não na grid de visualização.

    Tipo: Boolean

    admin.fields = { :image => {:order => false}}

  • collection:

    Descrição: Definição das opções de um campo do tipo Lista (combo_box, ou list box)

    Tipo: Procedure

    admin.fields = { :gender => {:type => :list_string, :collection => Proc.new { ["Masculino", "Feminino"] }} }

  • start_blank:

    Descrição: Define se o campo do tipo Lista terá um valor em branco ou não.

    Tipo: Boolean

    admin.fields = { :gender => {:type => :list_string , :start_blank => false, :collection => Proc.new { ["Masculino", "Feminino"] }} }

  • class:

    Descrição: Nome da classe do Objeto

    Tipo: String

    admin.fields = { :gender => {:class => “large”} }

  • can_add:

    Descrição: Define se o usuário pode adicionar novos itens em um campo do tipo has_many_edit.

    Tipo: Boolean

    admin.fields = { :languages => { :type => :has_many_edit, :can_add => false, :can_destroy => false } }

  • can_destroy:

    Descrição: Define se o usuário pode adicionar novos itens em um campo do tipo has_many_edit.

    Tipo: Boolean

    admin.fields = { :languages => { :type => :has_many_edit, :can_add => false, :can_destroy => false } }

  • read_only:

    Descrição: Define se o usuário pode editar/adicionar/remover os itens em um campo do tipo has_many_edit

    Tipo: Boolean

    admin.fields = { languages => { :type => :has_many_edit, :read_only => true } }

  • rows:

    Descrição: Define a quantidade de linhas um campo do tipo text terá.

    Tipo: Integer

    admin.fields = { :description => { :rows => 5 }}

  • filter_type:

    Descrição: Tipo do campo nos filtros (Veja mais em Tipo dos Campos)

    Tipo: String ou Symbol

    admin.fields = {:name => {:filter_type => :text}}

  • onchange:

    Descrição: Executa uma instrução javascript ao alterar o valor de um campo do tipo lista.

    Tipo: String

    admin.fields = { :unidade => {:onchange => "ChangeForm();” } }

  • remote:

    Descrição: Ao alterar um campo do tipo lista, modifica as opções de outro campo do tipo lista por ajax. Hash com dois valores:

    Field: Campo que será alterado

    Collection: Procedure que irá preenche as opções do campo destino.

    Tipo: Hash

    admin.fields = {
      :state => {
        :type => :belongs_to, 
        :filter_type => :default,
        :collection => Proc.new { State.all.map { |i| [i.to_s, i.id] } },
        :remote => {
          :field => "city",
          :collection => Proc.new { |value| City.all(:conditions => {:state_id => value}).map { |i| [i.to_s, i.id] } },
        }
      }
    }

  Obs.: As customizações podem ser adicionadas em um único Hash.

• admin.export_display

  Lista que define quais serão os campos exibidos ao exportar. Por padrão irá exportar os mesmo campos definidos no list_display.

  Os itens da lista podem ser um campo de tabela, como também pode ser um método dentro do modelo. Tipo: Array

  admin.export_display = [:name, :email, :phone]

• admin.per_page

  Define a quantidade de item que será exibido por página no grid de visualizações. Por padrão o valor é 10. Tipo: Integer

  admin.per_page = 20

• admin.collection

  Define as ações de class adicionais. [{Post ou Get}, nome da ação] Tipo: Array

  admin.collection = [
  	[:post, :approve],
  	[:post, :disapprove]
  ]

• admin.member

  Define as ações do objeto adicionais. [{Post ou Get}, nome da ação] Tipo: Array

  admin. member = [
    [:post, :up],
    [:post, :block]
  ]

Por padrão o MyAdmin considera o tipo do campo igual o tipo do objeto retornado, ou definido na base de dados. Os tipos de campos disponíveis são:

• belongs_to
• boolean
• clear_text (Campo do tipo text sem utilizar o plugin ckeditor)
• color
• date
• datetime
• decimal
• default (Campos do tipo string)
• email
• file
• float
• has_many
• has_many_edit
• has_many_locale
• integer
• list
• list_string
• money
• paperclip/attachment (Campos do tipo imagem)
• password
• read_only
• text (Campo do tipo text usando o plugin ckeditor)
• time

Caso os campos não atendem a demanda, é possível criar novos tipos, ou customizar campos específicos.

Por exemplo, para criar um novo campo do tipo unidade, precisamos criar três novas views para o MyAdmin renderizar:

• /app/views/my_admin/fields/edit/type/unidade.html.erb Que irá exibir no formulário de editar e alterar.

  As variáveis disponíveis são:

  • model: Modelo que está editando ou criado.
  • field: campo que está sendo renderizado
  • form: formulário que será enviado.
  • object: Objeto que está sendo criado ou editado.

• /app/views/my_admin/fields/type/unidade.html.erb Quer irá exibir no grid de visualização.

  As variáveis disponíveis são:

  • model: Modelo que está visualizando.
  • field: campo que está sendo renderizado
  • object: Objeto que está visualizando.

• /app/views/my_admin/fields/filter/unidade.hmtl.erb Que irá exibir no formulário de filtro.

  As variáveis disponíveis são:

  • model: Modelo que está visualizando.
  • field: campo que está sendo renderizado

A estrutura acima pode ser utilizada para alterar um tipo já existente. Alterando o nome Unidade, para Text, por exemplo.

Para customizar um campo especifico, deve seguir a mesma estrutura de criar um novo tipo de campo, com pequenas modificações da estrutura. Por exemplo, vamos customizar o campo ‘phone’:

• /app/views/my_admin/fields/edit/phone.html.erb
• /app/views/my_admin/fields/phone.html.erb
• /app/views/my_admin/fields/filter/phone.html.erb

No caso acima você alterará todos os campos que tiverem o nome ‘phone’ de todos os modelos do admin.

Porém se você desejar alterar os campos somente de uma grupo, siga a estrutura abaixo, com exemplo de que o grupo se chama “contatos”.

• /app/views/my_admin/applications/contatos/fields/edit/phone.html.erb
• /app/views/my_admin/applications/contatos/fields/phone.html.erb
• /app/views/my_admin/applications/contatos/fields/filter/phone.html.erb

O mesmo serve para criar ou editar um tipo de campo para um grupo.

• /app/views/my_admin/applications/contatos/fields/edit/type/unidade.html
• /app/views/my_admin/applications/contatos/fields/type/unidade.html
• /app/views/my_admin/applications/contatos/fields/filter/type/unidade.html

Ainda existe a possibilidade de customizar um campo de um modelo especifico. Veja o exemplo abaixo do modelo “User“.

• /app/views/my_admin/models/users/fields/edit/phone.html.erb
• /app/views/my_admin/models/users/fields/phone.html.erb
• /app/views/my_admin/models/users/fields/filter/phone.html.erb

O mesmo para tipo de campo.

• /app/views/my_admin/models/users/fields/edit/type/unidade.html
• /app/views/my_admin/models/users/fields/type/unidade.html
• /app/views/my_admin/models/users/fields/filter/type/unidade.html

Obs.: A pasta do modelo deve ser o mesmo nome da tabela do modelo.

Caso precise alterar a estrutura da área do qualquer campo, é possível criando o arquivo com o mesmo nome porém com _struct na frente. Ex: /app/views/my_admin/fields/edit/type/unidade_struct.html.erb

Para ver como cada tipo de campo se comporta por padrão, acesse os arquivos no diretório/gems/my_admin/views/my_admin/fields/.

Obs: Caso um dos arquivos não seja criado, o MyAdmin irá utilizar a view do tipo default.