Effortless admin interface for your Rails application.
Pull request Compare This branch is 1 commit ahead, 6084 commits behind typus:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app
config/locales
generators
lib
tasks
test
.gitignore
MIT-LICENSE
README.rdoc
Rakefile
init.rb

README.rdoc

Typus: Effortless admin interface for your Rails application

As Django Admin, Typus is designed for a single activity:

Trusted users editing structured content.

Typus doesn't try to be all the things to all the people but it's extensible enough to match lots of use cases.

You can see some screenshots on the wiki.

Quick demo in 3 steps

Step 1. Create a Rails application using a template.

$ rails application_with_typus -m http://gist.github.com/86613.txt

Step 2. Start the server:

$ cd application_with_typus && script/server

Step 3. Go to the admin area and enjoy it!

http://0.0.0.0:3000/admin

Installing

Install from GitHub the latest version which it's compatible with Rails 2.3.2.

$ script/plugin install git://github.com/fesplugas/typus.git

Once plugin is installed generate Typus files and migrate your database (typus_users table is created)

$ script/generate typus
$ rake db:migrate

To create the first user, start the application server, go to 0.0.0.0:3000/admin and follow the instructions.

Compatibility and old versions

Master branch is tested with:

  • Rails: 2.3.2 and Egde.

  • Ruby: 1.8.6-p287 and 1.8.7-p72.

If you want to use Typus with Rails 2.2.2 install the 2.2.2 branch of the plugin. This branch will be mantained during 3 months from the release of Rails 2.3.2.

$ script/plugin install -r '2.2.2' git://github.com/fesplugas/typus.git

Available rake tasks

You can view the available tasks running:

$ rake -T typus
(in /Users/fesplugas/Development/typus_core)
rake doc:plugins:typus  # Generate documentation for the typus plugin
rake typus:i18n         # Install simplified_translation plugin.
rake typus:misc         # Install Paperclip, acts_as_list, acts_as_tree.
rake typus:roles        # List current roles
rake typus:ssl          # Intall ssl_requirement plugin.

Plugin Configuration Options

You can overwrite the following settings.

Typus::Configuration.options[:app_name]
Typus::Configuration.options[:config_folder]
Typus::Configuration.options[:email]
Typus::Configuration.options[:locales]
Typus::Configuration.options[:recover_password]
Typus::Configuration.options[:root]
Typus::Configuration.options[:ssl]
Typus::Configuration.options[:templates_folder]
Typus::Configuration.options[:user_class_name]
Typus::Configuration.options[:user_fk]

Model options.

Typus::Configuration.options[:edit_after_create]
Typus::Configuration.options[:end_year]
Typus::Configuration.options[:form_rows]
Typus::Configuration.options[:icon_on_boolean]
Typus::Configuration.options[:minute_step]
Typus::Configuration.options[:nil]
Typus::Configuration.options[:per_page]
Typus::Configuration.options[:sidebar_selector]
Typus::Configuration.options[:start_year]
Typus::Configuration.options[:toggle]

Model options can also be defined by model on the yaml files located on config/typus.

Post:
  options:
    edit_after_create: false
    end_year: 2015
    form_rows: 25
    icon_on_boolean: true
    minute_step: 15
    nil: 'nil'
    per_page: 5
    sidebar_selector: 5
    start_year: 1990
    toggle: true

Translating the interface

By default Typus I18n is set to English. You can change this with the following configuration option. (i.e. interface in Español)

Typus::Configuration.options[:locales] = [ [ "Español", :es ] ]

If you need more than one language you can use the following settings.

Typus::Configuration.options[:locales] = [ [ "English", :en ], 
                                           [ "Español", :es ]  ]

Previous settings makes appear a language list on the right bottom of the interface.

Available languages are:

  • English

  • Español

  • Brazilian Portuguese

Recover password

Recover password is disabled by default. To enable it you should provide an email address which will be shown as the sender.

Typus::Configuration.options[:email] = 'typus@application.com'
Typus::Configuration.options[:recover_password] = true

Enable SSL

You can use SSL on Typus. To enable it update the initializer.

Typus::Configuration.options[:ssl] = true

Remember to install the ssl_requirement plugin to be able to use this feature.

$ rake typus:ssl

Disable password recover

You can disable password recover on the login page. By default, password recovery is disabled.

Typus::Configuration.options[:recover_password] = false

Disallow toggle

When you have a boolean on the lists you can toggle it's status from true to false and false to true. You can disable this link with:

Typus::Configuration.options[:toggle] = false

Redirect to index after create a record

After creating a new record you'll be redirected to the record so you can continue editing it. If you prefer to be redirected to the main index you can owerwrite the setting. This setting can be defined globally or by model.

Typus::Configuration.options[:edit_after_create] = false

Configuration file options

You can configure all Typus settings from the yaml files which are placed on config/typus folder. This file is created once you run the typus generator.

There are two kind of files, the *.yml and the *_roles.yml. Look the generated files to see the available options.

Typus Fields

Define the collection of fields which you want to display on different parts of the site. List is for lists, form is for forms.

fields:
  list: name, created_at, category, status
  form: name, body, created_at, status

File fields

Upload files works if you follow Paperclip naming conventions.

Asset:
  fields:
    list: asset_file_name
    form: asset_file_name

Read only fields

In form fields you can have read only fields and read only fields for autogenerated content. These kind of fields will be shown in the form but won't be editable. Example with the name attribute being read-only:

fields:
  list: name, created_at, category, status
  form: name, body, created_at, status
  relationship: name, category
  options:
    read_only: name

Auto generated fields

Define auto generated fields.

Order:
  fields:
    list: tracking_number, first_name, last_name
    form: tracking_number, first_name, last_name
    options:
      auto_generated: tracking_number

You can then initialize it from the model.

# app/models/order.rb
class Order < ActiveRecord::Base

  def initialize_with_defaults(attributes = nil, &block)
    initialize_without_defaults(attributes) do
      self.tracking_number = Random.tracking_number
      yield self if block_given?
    end
  end

  alias_method_chain :initialize, :defaults

end

Virtual attribute fields

Define a virtual attributes. (i.e. model which has an slug attribute which is generated from the title)

# app/models/post.rb
class Post < ActiveRecord::Base

  validates_presence_of :title

  def slug
    title.parameterize
  end

end

Add slug as field and it'll be shown on the listings.

# config/typus/application.yml
Post:
  fields:
    list: title, slug
    form: title

External Forms

Typus will detect automatically which kind of relationships has the model and will appear on the listings.

relationships: users, projects

Filters

Define which filters you want to have on an specific model. (i.e. show status, author and created_at filters for posts)

filters: status, author, created_at

Order

Det the default display order of the items on a model.

order_by: attribute1, -attribute2

Adding minus (-) sign before the attribute will make the order DESC.

Searches

Define which fields will be used when performing a search on the model.

search: attribute1, attribute2

Selectors

Need a selector, to select gender, size, status, the encoding status of a video or whatever in the model?

Person:
  fields:
    list: ...
    form: first_name, last_name, gender, size, status
    options:
      selectors: gender, size, status

From now on the form, if you have enabled them on the list/form you'll see a selector with the options that you define in your model.

# app/models/video.rb
class Video < ActiveRecord::Base

  validates_inclusion_of :status, :in => self.status

  def self.status
    %w( pending encoding encoded error published )
  end

end

Configuration file will look like this:

# config/typus/application.yml
Video:
  fields:
    list: title, status
    form: title, status
    options:
      selectors: status

If the selector is not defined, you'll see a text field instead of a select field.

Booleans

By default all your booleans will be represented with an icon, if you prefer to show it as a text to be more verbose you can disable it with:

Typus::Configuration.options[:icon_on_boolean]

Boolean text shows true & false, but you can personalize it “per attribute” to match your application requirements.

# config/typus/application.yml
TypusUser:
  fields:
    list: email, status
    options:
      booleans:
        # attribute: true, false
        default: publicado, no_publicado
        status: ["It's active", "It's inactive"]

This setting can be defined by model or system wide.

Date Formats

Date formats allows to define the format of the datetime field.

# config/typus/application.yml
Post:
  fields:
    list: title, published_at
    options:
      date_formats:
        published_at: post_short

# config/initializers/dates.rb
Date::DATE_FORMATS[:post_short] = '%m/%Y'
Time::DATE_FORMATS[:post_short] = '%m/%y'

Want more actions?

Define more actions which will be shown on the requested action.

Post:
  actions:
    index: notify_all
    edit: notify

Add those actions to your admin controllers.

class Admin::NewslettersController < AdminController

  # Action to deliver emails ...
  def deliver
    ...
    redirect_to :back
  end

end

For feedback you can use the following flash methods.

  • flash[:notice] just some feedback.

  • flash[:error] when there's something wrong.

  • flash[:success] when the action successfully finished.

Applications, modules and submodules

To group modules into an application use application.

application: CMS

Each module has submodules grouped using module.

module: Article

Example: (E-Commerce Application)

Product:
  application: ECommerce
Client:
  application: ECommerce
Category:
  module: Product
OptionType:
  module: Product

Example: (Blog)

Post:
  application: Blog
Category:
  application: Blog
Tag:
  module: Post

Custom Interface

You can customize the interface by placing on views/admin the following files.

Change default views

You can add your custom views to match your application requirements. Views you can customize.

index.html.erb
edit.html.erb
show.html.erb

Need a custom view on the Articles listing?

Under app/view/admin/articles add the file index.html.erb and Typus default index.html.erb will be replaced.

Blocks

Login Page

views/admin/login/_bottom.html.erb
views/admin/login/_top.html.erb

Dashboard

views/admin/dashboard/_bottom.html.erb
views/admin/dashboard/_sidebar.html.erb
views/admin/dashboard/_top.html.erb

Models

views/admin/<YOUR_RESOURCE>/_edit.html.erb
views/admin/<YOUR_RESOURCE>/_edit_bottom.html.erb
views/admin/<YOUR_RESOURCE>/_edit_sidebar.html.erb
views/admin/<YOUR_RESOURCE>/_edit_top.html.erb
views/admin/<YOUR_RESOURCE>/_index.html.erb
views/admin/<YOUR_RESOURCE>/_index_bottom.html.erb
views/admin/<YOUR_RESOURCE>/_index_sidebar.html.erb
views/admin/<YOUR_RESOURCE>/_index_top.html.erb
views/admin/<YOUR_RESOURCE>/_new.html.erb
views/admin/<YOUR_RESOURCE>/_new_bottom.html.erb
views/admin/<YOUR_RESOURCE>/_new_sidebar.html.erb
views/admin/<YOUR_RESOURCE>/_new_top.html.erb
views/admin/<YOUR_RESOURCE>/_show.html.erb
views/admin/<YOUR_RESOURCE>/_show_bottom.html.erb
views/admin/<YOUR_RESOURCE>/_show_sidebar.html.erb
views/admin/<YOUR_RESOURCE>/_show_top.html.erb

Attribute templates

It is possible to change the presentation for a attribute within the form. In the example below the published_at attribute will be rendered with the template app/views/admin/templates/_datepicker.html.erb. The resource and the attribute name will be sent as local variables resource and attribute. You can change the folder with Typus::Configuration.options.

# config/typus/application.yml
Post:
  fields:
    list: title, published_at
    options:
      templates:
        published_at: datepicker

# app/views/admin/templates/_datepicker.html.erb
<li><label><%= t(attribute.humanize) %></label>
  <%= calendar_date_select :item, attribute %>
</li>

Roles

Typus has roles support. You can can add as many roles as you want. They are defined in config/typus/application_roles.yml and you can can define the allowed actions per role.

admin:
  Category: create, read, update, delete
  Post: create, read, update, delete, rebuild
  TypusUser: create, read, update, delete

editor:
  Category: create, update
  Post: create, update

Resources which are not models

Want to manage memcached, see the current starling queue or have an special resource which is not related to any model?

# config/typus/application_roles.yml
admin:
  ApplicationLog: index
  Backup: index, download_db, download_media
  Git: index, commit
  MemCached: index

When you start Typus needed controllers and a default view will be created.

app/controllers/admin/backup_controller.rb
app/views/admin/backup/index.html

Testing the plugin

You need to have mocha installed to test the plugin.

$ sudo gem install mocha

To test the plugin create an empty application and remove the default routes on routes.rb, once the application is created install the plugin and run rake.

$ cd YOUR_APPLICATION/vendor/plugins
$ git clone git://github.com/fesplugas/typus.git
$ rake

By default tests are be performed against a SQLite3 database in memory. You can also run tests against PostgreSQL and MySQL databases. (database name is typus_test)

$ rake DB=mysql
$ rake DB=postgresql

Splitting configuration files

You can split your configuration files in several files so it can be easier to mantain. Files are loaded by alphabetical order.

config/typus/001-application.yml
config/typus/002-newsletter.yml
config/typus/003-blog.yml
config/typus/001-application_roles.yml
config/typus/002-newsletter_roles.yml
config/typus/003-blog_roles.yml

Quick edit

To enable quick edit include the AdminPublicHelper on your application_helper.rb.

module ApplicationHelper
  include AdminPublicHelper
end

Include the helper on your views.

<%= quick_edit :resource => 'pages', 
               :id => @page.id, 
               :message => 'Edit this page' %>

What is coming to Typus?

There's no a date for this new features, but are things which I'd like to see in Typus in the near future.

  • Sphinx search integration when available.

  • Search in multiple models.

  • Nested models.

  • Content Management System generator.

  • Server administration tools.

Contributors

Author, contact, bugs, mailing list and more

Copyright © 2007-2009 Francesc Esplugas Marti, released under the MIT license