[Tickets #1395] Add preference data type support for floating point numbers

[bugs at bugs.horde.org]

DO NOT REPLY TO THIS MESSAGE. THIS EMAIL ADDRESS IS NOT MONITORED.

Ticket URL: http://bugs.horde.org/ticket/?id=1395
-----------------------------------------------------------------------
 Ticket             | 1395
 Updated By         | scott at realorganized.com
 Summary            | Add preference data type support for floating point numbers
 Queue              | Horde Base
 Version            | 3.0.3
 State              | Feedback
 Priority           | 1. Low
 Type               | Enhancement
 Owners             | Horde Developers
-----------------------------------------------------------------------


scott at realorganized.com (2005-02-18 09:55) wrote:

I have some text for the wiki, however I can't figure out how to create a
new page.  

Here is the text for your review:

Preferences are an important infrastructure capability of the Horde
Framework.  Each user has their own preference settings.  These settings are
preserved from session to session and therefore are a useful way to retain
long-term preference settings for the user.  Since preferences are unique to
each user, it would not be appropriate to use preferences to specify general
server settings for the entire Horde server.  You should use the Horde
Configuration capability for that.  Preferences are saved across multiple
sessions.  If you would like to store state information for a particular
session, use the PHP session capability.

Horde preferences can be specific to your application or can be shared
amongst multiple applications.  Generally, your preference settings would be
local and not shared.  However, if you had a suite of applications which
each used a particular preference you would designate that preference as
shared.

Horde preferences can be locked.  What this means is that the user would not
be able to view, or edit this preference from the setting screens.  However,
locked preferences can be changed via programatic interface.  For example,
if you allowed users to modify their sort order via a control within your
application, then there would be no need to display this information in the
settings screens.  This preference setting would be considered locked. 
Another use for a locked preference is to store a preference for a setting
that you have not yet decided to expose to the user.  Your code can operate
on this setting, but the user is not allowed to view or change it.

To initialize your preferences, you would place your initial preference
settings in the prefs.php file located here:
yourapplication/config/prefs.php
Each preference setting is called a property and is initialized with code
similar to that shown below:

$_prefs['yourpropertyname'] = array(
    'value' => '28',
    'locked' => false,
    'shared' => false,
    'type' => 'floatnumber',
    'desc' => _("% Housing-to-Income Ratio")
);

The 'value' element is the default value for your property.  'locked' and
'shared' are as we have discussed above.  'type' is the way you would like
your data to be presented to the user when they view your preferences panel.
 'desc' is a description string that is displayed in your preferences panel
describing the property.  Notice the double quotes and enclosure using _( ).
 This is used for internationalization support.

If you have many preferences, you can organize them into preference groups. 
These are logical groups of one or more properties organized into individual
preference penal.  When the user views the settings for your application,
they would see an initial screen of all the individual preference panels. 
The user then selects an individual panel (group).

To create a preference group, you would add code like this to your prefs.php
file:

$prefGroups['calculator'] = array(
    'column' => _("Calculator Settings"),
    'label' => _("Calculator Defaults"),
    'desc' => _("Change default calculator settings."),
    'members' => array('yorproperty', 'anotherproperty', ... )
);

Add a section like that shown above for each preference panel.

Information about possible values for each of these arrays can be found
here: 'horde/config/prefs.php'

The predefined types provided are fairly complete and can provide basic
support for user preferences.  However, there will always be a need to
create some level of customization of individual properties.

To create your own custom property handler, set your 'type' => 'special'.
Then add a file to 'yourapplication/templates/prefs/yourpropertyname.inc'
containng the html code generation code for the control.
Add a function handler into the file 'yourapplication/lib/prefs.php'
The function handler is of the form 'handle_yourpropertyname($updated)'

One limitation of custom property handlers is that they are specific to an
individual property.  If you have several properties that need the same
custom control, you cannot reuse the handler.  For cases where you would
like to reuse your handler, you can create your own custom type hander.

To create your own custom type handler:
Assign your own custom type to 'type' => yourcustomtype
Place a file inside your application at 'templates/prefs/yourcustomtype.inc'
which contains the html for the control.
Inside of the lib/prefs.php in your application, add a function
'handle_yourcustotype'

Warning: If you have a shared preference, custom UI gadgets will not be
available to other applications.