=Kryptonite. A really simple CMS

Comming

==Installation

— Create a new Rails project (or use an existing one) and enter the project directory from a terminal prompt.

— Add the Kryptonite gem to your Gemfile:

  gem 'kryptonite'
	
- Then use bundler to install Kryptonite and its dependencies:

  bundle install
	
— If you have just created a new project, then remember to add your database details to /config/database.yml at this point.

— These installation instructions also assume that you have set up your RAILS_ENV environment variable.

— To enable Kryptonite notification emails (used for new users and forgotten passwords) then add your SMTP server information to your initializers. For example create a new file called initializers/setup_mail.rb and add the following to it:

  ActionMailer::Base.delivery_method = :smtp
  ActionMailer::Base.raise_delivery_errors = false
  ActionMailer::Base.smtp_settings = {
    :enable_starttls_auto => false,
    :address => "mail.yourdomain.com",
    :port => 25,
    :domain => "yourdomain.com",
    :user_name => "donotreply@yourdomain.com",
    :password => "whatever",
    :authentication => :login
  }

— Install Kryptonite configuration files into your project. This should not be run more than once without backing up or merging the generated files, as your customisations will be overwritten:

  rails g kryptonite:install
	
— Add Kryptonite assets to your project /public folder. These should not be modified as they may be overwritten in future updates:.

  rails g kryptonite:update
	
— Perform a database migration to create the Kryptonite users table:
 
  rake db:create (if needed)
  rake db:migrate
	
— Run the following Rake task to set up an initial user. The default login and password will be displayed once the task has completed. You should specify your email address. If you set up an SMTP server in your Rails environment then you’ll also receive an email notification about the new account.

  rake kryptonite:users:create_admin email=you@yourdomain.com

— Run your app! (rebooting the web server if applicable)

— You can access Kryptonite at http://yourdomain.com/kryptonite or http://yourdomain.com/admin

<b>Kryptonite should now be running! You should change the default password immediately!</b>

==Usage

The default Kryptonite install supports user authentication. Users may have a status of either ‘admin’ or ‘user’. The former is allowed to add, edit and delete other Kryptonite users. The latter is only allowed to edit their own profile.

Kryptonite is a framework allowing you to quickly build up an interface to edit and create new records from your database model. As well as the user support and user interface, there are many configurations and generators to help you along the way.

==Configuration

<b>app/helpers/kryptonite/config_helper.rb</b>

This is the main Kryptonite configuration file that allows you to change things such as the website name, logo, notification email address, dashboard URL, etc. The options are documented within the file.

<b>views/kryptonite/layouts/_left_navigation.html.erb</b>

An ERB partial for the the left navigation tabs. Note that using the scaffolding generator will automatically add tabs into this file, but it can also be manually edited and rearranged.

<b>view/kryptonite/layouts/_right_navigation.html.erb</b>

An ERB partial for the the right navigation tabs. Note that the ‘users’ tab is added automatically for admin users.

<b>/public/kryptonite/javascripts/custom.js & /public/kryptonite/stylesheets/custom.css</b>

The Kryptonite assets are located in /public/kryptonite. These are the only two files you should change. They allow you to add custom JavaScript or CSS to your Kryptonite deployment. These files are not overwritten using the ‘rails g kryptonite:update’ command.

==Customising

Now that you have the basic Kryptonite installed and configured, you’ll want to extend it so that it actually has some functionality for your project!

<b>Rules and conventions</b>

* Kryptonite extension controllers and helpers should be namespaced to 'Kryptonite::'
* Kryptonite extension controllers should derive from Kryptonite::KryptoniteController and not ApplicationController
* To set the page title, your controller action should set @kryptonite_page_title. If this is not set, then Kryptonite will use a default created from your project name.

<b>Right bar</b>

The right bar in Kryptonite should be used for view specific actions, e.g. "Add user" for users/index, or "Back to list", "Delete user" for users/show.

To specify the contents of the sidebar, you must add a 'content_for :sidebar' block in the relevant view file (index, show, etc.) e.g.:
 
  <%= content_for :sidebar do %>
    <li><%= link_to "#{kryptonite_show_icon('table')}Back to list".html_safe, kryptonite_users_path %></li>
  <% end %>

The kryptonite_show_icon function will display any icon present in the /public/kryptonite/images/icons folder. By default this only contains add, delete and table after install. However, more can be added as required by downloading from http://www.famfamfam.com/lab/icons/silk/

<b>Helper functions</b>

There are several Kryptonite helper functions that are automatically available in any of your Kryptonite extension views.

<i>TODO: These will be documented later. For now, just browse the kryptonite_helper.rb file to see what’s available.</i>

<b>Kryptonite version</b>

Your Rails application may discover what version of Kryptonite it is currently running by calling the function:

  kryptonite_get_version_info

This will return an array with the keys 'major', 'minor' and 'patch'.

<b>Rake tasks</b>

There are several Kryptonite Rake tasks available to manage users. To see what is available, list all Rake commands using:

  rake -T

The Kryptonite Rake tasks are all namespaced with ‘kryptonite:’

==Scaffolding

Kryptonite has a scaffolding generator to automatically create all the views and controllers for your project models. This is the fastest way to add Kryptonite support to your project.

The command to run the scaffolding generator is:

  rails g kryptonite:scaffold ModelName [field:type, field:type]

Where:

* ModelName – The singular name of your model, e.g. customer
* field:type – The name of your database fields and their types, e.g. name:string. The field name must match the name in your migrations and the type must be one of the Rails migration types (string, text, integer, float, decimal, datetime, timestamp, time, date, binary, boolean). Note that you do not have to specify all of the fields in your model, but just the ones that you wish to be editable in Kryptonite.

e.g. a typical scaffolding command might look like:

  rails g kryptonite:scaffold customer name:string age:integer date_of_birth:date is_male:boolean

There is one command-line option that can be added to the end of the generate command:

  --create-model-and-migration = Also creates a model and migration. By default the scaffold generator will work from existing models, but this option will generate the model and database migration files for you. This means you can also use Kryptonite to set up a new project quickly as well.

Once the command has been executed, the generator will:

* Add a new tab for the model to: app/views/kryptonite/layouts/_left_navigation.html.erb
* Create a controller with the name: app/controllers/kryptonite/model_controller.erb
* Add views for index, new and show to: app/views/kryptonite/model/
* If you restart and run your application now, you’ll be able to log in to Kryptonite and directly edit and create new instances of your model data right away!

However, you’ll probably want to customise your views and side bars and extend your controller to suit your project. The scaffold generator just sets up the defaults for you.

<em>NOTE: Once you start customising the generated scaffolding files, you should be aware that if you run the generator again you should not overwrite the changed files without backing them up first. The generator will warn you each time it finds a file that you’ve customised. If you run the scaffold generator from a new version of Kryptonite, then you should manually merge your backup and the new file. You can of course however, leave your originals untouched.</em>

===Changing form elements / other helpers

Kryptonite will insert form elements suitable for the field types you specified in the command line. However, you may wish to customise these, e.g. swap a text field for a password field, swap an integer field for a select dropdown, or swap a date field for a full calendar picker, etc.

You will find the form used for both new and show in a partial named _fields.html.erb

All of the standard Rails form helpers are available, but the Kryptonite versions are prefixed with kryptonite_. These versions are styled for the Kryptonite interface and have automatic support for validation error reporting.

  kryptonite_text_field form, model, attribute, options = {}
  kryptonite_password_field form, model, attribute, options = {}
  kryptonite_text_area form, model, attribute, options = {}
  kryptonite_text_area_big form, model, attribute, options = {}
  kryptonite_check_box form, model, attribute, options = {}
  kryptonite_check_box_group form, model, check_boxes = {}
  kryptonite_radio_button form, model, attribute, tag_value, options = {}
  kryptonite_radio_button_group form, model, radio_buttons = {}
  kryptonite_select form, model, attribute, option_tags, options = {}
	kryptonite_time_zone_select form, obj, attribute, option_tags, options = {}
  kryptonite_date_select form, model, attribute, options = {}
	kryptonite_time_select form, model, attribute, options = {}
  kryptonite_datetime_select form, model, attribute, options = {}
  kryptonite_file_field form, model, object_name, attribute, options = {}
  kryptonite_hidden_field form, model, attribute, options = {}

For more information on each function, check the app/helpers/kryptonite/kryptonite_helper.rb file within the project. The method parameters are typically the same as the Rails form tag helpers. There are some extra Kryptonite options that can be passed through as part of the options hash:

  :kryptonite_label – by default the humanized version of the database field name is used as the label, but this will override it with a string of your choice.
  :kryptonite_button_label – available in kryptonite_radio_button and kryptonite_check_box. Used to give individual buttons their labels.
  :kryptonite_truncate - may be passed into kryptonite_table_cell_link along with a maximum length to automatically truncate strings and suffix with '...'

===Changing form layout

A basic two-column layout is automatically created by the scaffold generator. The position of form elements is controlled by parent DIVs. A left column element is housed in a “tfContainer” and a right column element in “tfContainer tfContainerSecond”. Note that the generator does not take form element height into account, so you may need to have two sequential matching tfContainer types to balance out some of the larger components, such as the calendar picker.

There is an optional container class that forces form elements to use the whole width of the page. This is “tfContainer tfContainerFullWidth” and if used together with kryptonite_text_area_big will create a textarea suitable for, say, editing full page content.

===Adding styled help blocks

Sometimes it is necessary or useful to add guidelines or help text to your forms and tables. Kryptonite offers a CSS class for this called “help”, which can be used throughout your views as necessary.

===Routes

Kryptonite adds the routes for the scaffolded models to the top of your application’s routes.rb file. It also adds default routes for basic Kryptonite functionality <b>after</b> your application’s routes. If you have a catch-all style route defined, then these defaults won’t be run. You can solve this be using Rails’ constraint feature and the supplied Kryptonite::RouteConstraint, which will stop your catch-all from matching if the request is for a Kryptonite resource.

e.g.

  match ':controller(/:action(/:id(.:format)))', :constraints => Kryptonite::RouteConstraint.new

==Acknowledgements

The icons used in Kryptonite were created by Mark James and are licensed under the Creative Commons Attribution 2.5 License (http://creativecommons.org/licenses/by/2.5/). The full series of icons are available here: http://www.famfamfam.com/lab/icons/silk/
This Project is inspired by the Casein CMS.