/carnival

Primary LanguageRubyMIT LicenseMIT

#Carnival By Vizir.

Vizir Logo

Carnival is an easy-to-use and extensible Rails Engine to speed up the development of data management interfaces.

When you use Carnival you'll benefit from a big suite of feature already done. If you need to change anything, you can write your own version of the code, using real Ruby code in Rails standard components without worrying about a specific syntax or DSL.

##Features

  • Easy way to CRUD any data;
  • Search data easily;
  • Advanced searches in a minute. You can specify which fields you want to search for;
  • Fancy time filter, based on Toggl design;
  • Nice default layout, ready to use.
  • New and Edit forms are easily configured. If you do ot like, you can write your own views.

Detailed features list

  • Index List
    • Ordering by any column
    • Scope
    • Advanced Search
    • Custom Links
    • Remote Actions
    • Custom Actions
    • Batch Operations
    • Custom Css Cel
    • Delete
    • CSV Export
    • PDF Export
  • Edit form
    • Create new
    • Update existent
    • Nested Form
    • Associate an existent
    • Create new
    • Update
    • Delete
    • ImagePreview
    • Relation select (Autocomplete)
    • Grid config (field order and size)
    • Select Enum
  • Show
    • Grid config (field order and size)
    • Relation links
    • Custom partial view
    • Show as list
  • Menu
    • Customize Order, route, text, label and class

It can be easily integrated with gems that you are already used to use

Authentication

Rich Text Editor

Upload files

##How it works In some words, Carnival provides a managing infra-structure for your application. All the data related to Carnival will be located under the /admin namespace.

Getting started

Carnival works with Rails 4.0 onwards. You can add it to your Gemfile with:

gem 'carnival'

Run bundle install

Execute rails generate carnival:install after you install Carnival to generate the initializer.

What does Carnival include?

After you install Carnival, you will have a running CRUD application which is ready to manage the currently register useres. The real power of Carnival is that you easily extend to manage your data. Let's start to use it.

Carnival Admin Application

The Carnival application will be under the '/admin' namespace. Some features are already implemented. To use it, do the following:

  • Start your Rails web server and acess the /admin page.

http://server-name/admin

Basic Usage

Carnival started relying only on MVC model. As we developed it, we saw that it would be good to have a Presenter to better describe our models. We used the presenter to avoid the fat models emerge on our systems.

Model

It is a commom Active Record model. We only have to include the Carnival Helper.

include Carnival::ModelHelper

module Admin
  class Company < ActiveRecord::Base

    include Carnival::ModelHelper

  end
end

Controller

It is also a commom Controller, with some things to note:

  • Inherits from Carnival::BaseAdminController
  • Uses the default admin layout: layout "carnival/admin"
  • When creating or editing data, you should configure the Rails 4 permitted params.
module Admin
  class CompaniesController < Carnival::BaseAdminController
    layout "carnival/admin"

    def permitted_params
      params.permit(admin_company: [:name])
    end
  end
end

Presenter

All the "magic" of Carnival happens at Presenter. Each model managed under Carnival Admin will have a presenter associated to it. The presenter describes each model attributed that will be acessible in any of Carnival's CRUD interfaces.

module Admin
  class CompanyPresenter < Carnival::BaseAdminPresenter
    field :id,
          :actions => [:index, :show], :sortable => false,
          :advanced_search => {:operator => :equal}
    field :name,
          :actions => [:index, :new, :edit, :show],
          :advanced_search => {:operator => :like}
    field :created_at, :actions => [:index, :show]

    action :show
    action :edit
    action :destroy
    action :new

  end
end

Dependent Selects

This feature is used when you have dependent selects like Country, State and City to fill an Address or a Location, because Cities Select only can be filled withe the oprions when a State is selected, and the State when de Country is selected, to implement this kind of behavior in a form, just use the option :depends_on in the dependent field with the symbol of the dependency, follows an example bellow:

field :country,
      :actions => [:index, :csv, :pdf, :new, :edit, :show]
field :state,
      :actions => [:index, :csv, :pdf, :new, :edit, :show]
      :depends_on => :country
field :city,
      :actions => [:index, :csv, :pdf, :new, :edit, :show]
      :depends_on => :state

Menu

The menu of the carnival can be configured in the 'config\initializers\carnival_initializers.rb' file

Ex:

config.menu =
{
  :city => {
    :label => "city",
    :class => "",
    :link => 'admin_cities_path', #You can use the route name as String to define the link
    :subs => [
      {
      :label => "custom_city",
      :class => "",
      :link => 'admin/custom/cities', #Or you can use the full path
      },
      {
        :label => 'google',
        :class => "",
        :link => 'http://www.google.com'
      }
    ]
  },
  ...
}

Presenter Properties

Specific

Table items

If you want to determine a specific list of items that will appear in the table you have to define the table_items method in your controller returning a Array or ActiveRelation

Ex:

module Admin
  class CompaniesController < Carnival::BaseAdminController
    layout "carnival/admin"

    def table_items
      Company.where(:country => 'Brazil')
    end

    def permitted_params
      params.permit(admin_company: [:name])
    end
  end
end

Presenter Class Name

If you want to define a custom Presenter you need to define in your controller the method carnival_presenter_class

Ex:

  class CompaniesController
    def carnival_presenter_class
      MyCustomCompanyPresenter
    end
  end

In this case you have to define the method full_model_name in your presenter

Ex:

  class MyCustomCompanyPresenter
    field :id,
          :actions => [:index, :show], :sortable => false,
          :advanced_search => {:operator => :equal}
    field :name,
          :actions => [:index, :new, :edit, :show],
          :advanced_search => {:operator => :like}
    field :created_at, :actions => [:index, :show]

    action :show
    action :edit
    action :destroy
    action :new

    def full_model_name
      'Company'
    end

  end

Custom Views

The Carnival permits that you specify some partials for your page, you just need just add your partial in the app/views/carnival/extra_header.html.haml

Possible Partials:

  • extra_header

    • Extra html to render in page header

  • app_logo

    • Define a specific partial for your app logo
    • Default Value: link_to App Name, root_path

  • extra_footer

    • Extra html to render in page footer

Configurations

Custom AdminUser

If you want to have your own AdminUser class or need to add methods to that class, you need to do the following steps:

  • Configure the ar_admin_user_class in the carnival_initializers.rb file
config.devise_class_name = 'MyAdminClass'
  • Your class need to inheritance from Carnival::AdminUser

Custom Root Action

config.root_action = 'my_controller#my_action'

Application Name

config.app_name = 'Application Name'

Custom Translations

You can add custom translations for the actions [:new, :show, :edit, :destroy]

  company:
    new: Create New company
    show: Show company

Additional Docs

You can find more detailed docs in the links below

##TODO

  • create has many association input data