hw02
hw02: Functions that return (html) text

Due 2015.Feb.09 (Mon) 11:00 Submit on D2L, and a bring hardcopy of your four files utils.php, utils-test.php, silly-page.php, and index.php to the following class. The files should also be viewable on the web, as discussed below.

For this homework, create a directory ~/dynamic_php/itec325/hw02. It will contain four files (three of which are similar to hw01):

utils.php, which contains (only) code for php functions below.
utils-test.php, which contains only the runnable test cases for those functions.
This time, your tests should be (mostly) silent on success, and only print output when a test fails (such as utils-test-v2_php.txt). Remember to use === (or, !==) to compare the actual and expected results. A successful test will print some small progress-indication like “.”.
Optional: If you want you can make tests either print “.” or nothing, depending on (say) some named constant. You can create named constants via define: e.g. define( 'QUIET_ON_SUCCESS', someBool );. Regardless of this flag, failed tests should always print a loud message.

secret agenda: I'm hoping that typing all the tests becomes so much typing that you get fed up and automated it by writing your own function — something like test( $actual, $expected ).
silly-page.php, which (when run) just prints out (what happens to be) valid html for a web page that includes a hyperlink, a thumbnail image, a comma-separated list, and a list of ~~nav-links~~ links created via table-of-contents (all created by calling your functions).
This time, silly-page.php should be mostly not enclosed in <?php>. After testing that this file prints some html from the command-line, make sure it is viewable on the web as
A file index.php, as discussed below.

(10pts) Write a function string hyperlink( string $url, string-or-boolean $linkTxt ) which returns a string of html. If the provided $linkTxt is false (instead of a string), then use the $url as the link text.
hyperlink( "http://www.gutenberg.org", "free books!" ) === "<a href='http://www.gutenberg.org'>free books!</a>"
hyperlink( "myLocalFile.html", false ) === "<a href='myLocalFile.html'>myLocalFile.html</a>"
Note that this is just a regular ol' function that takes in strings and returns strings!
The fact that the strings happen to have angle-brackets in them means that the result might be useful to people generating html, but the function itself does't really care.

(You don't need to come up with additional test cases, but you do need to actually include these tests or their equivalent. You can assume that neither string is ever empty.)

Note how the input strings don't contain any quote-characters, but the returned result does (since HTML attributes must be quoted). I recommend that your generated html uses single quote marks around attributes, but you'll get full credit for either single- or double-quote marks, as long as it is valid HTML. Make sure your test case(s) express exactly what you want the desired output should be!
(15pts) We will write a function to help us generate thumbnails:
1. What is the html element for an image with source pony.jpg (in the same directory), that is rendered 300px wide?
  Include your answer in a comment, in your test-file.
2. What is the html for such an image which is also a link — where the link would take you to that ~~file~~image (not a html page — just that ~~file~~image).
  Include your answer in a comment, in your test-file.
3. Make the above into a runnable test-case for thumbnail("pony.jpg",300); the expected-output should be a string that happened to be your answer.
  You don't need further test-cases for this problem.
  
  Pay close attention to the exact spacing you want to have. As discussed in class, I recommend using single-quotes (') around the attribute-values.
4. Finally, implement the function thumbnail that takes in a string (a URL) and a number (the width in pixels), and returns a string that is an html link containing an image.
  For full credit, your function should call hyperlink as already written!
(20pts) Write a function which takes in an array of strings, and returns a single, long string: a comma-separated list of all the individual strings, with “and” before the last element (if more than one)¹. The resulting string should be suitable for splicing into the middle of a paragraph of prose, and should be proper, grammatical English. (This function has nothing to do with html.) Include at least three test cases, each testing a different situation.
(20pts) Write a function toc (“table of contents”): It takes an array of strings, and returns a string that is HTML for an un-ordered list of links to anchors within the same document.
For example, given an array with "thumbnail-problem", "commaList-problem", and "due-date", it would return HTML that would render as:
(Try clicking on those items, and feel free to view-source, to understand what it's doing. Of course, this function is only helpful if the strings in the array are also used as id attributes elsewhere in the page.)

For full credit, this function should involve a call to hyperlink.
(10pts) Make sure your files are viewable via the web at https://php.radford.edu/~yourUserName/itec325/hw02/silly-page.php, as well as the file https://php.radford.edu/~yourUserName/itec325/hw02/index.php, as described below.

(15pts) Finally, create one further file, index.php, which (when viewed on the web) will contain:

Your name.
A link to this assignment-page.
A link to your hw02's silly-page.php.

The source-code of all your files, viewable only after² the assignment-deadline, up to the start of the summer. It will presumably include code along the lines of:

          if (strtotime('2015-Feb-05 14:00') <= time() && time() < strtotime('2015-Jun-01 00:00')) { 
               echo "<hr/>";
               echo "<h3 id='file1'>", hyperlink("file1"), "</h3>";
               echo highlight_file( 'file1', true );
               //... repeat(?) for each file in this hw, including this index.php itself.
          }
          else {
              echo "(Source files viewable from 2015-Feb-05 until 2015-Jun-01 only.)";
          }

As mentioned in class, you'll want to call date_default_timezone_set('America/New_York') before calling strtotime.

Before the full listing, have a table of contents: an unordered list containing items like: <li>< a href='#file1'>file1</a> </li>. Use your toc function to generate this.

Notes:

For all assignments in this class (and for all your classes) your primary file (utils.php in this case) must start with a comment containing: Your name; the class/semester; the URL of this assignment page.
Every function should be commented with a short (1-sentence) description, (which mentions every parameter by name), and should indicate the types of the parameters and the return-type.
You do not need to check for invalid-inputs to your functions. E.g.: if I ask for a function taking in (say) a number and a string, and you repeat in your function-comment that your function handles a number and a string, then you don't need to check for being given incorrect inputs — that's the caller's problem, not yours. Similarly for more refined types like "non-empty-string" or "integer in the range [1,12]": if it's in the comments as a pre-condition, that'll suffice.³

(We'll talk about validating input received from the (external, untrusted) user later.)
Any HTML/XML for this class should follow the following common guidelines:
- Every tag must be closed. (Empty-tag notation is fine, but no dangling <p> open-tags.)
- Every attribute must have a value, and it must be quoted.
- Tags are case-sensitive.
- Indent clearly, as for any programming class (or your non-programming classes for that matter).
We'll require these even where it's not strictly needed for (mere) HTML5 compliance.

¹When having a list of more than 2 items, I personally recommend using the Oxford comma (or, see wikipedia) but I will leave it to your preference. ↩

² You presumably want to check that your file-sources really are visible only after the due-date. To test this, first write the code so that it only even mentions index.php itself, and make sure it turns but that the source file is not publically displayed. Add the other files, and confirm that the source files are still not displayed. Then: temporarily change the date to 2013 (instead of 2015) and verify that the source-files display; then immediately change the date back and re-verify that they are not being displayed. ↩

³ While the defensive-programming can be helpful in bigger projects (esp. in untyped languages like php), it's never interesting code. If you DO want to do the checks anyway, that's fine, but do all the type-validation right away (before you enter the 'real' function-logic), and throw an error if something goes wrong (don't continue and return some sort of odd, undocumented answer). For example:

function foo( $someNum ) {
  // optional error-check:
  if !(is_numeric($someNum)) { throw new InvalidArgumentException( 'foo: expected number, given ' . $someNum ); }

  // ...now put your real code, uncluttered by further type-checks.
}

(Ideally, you'd include the type-requirements in comments, and then a tool would automatically generate the above boilerplate error-checking for you. That's what Java's type-system gives you, for example.) ↩

home—lects—hws
D2L—breeze (snow day)

©2014, Ian Barland, Radford University
Last modified 2015.Feb.09 (Mon) Please mail any suggestions
(incl. typos, broken links)
to ibarlandradford.edu

hw02 hw02: Functions that return (html) text

hw02
hw02: Functions that return (html) text