Beyond the Config File: User-Friendly Configuration For Web Apps ================================================================ :Author: Leonard Richardson :Contact: leonardr@segfault.org [This slideshow designed for use with Mozilla or other accesskey-supporting browsers; use alt-N and alt-B to navigate forward and backward, alt-I to return here. Or you can `view the reST presentation source`_ and `the source to the slide generator`_] .. _view the reST presentation source: slides.txt .. _the source to the slide generator: http://www.crummy.com/devel/download/ThePowerOfGreypoint.py % Preemptive Conclusion --------------------- In so far as is possible, you should move configuration settings out of configuration files and into a configuration framework. * Your app will be easier to configure * It will also be easier to develop .. raw:: html
--------------------------- Usability ----------------------------------> .. raw:: html
+----------------+--------------------+-------------------------+ | Code constants | Configuration file | Configuration framework | +================+====================+=========================+ | |stage1| | |stage2| | |stage3| | +----------------+--------------------+-------------------------+ .. |stage1| image:: graphics/stage1.png .. |stage2| image:: graphics/stage2.png .. |stage3| image:: graphics/stage3.png % What's A Configuration Framework? --------------------------------- * An interface to an application's configuration settings * Allows you to configure the application from within the application * Can coexist with scriptable configuration files on the backend Advantages of configuration frameworks: * More user-friendly * Safer to use * Self-documenting * Impressive results with little incremental effort * Easy to respond to user requests * More of your application is web-accessible % What's A Configuration Framework Not? ===================================== * Not an application framework - You could try to do your whole application this way, but it would be ugly. - Automatically-generated interface to something which would otherwise have no interface at all. * Not neccessarily web-based - This only covers web configuration frameworks, but an ncurses or pyGTK framework would work on the same principles. * Neither floor wax nor desert topping % Anatomy of a Configuration Framework ------------------------------------ 1. Option definition store - Defines which options there are 2. Configuration store - Store the current values of the options 3. Option display and semantics - Different logic and data types for different types of option - Dependencies between options 4. User interface - Lets the user in on the fun **Next: excruciating detail!** % Excruciating Detail Part I: Option definition store --------------------------------------------------- * Defines which options exist * Each option corresponds to an application feature * Probably not changable at runtime * Includes documentation and defaults * A flat file is good % E.D. Part II: Configuration store --------------------------------- * Stores the current values of the options * Storage format should fit with the application framework: - A database is good - Also key-value pairs - Or some XML thing, I don't care % E.D. Part III: Option display and semantics ------------------------------------------- * Controls what edit controls for options should look like * Controls relevancy (whether or not displayed) - Option might be moot - User may not have permission to view or edit option value * Performs option validation * Enforces option interdependencies * Transforms the value as stored in the configuration store into something the application can use % E.D. Part III Part II: Some option types ---------------------------------------- Boolean option: * Edit interface: checkbox * Value: boolean (though maybe stored as string internally) String option: * Edit interface: text box * Value: string * May enforce maximum length ZIP code option: * Edit interface: 10-character text box * Must match ##### or #####-#### * May have an associated US state option - If both provided, value for ZIP code must match provided state. User selection option: * Edit interface: drop-down selection box * Select one of the application's user accounts (e.g. to assign a user some task). * Obtain the list of users dynamically (via database, disk, LDAP, etc.) rather than relying on a static list. * Not displayed if there are no relevant user accounts. % E.D. Part IV: User interface ---------------------------- This should be a CGI that fits with your larger application framework. * Get submitted data and scan for errors * If errors, display the corresponding error messages * If no errors, make changes to configuration store * Print editing form with current values from configuration store (or from previous invalid form submission) % .. raw:: html
Option definition store 
option=maximumImageSize
  displayName=Maximum image size?
  type=ByteSizeOption
  unit=kb
  defaultValue=10
  maxValue=10000
Option store 
maximumImageSize=100
Option semantics 
class ByteSizeOption(IntegerOption):
     def printEditControl(self):
         IntegerOption.printEditControl(self)
         print self.getUnitAbbreviation()

     def getUnitAbbreviation(self):
         return self.unit
+User interface 
class ConfigurationCGI(BaseCGI):

       def processRequest():
           ...
Configuration framework
Maximum image size? kb
% Option Grouping =============== If you have more than about 10 options, you probably want to arrange them into coherent groups. If your configuration framework contains one page with dozens of checkboxes, users will be overwhelmed and usability will suffer. Many people like potatoes. Do you like potatoes? Do you consider the Mr. Potato Head toy to be a potato? How about the `ktuberling`_ program? How do you like your potatoes prepared: baked, boiled, or mashed? The ocean sunfish, or mola mola, can achieve weights of up to 1500 pounds. What is the minimum sunfish weight you are interested in? How about the maximum weight? Should sunfish outside those weight limits be thrown back or should I try to sell them to an aquarium? .. _ktuberling: http://opensource.bureau-cornavin.com/ktuberling/ % Let's try that again ==================== .. raw:: html
Option Grouping Potatoes Sunfish

If you have more than about 10 options, you probably want to arrange them into coherent groups. If your configuration framework contains one page with dozens of checkboxes, users will be overwhelmed and usability will suffer.

% Limitations of Configuration Frameworks ======================================= Don't expose anything such that changing it can break the application. * Be careful about irrevocable changes in general * Locations of resources on server * Passwords to databases % I Want Options: An Extensible Configuration Framework ===================================================== * Contains all configuration-related logic * Includes many bizarre and useful option classes * Extend a couple classes to fit it into your framework: - ``OptionConfig``: option definition store reader - ``OptionWrapper``: a mix-in class allowing you to extend option display and semantics with application-specific logic - ``Context``: configuration store accessor The context is the unit of configuration * For site-wide options, the site * For user preferences, the user * For NewsBruiser, the notebook * Get it from http://www.crummy.com/devel/download/IWantOptions.py % Conclusion ========== With a configuration framework: * Your users need not switch tools or mindsets to become administrators * You can respond more rapidly to user requests * Your application is self-documenting (and looks nicer)