CSCE-315: Programming Studio (Fall 2020)

Project 1: PHP-based Website

Due dates and updates

Here are the various due dates. See near the end for details (i.e., what you need to submit for each submission window.

  1. CSV file + Simplified Wikitext processor code (due 8/30 Sunday 11:59pm)
  2. Interactive gallery code (due 9/6 Sunday 11:59pm)
  3. Final version including search code + writing assignment (due 9/13 Sunday 11:59pm)

Any updated info about the project will also be posted here.

  1. 9/7: Important: See right below for submission requirement changes for final submission.
  2. 8/18: The generated HTML source should be human readable.
  3. 8/18: inlcude docker config files in your submission if you're using docker.
  4. The language to be used for this project are HTML, PHP, Javascript, CSS. No other languages are allowed.
  5. FINAL SUBMISSION: Submission files should be incude (case sensitive):
    • Main zip file: 315-fall2020-<section>-<UIN>-prj1-<submission #>.zip (team ID = a, b, c, ...; submission # = 1, 2, 3, 4, etc., for design document, etc., respectively).
    • index.php : main page -- your professional information, similar to your resume.
    • proc_csv.php: CSV file processor functions
    • proc_wikitext.php: Wikitext processor functions
    • gallery.php : interactive gallery
    • proc_gallery.php : gallery functions
    • blog.php : development blog article (Writing requirement)
    • tips.php : coding tips collection (example: regular expressions, sort, debugging tips, HTML forms, etc.)
    • resources.php : resources collection (links and brief description to development resources)
    • [NEW] search.php : include your search functions and the main search interface (HTML form input) here. (list of pages matching the search criteria will be listed in this page).
    • [NEW] development.docx (or development.txt): your development blog article in ASCII txt or MS word format. Submit this file by itself to a separate eCampus submission stub. Write this first, and put this on your blog.php file.
    • Any deviations from these naming will each result in -1/100 for that submission.

Individual project (not a team project)

This project is an indivdual project. No collaboration is allowed.

In a nutshell

This project consists of two major parts.

  1. The first part is to write PHP (and associated) code to develop a web site framework with easily configurable content using plain text data files, and interactive features.
    • CSV file for tabular data
    • Simplified Wikitext data
    • Interactive gallery
    • Local web page search
  2. The second part is to use the framework to author a professional-looking web site about your coding projects.

    * Important restrictions:
    1. You must implement everything from scratch, just using the functions provided by the core PHP/Javascript language.
    2. External sources you are not allowed to use: Open source or any third party libraries that implement the core requirements (CSV, Wikitext processing, gallery etc.).
    3. External sources you are allowed to use: You may use code snippets (or idioms) from various sources, such as https://devhints.io/wip/php, https://catswhocode.com/php-regex/, https://htmlcheatsheet.com/js/, https://cheatography.com/davechild/cheat-sheets/php/.

PHP development environment

Since the department discontinued server support for PHP programming, we will use either of the two options below. More detailed setup will be discussed during the class and the labs.
  1. Infinityfree.net: A free hosting service. Create an account, and create a subdomain, then edit (or upload the files) to the htdocs directory. An example I created.
  2. Docker: install docker on your PC, install docker-compose, create a YML file to specify the container spec (https://phpdocker.io/generator makes this process easy), and fire up a container to run your private web server. Unzip the file you created from phpdocker into a new directory (let's say 315-docker/), cd to the directory, then run:
    docker-compose up -d
    and then you can connect to http://localhost:5555 (the port 5555 may be different, depending on what you chose when creating the spec in phpdocker). Edit the files in 315-docker/public/ on your local file system where you've unzipped the files, and this will immediately show up on your local web site. When you're done,
    docker-compose down
    to turn off the container.

PART I: Web site framework

The main file that serves as the entry to your web site will be "index.php". A PHP file mixes HTML, CSS, javascript, to generate static/dynamic content. For example, this course's web page is written in PHP. The PHP script can be written in any style, and the content can be of your choosing, but it will require the following technical elements:
  • A multiple-page web site focused on highlighting your professional skills.
    1. index.php : main page -- your basic professional information, education, skills, experiences, professional interests.
    2. gallery.php : gallery (Javascript-based): highlight your previous project screenshots or other people's project you find interesting.
    3. blog.php : development blog (Writing requirement)
    4. tips.php : coding tips collection
    5. resources.php : resources collection
  • Use of CSS for consistent styling across the entire site: headings, paragraphs, code boxes, etc.
  • Use of the following elements in your PHP scripts:
    1. regular expressions
    2. file I/O
    3. arrays
    4. sorting
    5. date/time functions
    6. automatically generated tabular data
    7. HTML forms (implementing search function)
    8. security features (sanitizing user input)
    9. Javascript functions for image gallery UI and navigation
There are four major features you need to support:
  1. CSV file processor : to display tabular data read from a file.
  2. Simplified Wikitext processor : to display Wikitext-like formatted text, read from a file.
  3. Interactive gallery : photo gallery supporting navigation and different views (list view vs. matrix view), and thumbnail size control.
  4. Search : search for text in your web site.
Below are more details about these four features.

1. CSV file processor

The CSV file processing function should take an arbitrary CSV file and render it as a nice-looking table in HTML.
  • It should be able to handle arbitrary delimiters (usually ',', but needs to support [tab], etc.), and the quote character for the text strings (usually '"').
  • Also, it must be able to show selected columns. "1:3:4:7" means, only show 1st, 3rd, 4th, and 7th columns. "ALL" means show all columns.
  • First row in the CSV file is assumed to the the column title. Thus, the first row must be rendered in HTML in a distinct style to seperate it from the data rows.

# function definition: use the exact interface in your code.

function proc_csv ($filename, $delimiter, $quote, $columns_to_show) {

... # function body

}

...

# example calls

proc_csv("test.csv",",","\"", "1:3:4:7");

proc_csv("test.csv",",","\"", "ALL");

# output would be formatted HTML code (table), that will be embedded where the above call is made in the PHP file.

2. Simplified Wikitext

For this, you will load a text file that containt a simplified Wikitext document, that allows you to write formatted text quickly and easily without using the full HTML tags. Resources:

# function definition: use the exact interface in your code.

function proc_wikitext ($filename) {

... # function body

}

...

# example call

proc_wikitext("test.wiki");

# the "test.wiki" file will contain plain ASCII text, in Wikitext syntax.

From the full Wikitext definition, you must support the following (below).

Type these in into the wikipedia sandbox (Wikipedia Sandbox) to see how they are rendered. Click on [edit source code], then type in Wikitext code, then click on [Preview].

1. Section headings (do not need to implement the table of contents).

= Heading 1 =
== Heading 2 ==
=== Heading 3 ===
==== Heading 4 ====
===== Heading 5 =====
====== Heading 6 ======

2. Horizontal rule

----

3. Line breaks (and paragraphs)

A single newline here
has no effect on the layout.

But an empty line starts a new paragraph, 
or ends a list or an indented part.

4. Indent text (note: no Outdent needed)

Indentation as used on talk pages:
:Each colon at the start of a line
::causes the line to be indented by three more character positions.
:::(The indentation persists
so long as no carriage return or line break is used.)
:::Repeat the indentation at any line break.
::::Use an extra colon for each response.
:::::And so forth ...
::::::And so on ...

5. Blockquote (see Template:Quote)

{{Quote
|text=Quoted material.
}}

{{Quote
|text=Quoted material.
|author=First M. Last
}}

6. Unordered lists

* Item1
* Item2
* Item3
* Item4
** Sub-item 4 a)
*** Sub-item 4 a) 1.
**** Sub-item 4 a) 1. i)
**** Sub-item 4 a) 1. ii)
** Sub-item 4 b)
* Item5

7. Ordered lists

# Item1
# Item2
# Item3
# Item4
## Sub-item 1
### Sub-sub-item
#### Sub-sub-sub-item
## Sub-item 2
# Item5

8. Description lists

; Term : Definition1

; Term
: Definition1
: Definition2
: Definition3
: Definition4

9. Italics and bold

To ''italicize text'', put two consecutive apostrophes on each side of it.

Three apostrophes each side will '''bold the text'''.

Five consecutive apostrophes on each side (two for italics plus three for bold) produces '''''bold italics'''''.

10. Links

	10-1. Named links

	[http://www.wikipedia.org Wikipedia]

	10-2. Bare URL
	http://www.wikipedia.org


11. Images

	11-1. Single picture

	A picture: [[File:wiki.png]]

	11-2. Single picture with size

	A picture: [[File:wiki.png|px=100]]


12. Coloring text

I will change the color in {{color|blue|the middle part of}} this sentence.

13. Highlighting text

This is how to {{Font color||yellow|highlight part of a sentence}}.

3. Interactive gallery

The interactive gallery will have the following interface (the different display modes and sort_modes must be supported):
 
# function definition: use the exact interface in your code.

function proc_gallery($image_list_filename, $mode, $sort_mode) {

   # $mode == "list"	   : list of large images view
   # $mode == "matrix"	   : image matrix view (3 columns)
   # $mode == "details"	   : file details view (text)

   # $sort_mode == "orig"  : original ordering in the CSV file
   # $sort_mode == "date_newest"  : newest images first
   # $sort_mode == "date_oldest"  : oldest images first
   # $sort_mode == "size_largest" : largest file size first
   # $sort_mode == "size_smallest": smallest file size first
   # $sort_mode == "rand"  : random ordering

}

# example calls

proc_gallery("my_favorite.csv", "matrix", "date_newest")

proc_gallery("my_projects.csv", "list", "size_largest")

# my_favorite.csv etc. will be a properly formatted CSV file that has the two following columns:
#     "filename.jpg","description text string" 

4. Search

A simple search function should be provided, based on user input (HTML form input: text box).
  1. search all web pages within your local web directory
  2. provide list of links to the pages that contain the search word (or phrase).
  3. each link should append ?highlight=search_word at the end of each php page's URL, and the php page must be able to handle this highlighting function. For example, when the search phrase was "search keyword", the link would look like this:
    http://your.site.com/gallery.php?highlight=search%20keyword
  4. Important: You must sanitize the user input, to avoid any security issues.
Note: this highlighting feature can be a bit tricky to implement, since the keyword may appear only in the final rendered HTML, if they originated from some of the data files (CSV or Wikitext files). You may have to modify all functions that generate HTML code and do a postprocessing on the result to highlight the keywords.
 
# function definition

function search($string)  {

}

# example calls

search("search keyword")

# this will result in a list of hyperlinks that point to your 
# web pages that contian the search keyword.
#
# 1. http://your.site.com/blog.php?highlight=search%02keyword 
# 2. http://your.site.com/resources.php?highlight=search%02keyword 
# ...

PART II: Writing Requirement

As mentioned in the syllabus, this course is a writing intensive course, and as an integrat part of the course design, you are required to write a substantial article. There will be a total of three writing assignments, one for each of the three projects, and the assignment for this project will be the major one (~1,200 words, while the other two assignments will be ~400 words each). The second topic, "topic2.php", will be the article you will write. The atricle will be about your development experience while working on this project. For a good example, see Qiang Hao's Bits and Pieces blog post on developing Google Docs Add-on in Two weeks. Follow the overall structure of Hao's blog post when writing your article. Writing resources: * Note * Until after the final submission date, password protect the development blog page, using .htaccess and .htpasswd (need to check if infinityfree supports this).

Deliverables and Requirements

  • Use of github is mandatory. http://github.tamu.edu. Give access to the TA.
  • You must maintain a development log (wiki page in github.tamu.edu titled "Development log") updated by you. This log will be graded. There is no designated format, except that you need to time stamp and write a brief description of the activity. We will check your daily progress. Note: This is a free-formatted notebook, different from the development blog writing component. However, if you write down your experience and your activities, it'd be easier to write your development blog article.
  • Demo in the lab may be required.
  • Intermediate submissions:
    1. 10%: layout, style, comments
    2. 30%: implementation (regardless of actual functioning)
    3. 50%: function (properly functioning)
    4. 5%: development log
    5. 5%: regular use of github (semi-daily commits)

  • Project Final Grading (Part I): Coding (100/100, worth 15% of your Final course grade). Rubrics are as follows:
    1. 5%: layout, style, comments, development log, github use
    2. 5%: Web site content -- the site as a whole must highlight your professional preparation. You must also use all the components you developed in this project in an integral part of your web page design. Note: The generated HTML source must be human-readable (with ample newline characters, indenting, etc.)
    3. 20%: CSV file processor
    4. 20%: Simplified Wikitext
    5. 20%: Interactive gallery
    6. 20%: Search
    7. 10%: Weighted grades from earlier submissions (CSV, Wikitext, each 5%).

  • Project Final Grading (Part II): Writing (100/100, worth 10% of your Final course grade)
    1. 80/100 of the grade for this assignment will be based on what you submit for the final project deadline.
    2. 20/100 of the grade for this assignment will be based on a reivision of your blog article after you have received feedback from the instructor/TA.
    3. Rubrics (motivated by Utha State University rubric:
      • Content, structure, and organization: 70/100 (each item 10 points each)
        1. Content is effective and clearly organized
        2. Article follows logical, consistent pattern of development of ideas
        3. Paragraphs discuss one main idea
        4. Paragraphs are appropriate in length (5 +- 2 sentences)
        5. Each sentence contains one main idea.
        6. Transitions between paragraphs are smooth.
        7. Appropriate references are made (5 or more links to resources are mandatory, put in a "Reference" section at the end).
      • Spelling, grammar, punctuation: 30/100.

Submission

  • All submissions should be through ecampus.tamu.edu
  • First, fork your latest project into an archival branch named: Submission 1, Submission 2, and Submission 3, etc. for the code submissions, respectively.
  • Include all php files, other code, and related media for your web site in the zip file.
  • Use the "Download ZIP" feature in github and upload the resulting zip file. Include all documents like development log, etc. in the zip file (you can add these after you download the zip from GitHub).
  • Standard late penalty applies.
  • File naming convention:
    • Main zip file: 315-fall2020-<section>-<UIN>-prj1-<submission #>.zip (submission # = 1, 2, 3, 4, etc., for weekly submissions, etc., respectively).
    • See top of the page (Updates) and piazza announcement for files to include in final submission.
    • index.php : main page -- your professional information
    • proc_csv.php: CSV file processor functions
    • proc_wikitext.php: Wikitext processor functions
    • gallery.php : interactive gallery
    • blog.php : development blog (Writing requirement)
    • tips.php : coding tips collection
    • resources.php : resources collection
    • if you're using docker, all docker-related files (*.yml, phpdocker/, etc.): entire docker directory, if you're using docker, so that the container can be instantiated and tested. Best to have your source code in the public/ directory.
    • Any deviations from these naming will each result in -1 (out of 100) for that submission.