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.

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