1 - Transitions

A very simple application that has 2 or 3 HTML files which have transitions to each-other and have some links to external pages. Explains what are the transitions and the difference between the transitions and the links. Explains how to debug transitions.


Test Browse Download

Table of Contents


Transitions by Goto

The phpWebApp thinks of a web application as a state machine, where each state is a web page. Each time the browser loads something new in its window, you see a snapshot of the application in a certain state. Transitions from one state (page) of the application to another are done by using the javascript function GoTo('page.html'). This function is declared by the framework itself and is included automatically at the head of each page of the application. The parameter given to GoTo() is the target page, i.e. the next page that will be displayed by the framework.

In real applications, usually the link calls a JavaScript function, and this function makes the transition by calling GoTo(). So, the application has a chance to make any error checkings, input data validations etc. before making the transition to the other page.

See the code of the first page and notice how the GoTo() is used.
If you have not tested the application yet, please test it now and pay attention to how the GoTo() is used.

TOC

External Pages

The external pages are HTML pages that are outside the application. They are linked as usually in HTML, without using transitions and the function GoTo(). These pages are not part of the application, they are either plain HTML pages or pages of other applications.

While in an external page, you cannot go back to a page of the application by using the function GoTo() because it is undefined. You can only go back to the same page of the application from which you got out by pressing the button back in the browser (or calling the JS function history.back()).

If you open a page of the application by linking (as an external page), not by a GoTo() transition, then it will not behave as a page of the application (because the GoTo() function and other framework related things are not included in it).

See an example of linking to external pages.

TOC

The Structure of the Application

Each application build with phpWebApp framework must have some files that are required by the framework. Besides them it should also have its own files. The required files are almost the same for every application. The application files and folders are created by the application developer and they are different for each application.

If you have not yet browsed the application, then browse it now.

The files required by the framework are:

  config/                 -- configuration files for the application
      const.Paths.php     -- constants of paths used in the application
      const.Options.php   -- constants that change the behaviour of the app
      const.Debug.php     -- constants that are used for debugging the app

  index.php               -- standart framework file
  webapp.php              -- standart framework file

The application files and folders are:

    img/
        back.png
        home.png
        state_diagram.png
    page1.html
    page2.html
    page3.html
    styles.css

The file browse.php is not required by the framework and is almost the same for each application. It is usually used during the development of the application to preview how the templates and weboxes look like. The file external_page.html does not belong neither to the framework nor to the application; it just happens to be in the folder of the application.

The files index.php and webapp.php are the same for each application, you don't need to modify them and usually they should not be touched. In the config files, there are three constants that must be set for each new application, and the rest of them are optional. These constants are: WEBAPP_PATH and TPL_PATH in const.Paths.php, and FIRSTPAGE in const.Options.php

TOC

Exerxises

To be able to try the exercises you have to instal the framework and the sample applications in your computer or somewhere where you can make changes.

1 - Create a new application

In this exercise you will create another application which is identic with app1 but has a different name, app1_test. Follow these steps:

  1. Copy the folder app1 to the folder app1_test:
    $ cp -R app1 app1_test
  2. That was all, open the application /app1_test/ in browser to test it. It should work.

2 - Move an application to another location

In this exercise you will move the application app1_test to test/app1_test.

  1. Create the folder test and move app1_test to it:
    $ mkdir test
    $ mv app1_test test
  2. Edit the file test/app1_test/config/const.Paths.php so that the constant WEBAPP_PATH is set to UP_PATH."../web_app/".
  3. Open the application /test/app1_test/ in browser to test it; it should work.

WEBAPP_PATH is the path of the phpWebApp framework and tells the application where to find the framework. This constant is used by the file webapp.php to include the framework classes and modules. The constant UP_PATH which is defined in webapp.php, contains the parent folder of the application (app1_test) folder.

In this example it is set as a relative path, but it can be set as an absolute path as well, e.g. /var/www/html/web_app/ (or c:/www/html/web_app/ for Windows). In this case you don't have to wory about changing it when moving an application to another location.

3 - Debugging Transitions

  1. Edit the file config/const.Debug.php and set the constant DEBUG_GOTO to true.
  2. Test the application and notice that each time that you make a transition you get an alert about it.

4 - Add a New Page to the Application

  1. Copy page1.html to page4.html and change its title and content to Page 4.
    $ cd test/app1_test
    $ cp page1.html page4.html
  2. Change the links at the bottom of the pages to link to page4.html as well. You should link to it using the GoTo() function.
  3. Test it.

5 - Set the initial page of the application

  1. Open the file config/const.Options.php and set the FIRSTPAGE variable to page2.html.
  2. Test the application and press the Home button.

6 - Put the pages in another folder

In this exercise you will put all the pages of the application in another folder.

  1. Create a new folder named pages:
    $ mkdir pages
  2. Move all the pages to this folder:
    $ mv page*.html pages
  3. Open the file config/const.Paths.php and set the constant TPL_PATH to APP_PATH."pages/".
  4. Test the application. It should work.

The constant TPL_PATH tells to framework where to look for the pages (in the phpWebApp jargon pages are called templates because they may contain variables and other extra tags that are reckognized by the framework). When you write GoTo('page1.html'), the framework looks for page1.html in the TPL_PATH. The constant APP_PATH is a predefined constat and it contains the path of the application itself.

By convention, the names of the path constants have a _PATH extension at the end, e.g. MENU_PATH, TUTORIAL_PATH, etc. They represent paths in the server, e.g. TPL_PATH may have the value: /var/www/html/test/app1_test/pages/. Their value always has a slash / at the end (by convention).

Another kind of constants used in the framework, the URL constants, represent paths in the application starting from the DocumentRoot (the part of the URL comming after the server name and before the file name). By convention, they end with an _URL and their value ends with a slash /. E.g. IMG_URL, JS_URL, etc.

TOC

Experiments and questions

Try to do these experiments and to answer these questions.

  1. Move the external_page.html to the folder pages and see whether the link to it works. How you should change this link to make it work?
  2. Move the stylesheet styles.css to the folder pages and see whether it works. What changes you can do to make the application find the stylesheet?
  3. Rename the folder img to images. What changes you can do to make the application work?



TOC