Thread: [phpwebapp-commits] CVS: web_app/doc changes_4.txt,NONE,1.1 xhtml_template_specification.txt,1.4,1.5

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/phpwebapp/web_app/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19835/doc

Modified Files:
	xhtml_template_specification.txt tasks.txt changes.txt 
	ToDo.txt 
Added Files:
	changes_4.txt 
Log Message:

--- NEW FILE: changes_4.txt ---
phpwebapp-1.1

Changes made to the application framework
that the framework users should know:
===========================================

-------------------------------------------------------------------

* Parsing is done using an XML parser.  This means that some 
  restrictions that were due to the previous parser, now are removed.
  Such improvments are:

  - The names of the framework tags and their attributes now are
    case insensitive (however lowercase is recommended, according
    to XHTML standards).

  - The framework comments can be like this: <!--#Comment .... -->.
    The empty space after the first diesis is not requried anymore,
    and the ending diesis (#-->) can be omitted.

  - The closing and ending tags are not required to be in separate
    lines anymore.  E.g. something like this is ok:
      <if condition="..."> ... </if>
    Previously it was required to be like this:
      <If contition="...">
        ...
      </If>

  - Templates are now required to be XHTML code, otherwise the
    parser will not parse them successfully.

-------------------------------------------------------------------

* The main (root) template should start like this:

    <?xml version="1.0" encoding="iso-8859-1"?>
    <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
              "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    <html xmlns="http://www.w3.org/1999/xhtml" lang="EN">

  because if no DOCTYPE is defined, the parser will have problems
  with reckognizing entities (&nbsp; &amp; etc.), and there may
  be any other problems as well.

  For the other templates, however, these headers shoud not be
  added, because the parser will add them automatically to them,
  so that they become well-formed xml and are parsed successfully.
  The headers that will be added to the other templates will be
  a copy of the headers of the main template.

-------------------------------------------------------------------

* <Repeat> syntax changed.

  There was a problem with the <Header>/<Footer> tags, because the
  contents of the <Header> usually is not well-formed xml and
  it breaks the parser. E.g. it may be something like this:
      <repeat rs="rs_id">
        <header>
          <table>    <---- not well-formed XML
        </header>
            <tr><td>{{xyz}}</td></tr>
        <footer>
          </table>
        </footer>
      </repeat>

  In order to solve this, <Header> and <Footer> tags were removed at all.
  Now it can be done like this (which is well-formed xml):
      <table>
        <repeat rs="rs_id">
          <tr><td>{{xyz}}</td></tr>
        </repeat>
      </table>

  For the case of paged recordsets, when we need the navigation variables
  (to get the next page, previous page, etc.) a new framework tag was added:
      <RSNavig rs="paged_rs_id"> ... </RSNavig>

  The tags <IfEmpty>, <Separator> and the dummy tag <RepeatBody> can be
  used the same as before. 

-------------------------------------------------------------------

* This is wrong: <If condition="'{{CurrPage}}'<>'{{PrevPage}}'">
  This is right: <If condition="'{{CurrPage}}'!='{{PrevPage}}'">
  because the xml parser complains about the characters < and >
  inside the value of an attribute.

-------------------------------------------------------------------

* In order to put a check in a checkbox according to the value of
  some state variable, framework used something like this:
     <input type="checkbox" name="all_books" {{all_books}} 
            onclick="set_chkbox(this)>
  where the variable {{all_books}} has a value of 'checked' or ''.

  This is not well-formed XHTML and it breaks the xml parser,
  because, instead of {{all_books}} the parser expects an attribute
  name and value.

  In XHTML this attribute should be used like this: checked="checked".
  However, doing it like this: 
     <input type="checkbox" name="all_books" checked="{{all_books}}" 
            onclick="set_chkbox(this)>
  would not solve the problem, because the browser will check the
  checkbox no matter what is the value of the checked attribute;
  the presense of the 'checked' attribute is enough for the browser
  to check the checkbox.

  In order to solve this problem, the framework, when it renders the
  HTML page, replaces 'checked=""' with empty (removes it).
  It also removes: checked="no" and checked="false".  On the other hand,
  it replaces checked="yes" and checked="true" by checked="checked",
  so that the output complies with XHTML.

  The same thing is done for: selected="selected", selected="",
  selected="yes", selected="no", selected="true" and selected="false".

-------------------------------------------------------------------

* Added the tag <example>.  It can be used like this:

<example style="border: 1px solid #eeeeee;">  test
  <b>test</b>
  {{test}}
  <Include SRC="{{content_html}}" />
</example>

  It is converted by the framework to an <xmp> element, like this:

<xmp style="border: 1px solid #eeeeee;">  test
  <b>test</b>
  {{test}}
  <Include SRC="{{content_html}}" />
</xmp>

  The content of the element is copied verbatim, no variable replacement
  or other processing is done.  Even the white-space is preserved and
  the overall indentation of the generated page does not touch the
  original indentation of this element.

  Also, the framework preserves the original white-space and indentation 
  for the xhtml tags <pre> and <xmp>, however their contents are processed
  for template variables and framework tags.

-------------------------------------------------------------------

* When switching an existing web application to the new version 
  of the framework (with the xml parser), these modifications 
  need to be done to the templates:

  1 - Find and remove all <Header> and <Footer> tags and place their
      contents outside the <Repeat> element.  In case that the 
      recordset of the <Repeat> is a paged recordset and page variables
      ({{PrevPage}}, {{NextPage}} etc.) are used for navigation, 
      then put the navigation part of the template inside the element
      <RSNavig>.

  2 - Replace 'not-equal operator' <> by !=, in the condition of <If>
      elements: <If condition="'{{CurrPage}}'<>'{{PrevPage}}'">
      If there is any 'smaller-than' operator < in attribute values,
      replace it by &amp;lt;.  If it is in the contents of an element
      (e.g. in the contents of a <Query> element), then either replace
      it by &lt; or enclose the query inside <![CDATA[...]]>, like
      this: <Query><![CDATA[ . . . ]]></Query>

  3 - Replace the old usage of 'checked' in checkboxes with the new
      usage; replace {{checked_var}} with checked="{{checked_var}}".
      Do the same for the 'selected' attribute of the listboxes:
      replace {{selected_var}} with selected="{{selected_var}}"

  4 - Convert all the templates to clean XHTML code (convert all tags
      and attributes to lowercase, replace <img...> by <img ... />,
      etc.).  Maybe 'tidy' can be used for this, however sometimes 
      it does not produce the desired results (because of the framework
      tags).

  5 - Add these lines at the beginning of the root templates:
        <?xml version="1.0" encoding="iso-8859-1"?>
        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
        <html xmlns="http://www.w3.org/1999/xhtml" lang="EN">

  6 - Each xml parser is required to process the entities: &amp; &lt;
      &gt; &quot; and &apos; and to return the corresponding character
      instead of the entity itself. So, it is neccessary to replace
      in the templates all the xml builtin entities, like this: 
        &amp;  --> &amp;amp;
        &lt;   --> &amp;lt;
        &gt;   --> &amp;gt;
        &quot; --> &amp;quot;
        &apos; --> &amp;apos;

-------------------------------------------------------------------

* Some conversion scripts are added (in the forlder web_app/convert/),
  in order to automate most of the modifications to the templates.
  Read web_app/convert/README.

-------------------------------------------------------------------

Index: xhtml_template_specification.txt
===================================================================
RCS file: /cvsroot/phpwebapp/web_app/doc/xhtml_template_specification.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** xhtml_template_specification.txt	13 Jul 2004 16:15:20 -0000	1.4
--- xhtml_template_specification.txt	29 Jul 2004 07:58:16 -0000	1.5
***************
*** 6,10 ****
  ==========
    <!--# Comments are denoted like this #-->
-   <!--# diesis at the beginning, diesis at the end #-->
    <!--#
      Such comments are not included
--- 6,9 ----

Index: tasks.txt
===================================================================
RCS file: /cvsroot/phpwebapp/web_app/doc/tasks.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** tasks.txt	13 Jul 2004 13:18:08 -0000	1.4
--- tasks.txt	29 Jul 2004 07:58:16 -0000	1.5
***************
*** 4,19 ****
  ========================================================

- + 1 - Automatic Documentation
- 
- 2 - Implement Template Merge/Separator Tool
- + 3 - Find HTML Reformater Tool (tidy)
- + 4 - Improve the Output of the Framework to be Regular HTML
- 
- 5 - Parse and the templates using an XML parser.
- 
- 6 - Corrections in WebBoxes and WebClasses.
- 
- - 7 - Page and Component Caching.
- 
  8 - Improvments in DB Component.
      + class.OracleCnn.php etc
--- 4,7 ----
***************
*** 24,34 ****
  9 - Misc (small changes)
      + WebApp::GoTo()
!     + Improve Error Handling and Multiple Language Support
!       for Framework Messages. 
!     + formWebObject
!     + etc
! 
! 10 - Apply the improvements in framework to the "documentation" 
!      project.

  11 - Update and improve the model of the framework 
--- 12,16 ----
  9 - Misc (small changes)
      + WebApp::GoTo()
!     + Multiple Language Support for Framework Messages. 

  11 - Update and improve the model of the framework 

Index: changes.txt
===================================================================
RCS file: /cvsroot/phpwebapp/web_app/doc/changes.txt,v
retrieving revision 1.9
retrieving revision 1.10
diff -C2 -d -r1.9 -r1.10
*** changes.txt	23 Jul 2004 10:17:07 -0000	1.9
--- changes.txt	29 Jul 2004 07:58:16 -0000	1.10
***************
*** 5,201 ****

  -------------------------------------------------------------------
! 
! * Parsing is done using an XML parser.  This means that some 
!   restrictions that were due to the previous parser, now are removed.
!   Such improvments are:
! 
!   - The names of the framework tags and their attributes now are
!     case insensitive (however lowercase is recommended, according
!     to XHTML standards).
! 
!   - The framework comments can be like this: <!--#Comment .... -->.
!     The empty space after the first diesis is not requried anymore,
!     and the ending diesis (#-->) can be omitted.
! 
!   - The closing and ending tags are not required to be in separate
!     lines anymore.  E.g. something like this is ok:
!       <if condition="..."> ... </if>
!     Previously it was required to be like this:
!       <If contition="...">
!         ...
!       </If>
! 
!   - Templates are now required to be XHTML code, otherwise the
!     parser will not parse them successfully.
! 
! -------------------------------------------------------------------
! 
! * The main (root) template should start like this:
! 
!     <?xml version="1.0" encoding="iso-8859-1"?>
!     <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
!               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
!     <html xmlns="http://www.w3.org/1999/xhtml" lang="EN">
! 
!   because if no DOCTYPE is defined, the parser will have problems
!   with reckognizing entities (&nbsp; &amp; etc.), and there may
!   be any other problems as well.
! 
!   For the other templates, however, these headers shoud not be
!   added, because the parser will add them automatically to them,
!   so that they become well-formed xml and are parsed successfully.
!   The headers that will be added to the other templates will be
!   a copy of the headers of the main template.
! 
! -------------------------------------------------------------------
! 
! * <Repeat> syntax changed.
! 
!   There was a problem with the <Header>/<Footer> tags, because the
!   contents of the <Header> usually is not well-formed xml and
!   it breaks the parser. E.g. it may be something like this:
!       <repeat rs="rs_id">
!         <header>
!           <table>    <---- not well-formed XML
!         </header>
!             <tr><td>{{xyz}}</td></tr>
!         <footer>
!           </table>
!         </footer>
!       </repeat>
! 
!   In order to solve this, <Header> and <Footer> tags were removed at all.
!   Now it can be done like this (which is well-formed xml):
!       <table>
!         <repeat rs="rs_id">
!           <tr><td>{{xyz}}</td></tr>
!         </repeat>
!       </table>
! 
!   For the case of paged recordsets, when we need the navigation variables
!   (to get the next page, previous page, etc.) a new framework tag was added:
!       <RSNavig rs="paged_rs_id"> ... </RSNavig>
! 
!   The tags <IfEmpty>, <Separator> and the dummy tag <RepeatBody> can be
!   used the same as before. 
! 
! -------------------------------------------------------------------
! 
! * This is wrong: <If condition="'{{CurrPage}}'<>'{{PrevPage}}'">
!   This is right: <If condition="'{{CurrPage}}'!='{{PrevPage}}'">
!   because the xml parser complains about the characters < and >
!   inside the value of an attribute.
! 
! -------------------------------------------------------------------
! 
! * In order to put a check in a checkbox according to the value of
!   some state variable, framework used something like this:
!      <input type="checkbox" name="all_books" {{all_books}} 
!             onclick="set_chkbox(this)>
!   where the variable {{all_books}} has a value of 'checked' or ''.
! 
!   This is not well-formed XHTML and it breaks the xml parser,
!   because, instead of {{all_books}} the parser expects an attribute
!   name and value.
! 
!   In XHTML this attribute should be used like this: checked="checked".
!   However, doing it like this: 
!      <input type="checkbox" name="all_books" checked="{{all_books}}" 
!             onclick="set_chkbox(this)>
!   would not solve the problem, because the browser will check the
!   checkbox no matter what is the value of the checked attribute;
!   the presense of the 'checked' attribute is enough for the browser
!   to check the checkbox.
! 
!   In order to solve this problem, the framework, when it renders the
!   HTML page, replaces 'checked=""' with empty (removes it).
!   It also removes: checked="no" and checked="false".  On the other hand,
!   it replaces checked="yes" and checked="true" by checked="checked",
!   so that the output complies with XHTML.
! 
!   The same thing is done for: selected="selected", selected="",
!   selected="yes", selected="no", selected="true" and selected="false".
! 
  -------------------------------------------------------------------
- 
- * Added the tag <example>.  It can be used like this:
- 
- <example style="border: 1px solid #eeeeee;">  test
-   <b>test</b>
-   {{test}}
-   <Include SRC="{{content_html}}" />
- </example>
- 
-   It is converted by the framework to an <xmp> element, like this:
- 
- <xmp style="border: 1px solid #eeeeee;">  test
-   <b>test</b>
-   {{test}}
-   <Include SRC="{{content_html}}" />
- </xmp>
- 
-   The content of the element is copied verbatim, no variable replacement
-   or other processing is done.  Even the white-space is preserved and
-   the overall indentation of the generated page does not touch the
-   original indentation of this element.
- 
-   Also, the framework preserves the original white-space and indentation 
-   for the xhtml tags <pre> and <xmp>, however their contents are processed
-   for template variables and framework tags.
- 
  -------------------------------------------------------------------
-  
- * When switching an existing web application to the new version 
-   of the framework (with the xml parser), these modifications 
-   need to be done to the templates:
- 
-   1 - Find and remove all <Header> and <Footer> tags and place their
-       contents outside the <Repeat> element.  In case that the 
-       recordset of the <Repeat> is a paged recordset and page variables
-       ({{PrevPage}}, {{NextPage}} etc.) are used for navigation, 
-       then put the navigation part of the template inside the element
-       <RSNavig>.
- 
-   2 - Replace 'not-equal operator' <> by !=, in the condition of <If>
-       elements: <If condition="'{{CurrPage}}'<>'{{PrevPage}}'">
-       If there is any 'smaller-than' operator < in attribute values,
-       replace it by &amp;lt;.  If it is in the contents of an element
-       (e.g. in the contents of a <Query> element), then either replace
-       it by &lt; or enclose the query inside <![CDATA[...]]>, like
-       this: <Query><![CDATA[ . . . ]]></Query>
- 
-   3 - Replace the old usage of 'checked' in checkboxes with the new
-       usage; replace {{checked_var}} with checked="{{checked_var}}".
-       Do the same for the 'selected' attribute of the listboxes:
-       replace {{selected_var}} with selected="{{selected_var}}"
- 
-   4 - Convert all the templates to clean XHTML code (convert all tags
-       and attributes to lowercase, replace <img...> by <img ... />,
-       etc.).  Maybe 'tidy' can be used for this, however sometimes 
-       it does not produce the desired results (because of the framework
-       tags).
- 
-   5 - Add these lines at the beginning of the root templates:
-         <?xml version="1.0" encoding="iso-8859-1"?>
-         <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-                   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-         <html xmlns="http://www.w3.org/1999/xhtml" lang="EN">
- 
-   6 - Each xml parser is required to process the entities: &amp; &lt;
-       &gt; &quot; and &apos; and to return the corresponding character
-       instead of the entity itself. So, it is neccessary to replace
-       in the templates all the xml builtin entities, like this: 
-         &amp;  --> &amp;amp;
-         &lt;   --> &amp;lt;
-         &gt;   --> &amp;gt;
-         &quot; --> &amp;quot;
-         &apos; --> &amp;apos;
- 
- 
- -------------------------------------------------------------------
- 
- * Some conversion scripts are added (in the forlder web_app/convert/),
-   in order to automate most of the modifications to the templates.
-   Read web_app/convert/README.
- 
  -------------------------------------------------------------------
--- 5,12 ----

  -------------------------------------------------------------------
! * The tag <textarea> is treated as preformated (similar to <pre>,
!   <xmp> and <example>). This means that the indentation and the 
!   white-space of its contents are preserved by the framework.
  -------------------------------------------------------------------
  -------------------------------------------------------------------
  -------------------------------------------------------------------

Index: ToDo.txt
===================================================================
RCS file: /cvsroot/phpwebapp/web_app/doc/ToDo.txt,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** ToDo.txt	13 Jul 2004 13:18:08 -0000	1.6
--- ToDo.txt	29 Jul 2004 07:58:16 -0000	1.7
***************
*** 73,78 ****
      that helps when working with phpWebApp.
  -------------------------------------------------------------
- * - Parse and process the templates using an XML parser.
- -------------------------------------------------------------
  * - Parse and process the templates using a DOM XML parser.
  -------------------------------------------------------------
--- 73,76 ----
***************
*** 392,398 ****
    (actually 'browse' is implemented like a tool, or a webbox that
    is not totally independent from the application that it browses).
-   It may also be useful for "tidy", an application that rewrites
-   the templates of an egzisting application in XHTML format, with
-   good indentation etc. 
    It will also be useful for the WADE (Web Application Development 
    Environment), so that it is an independent application and 
--- 390,393 ----