update comments

git-svn-id: https://source.sakaiproject.org/svn/lessonbuilder/rutgers/lessonbuilder/trunk@94804 66ffb92e-73f9-0310-93c1-f5514f145a0a

lessonbuilder/PROGRAMMER.SHOWPAGE

@@ -9,6 +9,31 @@ producer ShowPageProducer.java. Most of the functionality comes from
 buttons in the toolbar, and from "edit" buttons next to items on the
 page.
 
+ShowPage is a bit complex to work with, because the actual page is
+produced by the interaction of 3 different things. ShowPage.html,
+ShowPageProducer.java, and show-page.js. ShowPage.html contains HTML
+tmplates. ShowPageProducer has all the logic for controlling which
+parts of the template are shown and adding information from the
+database. show-page.js is used primarily for the popup dialogs. Even
+after ShowPageProducer has filled in data from the database, many of
+the dialogs have fields that are empty. The problem is that we don't
+want to output a separate dialog box for each Edit Button. That would
+make the HTML file too big. Thus we output just one edit dialog box
+with blank fields. The Javascript code takes data from the particular
+item being edited, populates the fields in the dialog box, and then
+opens it.
+
+The structure is also complicated by the fact that we have to
+interface to various Sakai tools, and they all have their own
+peculiarities. For that reason we have a set of classes that know
+about each tool, but all implement a single Lesson Builder interface.
+ShowPage only knows about that interface class. This makes it a lot
+easier to add support for a new type of tool. Note that it is possible
+to chain more than one class of a given type. E.g. we support both
+Samigo and Mneme as testing engines. ShowPage doesn't know which
+engine you're using. In fact your site can have both, and showPage
+won't know it.
+
 In general things like "Add Quiz" are buttons that call separate
 pages, e.g. the quiz picker. The quiz picker looks up all quizes in
 the site, lets you choose one (or call Samigo to create a new one),
@@ -21,8 +46,8 @@ section at the bottom of the page in ShowPage. However they are
 initialized and popped up by Javascript code in show-page.js.
 
 There may be a dozen different quizes on the same page. But there is
-only one actual dialog box. The specific items defining the individual
-quiz are in variables right after the link for the edit button. The
+only one actual dialog box. The specific data defining the individual
+quiz is in hidden variables right after the link for the edit button. The
 Javascript code for "edit quiz" is called by the edit button with a
 pointer to the edit button. The Javascript uses that pointer to find
 the data associated with that item, initialized all the fields in the
@@ -46,13 +71,32 @@ Adding something touches a number of files:
 	./components/src/ddl/oracle/simplepage.sql
   you may need to add a new file such as SamigoEntity.java, which
       encapsulates most of the code for talking to the Sakai tool
-      that implements an object.
-      If you look at an existing one, you can see how they work.
+      that implements an object. In some cases you may also
+      need to define an interface. E.g. Common Cartridge input
+      calls a method to create a new object. Creating a test
+      requires different arguments than creating a forum.
+      Thus there's an interface definition for tests, used by
+      both Samigo and Mneme. It defines the method used to
+      create one. SamigoEntity.java implements both LessonEntity,
+      which has most of the methods used to interface to a tool,
+      and the special interface for tests, which defines the
+      one method used for creating object.
+      If you look at an existing file, you can see how they work.
   ShowPage.html - this is the template for the main web page.
-      It goes together with ShowPageProducer, using RSF
+      It goes together with ShowPageProducer, using RSF.
+      It has the template for displaying each type of thing,
+      as well as the dialogs.
   ShowPageProducer.java - the Java code behind ShowPage.html
   show-page.js - the Javascript used on ShowPage.html. The
-      popups are produced by code here.
+      popups are produced by code here. In some cases the code
+      to produce a popup is fairly complex. E.g. the same
+      popup is used to edit assignments, tests, and forums.
+      The Javascript code looks at hidden variables after
+      the visible part of the item. They define all the
+      things that the dialog box will need. The Javascript
+      code gets all that data and populates the fields in
+      the popup, unhides the ones that should show, and
+      then creates the popup.
   Simplepagetool.css - in case you need to add any styles
   messages.properties - all text should be put in this file.
       This application is internationalized, meaning that no

lessonbuilder/tool/src/java/org/sakaiproject/lessonbuildertool/tool/producers/ShowPageProducer.java

@@ -239,6 +239,9 @@ public void fillComponents(UIContainer tofill, ViewParameters viewParams, Compon
 		GeneralViewParameters params = (GeneralViewParameters)viewParams;
 
 	        if (!canReadPage) {
+		    // this code is intended for the situation where site permissions haven't been set up.
+		    // So if the user can't read the page (which is pretty abnormal), see if they have site.upd.
+		    // if so, give them some explanation and offer to call the permissions helper
 		    String ref = "/site/" + simplePageBean.getCurrentSiteId();
 		    if (simplePageBean.canEditSite()) {
 			SimplePage currentPage = simplePageBean.getCurrentPage();
@@ -250,6 +253,7 @@ public void fillComponents(UIContainer tofill, ViewParameters viewParams, Compon
 
 		    }
 
+		    // in any caae, tell them they can't read the page
 		    UIOutput.make(tofill, "error-div");
 		    UIOutput.make(tofill, "error", messageLocator.getMessage("simplepage.nopermissions"));
 		    return;
@@ -315,13 +319,13 @@ public void fillComponents(UIContainer tofill, ViewParameters viewParams, Compon
 		}
 
 		// security model:
-		// canEditPage and canReadPage are normal Sakai privileges. They all to all
+		// canEditPage and canReadPage are normal Sakai privileges. They apply to all
 		//    pages in the site.
 		// However when presented with a page, we need to make sure it's actually in
 		//    this site, or users could get to pages in other sites. That's done
 		//    by updatePageObject. The model is that producers always work on the
-		//    current page, and updatePageObject makes sure that is in the current site
-		//    at that point we can safely use canEditPage. 
+		//    current page, and updatePageObject makes sure that is in the current site.
+		//    At that point we can safely use canEditPage. 
 
 		// somewhat misleading. sendingPage specifies the page we're supposed to go to
 		if (params.getSendingPage() != -1) {
@@ -634,6 +638,8 @@ public void fillComponents(UIContainer tofill, ViewParameters viewParams, Compon
 					    decorate(new UIFreeAttributeDecorator("title", 
 						  messageLocator.getMessage("simplepage.edit-title.generic").replace("{}", i.getName())));
 
+					// the following information is displayed using <INPUT type=hidden ...
+					// it contains information needed to populate the "edit" popup dialog
 					UIOutput.make(tableRow, "prerequisite-info", String.valueOf(i.isPrerequisite()));
 
 					if (i.getType() == SimplePageItem.ASSIGNMENT) {
@@ -697,6 +703,10 @@ public void fillComponents(UIContainer tofill, ViewParameters viewParams, Compon
 
 			} else if (i.getType() == SimplePageItem.MULTIMEDIA) {
 
+			    // the reason this code is complex is that we try to choose the best
+			    // HTML for displaying the particular type of object. We've added complexities
+			    // over time as we get more expeerience with different object types and browsers.
+
 				StringTokenizer token = new StringTokenizer(i.getSakaiId(), ".");
 
 				String extension = "";
@@ -725,7 +735,8 @@ public void fillComponents(UIContainer tofill, ViewParameters viewParams, Compon
 				if (mimeType != null && (mimeType.startsWith("http") || mimeType.equals("")))
 				    mimeType = null;
 
-				// here goes. dispatch on the type and produce the right tag type
+				// here goes. dispatch on the type and produce the right tag type,
+				// followed by the hidden INPUT tags with informatio for the edit dialog
 				if (simplePageBean.isImageType(i)) {
 
 					UIOutput.make(tableRow, "imageSpan");
@@ -822,7 +833,9 @@ public void fillComponents(UIContainer tofill, ViewParameters viewParams, Compon
 				} else if ((mimeType != null && !mimeType.equals("text/html") && !mimeType.equals("application/xhtml+xml")) ||
 					   (mimeType == null && Arrays.binarySearch(multimediaTypes, extension) >= 0)) {
 
-				    // this code is used for everything that isn't HTML. HTML is done with an IFRAME
+				    // this code is used for everything that isn't an image, Youtube, or HTML. Typically
+				    // this is a flash presentation or a movie. Try to be smart about how we show movies.
+				    // HTML is done with an IFRAME in the next "if" case
 
 				        UIComponent item2;
 					UIOutput.make(tableRow, "movieSpan");
@@ -834,7 +847,8 @@ public void fillComponents(UIContainer tofill, ViewParameters viewParams, Compon
 					// in theory m4v can be DMRed. But Apple's DRM is useless on a web page, so it's got to be an unprotected file.
 					boolean isMp4 =  mimeType.equals("video/mp4") || mimeType.equals("video/x-m4v");
 					// FLV is special. There's no player for flash video in the browser
-					// it shows with a special flash program, which I supply
+					// it shows with a special flash program, which I supply. For the moment MP4 is
+					// shown with the same player so it uses much of the same code
 					if (mimeType != null && ( mimeType.equals("video/x-flv") || isMp4)) {
 					    mimeType = "application/x-shockwave-flash";
 					    useJwPlayer = ServerConfigurationService.getBoolean("lessonbuilder.usejwplayer", false);