Permalink
Browse files

Updating documentation

  • Loading branch information...
1 parent 22d8905 commit 07369d28132d156515e0662808f45907edc61922 @bermi bermi committed Jan 25, 2010
View
@@ -0,0 +1,254 @@
+== Welcome to Akelos
+
+Akelos is a web-application framework that includes everything needed to create
+database-backed web applications according to the Model-View-Control pattern.
+
+This pattern splits the view (also called the presentation) into "dumb" templates
+that are primarily responsible for inserting pre-built data in between HTML tags.
+The model contains the "smart" domain objects (such as Account, Product, Person,
+Post) that holds all the business logic and knows how to persist themselves to
+a database. The controller handles the incoming requests (such as Save New Account,
+Update Product, Show Post) by manipulating the model and directing data to the view.
+
+In Akelos, the model is handled by what's called an object-relational mapping
+layer entitled Active Record. This layer allows you to present the data from
+database rows as objects and embellish these data objects with business logic
+methods. You can read more about Active Record in
+link:vendor/akelos/active_record/README.markdown
+
+The controller and view are handled by the Action Pack, which handles both
+layers by its two parts: Action View and Action Controller. These two layers
+are bundled in a single package due to their heavy interdependence. This is
+unlike the relationship between the Active Record and Action Pack that is much
+more separate. Each of these packages can be used independently outside of
+Akelos. You can read more about Action Pack in
+link:vendor/akelos/action_pack/README.markdown.
+
+
+== Getting Started
+
+1. Make sure the ./public is visible to your web server.
+2. Point your http://localhost/ and get the welcome screen.
+3. Follow the guidelines to start developing your application
+
+
+== Web Servers
+
+== Debugging Akelos
+
+Sometimes your application goes wrong. Fortunately there are a lot of tools that
+will help you debug it and get it back on the akelos.
+
+First area to check is the application log files. Have "tail -f" commands running
+on the development.log. Akelos will automatically display debugging and runtime information
+to that file. Debugging info will also be shown in the
+browser on requests from 127.0.0.1.
+
+You can also log your own messages directly into the log file from your code using
+the AkLogger class from inside your controllers. Example:
+
+ class WeblogController extends ActionController{
+ public function destroy(){
+ $weblog = $this->Weblog->find($this->params['id']);
+ $weblog->destroy();
+ $this->_log->info("Destroyed Weblog ID {$weblog->id}!");
+ $this->_log->info("Destroyed Weblog ID {$weblog->id}!");
+ }
+ }
+
+The result will be a message in your log file along the lines of:
+
+ Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1
+
+
+== Console
+
+You can interact with the domain model by starting the console through +./script/console+.
+Here you'll have all parts of the application configured, just like it is when the
+application is running. You can inspect domain models, change values, and save to the
+database.
+
+== Differences from Ruby on Rails.
+
+- On the controller you must access to $this->params, $this->ModelName,
+$this->Request, $this->Response, intead of @request ....
+
+- Templates are ended in .tpl and not .erb
+
+- Views work using PHP, and a pseudo-ruby syntax for calling helpers.
+
+- All the methods (but helpers) use PEAR like naming conventions so instead of
+AkActionController::url_for() you need to call AkActionController::urlFor()
+
+- Helpers are located at /vendor/akelos/action_pack/helpers (it's worth having a look
+at them)
+
+- In order to expose data from your controllers to the views, you'll simply
+need to assign them as attributes of the controller that is handling the
+action so:
+
+ class PostController extends ApplicationController
+ {
+ function index() {
+ $this->message = 'Hello World';
+ }
+ }
+
+Will expose into ./app/views/post/index.tpl $message variable so you can use
+it like:
+
+ <?php echo $message; ?>
+
+or the same using SinTags
+
+ {message}
+
+
+
+== i18n and l10n the Akelos way
+
+Locale files are located at:
+
+ ./config/locales/ # Akelos Framework locales
+ ./app/locales/
+
+In order to change the language of your application can prefix your request
+with the locale name so:
+
+ http://example.com/es/post/add # will load ./config/locales/es.php
+and
+ http://example.com/en/post/add # will load ./config/locales/en.php
+
+
+All the functions for writing multilingual code rely on the Ak::t() method.
+Based on the Ak::t() function you can find:
+
+ $PostController->t() # controller
+ $Post->t() # model
+ $text_helper->t() # for the view
+ _{ hello world } # for the view (Sintags)
+
+All these four will save new locales onto their corresponding namespace in
+the example above "./app/locales/post/en.php"
+
+If you want to use your own namespace for storing locales you can do it like:
+
+ translate('Hello world', null, 'shared_posts');
+
+In this case it will store it at "./app/locales/shared_posts/en.php"
+
+
+Deal with Compound Messages
+
+As you can see the Framework has been designed with l10n and i18n in mind. One
+nice and flexible feature common to all these functions but the sintags one is
+the ability to add compounded messages, you might already realized this but
+here is a small example:
+
+Ak::t('Hello %title %last_name,',
+array('%title'=>$title,'%last_name'=>$last_name,'%first_name'=>$first_name));
+
+ Ak::t('Today is %date', array('%date'=>Ak::getDate()));
+ // You can use Ak::t or any of its derived methods
+
+The Sintags way to deal with compounded messages is
+
+ _{Today is %date}
+ // which will be converted to
+ // <?=$text_helper->translate('Today is %date', array('%date'=>$date));?>
+ // note that $date is selected by replacing the % from the needle
+
+Internationalizing Models.
+
+You can have multilingual database columns by adding the locale prefix plus
+and underscore to the column name. This way when you do
+
+ $Article->get('title')
+
+you'll get the information on the "en_title" column if "en" is your current
+locale.
+
+The same way you can set posted attributes like
+
+ $_POST = array('title'=>array('en'=>'Tech details',
+ 'es'=>'Detalles técnicos'));
+ $Article->setAttributes($_POST);
+
+and the attributes will be mapped to their corresponding columns.
+
+In order to make this work you need to add to your config/config.php
+
+ define('AK_ACTIVE_RECORD_DEFAULT_LOCALES', 'en,es');
+
+
+In order to convert between charsets you can use Ak::recode() and
+Ak::utf8('My ISO Text', 'ISO-8859-1').
+
+
+
+== Description of Contents
+
+app
+ Holds all the code that's specific to this particular application.
+
+app/controllers
+ Holds controllers that should be named like weblogs_controller.php for
+ automated URL mapping. All controllers should descend from ApplicationController
+ which itself descends from AkActionController.
+
+app/models
+ Holds models that should be named like post.php.
+ Most models will descend from ActiveRecord.
+
+app/views
+ Holds the template files for the view that should be named like
+ weblogs/index.html.tpl for the WeblogsController#index action. All views use eRuby
+ syntax.
+
+app/views/layouts
+ Holds the template files for layouts to be used with views. This models the common
+ header/footer method of wrapping views. In your controllers, define a layout using the
+ +$layout = 'default'+ and create a file named default.html.tpl. Inside default.html.tpl,
+ call {content_for_layout} to render the view using this layout.
+
+app/helpers
+ Holds view helpers that should be named like weblogs_helper.php. These are generated
+ for you automatically when using script/generate for controllers. Helpers can be used to
+ wrap functionality for your views into methods.
+
+app/installers
+ Holds the migration files for creating the database schema and other actions that require
+ version control.
+
+app/locales
+ Holds the text translations for multilingual apps.
+
+config
+ Configuration files for the Akelos environment, the routing map, the database, and other dependencies.
+
+doc
+ This directory is where your application documentation will be stored when generated
+ using +rake doc:app+
+
+lib
+ Application specific libraries. Basically, any kind of custom code that doesn't
+ belong under controllers, models, or helpers. This directory is in the load path.
+
+public
+ The directory available for the web server. Contains subdirectories for images, stylesheets,
+ and javascripts. Also contains the dispatchers and the default HTML files. This should be
+ set as the DOCUMENT_ROOT of your web server.
+
+makelos
+ Rake for PHP. Use it for automation. run +./makelos+ to see available options.
+
+script
+ Helper scripts for automation and generation.
+
+test
+ Unit and functional tests along with fixtures. When using +./makelos generate+ scripts, template
+ test files will be generated for you and placed in this directory.
+
+vendor
+ External libraries that the application depends on. Includes the plugins subdirectory and is the
+ default location for the Akelos Framework.
@@ -8,3 +8,68 @@ if you want to make your own, Akelos gives you a great way to do this
by running:
./makelos generate task
+
+
+
+Autocompletion on bash prompts
+--------------------------------
+
+You can add bash autocompletion support to Makelos
+
+First you'll need to have installed bash-completion
+
+ Mac OS: sudo port install bash-completion
+ Debian: apt-get install bash-completion
+
+Add to the very bottom of your bash profile (Nice post by
+Todd Werth http://blog.infinitered.com/entries/show/4 on
+the subject)
+
+ Mac OS ~/.profile:
+
+
+ if [ -f /opt/local/etc/bash_completion ]; then
+ . /opt/local/etc/bash_completion
+ fi
+
+ Debian ~/.bashrc:
+
+
+ if [ -f /etc/bash_completion ]; then
+ . /etc/bash_completion
+ fi
+
+
+Create the file
+
+ Mac OS: /opt/local/etc/bash_completion.d/makelos
+ Debian: /etc/bash_completion.d/makelos
+
+with the following code
+
+ _makelos()
+ {
+ local cur colonprefixes arguments
+ COMPREPLY=()
+ cur=${COMP_WORDS[COMP_CWORD]}
+ # Work-around bash_completion issue where bash
+ # interprets a colon
+ # as a separator.
+ # Work-around borrowed from the darcs/Maven2
+ # work-around for the same issue.
+ colonprefixes=${cur%"${cur##*:}"}
+ arguments=("${COMP_WORDS[@]:1}")
+ COMPREPLY=( $(compgen -W '$(./makelos makelos:autocomplete \
+ ${arguments[@]})' -- $cur))
+ local i=${#COMPREPLY[*]}
+ while [ $((--i)) -ge 0 ]; do
+ COMPREPLY[$i]=${COMPREPLY[$i]#"$colonprefixes"}
+ done
+ return 0
+ } &&
+
+complete -o bashdefault -o default -F _makelos ./makelos 2>/dev/null \
+ || complete -o default -F _makelos ./makelos
+
+
+cd to your app dir in a new prompt and enjoy makelos autocompletion.
Oops, something went wrong.

0 comments on commit 07369d2

Please sign in to comment.