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[:templates_folder].

    # 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

• Laia Gargallo (Lover and tea provider) azotacalles.net
• Isaac Feliu (Codereview on first public release) www.vesne.com
• Lluis Folch (Icons, feedback & crazy ideas) wet-floor.com
• Sergio Espeja (Code) github.com/spejman
• Eadz (Code) github.com/eadz
• Anthony Underwood (Code) github.com/aunderwo
• Felipe Talavera (Code) github.com/flype
• Erik Tigerholm (Code) github.com/eriktigerholm
• George Guimarães (Translation to Brazilian Portuguese and code) github.com/georgeguimaraes
• José Valim (Code) github.com/josevalim

Author, contact, bugs, mailing list and more

• You can recommend me on workingwithrails.com/person/5061-francesc-esplugas
• Browse source on GitHub github.com/fesplugas/typus/tree/master
• Visit the wiki github.com/fesplugas/typus/wikis
• Google Group groups.google.es/group/typus
• Report bugs github.com/fesplugas/typus/wikis/bugs

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