CS 540 Assignment #3

CS 549, Spring 2008

Assignment #3
(total = 20 pts., due on April 21, Wednesday)

You may work on this assignment as a group. If anything does not work as described here, notify the instructor immediately.

Part I: Checking Out the WebGen Environment (0 pts.)

From now on, you may periodically update the files checked out from the CVS repository by issuing the following commands. If any WebGen command fails, do this first.

  cd ~/public_html/ms_apps
  cd framework_v3
  cvs up -d
  cd ../web_gen
  cvs up -d
  cd ../treeview
  cvs up -d
  cd ../app_skeleton
  cvs up -d
  cd ../fishing_v2
  cvs up -d

The skeleton of a WebGen application can be copied as follows:

      cd ~/public_html/ms_apps
      cp -pr app_skeleton xxxx  # xxxx is application name
      cd xxxx
      find  . -name  CVS -type d | xargs rm -r   # remove CVS directories
      cd forms
      emacs datasource.php      # specify database source

These steps can be found in file ms_apps/app_skeleton/build_scripts/webgen_build.howto. Some details on these steps are explained below.

Copy the skeleton of an application to a new application directory ms_apps/xxxx, where xxxx is an application name such as garage_sale, with command
```
  cd ~/public_html/ms_apps
  cp -r app_sketeton xxxx
```
Then delete the CVS directories with commands
```
  cd xxxx
  find ./ -name CVS -type d | xargs rm -r
```

Another way to obtain such a copy of ms_apps/app_skeleton that is not registered in the CVS repository is to execute the following CVS command:

  cd ~/public_html/ms_apps
  mkdir xxxx                   # creat application directory
  cd xxxx
  cvs export -D '2008-01-25' ms_apps/app_skeleton  # use today's date
  mv ms_apps/app_skeleton/* .  # move copied files to current directory
  rm -r ms_apps/app_skeleton   # remove empty directories

Edit manually the forms/datasource.php file so that it provides correct database connection parameters as

    $Database_Host = "localhost";
    $Database_Name = "garage_sale";
    $Database_User = "cs540";
    $Database_Password ="CSxyz540";
    $Database_Type = "PgSQL";             // PgSQL or MySQL

Part II: Testing the WebGen Environment (0 pts.)

Part III: Automatic Generation of a Web-Based GIS/Database Interface (10 pts.)

In this part, you will generate a Web interface for database grarage_sale or fishing_v2.

The Web-based database interface can be created with WebGen according to the following steps given in file ms_apps/app_skeleton/build_scripts/webgen_build.howto:

cd ~/public_html/ms_apps
cp -pr app_skeleton my_fishing_v2   // application is my_fishing_v2
cd my_fishing_v2
find  . -name  CVS -type d | xargs rm -r   # remove CVS directories

cd forms
emacs datasource.php   # specify database source
emacs master.mconfig   # specify options applicable to every category

psql -U cs540 fishing_v2
fishing_v2> \i data_admin2/create_data_admin_tables.sql
fishing_v2> \q

cd build_scripts
php categorygen.php category_name_1, category_name_2, category_name_3, ...
emacs ../categories_tables.config  // specify tables in each category

php create_build_scripts.php
# Options specified in master.mconfig are not specified in
# each .mconfig file generated. However, those options can be overridden
# if the same options are specified in the .mconfig file.

php execute_build_scripts.php

In the following these steps are explained.

Edit manually the forms/master.mconfig file which is a shared meta-configuration file. The options specified in master.mconfig are used in generating each table-specific .config file. Those options, however, can be overwritten by the options specified in the table-specific .mconfig file.
Execute in forms/build_scripts,
```
  php categorygen.php category1 category2 category3 ...
```
After checking accessibility of the database, this categorygen.php generates file forms/categories_tables.config, which lists each category and possible tables in it. Possible tables are determined by their names. For example, any table that includes product as a substring of its name will be included in category product. for example, file categories_tables.config may constain an array declaration such as
```
  $categories_tables = array(
    'customer'=> array( 
      tables => array( customer, customer_order, customer_preference, ...), 
      tree_root_table => customer 
    ), 
    'supplier' => array(
      tables => array( supplier, supplier_contact, ...), 
      tree_root_table => city 
    ), 

      . . . 

    'other' => array(
      tables => array( donkey, unknown, ...), 
      tree_root_table => city 
    )
  );
```
Tables that cannot be put in any given category are put in category other.
Edit manually the categories_tables.config file to put all the tables in right categories.
Now execute in directory forms/build_scripts script create_build_scripts.php as
```
  php create_build_scripts.php
```
Based on the definitions provided in categoriy_tables.config, this script creates the following files.
1. Subdirectory forms/yyyy for each category yyyy.
2. Files mmconfgenAll.sh, mconfgenAll.sh, confgenAll.sh, layoutgenAll.sh, and webgenAll.sh in directory forms/yyyy for each category yyyy.
3. Files mmconfgenAllAll.sh, mconfgenAllAll.sh, confgenAllAll.sh, layoutgenAllAll.sh, webgenAllAll.sh in directory forms.
4. File forms/data_admin2/insert_d_data_admin_category.sql that contains the following SQL statement for each category yyyy:
```
INSERT INTO d_data_admin_category(display_value, tree_url)
  VALUES ('Yyyy','yyyy/zzzz_tree.phtml');
```
5. File forms/data_admin2/insert_data_admin_category_table.sql that contains the following SQL statement for each table zzz in category yyyy:
```
INSERT INTO data_admin_category_table
            (d_data_admin_category_id, data_admin_table_id)
  SELECT cat.d_data_admin_category_id, tab.data_admin_table_id
  FROM d_data_admin_category cat, data_admin_table tab
  WHERE cat.display_value = 'yyyy' AND tab.table_name = 'zzzz';
```
  This SQL statement associates each table zzzz with its category yyyy.
Execute execute_build_scripts.php as
```
  php execute_build_scripts.php
```
Inside this script, the following subscripts are executed.
1. create_data_admin_tables.sql, which creates tables d_data_admin_category, data_admin_table, and data_admin_category_table for data administration.
2. insert_d_data_admin_category.sql, which fills table d_data_admin_category with category names.
3. insert_data_admin_table.php, which fills table data_admin_table with the names of the tables in the database.
4. fill_dir.php, which fills for each table the directory column of table data_admin_table with the name of the directory where the scripts of that table are stored.
5. Scripts mmconfgenAllAll.sh, mconfgenAllAll.sh, confgenAllAll.sh, layoutgenAllAll.sh, webgenAllAll.sh in forms. These scripts execute scripts mmconfgenAll.sh, mconfgenAll.sh, confgenAll.sh, layoutgenAll.sh, and webgenAll.sh in directory forms/yyyy for each category yyyy.
6. You can explore the Data Administration page created at
```
http://nagara.een.orst.edu/eecs/~your-login-name/ms_apps/xxxx/forms/
data_admin2/index_top.php
```
  Please do not modify any data in the mail-order database.
Part IV: Regenerating Scripts for Individual Tables (5 pts.)
1. When a table zzzz is modified, you may reexecute the following commands.
```
  mmconfgen -f zzzz
  mconfgen  -f zzzz
  confgen   -f zzzz
  layoutgen -f zzzz
  webgen    -f zzzz
```
  However, once meta configuration file is manually modified for customization, do not execute mmconfgen or mconfgen from that point.
2. When WebGen templates are updated, you may execute confgenAll.sh, layoutgenAll.sh, and webgenall.sh in a subdirectry in order to generate the .config, _layout.config, and .phtml files for the tables relevant for the subdirectory. Furthermore, you may regenerate all the Web scripts by executing confgenAllAll.sh, layoutgenAllAll.sh, and webgenAllAll.sh in forms to execute confgenAll.sh, layoutAll.sh, and webgenAll.sh in each subdirectory.
3. When new tables are added to the database, You can insert the entries for the newly created tables in table data_admin_table by executing the command:
```
  php insert_data_admin_table.php
```
  When the subdirectories for the Web scripts for tables are added or renamed, those subdirectories can be correctly registered in table data_admin_table with the command:
```
  php fill_dir.php
```
  If those subdirectories are not correctly registered, the forms cannot be opened from the Data Administration page. The PHP scripts above can be executed repeatedly.
4. You can manually link a table to a category by adding an entry in table data_admin_category_table as follows.
  1. Open
```
http://www.engr.orst.edu/~your-login/
     ms_apps/xxxx/forms/data_admin2/index_top.php
```
  2. Click the tree icon for category Data Administration to open the data administration treeview.
  3. Once the treeview for the data administration is opened, click the + icon to expand the Categories node.
  4. If you want to add a new category, right-click the Categories node. Specify the category to be created in the Insert D Data Admin Category page.
  5. Click the + icon to expand the node for a category to see the tables in that category.
  6. To link a table to a category, right-click the node for that category and select the Insert Link option. Specify the table to be linked in the Insert Data Admin Category Table page.
  7. Refresh the treeview.
5. Provide screenshots of forms for at least one table and the Data Admin treeview. The URLs must be recognizable. The data displayed must indicate that your scripts are connected to your database.
Part V: Improving Scripts for Category Configuration File Generation (10 pts.)
1. Create in forms/build_scripts script category_mconfgen.php by modifying categorygen.php. This script is executed as
```
  php category_mconfgen.php department student course
```
  After checking accessibility of the database, this script generates file categories_tables.mconfig such as
```
  $categories_patterns = array(
    'department' => array('.*department.*'),
    'student'    => array('.*student.*'),
    'course'     => array('.*course.*'),
  );
```
  File categories_tables.mconfig lists each category and the regular expressions for the tables to be put in that category. If we want to add every table whose name contain student, country, or language to category student and every table that contain course or sesion to category course, we can edit categories_tables.mconfig as
```
  $categories_patterns = array(
    'department' => array('.*department.*'),
    'student'    => array('.*student.*', '.*country.*', '.*language.*'),
    'course'     => array('.*course.*', '.*session.*'),
  );
```
2. Create script category_confgen.php by modifying categorygen.php. This script generates categories_tables.config from categories_tables.mconfig when executed as
```
  php category_confgen.php
```

Part I: Checking Out the WebGen Environment (0 pts.)

Part II: Testing the WebGen Environment (0 pts.)

Part III: Automatic Generation of a Web-Based GIS/Database Interface (10 pts.)

Part IV: Regenerating Scripts for Individual Tables (5 pts.)

Part V: Improving Scripts for Category Configuration File Generation (10 pts.)