Proposal for "PEAR_PackageFileManager_Frontend"

» Metadata » Status
» Description
Summary
PEAR_PackageFileManager_Frontend (PFMFE) is designed to act as a backend with all logic for any frontend such as Web or Gtk2.

After a first attempt with my previous proposal (today deleted) called PEAR_PackageFileManager_GUI_Web, i've realized with Scott Mattocks future plan of Gtk2 frontend a real need to split my previous work in two parts:

- a backend (this proposal)
- a simple html web frontend with no PEAR_PackageFileManager2 process/logic.

PEAR_PackageFileManager_GUI_Web code revisited ... (in progress) will become soon my next proposal under name PEAR_PackageFileManager_Frontend_Web.

API resume
Error management

All errors are written in a PEAR_PackageFileManager_Frontend 'error stack. See PEAR_ErrorStack usage. Even errors/warnings from PEAR_PackageFileManager2 (PFM) are repackaged using Ian Eure solution and its StackThunk 0.9.0 package.

  1. hasErrors : Returns whether or not errors have occurred (and been captured).
  2. getErrors : Get a list of all errors since last purge.
  3. pushWarning : repackage PEAR_Error


Configuration
Beside these functions, you will find intensive usage of PEAR::Config package and its different containers.

Loading preferences, and change PFMFE behaviours begin so easy. You may change
PFM internal options (simpleoutput, baseinstalldir, ...) but also you can define which classes components will be use in a frontend (web/gtk2).

  1. loadPreferences : Load the user preferences for a frontend
  2. savePreferences : Save the user preferences for a frontend
  3. getOption : Gets a user preference node value using XPATH like format
  4. setOption : Sets a user preference value


Example below load preferences from php $conf array .

<?php
$conf['pfm']['outputdirectory'] = $_ENV['TMP'];
$conf['pfm']['baseinstalldir'] = 'PEAR/PackageFileManager';
$conf['pfm']['changelogoldtonew'] = false;
$conf['gui']['actions']['dump'] = 'ActionDump';
...
$config = array($conf, 'phparray');

$web =& PEAR_PackageFileManager_Frontend::singleton('Web', ...);
$web->loadPreferences($config);
?>


But you can also use a config container created on the fly

<?php
$config =& new Config_Container('section', 'config');
$config->createComment('PFM Config');
$pfm =& $config->createSection('pfm');
$pfm->createDirective('baseinstalldir', 'PEAR/PackageFileManager');
...
$web =& PEAR_PackageFileManager_Frontend::singleton('Web', ...);
$web->loadPreferences($config);
?>


or at least use an external config file (xml, php array, ...)

<?php
$config = array('prefGtk2.xml', 'xml');

$gtk2 =& PEAR_PackageFileManager_Frontend::singleton('Gtk2', ...);
$gtk2->loadPreferences($config);
?>


Example to retrieve the display driver class of my web frontend configuration value

<?php
$ActionDisplay = $this->getOption(array('settings','gui','actions','display'));
?>


In my Web frontend, i've a addPages function that read page from an external config source to build my QF controller. Here are how i get info using XPATH Config like syntax.

<?php
$pages = $this->getOption(array('settings', 'gui', 'pages'), false);

foreach($pages['pages']['page'] as $page) {
$pageN = array('settings', 'gui', 'pages',
array('page', array('id' => $page['@']['id']))
);
$this->addPage($pageN);
}
?>



Logging activity
Logs normal activity or simple to help for debug, two methods are available.

  1. setLogger : Set up a PEAR::Log object or compatible
  2. log : Log an error using PEAR::Log or compatible backend


Getting XML Package information
To initialize a frontend and all its logical pages, i've a unique method.

  1. getDefaults

and categories (package, release, maintainers, dependencies, replacements)

But there are also basic functions:

  1. getMaintList : Returns list of package maintainers
  2. getFileList : Prepare file list, with role, replacements and platform exception info.
  3. getDepList : Returns list of package dependencies (other packages and/or extensions)
  4. getRoleList : Returns list of directories and file extensions roles
  5. getExceptionList : Returns list of file role for specific files


Roadmap
PFMFE is just a stone for all frontend we can imagine. It should not be used alone. Conclusion will come with PEAR_PackageFileManager_Frontend_Web and PEAR_PackageFileManager_Frontend_Gtk2.
» Dependencies » Links
  • PEAR_PackageFileManager >= 1.6.0a7
  • Config >= 1.10.6
  • Log >= 1.9.0 (optional)
  • Var_Dump >= 1.0.1 (optional)
» Timeline » Changelog
  • First Draft: 2006-03-27
  • Proposal: 2006-03-28
  • Call for Votes: 2006-04-18
  • Voting Extended: 2006-04-26
  • Laurent Laville
    [2006-04-02 17:18 UTC]

    (highlight) Source code was updated related to new api 0.2.0

    to Christian Weiske comments:
    - added new api (simple wrapper to PFM api) to add / remove maintainers

    Error management :
    - hasErrors() method has now ability to check level error (PEAR_ErrorStack feature)

    New api :
    - setDefaults() to save initial data, allow a 'reset' button feature (see web frontend)
    - exportValue() to read data from container
    - getPageName() to retrieve a page name from its logical identifier
    (for example: in web frontend page1 === Package, page2 === Release, ...)

    Ready for PEAR_PackageFileManager_Frontend_Web !
  • Laurent Laville
    [2006-04-02 17:20 UTC]

    All source code, examples, ... are available at URI
    http://pear.laurent-laville.org/pepr/PEAR_PackageFileManager/Frontend/