## page was renamed from DevCenter/Projects/AddViewComments
= Add/View Comments =

||'''Version'''||'''Date'''||'''Changes'''||
||1.0||2006-12-01||Initial version.||

== Want to build an Online Help Manual "livedoc" via PHP ==

At the bottom of each help page there should be an option to add/view comments button.

=== Getting Started ===

So there are a lot of instances where you want to add something dynamic to output created in ePublisher. In many cases you can do this with Javascript but this is a problem when you want to do something that persists across different clients. A great example would comments. It would be really nice if an API you just documented and published via ePublisher could be commented on. This way developers or engineers could add code snippets and the like to small aspects of the documentation. This could be really difficult, but with a little PHP we can make a quick comment system in no time at all.

=== Step One: Google PHP ===

There are tons of great PHP tutorials that you can look into. Also the [[http://php.net|PHP]] website has very helpful documentation that has great comments! In the comment section of the PHP website documentation you will often find code snippets that you can use as well as helpful tips that can get you past any gotchas. 

Also, PHP is not the only language you can use. Virtually any language can be used to make CGI scripts or accept requests. Ask around your developers/engineers and see if they have a half a day to help out making a slick comment system for the output. 

=== Modifying the Page Template ===

The first step is to modify the Page.asp with the code shown in the attached [[attachment:ExamplePageAsp.zip.|ExamplePageAsp.zip]]

At the very top you will notice we have removed the XML declaration (<?xml version="1.0" ?>) because this interferes with the PHP parsing of the page. At the very top you will also see
{{{#!cplusplus
<?php 
session_start();
?>
}}}

This is a simple PHP session that we will use to prevent against someone refreshing the page and reposting the same comment. You may also need this if you are using PHP for something such as using a user login. 

At the bottom of the Page Template you will see more php code:

{{{#!cplusplus
<?php
  // Helpful Functions

  /* 
   * Simple function to display input forms for comments. 
   * 
   * We are just printing/echo'ing some forms. You could change them here.
   */
function display_forms() {
  echo "<form action='" . $_SERVER['PHP_SELF'] . "' method='post'>\n";
  echo "  <fieldset name='comment-forms'>\n";
  echo "    <legend>Add a Comment</legend>\n";
  echo "    <label for='comment-title'>Title:</label>\n";
  echo "    <input type='text' id='comment-title' name='title' maxlength='255' value='" . $_POST['title'] . "'/><br />\n";
  echo "    <label for='comment-content'>Comment:</label><br />\n";
  echo "    <textarea name='content' id='comment-content' rows='10' cols='40'>" . $_POST['content'] . "</textarea><br />\n";
  echo "    <input type='submit' name='submit' value='Add Comment' />\n";
  echo "  </fieldset>\n";
  echo "</form>\n";
}

/*
 * This displays the comments by reading the comments file for the
 * the specific file and prints it out.
 */
function display_comments() {
  $comment_file = rtrim(__FILE__, '.php') . '.comments.txt';
  if (is_file($comment_file)) {
    echo file_get_contents($comment_file);
  }
}


/*
 * Adds a comment to the comment file. 
 * The comment file is a simple text file in the same directory as the file
 * 
 * So, if the filename is MyFrameDoc.1.4.html
 * In ePublisher we change the extension to .php -> MyFrameDoc.1.4.php
 * Which makes the comment file -> MyFrameDoc.1.4.comments.txt
 */
function add_comment($title, $content) {
  
  // Check the session to see if this is a repost by the same user. 
  // 
  if ($_SESSION['comment-title'] == $title && $_SESSION['comment-content'] == $content) {
    return "";
  }
  
  /*
   * Create a quick bit of HTML to save in the comment file.
   * There should probably be some more checking here but for now it should be ok
   * 
   * WARNING: Your sys-admin will say this is a security hole. Please listen to him/her 
   *          and try to improve things.
   */
  $new_comment_string = "<div class='comment-block>\n";
  $new_comment_string .= "  <h4>" . htmlentities($title) . "</h4>\n";
  // making new lines actual line breaks
  $new_comment_string .= "  <div class='comment-content'>" . nl2br(htmlentities($content)) . "</div>\n";
  $new_comment_string .= "</div>\n";
  
  // Comment filename is the same as the requested file except with an extension
  // of 'comments.txt'
  $comment_file = rtrim(__FILE__, '.php') . '.comments.txt';
  
  // open the comment file for writing only at the beginning, if it is not there create it.
  $comment_file_handle = fopen($comment_file, "a+");
  if (fwrite($comment_file_handle, $new_comment_string)) {
    fclose($comment_file_handle);
    $_SESSION['comment-title'] = $title;
    $_SESSION['comment-content'] = $content;
    return "Comment Added!";
  } else {
    fclose($comment_file_handle);
    return "Error writing comment file. Please contact myemail@somedomain.com.";
  }
}


/* 
 * This is the actual logic of the script.
 */
if ($_POST['submit'] == "Add Comment") {
  if ($_POST['title'] != '' && $_POST['content'] != '') {
    echo add_comment($_POST['title'], $_POST['content']);
    display_forms();
  } else {
    echo "Please fill in the title and the content fields.";
    display_forms();
  }
 } else {
  display_forms();
 }
display_comments();
?>
}}}

Essentially all this code does is displays some forms and allows the user to post the values back to the page. The result will be a file in the same directory as the file with a filename in the format of:

  MY_OUTPUT_FILE.1.5.comments.txt

In order to use PHP in the output, the server must support PHP and the file might need a ".php" extension to tell the server that the file should be parsed by the PHP parser. If you have any questions regarding this aspect, just ask your sys-admin.

== More Options ==

This example uses PHP but any server language could be used just as easily. For example, ASP .NET also allows similar embedding of code within the output. JSPs or Java Server Pages also work in a similar fashion. The point being is that your system administrator can most likely easily help in adding simple additions that improve the user experience. 


== Online resources ==

Ajax – This allows someone to post or “ask the server” for some information without reloading the browser page

Ajax Apple Tutorial - http://developer.apple.com/internet/webcontent/xmlhttpreq.html

Simple Ajax Example - http://www.degraeve.com/reference/simple-ajax-example.php

Ajax with Prototype (A javascript library used in Ruby on Rails http://rubonrails.com ) - http://24ways.org/advent/easy-ajax-with-prototype 

The Complete Message Box Tutorial http://biorust.com/tutorials/detail/110/us/