== What is Kawaii? ==
Kawaii (Japanese for cute) is a web based console for Ruby on Rails
applications.
It is designed for people who spend all day with a script/console window
open, typing in pieces of code and trying to analyze incredibly long
strings for any kind of useful output.
If you type in code that returns data sets, Kawaii will nicely format
them in scrollable types. You can also easily configure your own
Kawaii views for your own classes.
It also supports saving snippets into local tables using ActiveRecord,
or into an Amazon S3 bucket to share across instances of your application.
== Requirements ==
- Kawaii depends on prototype.js, which is installed by default with
a Rails app. If you have removed them from your app, you will need
to add them back for Kawaii to work properly.
- If you want to store snippets on s3, you will need to install the
aws/s3 gem first:
sudo gem install aws-s3
== Installation ==
(Note: If you are upgrading Kawaii, see the Upgrading section.)
1. Install the Kawaii generator
If you want to generate Kawaii in multiple rails apps:
Copy the kawaii directory to ~/.rails/generators
To install for one rails app:
Copy the kawaii directory to your application's lib/generators directory.
(You might have to create lib/generators yourself.)
2. Generate Kawaii (make your application cute!)
Just run:
script/generate kawaii
3. Configure Kawaii
Edit the file config/kawaii.yml
Put a suitable password instead of CHANGE_ME.
If you wish to use Amazon S3 as a store for your snippets,
please add in the following keys to the YAML file:
access_key_id
secret_access_key
bucket_name
"bucket_name" is the location where the snippet files will be saved.
4. Configure Local Snippets
If you wish to store your snippets locally, please add in the following
to the YAML file
snippet_storage: local
Additionally, run the migration that was installed:
rake db:migrate
** If you don't wish to use local snippets, you should remove
the CreateKawaiiSnippets migration file from db/migrations
otherwise you might end up with a table you don't want **
5. Restart your application, and open a browser window to
http://localhost:3000/kawaii
== Upgrading Kawaii ==
Note for early adopters:
If you installed the first version of Kawaii from GitHub, the best
thing to do is to script/destroy kawaii of your old version, then
install the new version by running script/generate kawaii. An easy
way to tell if you have the first version is if your application
is configured in config/initializers/kawaii.rb instead of
config/kawaii.yml
To everyone else:
You can overwrite your generator installation with the current
version of Kawaii in either ~/.rails/generators/kawaii or
lib/generators/kawaii
Running script/generate kawaii should upgrade your application
safely, although you will have to tell it to overwrite files.
The generator is smart enough to not overwrite your kawaii.yml
or lib/kawaii_authentication.rb, so your application specific
settings should keep!
Restart your app and you're good to go!
== An important note about security ==
Kawaii is really just "eval." That means that someone with access
to your Kawaii console could seriously damage your server.
You are expected to pick a suitable password for your Kawaii
installation. Additionally, feel free to drop in your own
authentication in the lib/kawaii_authentication.rb
Also, please set up HTTPS so you aren't sending plain text
passwords that someone can sniff.
Finally, consider not running Kawaii on your production systems.
It's still immature software and it could represent a considerable
security risk.
== How to create your own Kawaii views of your classes ==
Kawaii includes some default views, for Arrays of ActiveRecord
objects (such as returned by find(:all)) and for viewing
schemas by simply evaluating the ActiveRecord class itself.
Kawaii looks for a method, too_cute, in your classes, when it does
its rendering. If one is not found, it calls .inspect on your class
and brings that back as a string.
When your application starts, Kawaii will automatically run all the
scripts in lib/too_cute.
too_cute needs to return a hash with a :type key, that can currently
be set to either 'string' or 'grid'.
== String Example ==
I think this example speaks for itself:
class Person
attr_accessor :name
def initialize(name)
@name = name
end
def too_cute
{:type => 'string', :string => @name}
end
end
== Grid Example ==
When you want to format a grid, you need to return a list of columns
as well:
class Persons
def people
persons = []
persons << {'name' => 'Robin'}
persons << {'name' => 'Jason'}
persons << {'name' => 'Mike'}
persons
end
def too_cute
{:type => 'grid',
:columns => [{:key => 'name'}]},
:data => people}
end
end
== About the Author ==
Kawaii was created by Evil Trout (a.k.a Robin Ward), the creator
of the browser-based MMO Forumwarz, because he was sick of poorly
formatted strings in his script/consoles.
He can be reached at eviltrout@forumwarz.com
== Kawaii on the Web ==
The official Kawaii home page is on Google Code:
http://code.google.com/p/kawaii/
The source code is hosted on Github:
http://github.com/eviltrout/kawaii/tree/master