[ Index ]

PHP Cross Reference of Web Application Component Toolkit

title

Body

[close]

/ -> README (source)

   1  --------------------------------------------------------------------------------
   2  Web Application Component Toolkit
   3  --------------------------------------------------------------------------------
   4  http://www.sourceforge.net/projects/wact
   5  
   6  --------------------------------------------------------------------------------
   7  !!!! VERY VERY IMPORTANT !!!!
   8  --------------------------------------------------------------------------------
   9  Release 0.1_alpha is EXPERIMENTAL. There are bugs we know about and many more we
  10  don't. Future releases may break APIs. Areas of WACT have yet to have their
  11  design finalized, in particular the classes in wact/framework/controllers/ and
  12  wact/framework/controllers/request.
  13  
  14  Use at your own risk!
  15  
  16  --------------------------------------------------------------------------------
  17  !!! IMPORTANT !!!
  18  --------------------------------------------------------------------------------
  19  Your PHP installation will need write access to a 'compiled' directory under
  20  every 'templates' directory in order for the examples and unit tests to work.
  21  
  22  On a Unix(ish) system the 'setup.sh' script will set up the required directories
  23  with permissions set to world writeable. You can run the script from this
  24  directory with the command:
  25  
  26  $ ./setup.sh
  27  
  28  Also, when working with the ServerCachedPageController class or the
  29  <cache:outputcache /> tag, you will need to provide read / write permissions to
  30  the cache directories (the location being specified in config.ini).
  31  
  32  --------------------------------------------------------------------------------
  33  DEPENDENCIES
  34  --------------------------------------------------------------------------------
  35  (For a full description of installing packages from PEAR, see the file PEARNOTES)
  36  
  37  WACT requires PEAR::XML_HTMLSax (v 2.1.2+) which provides the basis for WACT's
  38  template parser.  XML_HTMLSax is currently only used during the compile template
  39  phase.  The other pear modules used by WACT are for optional components.
  40  
  41  To install PEAR::XML_HTMLSax using the Pear Package manager (recommended) type;
  42  $ pear install http://pear.php.net/get/XML_HTMLSax-2.1.2.tgz
  43  
  44  Normally, when pear is installed, the PEAR directory will be placed into the
  45  default PHP include search path.  If this is not the case in your configuration,
  46  you can use the [pear] library_path configuration option in config.ini to specify
  47  a location for WACT to include PEAR modules.  Many PEAR modules cannot function
  48  correctly if the pear directory is not in the default search path.
  49  
  50  To use the version bundled with the release, edit config.ini and make sure you
  51  have;
  52  [pear]
  53  library_path = ../external/pear/
  54  
  55  If you do not have PEAR::XML_HTMLSax, WACT is configured to use a version that
  56  is bundled with this release.  A section in the compiler.ini file give a
  57  relative path to the bundled version of XML_HTMLSax, based on the location of
  58  the framework directory:
  59  
  60  [XML_HTMLSAX]
  61  library_path=../external/pear/XML/
  62  
  63  You can change this path in compiler.ini to point to any directory containing
  64  XML_HTMLSax.  There is one caveat, however.  The current version of XML_HTMLSax
  65  includes the file pear.php.  If you try to use this configuration option and
  66  you do have PEAR installed, it is possible to receive redeclaration errors if
  67  pear.php is included twice. Additionaly, the current version of XML_HTMLSax
  68  expects pear.php to be in the standard include path.  If you do not have PEAR
  69  installed, this will not be the case.
  70  
  71  Alternatively, you can place a copy of pear.php into the XML directory pointed
  72  to by the library_path option.  This is only recommended if you do not have
  73  PEAR installed.  Future versions of XML_HTMLSax may eliminate this dependency
  74  on pear.php and simplify the process of using WACT without PEAR installed.
  75  
  76  WACT provides template caching facilities that require PEAR::Cache_Lite (v1.1+)
  77  This will be needed when using the <cache:outputcache /> tag. To install;
  78  $ pear install http://pear.php.net/get/Cache_Lite-1.2.tgz
  79  
  80  The <calendar:month /> tag requires PEAR::Calendar (version 0.4+). To install;
  81  $ pear install http://pear.php.net/get/Calendar-0.4.tgz
  82  
  83  WACT provides optional "drivers" PEAR::DB and ADODB for database access,
  84  in addition to native drivers (currently only MySQL).
  85  
  86  If you wish to use PEAR::DB with WACT, make sure that it is available under
  87  your PEAR installation (it is usually bundled with the base PEAR installation.
  88  Otherwise install with;
  89  $ pear install DB
  90  
  91  To use ADODB, the library should be available in the directory specified in the
  92  config.ini file.  The default setting is:
  93  
  94  [adodb]
  95  library_path = ../external/adodb/
  96  
  97  --------------------------------------------------------------------------------
  98  UNIT TESTS
  99  --------------------------------------------------------------------------------
 100  The WACT unit test suite uses the SimpleTest unit testing framework, available
 101  from:
 102  
 103  http://www.lastcraft.com/simple_test.php
 104  
 105  The simpletest distribution should be made available in a 'external/simpletest'
 106  directory.
 107  
 108  Some of the unit test cases use SimpleTest's web testing facilities - for these
 109  tests to work you will need to set the value of the WACT_TEST_HTTP_PATH constant
 110  in tests/common.inc.
 111  
 112  The CLI interface for the WACT unit test suite requires PEAR::Console for full
 113  functionality - you are likely to have this installed already if you have used
 114  the PEAR installer.
 115  
 116  --------------------------------------------------------------------------------
 117  HELP NEEDED
 118  --------------------------------------------------------------------------------
 119  Most important is documentation. We are using the WACT WIKI;
 120  http://wact.sourceforge.net to provide user documentation as well as API
 121  docs available at http://wact.sourceforge.net/api/. Be aware that there
 122  are links from the API docs to the WIKI. In most cases a terse entry will
 123  have been added. Please add your notes / comments / examples as you work
 124  with WACT.
 125  
 126  For bug reports. Please submit bugs to the SF tracker:
 127  http://sourceforge.net/tracker/?group_id=85372&atid=575984
 128  
 129  If you have feature requests, please use the feature request tracker:
 130  http://sourceforge.net/tracker/?group_id=85372&atid=575987
 131  
 132  We are also in need of extra hands. WACT is quickly growing beyond the time
 133  available to the current developers. The sort of help we need;
 134  
 135  - A port of the WIKI (http://phpwiki.sourceforge.net/) to WACT. Although
 136    PHP Wiki has some great features, it's slow and lacking in mechanisms
 137    to build useful site indexes, which is important.
 138  
 139  - Providing examples / example applications and working on the WACT Petstore
 140  
 141  - Someone (able to fluently speak a language other than English) to put together
 142    a simple app demonstrating i18n with WACT
 143  
 144  - Tags! The more tags the better. See the "Developing a Calendar Component TAG"
 145    in the WIKI:
 146  
 147  http://wact.sourceforge.net/index.php/Developing%20A%20Calendar%20Component%20Tag
 148  
 149  - Patches / bug fixes.
 150  
 151  - Last but not least, developers willing to go "full time" to work on WACT.
 152  
 153  If you're interested, it's best to immerse yourself in WACT. Read the WIKI.
 154  Examine the code in as much detail as you can.
 155  
 156  --------------------------------------------------------------------------------
 157  SECURITY
 158  --------------------------------------------------------------------------------
 159  Depending on how you install WACT, be careful about where you place the template
 160  directories and (if any) cache directories. Ideally these (plus the framework
 161  directory) should be kept outside your document root. Be careful with .ini files
 162  as well, as exposing them in a public directory may be giving away information
 163  like database username / password.
 164  
 165  You might consider using .htaccess files, if possible, contain either;
 166  
 167      order deny,allow
 168      <FilesMatch "\.(ini)$">
 169         deny from all
 170      </FilesMatch>
 171  
 172  Will prevent access to .ini files in or below the current directory.
 173  
 174      order deny,allow
 175      deny from all
 176  
 177  Will prevent all access to the current directory and below (good for template
 178  / cache directories).
 179  
 180  Otherwise be aware of the classes in the framework/request/ directory, which,
 181  if used (and they are automatically by some WACT form controllers) are
 182  designed to strip magic_quotes, if they are switched on.
 183  
 184  --------------------------------------------------------------------------------
 185  CONFIG.INI
 186  --------------------------------------------------------------------------------
 187  In WACT_ROOT you will find the file config.ini. This the central
 188  configuration file which WACT falls back to unless it finds a configuration
 189  file in the directory where the current PHP script is executing.
 190  
 191  If you place a config.ini file in the same directory as a PHP script which is
 192  being executed, it will prefer that over the file in WACT_ROOT. Otherwise the
 193  constant WACT_CONFIG_DIRECTORY can be defined at the start of your code to
 194  specify the location of config.ini.
 195  
 196  Some important settings in config.ini
 197  
 198  [templates]
 199  forcecompile = TRUE | FALSE
 200  
 201  When developing WACT templates, this should be
 202  switched to "TRUE" so that templates are recompiled on each viewing. Once
 203  you're finished editing templates, switch it to "FALSE" (and watch performance
 204  improve significantly).
 205  
 206  [database]
 207  ; which database driver to use.
 208  driver = mysql | pear | adodb
 209  
 210  ;Mysql settings
 211  mysql.database = "wactexamples"
 212  mysql.user = "wack"
 213  mysql.password = "wacky"
 214  mysql.host = "localhost"
 215  
 216  ;PEAR::DB settings
 217  pear.dbtype = "oracle"
 218  pear.database = "wactexamples"
 219  pear.user = "wact"
 220  pear.password = "wacky"
 221  pear.host = "localhost"
 222  
 223  ;ADOdb settings
 224  adodb.dbtype = "pgsql"
 225  adodb.database = "wactexamples"
 226  adodb.user = "wact"
 227  adodb.password = "wacky"
 228  adodb.host = "localhost"
 229  
 230  Hopefully the database settings explain themselves. WACT comes with a
 231  "database driver" for MySQL but also has drivers which adapt PEAR::DB
 232  and ADOdb to the WACT database (DBC) API. You will need to configure
 233  the local config.ini files in WACT_ROOT/examples/demoapp and
 234  WACT_ROOT/examples/dbadapters to run those examples.
 235  
 236  The [output_cache] section is specific to the Core Outputcache Tag, the
 237  settings here controlling the behaviour of PEAR::Cache_Lite which is used
 238  the the underlying library for caching.
 239  
 240  The remain sections for [adodb] and [pear] specify the locations from
 241  where these libraries can be found for inclusion.
 242  
 243  --------------------------------------------------------------------------------
 244  WHAT DO I NEED AS A USER
 245  --------------------------------------------------------------------------------
 246  The following files/directories below the WACT_ROOT directory
 247  contain classes you may be interested in using;
 248  
 249  WACT_ROOT/common.inc.php
 250  You always need to include this file
 251  
 252  WACT_ROOT/template/template.inc.php
 253  You need this to use templates (probably always)
 254  
 255  WACT_ROOT/db/db.inc.php
 256  You need this if you are going to access a database. It takes care of
 257  including the specific driver you need automatically
 258  
 259  WACT_ROOT/template/components
 260  The classes in here are automatically included by the WACT template
 261  engine when you use the corresponding Tag in your template. You do
 262  need to be aware of the classes here though, as you'll be using them
 263  to control the behaviour of template components at runtime.
 264  
 265  WACT_ROOT/controllers/
 266  In here are controllers to help you work with forms and more. The
 267  formcontroller.inc.php is the most stable, and helps you build
 268  forms which validation etc. Be warned that the APIs for these classes
 269  are likely to change though.
 270  
 271  WACT_ROOT/util/
 272  There are a number of classes in here to be aware of, mainly to help
 273  working with datasets. The files you are most likely to need to
 274  specifically include are;
 275  
 276  arraydataset.inc.php - allows you to build a dataset from a PHP array
 277  datasetdecorator.inc.php - decorate an existing dataset with further
 278  functionality dataspacemapper.inc.php - remap variable names in the dataspace.
 279  
 280  --------------------------------------------------------------------------------
 281  TEMPLATE NOTES
 282  --------------------------------------------------------------------------------
 283  
 284  Template tag components come in four flavors (see the API docs for heirarchies);
 285  
 286  - Silent Compiler Directives (e.g. <core:import> and <core:set>) do not "exist"
 287    at runtime and do not write anything to the compiler template. They are used
 288    purely at compile time and typically provide data to other tag components.
 289  
 290  - Compiler Directives (e.g. <core:include> and <core:wrap>) do not "exist" at
 291    runtime but do write to the compiled template
 292  
 293  - Server Components (e.g. <core:block> and <list:list>) "exist" at runtime
 294    (that is they have some form of runtime API which you can interact with
 295    in your code). They do not correspond directly to any output HTML (or
 296    otherwise) tags though. They may still be responsible for generating HTML,
 297    such as the <calendar:month> tag but will not directly show up in the output
 298    delivered to the end user.
 299  
 300  - Server Tag Components (e.g. <form runat="server">, <input runat="server">
 301    and "anyTags") correspond to real output HTML (or otherwise) tags and have
 302    a runtime API. Because these tags will render directly (in some form) to
 303    the end user, special rules apply to them. Currently, Server Tag Components
 304    must have either an naming id attribute or a runat="server" attributem, to
 305    be generated as a runtime component. Without these attributes, the parser
 306    will simply ignore them and treat them as normal HTML, writing them "as is"
 307    to the compiled template for display. Note we may decide to be stricter about
 308    this in future, with runat="server" being the only mechanism to declare a
 309    Server Tag Component - not yet decided. The use of the id attibute also has
 310    a meaning in CSS / DOM...
 311  
 312  The "rules" of the template engine will generally make themselves clear to you
 313  as you use it - it has syntax checking rules for WACT tags (not HTML - yet) and
 314  will generally provide you with useful error messages including a line number /
 315  column where it discovered the error (not this may not always be the place
 316  where the cause of the problem can be found but is where the parser noticed the
 317  problem - the resulting error message should help you work it out).
 318  
 319  --------------------------------------------------------------------------------
 320  WHERE NOW
 321  --------------------------------------------------------------------------------
 322  Online you'll find further information at;
 323  
 324  http://wact.sourceforge.net/api (with links to relavant WIKI pages)
 325  http://wact.sourceforge.net/examples
 326  
 327  The examples are also provided with the distribution and present the best source
 328  of further information. With the examples is a tutorial walking through building
 329  an RSS feed with WACT.


Generated: Sun Nov 28 19:36:09 2004 Cross-referenced by PHPXref 0.5