[Jamwiki-commit] SF.net SVN: jamwiki:[4114] wiki/branches/cclavadetscher

[<ccl...@us...>]

Revision: 4114
          http://jamwiki.svn.sourceforge.net/jamwiki/?rev=4114&view=rev
Author:   cclavadetscher
Date:     2012-07-20 11:31:02 +0000 (Fri, 20 Jul 2012)
Log Message:
-----------
User Preferences Management.

* New class UserPreferencesUtil: this class is a container for user preferences. It simplifies
  the handling of user preferences in the GUI.

New process for adding user preferences: Step by step with a fictional example.

Let's suppose that we want to add a user preference recording the preferred food.

1. Define a default entry in jam_user_preferences_defaults:

   insert into jam_user_preferences_defaults (pref_key, pref_value)
   values ('user.preferred.food',null);

2. Define a constant in UserPreferencesUtil:

   public static final String USER_PREFERENCE_PREFERRED_FOOD = 'user.preferred.food';

3. Define the value range of the preference if necessary.

   If we wanted to let the user decide freely, there is no need to define anything. The default
   display is an input field of type text.
   
   In this example we want to limit the choices of the user to a few items. To do that we can
   use a list of Strings or a Map<String, String>. Depending on the choice you will need to
   add an if statement either to
   
   - UserPreferenceItem.getList()
   - UserPreferenceItem.getMap()
   
   Notice that UserPreferenceItem is an inner class of UserPreferencesUtil, which is necessary
   in order to access selectively preference values from JSTL.
   
   We decide to limit the access using a list of Strings. So we add the following lines:
   
			else if(prefName.equals(USER_PREFERENCE_PREFERRED_FOOD)) {
				return new String[]{"Pizza", "Spaghetti", "T-Bone Steak"};
			}

4. Add text for the GUI: In ApplicationResources.properties add

   user.preferred.food.label=Preferred food
   user.prererred.food.help=This value is used to diplay food icons on the recipe pages

5. If the field has a preview also add the necessary code to
   
   UserPreferenceItem.getPreview():
   else if(prefName.equals(USER_PREFERENCE_PREFERRED_FOOD)) {
      return ...;
   }
   
6. Finally, in order to enable new setups and upgrades, proceed as follows:

   In WikiDatabase.setupUserPreferencesDefaults and:
   In DatabaseUpgrades.upgradeXXX() // XXX depends on the version number
   add:
   
   handler.writeUserPreferenceDefault(UserPreferencesUtil.USER_PREFERENCE_PREFERRED_FOOD, null);

7. After these steps the preference is managed in the GUI without additional implementation or modifications
   of the JSP.
   The developer can focus on the usage of the preference in the application.

Modified Paths:
--------------
    wiki/branches/cclavadetscher/jamwiki-core/src/main/java/org/jamwiki/db/AnsiDataHandler.java
    wiki/branches/cclavadetscher/jamwiki-core/src/main/java/org/jamwiki/db/AnsiQueryHandler.java
    wiki/branches/cclavadetscher/jamwiki-core/src/main/java/org/jamwiki/db/DatabaseUpgrades.java
    wiki/branches/cclavadetscher/jamwiki-core/src/main/java/org/jamwiki/db/WikiDatabase.java
    wiki/branches/cclavadetscher/jamwiki-core/src/main/java/org/jamwiki/model/WikiUser.java
    wiki/branches/cclavadetscher/jamwiki-core/src/main/java/org/jamwiki/parser/jflex/WikiSignatureTag.java
    wiki/branches/cclavadetscher/jamwiki-core/src/main/java/org/jamwiki/utils/DateUtil.java
    wiki/branches/cclavadetscher/jamwiki-war/src/main/resources/ApplicationResources.properties
    wiki/branches/cclavadetscher/jamwiki-war/src/main/resources/ApplicationResources_de.properties
    wiki/branches/cclavadetscher/jamwiki-war/src/main/resources/ApplicationResources_it.properties
    wiki/branches/cclavadetscher/jamwiki-war/src/main/webapp/CHANGELOG.txt
    wiki/branches/cclavadetscher/jamwiki-war/src/main/webapp/WEB-INF/jsp/register.jsp
    wiki/branches/cclavadetscher/jamwiki-web/src/main/java/org/jamwiki/servlets/RegisterServlet.java

Added Paths:
-----------
    wiki/branches/cclavadetscher/jamwiki-core/src/main/java/org/jamwiki/utils/UserPreferencesUtil.java

Property Changed:
----------------
    wiki/branches/cclavadetscher/

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.