[phpWebApp-commits] CVS: documentation/templates/webobjects/pages browse.txt,NONE,1.1 datebox.txt,NO
Brought to you by:
dashohoxha
Menu
▾
▴
[phpWebApp-commits] CVS: documentation/templates/webobjects/pages browse.txt,NONE,1.1 datebox.txt,NONE,1.1 dbTable.txt,NONE,1.1 folderListing.txt,NONE,1.1 form.txt,NONE,1.1 leftMenu.txt,NONE,1.1 listbox.txt,NONE,1.1 table.txt,NONE,1.1 tabs.txt,NONE,1.1 xlistbox.txt,NONE,1.1
|
From: Dashamir H. <das...@us...> - 2003-02-23 14:42:43
|
Update of /cvsroot/phpwebapp/documentation/templates/webobjects/pages
In directory sc8-pr-cvs1:/tmp/cvs-serv20867/templates/webobjects/pages
Added Files:
browse.txt datebox.txt dbTable.txt folderListing.txt form.txt
leftMenu.txt listbox.txt table.txt tabs.txt xlistbox.txt
Log Message:
--- NEW FILE: browse.txt ---
What is it
----------
The 'fileBrowser' tool of WebApp is a WebBox which is used to
preview the templates and WebBox-es of a WebApp application.
It allows the users to browse the folders of the application
and to display the files. The files are displayed according
to their types, e.g. a php file is displayed as code, an image
file is displayed as an image, an HTML file can be displayed
both as HTML code and as rendered HTML, etc.
It is usually used by the grafical designer of the application
to see how the templates look in the application. He cannot see
the templates properly just by opening them in the browser, because
the templates contain {{#variables}}, template tags (like <Repeat>, <if>,
<Recordset>) etc. It can also be used by the JavaScript programmer
and PHP/DB programmer to test the functionality of a WebBox separately
from the rest of the application (if the WebBox is well encapsulated).
How to enable it for a certain application
------------------------------------------
To use it for a certain application, add a php file (e.g.
'browse.php') in the root folder of the application, which
contains these lines:
<?php
include "webapp.php";
WebApp::addVar("APP_STYLE", APP_URL."templates/styles.css");
WebApp::constructHtmlPage(BROWSER_PATH."fileBrowser.html");
?>
It is not a standalone application, it is like a plug-in tool
that can be added to an existing application. The constant
BROWSE_PATH is declared by the framework itself. By including
the "webapp.php" of the application, it gets the paths,
the DB connection and the configuration of the application itself,
which are needed in order to preview the templates correctly.
How it is used
--------------
On the left-side of the page there is a box that allows the user to
browse a folder and to select a file. The selected file is displayed
on the right side of the page. On the top of the page there is a
panel that allows the user to change the way the template is displayed.
If you check the "Hide Folder Box" and then click refresh, then the
left box that is used to browse the folders is hidden (this may be
useful when the template that is being displayed is too large and
fills all the width of the browser).
The options "Code View" and "Preview" change the viewing mode of
the HTML files. When "Code View" is selected, the HTML code of the
templates will be displayed. When "Preview" is selected, the templates
are displayed in the same way that they will be displayed in the
application.
The second box on the top allows the user to change any session variables,
and the third box allows him to change the root folder of the select box.
The configuration file
----------------------
Sometimes the templates may have variables inside it, or may be associated
with recordsets that contain variables. If these variables are given
values somewhere else in the application (outside the template) then these
variables will be uninstantiated and the template will not be displayed
properly. In order to correct this situation, a configuration file may
be used for each template. The 'fileBrowser' looks for the file
'tplFile.cfg.php', includes it if found, and calls the function
'tplFile_config()'. In this function the user can instantiate these
variables so that the template is displayed correctly (similar to how
it is displayed in a real situation in the application).
--- NEW FILE: datebox.txt ---
The webobject datebox can be used to select the date from a calendar.
It can be used like this:
First include the webclass that defines it:
<Include SRC="{{#DATEBOX_PATH}}datebox.html" />
(DATEBOX_PATH is defined by the framework)
Then declare as many datebox objects as needed:
<WebObject Class="datebox" Name="information_date"
value="{{#info_date}}"
format="YYYY-MM-DD"
onchange="check_selected_date(this)" />
<WebObject Class="datebox" Name="proposal_date" />
<WebObject Class="datebox" Name="contact_date" />
etc.
The attribute 'value' is used to initialize the datebox
with an initial value. If it is not given, then the
default is {{#{{#obj_name}}}} (in the last example above
it would be {{#contact_date}}).
The attribute 'format' is used to specify the format of the
date. The reckognized formats are:
YYYY-MM-DD (default)
MM/DD/YYYY
MM-DD-YYYY
DD/MM/YYYY
DD-MM-YYYY
Actually this is only the format of the display, because the
internal format is allways YYYY-MM-DD, the format used by
the databases. E.g. if the above datebox webobject is declared
inside a form with the name 'editDoc', then
"document.editDoc.information_date.value" returns the date in
the internal format (in the format YYYY-MM-DD).
The attribute 'onchange' (be carefull, all lowercase) is used
to call any validation function at the time that the date is changed.
If you pass 'this' as a argument to this function, then it
refers to the display format. E.g. if 'date' is the parameter to
which 'this' is passed, then "d = date.value;" gets the selected
date in the display format (which is specified by the attribute
'format'), and "date.value = d;" sets the date of the datebox
('d' should be in the format specified by 'format').
If you want to modify this webobject, you can copy it to a path
local to the application, modify it and use the modified copy, e.g.
<Include SRC="{{#./}}datebox/datebox.html" />
Bugs: When you change the date, the validation code of the "onchange"
is executed and it changes the date like this: "date.value = d;"
the internal value is not updated, so the value saved in the DB
is the selected one (which is wrong).
--- NEW FILE: dbTable.txt ---
WebObject 'dbTable' is used to display and edit the content
of a database table inside a page. It is used like this:
<Include SRC="{{#DBTABLE_PATH}}dbTable.html" />
<WebObject Class="dbTable" Name="offices"
table = "offices"
fields = "off_id,name"
where = "off_id < 10"
editable = "true"
selectable="true" />
The attribute 'table' is the name of the table that will be displayed.
If it is not specified, its default value is {{#obj_name}} (the value
of attribute 'Name').
The attribute 'fields' is the list of fields that will be displayed.
It is optional and its default value is "*" (all fields).
The attribute 'where' is the select condition for selecting the records.
It is optional and its default value is "" (all the records).
The attributes 'editable' and 'selectable' have default values of "false".
In this case the 'dbTable' behaves just like 'table'.
When 'editable' has a value "true", then the table is editable,
i.e. its records can be added, deleted or modified.
When 'selectable' has a value "true", then it is possible to select
a record from the displayed ones. The fields of the selected record
are declared as global template variables and can be used where they
are needed.
Since WebObject 'dbTable' behaves like 'table' when 'selectable' and
'editable' are "false", then there is no need to use 'table'. But it
is simpler than 'dbTable' and it can be easier to modify and customize
to fit the needs of a certain application.
--- NEW FILE: folderListing.txt ---
This box allows the browsing of a folder. It displays a list of
subfolders and files that are contained in the folder. It also
allows the user to browse the subfolders, to go to the parent folder,
to select a file, etc. The files that are displayed are those that
match a certain filter specified by the programmer.
The variables
-------------
The 'folderListing' box uses some state variables to keep its
state. Some of these variables can be changed or can be used by the
box (or application) that contains this web box. These variables are:
* folderListing->root
Contains the root folder. Should be initialized by the application
the first time that the web box is rendered, and can be changed by
the application at any time.
* folderListing->fileFilter
Contains an ereg expression that is used to filter the files that
are displayed. Should be initialized by the application the first
time that the web box is rendered. If it is not initialized by the
application, then it has a default value of ".*" (filter nothing).
* folderListing->currentPath
Contains the path from the root to the current folder.
* folderListing->selectedFile
Contains the name of the last file that was selected (clicked).
The events
----------
The 'folderListing' box raises some events and handles them internally.
These events can be used as well by the box or the application that
contains the 'folderListing'. These events are:
* folderListing.folder(folder_name)
Raised when a folder is clicked.
The box handles this by displaying the selected folder.
* folderListing.up()
Raised when the link to the parent folder is clicked.
The box displays the parent folder.
* folderListing.file(file_name)
Raised when a file is clicked.
The box doesn't change its view.
* folderListing.root()
Raised when the link to the root folder is clicked.
The box displays the root folder.
* folderListing.path(path)
Raised when the sensitive path is clicked.
The box displays the selected folder.
* folderListing.changeRoot(root_folder)
Raised from outside the box (from the application that uses it).
The box changes the root folder and displays it.
How to Use this Box
-------------------
Usually it can be used by including this line in the template that
contains it:
<Include SRC="{{#FOLDERLISTING_PATH}}folderListing.html" />
({{#FOLDERLISTING_PATH}} is declared by the framework itself)
In case that you want to change the layout of the webbox, then
you should copy the folder 'web_app/boxes/folderListing' from
the framework to some place in your application, then make changes
to it and include it like this:
<Include SRC="{{#folderListing_path}}folderListing.html" />
({{#folderListing_path}} must be declared by your application)
To change the layout of the webbox you can change the file
'folderListing.html' and the file 'folderListing.css'.
--- NEW FILE: form.txt ---
formWebObj is a webobject that makes easy the handling of big
forms (which have many inputs) and their data connection to the
database. It is used like this: when you have a webbox that
has a big form, in the PHP code of the webbox you include the
class 'formWebObj', and then inherit this class, instead of
inheriting 'WebObject' ('formWebObj' itself extends 'WebObject',
so this is OK). E.g.:
<WebBox ID="editProject">
<form name="bigForm">
. . . . . . . .
<!--# many <input>s, <select>s, etc. here #-->
. . . . . . . .
</form>
</WebBox>
----------------------------------------------
<?
include_once FORM_PATH."formWebObj.php";
class editProject extends formWebObj
{
. . . . . . . . . .
}
?>
----------------------------------------------
<?
class formWebObj extends WebObject
{
. . . . . . . . . . .
}
?>
Then, in the JS code of the webbox you can use these JS functions
which have been declared and included by the 'formWebObj':
getEventArgs(form);
/**
* Returns all the data in the inputs of the given form
* so that they can be sent as event args, e.g.
* GoTo("thisPage?event=editProject.save(" + getEventArgs(form) + ")");
*/
saveFormData(form);
/**
* Transmit the data of the form, so that
* the changed values are not lost.
* Must be called before GoTo().
*/
This is useful when the page is refreshed for some reason,
but you don't want to lose the values that are inputed in it.
There are also these two functions that are used internally by
'formWebObj', but you can use them as well, if you need them:
function getFormData(form)
//returns all the data filled in the given form
function setFormData(form, formData)
//fills the form with the given data
--- NEW FILE: leftMenu.txt ---
WebObject 'leftMenu' displays a menu, usually on the left side of the page.
It is used like this:
<Include SRC="{{#LEFTMENU_PATH}}leftMenu.html" />
<WebObject Class="leftMenu" Name="su"
items="{{#./}}su_menu_items.php" />
The attribute 'items' is a PHP file that contains the items of the menu,
like this:
<?
/**
* The $menu_items array contains the items of the leftMenu.
*/
$menu_items = array(
"item1" => " Menu Item 1 ",
"item2" => " Menu Item 2 ",
"item3" => " Menu Item 3 ",
"etc1" => " . . . ",
"etc2" => " . . . "
);
?>
The item of the menu that is selected can be retrieved like this:
$selected = WebApp::getSVar("leftMenu::su->selected_item");
If you need to change the look of the leftMenu, then make a local
copy and modify 'leftMenu.css'.
--- NEW FILE: listbox.txt ---
The WebClass "listbox" is used to display a list of values with the
<select> tag of HTML. These values are taken from a recordset (which
can be retrieved from DB or can be supplied by PHP code. The recodset
associated with the listbox must have two fields: 'id' and 'label'.
'label' is the field displayed, and 'id' is the value that is selected,
saved in DB and retrieved from DB.
Recordset example:
<Recordset ID="listbox::country">
<Query>
SELECT country_id AS id, country_name AS label
FROM countries
</Query>
</Recordset>
Usage example:
<Include SRC="{{#LISTBOX_PATH}}listbox.html" />
<WebObject Class="listbox" Name="country"
rs = "rs_id"
onchange = "alert(this.options[this.selectedIndex].text)"
width = "---------------" />
The attribute "rs" is optional. Its default value (if not specified) is
{{#obj_id}} (in the example above, it would be 'listbox::country').
The attribute "onchange" (all lowercase), is optional and is used as
the "onchange" attribute of the <select> tag.
The attribute "width" is also optional; it is used as the last line of the
list, in order to keep the width of the <select> to a certain size, and
can also be used as a "nothing selected" (none of the above) value.
This WebClass uses a <select> tag like this:
<select name="{{#obj_name}}" onchange="{{#onchange}}">
. . . . .
</select>
So, this should be kept in mind when accessing the selected value
and when giving an initial value.
If the 'listbox' is used inside a 'formWebObj' webbox, then it
takes care of it automatically.
--- NEW FILE: table.txt ---
WebObject 'table' is used to display the content of a table inside a page.
It is used like this:
<Include SRC="{{#TABLE_PATH}}table.html" />
<WebObject Class="table" Name="offices"
table="offices"
fields="off_id,name"
where="off_id < 10" />
If attribute 'table' is the name of the table that will be displayed.
If it is not specified, its default value is {{#obj_name}} (the value
of attribute 'Name').
The attribute 'fields' is the list of fields that will be displayed.
It is optional and its default value is "*" (all fields).
The attribute 'where' is the select condition for selecting the records.
It is optional and its default value is "" (all the records).
--- NEW FILE: tabs.txt ---
WebObject 'tabs1' displays a horizontal menu. It is used like this:
<Include SRC="{{#WEBOBJ_PATH}}tabs/tabs1.html" />
<WebObject Class="tabs1" Name="su"
items="{{#./}}su_menu_items.php" />
The attribute 'items' is a PHP file that contains the items of the menu,
like this:
<?
/**
* The $menu_items array contains the items of the tabs1.
*/
$menu_items = array(
"item1" => " Menu Item 1 ",
"item2" => " Menu Item 2 ",
"item3" => " Menu Item 3 ",
"etc1" => " . . . ",
"etc2" => " . . . "
);
?>
The item of the menu that is selected can be retrieved like this:
$selected = WebApp::getSVar("tabs1::su->selected_item");
If you need to change the look of the tabs1, then make a local
copy and modify 'tabs1.css'.
WebObject 'tabs2' is very similar to 'tabs1', but the styles are
different. It has a tab-like view.
WebObject 'tabs3' is very similar to 'tabs2', but it is vertical
instead of horizontal. It usually stays on the left of the page.
ToDo: It is better to have just one WebClass: 'tabs', and then
add another attribute, 'style', which will determine the
style of the tabs (horizontal, vertical, etc.).
--- NEW FILE: xlistbox.txt ---
'xlistbox' is a multiple listbox (or extended listbox, or hierarchical
list) webclass. It consists of several listboxes that depend on each-other
hierarchically, so that when the selection changes in one of them, the
content of the list that depends on it is refreshed to reflect the change.
It is used like this:
<WebObject Class="xlistbox" Name="office"
mainlist="true"
sublist="department"
onchange="alert(this.options[this.slectedIndex].text)" />
<WebObject Class="xlistbox" Name="department"
sublist="users"
onchange="alert(this.options[this.slectedIndex].text)" />
<WebObject Class="xlistbox" Name="user"
onchange="alert(this.options[this.slectedIndex].text)" />
The 'mainlist' attribute, when it is true, tells that this is the first
list in the group and it is not dependent of any other list. Its default
value is 'false'.
The 'sublist' attribute tells which is the list that depends on this one,
i.e. the list that is refreshed when the selection of this list is changed.
The last list of the group has no 'sublist' attribute.
The 'onchange' attribute contains the JS code that should be executed when
the content of the list changes. It is optional (can be ommitted).
Each xlistbox is connected with a recordset whith ID "xlistbox::obj_name".
The fields of these recordsets are (id, label) for the main xlistbox of
the group, and (master_id, id, label) for the other lists of the group.
E.g.:
<Recordset ID="xlistbox::office">
<Query>
SELECT off_id AS id, name AS label
FROM offices
</Query>
</Recordset>
<Recordset ID="xlistbox::department">
<Query>
SELECT off_id AS master_id, dept_id AS id, name AS label
FROM departments
</Query>
</Recordset>
<Recordset ID="xlistbox::user">
<Query>
SELECT department AS master_id, user_id AS id, username AS label
FROM users
</Query>
</Recordset>
'master_id' must be the same as the 'id' of the list above. When the
selection of the list above is changed, then the list is refilled with
all the items of the recordset that have master_id equal to the selected
id of the list above.
There can be any number of lists in a group. It is limited only by
performance reasons, e.g. if there are 4 or 5 lists in a group, then
the size of the data that is retrived from DB and immbeded in JS code
may be too big and it may increase the size of the page.
When there is only the main list, it behaves just like a 'listbox', and in
this case it would be better to use a 'listbox' object instead of a
'xlistbox' object, since it is more efficient.
If you want to init the lists with some values, you can add this JS code
after the </form> is closed:
<script language="javascript">
var form = document.userdata;
xlistbox_select(form.office, '{{#office}}');
fill_sublist(form.department, '{{#office}}', '{{#department}}');
fill_sublist(form.user, '{{#department}}', '{{#user}}');
</script>
The mainlist usually doesn't need to be initialized, because it is
initialized itself, but if it doesn't then it can be initialized
using: xlistbox_select(mainlist, id). The sublists can be initialized
using: fill_sublist(sublist, master_id, id).
Note: saveFormData() (of a 'formWebObj' webbox) doesn't work very well
with 'xlistbox' webobjects. Usually it collects all the data of
the form, transmits them and then redistributes them in the form,
so that they are not lost, even though they are not saved in DB.
For 'xlistbox' webobjects it can save and redisplay only the value
of the mainlist.
|
