PHPlus - Quick Usage


Section 1. -- Understanding the basic concept

first of all you need to understand the concept of the phplues framework; infact it's very simple.
phplus seperates the web page design and the application logic (which is used to manipulate the web page).
so obviously you need 2 main components: the web page and the manipulation file (presentation class).

1. the web page
this is a pure html page, having 'id' attributes in html tags which need to be manipulated.
eg. <a href="" id="Link1"></a>   this link address and link text can be dynamically set in the presentation class by refering to its id "Link1".
eg.   <span id="Message1"></span>   this can be used to dynamically display text on the page.
eg.   <tr id="TableRow1">     this can be used to dynamically populate a table on the web page.

2. the Presentation Class
this is a normal php class, which implements a particular interface.each web page you have, should have a corresponding presentation class. the filename and the class name inside should be the same. (Tip: the simplest way of writing this presentation class is to copy the TemplatePresentation.php in htdocs/welcome/presentation) and modify it.)
you can manipulate the web page in anyway you want from the presentation class. there are a lot of methods available for manipulating web pages, and they can be found in the DomHTML API reference document.

there's one more thing we need to know. the Presentation class cannot directly manipulate the web page. so we need to first convert the web page into an intermediate file. but don't worry; it can be directly generated using the xmlcplus tool (parser) that comes with the framework. It's done like this;

# xmlcplus mywebpage.htm      will generate the intermediate file "mywebpageHTML.php"

You can get a better understanding of the workflow in PHPlus by looking at this diagram -> PHPlus-WorkFlow


Section 2. -- Putting it all together (the 'welcome' application)

now lets see how to put all these pieces together to make an application.
the simplest way to understand this is to take a look at the sample 'welcome' project. (in /usr/local/apache2/htdocs/welcome). you need to understand the important files and directories that make up a web application in phplus framework. ( assume your apache web-root is /usr/local/apache2/htdocs )

application home eg.  htdocs/welcome This is the application home. your applications should have something like htdocs/myapp1.
'resources' directory eg.  welcome/resources This folder should have all the files generated by the xmlcplus parser . (these files will be something like mywebpageHTML.php)
'presentation' directory eg.  welcome/presentation This folder shold have the presentation files (php files in whcih you write your application logic). you can find a template presentation file (TemplatePresentation.php) in welcome/presentaion directory.
receiver.php eg.  welcome/receiver.php This file is the main controller of any application. (you need to have this in the home path of every application you write) eg.  welcome/ this configuration file stores details about the framework path, appplication path, default web page etc. you need to set the correct path info here.

having got the basic idea of the sample 'welcome' application, lets try to run it.
type   http://localhost/welcome/receiver.php   in your web browser. you should see the welcome page (hopefully..). (refresh the browser to see the time on the page change dynamically.)


Section 3. -- Other important points to remember

1. web page links
all links to other pages of the application should be in the form
    receiver.php?page=MySecondPage       -- when there exists a presentation class named "MySecondPage.php".
eg.   <a href="receiver.php?page=MySecondPage">go to second page</a>

2. images or javascript (or any other) folders
all source links on web pages should be relative to the application home directory.
eg.   <img src="images/mypic1.jpg">    -- mypic1.jpg should be in   <application-home>/images/mypic1.jpg
eg.   <script src="scripts/rollover.js">     -- rollover.js should be in <application-home>/scripts/rollover.js

3. web forms
some special actions are needed when using web forms. They are as follows;
* always set the 'action' attribute of web forms to 'receiver.php'.
* always add a hidden 'INPUT' tag with name='page' and value='your-target-presentation-class'
(also it is recommended that all web forms use the "POST" method.)
eg.   <form name="MyForm1" action="receiver.php" method="POST">
              <input type="hidden" name="page" value="ProcessForm">      
               ....    ....    ....
               ....    ....    ....
(where "ProcessForm.php" presentation class is the target of the web form)