Lesson Instruction altered

git-svn-id: http://webgoat.googlecode.com/svn/trunk@331 4033779f-a91e-0410-96ef-6bf7bf53c507

webgoat/main/project/doc/New Lesson Instructions.txt

@@ -0,0 +1,176 @@
+Detailed instructions for adding a lesson
+
+All you have to do is implement the abstract methods in LessonAdapter.  
+Follow the outline below.
+
+WebGoat uses the Element Construction Set from the Jakarta project.  
+You should read up on the API for ECS at 
+http://jakarta.apache.org/site/downloads/downloads_ecs.cgi.
+In addition you can look at the other lessons for examples of how to use the ECS.
+
+
+
+Step 1: Set up the framework
+
+import java.util.*;
+import org.apache.ecs.*;
+import org.apache.ecs.html.*;
+
+// Add copyright text - use text from another lesson 
+
+public class NewLesson extends LessonAdapter
+{
+
+	protected Element createContent(WebSession s)
+	{
+		return( new StringElement( "Hello World" ) );
+	}
+
+	public String getCategory()
+	{
+	}
+
+	protected List getHints()
+	{
+	}
+
+	protected String getInstructions()
+	{
+	}
+
+	protected Integer getRanking()
+	{
+	}
+
+	public String getTitle()
+	{
+	}
+}
+		
+
+
+Step 2: Implement createContent
+
+Creating the content for a lesson is fairly simple. There are two main parts: 
+	(1) handling the input from the user's last request, 
+	(2) generating the next screen for the user.  
+This all happens within the createContent method.  Remember that each lesson 
+should be handled on a single page, so you'll need to design your lesson to 
+work that way.  A good generic pattern for the createContent method is shown 
+below:
+
+// define a constant for the field name
+private static final String INPUT = "input";
+	
+protected Element createContent(WebSession s)
+{
+	ElementContainer ec = new ElementContainer();
+	try
+	{
+		// get some input from the user -- see ParameterParser 
+		// for details
+		String userInput = s.getParser().getStringParameter(INPUT, "");
+
+		// do something with the input
+		//   -- SQL query?
+		//   -- Runtime.exec?
+		//   -- Some other dangerous thing
+			
+		// generate some output -- a string and an input field
+		ec.addElement(new StringElement("Enter a string: "));
+		ec.addElement( new Input(Input.TEXT, INPUT, userInput) );
+			
+		// Tell the lesson tracker the lesson has completed.
+		// This should occur when the user has 'hacked' the lesson.
+		makeSuccess(s);
+
+	}
+	catch (Exception e)
+	{
+		s.setMessage("Error generating " + this.getClass().getName());
+		e.printStackTrace();
+	}
+	return (ec);
+}
+	
+ECS is quite powerful -- see the Encoding lesson for an example of how 
+to use it to create a table with rows and rows of output.
+
+
+Step 3: Implement the other methods
+
+The other methods in the LessonAdapter class help the lesson plug into 
+the overall WebGoat framework.  They are simple and should only take a 
+few minutes to implement.
+
+public String getCategory()
+{
+	// The default category is "General" Only override this
+	// method if you wish to create a new category or if you
+	// wish this lesson to reside within a category other the
+	// "General"
+		
+	return( "NewCategory" );  // or use an existing category
+}
+
+protected List getHints()
+{
+	// Hints will be returned to the user in the order they 
+	// appear below.  The user must click on the "next hint"
+	// button before the hint will be displayed.
+		
+	List hints = new ArrayList();
+	hints.add("A general hint to put users on the right track");
+	hints.add("A hint that gives away a little piece of the problem");
+	hints.add("A hint that basically gives the answer");
+	return hints;
+}
+
+protected String getInstructions()
+{
+	// Instructions will rendered as html and will appear below
+	// the area and above the actual lesson area.
+	// Instructions should provide the user with the general setup
+	// and goal of the lesson.
+		
+	return("The text that goes at the top of the page");
+}
+
+
+protected Integer getRanking()
+{
+	// The ranking denotes the order in which the menu item
+	// will appear in menu list for each category.  The lowest
+	// number will appear as the first lesson.
+		
+	return new Integer(10);
+}
+
+public String getTitle()
+{
+	// The title of the lesson.  This will appear above the
+	// control area at the top of the page.  This field will
+	// be rendered as html.
+		
+	return ("My Lesson's Short Title");
+}
+
+
+Step 4: Build and test
+
+Once you've implemented your new lesson, you can test the lesson by
+starting the Tomcat server (within Eclipse). See the
+"HOW TO create the WebGoat workspace.txt" document in the WebGoat root.
+
+
+
+	
+Step 5: Give back to the community
+
+If you've come up with a lesson that you think helps to teach people about 
+web application security, please contribute it by sending it to the people 
+who maintain the WebGoat application.
+
+Thanks!
+
+The WebGoat Team.