Configuration

Initializer: Understanding what typus.rb can do for you.

The initializer has two groups of options.

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

Model options, which can be defined by model.

Typus::Configuration.options[:end_year]
Typus::Configuration.options[:form_rows]
Typus::Configuration.options[:index_after_save]
Typus::Configuration.options[:minute_step]
Typus::Configuration.options[:nil]
Typus::Configuration.options[:per_page]
Typus::Configuration.options[:sidebar_selector]
Typus::Configuration.options[:start_year]

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

Post:
  options:
    end_year: 2015
    form_rows: 25
    index_after_save: false
    minute_step: 15
    nil: 'nil'
    per_page: 5
    sidebar_selector: 5
    start_year: 1990

↑ Back to top

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'

↑ Back to top

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

↑ Back to top

Redirect to index after creating 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[:index_after_save] = false

↑ Back to top

The yaml configuration file

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.

↑ Back to top

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

↑ Back to top

File fields

Upload files works if you follow Paperclip naming conventions.

Photo:
  fields:
    list: photo_file_name
    form: photo_file_name

↑ Back to top

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

↑ Back to top

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

↑ Back to top

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

↑ Back to top

Relationships

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

relationships: users, projects

↑ Back to top

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

↑ Back to top

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.

↑ Back to top

Searches

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

search: attribute1, attribute2

↑ Back to top

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

  STATUS = %w( pending encoding encoded error published )

  validates_inclusion_of :status, :in => STATUS

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.

↑ Back to top

Booleans

Boolean text shows true & false, but you can personalize it by 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"]

↑ Back to top

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'

↑ Back to top

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.

↑ Back to top

The *_roles.yaml configuration file

To be written.

↑ Back to top

Roles

Typus has roles support and you can add as many roles as you want. Define them in your config/typus/application_roles.yml configuration file and add granular access to different actions.

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

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

Note: You can use the shortcut all to allow user have access to all model actions.

↑ Back to top

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

↑ Back to top

User interface customization

Customize Typus interface by placing on views/admin your own views & partials. Typus defaults are good enough but sometimes you need more features.

↑ Back to top

Default views

Add your own views to match your application requirements.

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

Need a custom view on the Articles listing?

Drop the file index.html.erb on app/view/admin/articles and Typus default index.html.erb will be replaced. Easy, isn't it?

↑ Back to top

Blocks on views (partials)

Here's a list of available blocks you can add to your application. Typus views will detect this files, if they're in the right place.

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

You can specify these blocks by a resource or for all resources

views/admin/<RESOURCE>|resources/_sidebar.html.erb
views/admin/<RESOURCE>|resources/_index.html.erb
views/admin/<RESOURCE>|resources/_new.html.erb
views/admin/<RESOURCE>|resources/_edit.html.erb
views/admin/<RESOURCE>|resources/_show.html.erb

↑ Back to top

Attribute templates

It is possible to change the presentation for an attribute within the form. In the example below the published_at attribute is datetime attribute and will use the _datetime.html.erb template located on the templates folder app/views/admin/templates. The resource and the attribute name will be sent as local variables resource and attribute.

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

↑ Back to top

Exporting data

Typus allows to export data. Only XML and CSV exporting methods are implemented but you can easily add your own. You will see the export links on the sidebar of your resource.

Order:
  export: csv, pdf, xml

And the actions for those export options are:

def export_csv
  # Already implemented but you can overwrite it.
end

def export_xml
  # Already implemented but you can overwrite it.
end

def export_pdf
  # Not implemented, so you have to write it.
end

Please notice that in order to be able to use the export feature you need the following routes at the end of your routes.rb.

map.connect ':controller.:format'
map.connect ':controller/:id.:format', :action => 'show'

With this you'll be available to get for example xml listings and for individual records.

http://0.0.0.0:3000/admin/articles.xml
http://0.0.0.0:3000/admin/articles/42.xml

↑ Back to top

Quick edit

To enable quick edit include the Admin::PublicHelper on your application_helper.rb.

module ApplicationHelper
  include Admin::PublicHelper
end

And you can start using the helper on your views.

<%= quick_edit :message => 'Edit this page', 
               :path => "pages/edit/#{@page.id}" %>

↑ Back to top

Applications

To group resources into an application use application.

Model:
  application: CMS

Example for an E-Commerce & Blog

Product:
  application: E-commerce
Client:
  application: E-commerce
Post:
  application: Blog
Category:
  application: Blog
Comments:
  application:     # Leave it blank to not show on dashbard.

↑ Back to top