[ Index ] |
PHP Cross Reference of Web Application Component Toolkit |
[Summary view] [Print] [Text view]
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.
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Sun Nov 28 19:36:09 2004 | Cross-referenced by PHPXref 0.5 |