CHANGES.txt for Hobo 1.3

hobo/CHANGES.txt

@@ -0,0 +1,382 @@
+Hobo 1.3 Changes
+{.document-title}
+
+Hobo 1.3 is a significant update to Hobo.   The biggest change is that it now uses Rails 3.0 rather than Rails 2.X, but many other enhancements are included.
+
+Contents
+{.contents-heading}
+
+- contents
+{:toc}
+
+# Binary Apps
+
+There are 2 binary apps: hobo and hobofields. They have been rewritten from scratch and they accepts different options. Run the help for more details.
+
+    $ hobo --help
+    $ hobofields --help
+
+# HOBODEV
+
+This is a variable used only by hobo developers. You can set it to
+your local hobo git repository and the Gemfile will point to the local
+copy of your gems. It work even without git, because it adds the path
+to each gem root to the Gemfile.
+
+Examples
+
+    $ HOBODEV=./hobo3 ./hobo3/hobo/bin/hobo new hobo_app
+
+# Configuration Variables #
+
+They are set by the hobo engine at startup, and they can be overwrited by adding in `config/application.rb`:
+
+    config.hobo.<variable_name> = <value>
+
+
+variable name|type|description|default
+-------------|----|-----------|-------
+`app_name`|string|sets the application name|computed from the `application_module_name` generated by rails at the app creation
+`developer_features`|boolean|enables routes and actions for the dev controller|true in development and test env
+`routes_path`|Pathname object|sets the path of the auto generated routes file|`config/hobo_routes.rb`
+`rapid_generators_path`|Pathname object|sets the path of the generators rapid directory|`lib/hobo/rapid/generators`
+`auto_taglibs_path`|Pathname object|sets the path of the auto taglibs|app/views/taglibs/auto
+`read_only_file_system`|boolean|skips the generation of auto generated files (hobo routes, auto taglibs)|true only for Heroku deployed apps
+`show_translation_keys`|boolean|enable inline annotation of translated output|false
+`dryml_only_templates`|boolean|skips the generation of helper files|false
+{.big-table}
+
+## Notes
+
+### `read_only_file_system`
+
+You don't need to mess with `read_only_file_system` if you use heroku:
+it will be set automatically only when the application is run in the
+heroku environment.
+
+### `show_translation_keys`
+
+When `show_translation_key` is true it will show a label before each translated string, reporting the translation key used. The label is dryml friendly, i.e. does not contain any `<span>` tags (which are nicely styleable but mess everything up when inserted in the wrong place).
+
+It is omnipresent: it will just appear everywhere there is a key lookup, even in select-menu, so it is a real support for translation, debugging and overriding.
+
+It also shows how to override any hobo default strings for a specific
+model, (for example titles or heading for pages) since it shows both
+the called key and the fallback for each key passed to the ht method
+(sorry for the complicated explanation, but just try it and it will be
+self explanatory).
+
+
+
+# Application Name
+
+In previous Hobo, the app-name tag was generated by hobo and written into `application.dryml` and `<subsite>_site.dryml` and the canonical way to change it was just changing the string into the tag itself. Not anymore. The app-name tag in hobo has (almost) gone. Now it is a helper method that returns a combined string of application name and subsite name when present.
+
+The helper method takes the application name from a configuration variable: `config.hobo.app_name` that is set at startup by extracting it from the `<your_application_module_name>::Application`, which is a class that all rails 3 application (and engines) use in order to configure a lot of things. The `your_application_module_name` part is generated by the `rails new <your_application_module_name>` command.
+
+Although adding a custom app-name tag is possible and supported, it is reserved to local overriding (e.g. if you want to override just a subsite name for a specific subsite). If you want to override it application-wide, you should just set the `config.hobo.app_name` configuration variable in your `application.rb` (or somwhere else like in any environment file).
+
+    config.hobo.app_name = "Alternative Name"
+
+
+
+# Field Types
+
+The logic of sanitizing/escaping/marking-html-safe field types has changed as follow:
+
+The `to_html` method of a field type must always return a `html_safe?` string. Depending on the type itself and its common use, the result will be one of the following:
+
+- escaped string (html tags get escaped as html entities)
+- sanitized string (unsafe html tags get filtered out)
+- raw string (no changes)
+
+In detail:
+
+### HTML content fields
+
+* HtmlString : sanitized
+* RawHtmlString : raw
+* MarkdownString : sanitized
+* RawMarkdownString : raw
+* TextileString : sanitized
+
+### Non HTML content fields:
+
+* Text : escaped and `\n` translated to `<br/>`
+* EmailAddress : escaped and formatted as a "human-only" readable address
+* PasswordString : literal "\[password hidden\]" I18n translated
+
+### Internal content fields:
+
+* EnumString : raw and I18n translated
+* LifecycleState : raw and I18n translated
+
+
+# Generators
+
+Generators have been rewritten from scratch because rails 3 generators have been refactored a lot. The hobo generators have also been reorganized to fit to the new setup_wizard, and to be more DRY: indeed they often invoke each other from the inside. The section in the books that are referring to generators have to be rewritten almost completely.
+
+If you are used to the old hobo/rails syntax, please, noticed how these commands and names have changed:
+
+old command|new command
+---|---
+`ruby script/generate hobo_migration`|`hobo g migration`
+`ruby script/generate hobo_model_resource`|`hobo g resource`
+`ruby script/generate hobo_model`|`hobo g model`
+{.big-table}
+
+old generator|new generator
+---|---
+`hobo_migration`|`hobo:migration`
+`hobo_model_resource`|`hobo:resource`
+`hobo_model`|`hobo:model`
+{.big-table}
+
+
+## hobo generators
+
+The following command in a hobo/rails dir shows all the generators available:
+
+    $ hobo g --help
+
+(or)
+
+    $ rails g --help
+
+
+Under the *Hobo* group we find the hobo generators:
+
+    hobo:admin_subsite
+    hobo:assets
+    hobo:controller
+    hobo:front_controller
+    hobo:i18n
+    hobo:migration
+    hobo:model
+    hobo:rapid
+    hobo:resource
+    hobo:routes
+    hobo:setup_wizard
+    hobo:subsite
+    hobo:subsite_taglib
+    hobo:test_framework
+    hobo:user_controller
+    hobo:user_mailer
+    hobo:user_model
+    hobo:user_resource
+
+You can have more help about any generator (e.g. the 'hobo:resource' generator) by doing:
+
+    $ hobo g resource --help
+
+(which is the same as)
+
+    $ rails g hobo:resource --help
+
+As you may notice, if you use the hobo command you can omit the `hobo:` namespace prepended to hobo generators.
+
+The following options are common options for all the generators:
+
+    -q, [--quiet]    # Supress status output
+    -f, [--force]    # Overwrite files that already exist
+    -s, [--skip]     # Skip files that already exist
+    -p, [--pretend]  # Run but do not make any changes
+
+
+# Mailers
+
+Mailers have been rewritten in rails 3.  They are now simpler than before, and hobo adds a couple of useful helpers.
+
+`Hobo::MailerHelper` supplies the `app_name` (self explanatory) and `host` mailer-helpers: they are available as class and instance methods and as instance variables already set.
+
+The host helper is very useful when a mailer is called from a controller.  This allows the `url_for` method to work without the `:host` option (or if you set `default_url_options`). If your mailer runs in another context, the host helper returns the default host.
+
+The mailers become VERY simple with rails 3 and the hobo helpers. Take a look at the user mailer:
+
+    class UserMailer < ActionMailer::Base
+      default :from => "no-reply@#{host}"
+
+      def forgot_password(user, key)
+        @user, @key = user, key
+        mail( :subject => "#{app_name} -- forgotten password",
+              :to      => user.email_address )
+      end
+
+    end
+
+You can use the host helper in the class (as a class method), but you could do the same in any instance method like we do with `app_name`.   Alternatively, in the template you can use `@app_name` and `@host` without the need to set them in the mailer.
+
+
+# Routes
+
+Routes have changed a lot in rails 3 and the automatic routing system in Hobo has been rewritten almost from scratch. The main changes compared to previous versions are: 
+
+- Routes are now written in a file for easy user inspection and to make them work as they should in a regular app
+- The path file is a configuration variable (`routes_path`) and can be overwritten by the user in the application block in config.application.rb
+- The hobo engine paths (`dryml_support` and `dev_support`) are written in `hobo/config/routes.rb` and added by rails automatically
+- The user can override the hobo routes in the regular application `config/routes.rbfile`
+- The engine has a regular rails generator that generates the routes when needed, no monkey patch required.
+- No need to run the generator manually even the first time after deployment
+- The generation of the `hobo_routes.rb` file at startup is skipped when the read_only_file_system config variable is true (which it is when run in Heroku)
+
+
+# View Hints Alternatives
+
+In Hobo >= 1.3.* view hints are not files anymore, but their functionality has been moved elsewhere. Viewhints are now a subclass of `Hobo::Model::ViewHints` instead of `Hobo::ViewHints`. The class has been aliased so the old way is still supported.  If you create a `viewhints` directory and put some old style view hints file in there they will work as before.
+
+## Renaming
+
+View hints no longer are responsible for translating machine names into human readable strings; this now the responsibility of the i18n mechanism, also known as locales.  Hobo uses the Rails' i18n mechanisms and conventions.
+
+Here is the uncommented default config/locale/app.en.yml file.
+
+    en:
+      hello: "Hello world"
+
+      attributes:
+        created_at: Created at
+        updated_at: Updated at
+
+      activerecord:
+        models:
+          user:
+            one: User
+            other: Users
+        attributes:
+          user:
+            created_at: Created at
+            name: Name
+            password: Password
+            password_confirmation: Password Confirmation
+            email_address: Email Address
+        attribute_help:
+          user:
+            email_address: We will never share your address with third parties
+
+Please, note the following:
+
+- YAML files use a fixed number of spaces (2) to indent levels. 
+- Tabs are illegal
+- Quote marks are not mandatory
+
+The locale file structure is a rails convention.  For more information see the [rails 3 i18n guide](http://guides.rubyonrails.org/i18n.html).
+
+You can rename models and attributes by changing or adding key/values in the specific `activerecord.models` and `activerecord.attributes` sections, and adding attribute help you might need in the `activerecord.attribute_help` section (which is a hobo specific section). For example:
+
+    en:
+      hello: "Hello world"
+
+      attributes:
+        created_at: Created at
+        updated_at: Updated at
+
+      activerecord:
+        models:
+          user:
+            one: User
+            other: Users
+          contact:
+            one: Friend
+            other: Friends
+        attributes:
+          user:
+            created_at: Created at
+            name: Name
+            password: Password
+            password_confirmation: Password Confirmation
+            email_address: eAddress
+          contact:
+            name: Nickname
+            email_address: eAddress
+        attribute_help:
+          user:
+            email_address: We will never share your address with third parties
+          contact:
+            name: This is the nickname
+
+Just be careful: don't mess up the indentation!
+
+Notice: the key/values inside the first `attributes` group is used as the default for all the models.
+
+## Hints
+
+The `ViewHints.children` and the `ViewHints.inline_booleans` methods have been moved into the model, but they are used in the exactly same way they were used before.
+
+You can always reach the view_hints class by accessing the `Model.view_hints` method, so for example `User.view_hints.children` will return the children of the User model.  `parent`, `parent_defined`, `sortable?` and `paginate?` are also similarly accessible.
+
+
+## Deprecated methods
+
+- `model_name`
+- `model_name_plural`
+- `field_name`
+- `field_names`
+
+When called they raise an error, explaining the reason.
+
+# Internationalization
+
+The Hobo i18n framework has been completely rewritten.   See the [i18n
+manual chapter](/manual/i18n/) for more details
+
+# Other Changes
+
+## Hobo Installation
+
+You can install all the development dependencies of hobo by using the --development gem option
+
+## Rake Tasks
+
+Most of the old rake tasks have been replaced with generators. There
+is a new rake task useful to install and/or publish all the hobo gems
+to rubygems:
+
+    $ rake gems[install]
+    $ rake gems[push]
+
+## Lifecycles
+
+Added the :subsite lifecycle option which will generate the
+creator/transition route only in that subsite. E.g. if you don'set the
+:subsite option Hobo will generate a regular front controller route,
+while `:subsite => 'any_subsite'` will generate the route only in that subsite.
+
+## Front Controller
+
+Normalized the front controller form for first user with admin flag
+(now the first signed up user get active and get admin rights in a
+before_create handler)
+
+## `page_path` param
+
+The page_path parameter added to forms now contains the
+request.fullpath (and it's reversed with
+ActionController::Routing::Routes.recognize_path).  There are also 3
+helpers to manage it (these helpers are used internally so they are
+less interesting for users):
+
+- recognize_page_path
+- url_for_page_path
+- controller_action_from_page_path
+
+## Array#safe_join
+
+`Array#safe_join` is a hobo_support extension useful to deal with
+arrays of strings and html_safe strings. It always returns an
+html_safe? string preserving the already html_safe? items and
+separator, excaping the rest.
+
+## `hobo_model_*`
+
+`hobo_model_*` no longer accepts an argument.
+
+## Custom resource names
+A few generators allow more flexibility to the developer. You can assign a custom name to the `user_resource`, `front_controller` and `admin_subsite`.
+
+## dryml
+
+    render :something
+
+renders the tag 'something-page' thanks to the page_tag_resolver appended to the view_paths
+
+All the .dryml files in `app/views/taglibs/application/` and in each `app/views/taglibs/<subsite>_site/` will be auto included.