(****
 * 
 * Module Page defines the objects and operations related to creating a Page
 * for use by the CSTutor application.
 *
 *)

module Page;

from Data import PageRecord;
export all;

object Page is
	components: HTMLContent and GraphicObject and Name and Thumbnail;
	description: (*
		A Page contains elements to present information in a tutorial,
		namely text, graphics, sample code, and links to the internet and
		other Pages.
	*);
end Page;

object HTMLContent is (Tag or Text)*
	description: (*
		HTML content consists of command tags and text, interspersed.
	*);
end HTMLContent;

object Tag is TagsWeCareAbout or TagsWeDontCareAbout
	description: (*
		HTML tags are subdivided into two broad categories -- those that
		we care about in this tool, and the rest of the HTML tags that
		we don't care about because they are not used directly by this tool.
	*);
end Tag;

object Text is string;

object TagsWeCareAbout is
	components: InternalLink and ExeCodeSegment;
	description: (*
		These are tags that need to be modeled for the CSTutor's use of
		HTML, i.e., tags that the tool uses explicitly.  These include
		(but are not limited to) the  tag,  tags,
		and so forth.
	*);
end TagsWeCareAbout;

object TagsWeDontCareAbout is
	components: ExternalLink;
	description: (*
		The complete specification of HTML is published by the W3C
		organization, at http://www.w3.org/MarkUp.
	*);
end TagsWeDontCareAbout;

operation DisplayHtmlContent
	in: HTMLContent;
	out: RenderedHtmlContent;
	pre: (* Tags for the various cstutor-specific tools, such as 
		, , etc.  *);
	post: (* As the precondition.  *);
	description: (*
		The complete specification of HTML is published by the
		W3C organization, at http://www.w3.org/MarkUp,
		and also indicates how HTML content is rendered in a display.
	*);
end DisplayHtmlContent;

object RenderedHtmlContent is
	description: (*
		Appropriate lesson pages to be made into lessons,
		containing images, text, code segments, and linking capability.
	*);
end RenderedHtmlContent;

object GraphicObject is
	components: ImageFilename;
	description: (*
		A standard HTML-supported graphic, primarily .jpeg and .gif.
	*);
end GraphicObject;

object ImageFilename is string;

object ExeCodeSegment is
	components: Code;
	description: (*
		An Executable Code Segment is defined by the standard
		Java Language Specification, located here.
	*);
end ExeCodeSegment;

object Code is string;

object ExternalLink is
	description: (*
		A standard HTML link to a webpage on the Internet.
	*);
end ExternalLink;
	

object InternalLink is
	components: PageRecord;
	description: (*
		A link to another Page within the database.  The Page Record
		contains the information necessary to link to the appropriate
		page, utilizing the unique PageID and PageFile.
	*);
end InternalLink;

object Name is string
	description: (*
		The title of a Page.
	*);
end Name;

object Thumbnail is
	description: (*
		This is a scaled down opaque screenshot of the actual
		Page, used as a visual representation of the Page in the
		Tutorial builder.
	*);
end Thumbnail;

operation AddText is
	inputs: pg:Page, txt:Text;
	outputs: pg':Page;

	precondition:
		(*
		 * No real preconditions, except that a Page is open.
		 *)
		(pg != nil);

	postcondition:
		(*
		 * Nothing else about the Page was altered except for the added
		 * text.
		 *)
		(pg' = pg);

	description: (*
		Adding text either through typing or copy-pasting existing text.
	*);
end AddText;

operation AddGraphic is
	inputs: pg:Page, imgf:ImageFilename;
	outputs: pg':Page, go:GraphicObject;

	precondition:
		(*
		 * A Page is open, and the input ImageFilename is a valid path to
		 * a GraphicObject currently saved somewhere on a harddrive.
		 *)
		(pg != nil) and (imgf != nil);

	postcondition:
		(*
		 * Nothing else about the Page is altered or nerfed except for
		 * the added GraphicObject.
		 *)
		(pg' = pg);

	description: (*
		AddGraphic adds a given image/graphic with the provided
		ImageFilename into the Page.
	*);
end AddGraphic;

operation AddCode is
	inputs: pg:Page, cs:ExeCodeSegment;
	outputs: pg':Page;

	precondition:
		(*
		 * No real precondition, except that a Page is open.
		 *)
		(pg != nil);

	postcondition:
		(*
		 * Nothing else about the Page is altered or nerfed except for
		 * the added CodeSegment.
		 *)
		(pg' = pg);

	description: (*
		Adds an empty CodeSegment into the Page.
	*);
end AddCode;

operation AddExternalLink is
	inputs: pg:Page, el:ExternalLink;
	outputs: pg':Page;

	precondition:
		(*
		 * A Page is open, and the input ExternalLink is a valid path to
		 * the internet.
		 *)
		(el != nil) and (pg != nil);

	postcondition:
		(*
		 * Nothing else about the Page is altered or nerfed except for
		 * the added ExternalLink.
		 *)
		(pg' = pg);

	description: (*
		Adds a link to the internet into the Page.
	*);
end AddExternalLink;

operation AddInternalLink is
	inputs: pg:Page, lnkdPg:Page;
	outputs: pg':Page;

	precondition:
		(*
		 * A Page is open, and the input InternalLink is a valid path to
		 * another Page.
		 *)
		(pg != nil) and (lnkdPg != nil);

	postcondition:
		(*
		 * Nothing else about the Page is altered or nerfed except for
		 * the added InternalLink.
		 *)
		(pg' = pg);

	description: (*
		Adds a link to a previously created Page into the current Page.
	*);
end AddInternalLink;

operation NewPage is
	outputs: pg:Page;

	description: (*
		Opens a new page into the Page Editor window.
	*);
end NewPage;

operation OpenPage is
	inputs:  pg:Page;
	outputs: Page;

	description: (*
		Opens a previously saved page into the Page Editor window.
	*);
end OpenPage;

end Page;