[ZDP] Tutorial ....

[Tom Deprez]

Hi all,

Thanks to Martijns help, we could create a nice layout for our ZBook. I
thought, why not using this as a tutorial? So here it is. A good layout for
our tutorials will make it much better to read then now (maybe somebody a
good idea? Then let's us do it right away into Zope!)

Here it is. I must say, I'm not very optimal today, so I hope that somebody
will change this text in some better English and perhaps enhance some parts
which I forgot, are explain some clearer...

About Toturials : Users should already know the manage screen of Zope. I.e.
Adding DTML Methods, etc.

We should find a proper way to visualize tutorials. With style sheet?

Example : 

First, full code is shown :

Id of code (with lightblue background)
Code (with lightyellow background)

Then explenation of some parts, maybe also color specific?

Tom.



This Tutorial follows after some very small tutorials with some generic DTML.

With this tutorial, we're going to make us first Zope application. And what
can we use for this first application than our ZBook? So, after this
tutorial, you can make your own book of Zope! (Although we prefer that you
would put your additions in the original ZBook, offcourse :-)).

Determine the layout of our web application

When you're appointed to create a web-site, you first have to analyse the
information people want to show on the net. Then, when you know what you've
to display, you can start thinking how to present it onto the web. This
phase, stays the same for a creating a web-site into Zope. 

In this tutorial, we want to display some chapters of a book we've written
and we want that people can select a certain chapter (by clicking on it).
This capter then shows itself to the viewer. It has to be so that people
always know where they are reading inside the book. This because a book can
become very big and we don't want that people are getting lost. 

So, we choose for the following layout: On the left of the screen a table
of contents and on the right , the selected text will appear.

Implementation 

From this part on, the implementation of a web-site will probably
significally differ from the normal. Because, in Zope we'll take advantage
by the use of inheritance and acquisition. 

Creating the structure

Framework

Note: When adding a 'DTML Document' or folder, you've to enter an ID and
you can enter a name. In this tutorial, I always used the paragraph number
as id and the paragraph titel as name. I advise you to do the same, because
some things depend on this.

Before we start creating the contents of our web-site, we first make the
structure. This we do by making our hierarchy structure into Zope by using
the 'Folder' item. We call the start folder 'starting'. In this we define
another folder, which will contain the contents of our book, we call it
'Outline'. Here we take another decision about the translation of the
book-structure, to a web-structure. For every chapter, which contains other
chapters or subdivision we'll use the 'folder' item. In the other case, we
just leave that for now.

Content

Now, we're going to add all our text in the framework. For this we use the
'DTML Document' item. Perhaps, it was better to use a 'DTML Method' item
instead. But, then we've to be absolutely sure that we never what to add
specific properties to our 'Documents'. Because, I'm not sure about this
(maybe, one day I want to sort the documents, through a property), I use
the 'DTML Document' item. At this moment however, the sorting is done by
the declarations of the item-ID's. Don't forget that Zope is CASE-sensitive!


So finally the structure will look like this :

[use screenshot]

../starting
	/Outline
		/ChapterI
			Subdevisions
			...
		/ChapterII


Why using such a structure? Why not just dropping a file with all the nice
formatted text into the 'starting' folder? Well, doing it this way, we can
always add new chapters, change them without to much trouble interfering
the other parts. It just gives a nice way to manage the web-book. And the
most important point : This way, it is easy to change the way to present
the chapters. Plus, the 'table of contents' can be made full automatic (see
next paragraphe). Thus, we only have to add a new 'DTML Document' or
'Folder' and it will automatically be incorporated into the 'table of
contents'

Glueing all the things together

So, we've put our book on-line, but now, we still have to make it
representative, including our 'table of contents'.

Therefor we go to the folder which will be the 'homepage' of our web-site.
Typical in Zope is that when you browse to an object (in this case a
folder), Zope will try to find the 'DTML Document' called Index_html. If it
finds this document, then this document will be displayed. (note:you can
change this behaviour, but that's not for now). This is just what we want,
so we add a 'DTML Document' with Index_html as id. The contents are as
follows (you can just copy and paste it, if you've a lazy character :-))

Index_html

<!--#var standard_html_header-->
<!--#var zb_main-->
<!--#var standard_html_footer-->

Now, what is this all about? In Index_html we just say that the contents
are just made up by the contents of the document with id's :
'standard_html_header', 'zb_main', 'standard_html_footer'. The '#var' tag
is used to substitute some 'data' at that place.

Simple isn't it? But, yet we've to define these documents offcourse. Note:
Zope is case-sensitive! This means that if you refer to an id, you have to
write this id as you've declared it!

standard_html_header

<HTML><HEAD><TITLE><!--#var title_or_id--></TITLE>

<!--#var css_sheet-->

</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#008080" VLINK="#000080">
<TABLE WIDTH="100%" BORDER=0><TR VALIGN=TOP><TD><!--#var
zb_menu--></TD><TD>&nbsp;</TD>
<TD><!-- start of content-->

title_or_id is a reserved variable in Zope. And this variable will always
contain the title of the object, or if it doesn't have a title, it will
contain the id.

css_sheet is a 'DTML Method' defined by us. Here you see that substitution
isn't only for putting somthing in a document, css_sheet defines the style
of out document!

Here we also declare the layout of our pages. We wanted to show a 'table of
contents' to the left and on the right the contents of a chapter. This we
do by defining a table. Note however that the table doesn't has an end tag!
This will be declared in 'standard_html_footer'. But first we've to give the 

standard_html_footer

</td></tr></table></body></html>

For your convinience, I also write the stylesheet document down

css_sheet

<STYLE TYPE="text/css">
<!-- /* Hide content from old browsers */
.tree {
	font-size: 10pt;
	color: #335933;
	font-family: Geneva, sans-serif;
}

P {
	font-size: 10pt;
	font-family: Geneva, sans-serif;
	color: #000000;
}

/* end hiding content from old browsers */ -->
</STYLE>


zb_main

This is just a document which will be displayed on the right side of the
screen when people, have just arrived to our homepage 

zb_main
-------

<h2><!--#var title_or_id--></h2>
<p>
Hello,<br>
<br>
We would like to present you the text written so far as introduction to
Zope.<br>
Written by Tom Deprez, additions and corrections by Howard Shawn, Maartijn
Faassen and Pavlos Christoforou.<br>
<br>
Please, read it carefully, and discuss the context on the zdp list. <br>
Also send additions, corrections to the ZDP list! Thanks!<br>
Pictures, schematic overviews needed! I made a few, but not published them
yet.<br>
<br>
Do you need something explained and you can't find it here? Let us know!<br>
Enjoy your reading!
</p>

zb_menu

And here is the 'hart' of our home page! In these view lines, we create our
'table of contents'

<!--#tree Outline branches_expr="objectValues(['Folder', 'DTML Document'])"
nowrap=1-->
<SPAN CLASS="tree">
<!--#if expr="meta_type == 'Folder'"-->
 <!--#if tree-item-expanded-->
  <IMG SRC="<!--#var SCRIPT_NAME-->/HelpSys/hs_obook" ALIGN="TOP"
BORDER="0" width=16 height=16>
 <!--#else-->
  <IMG SRC="<!--#var SCRIPT_NAME-->/HelpSys/hs_cbook" ALIGN="TOP"
BORDER="0" width=16 height=16>
 <!--#/if-->
 <!--#var title_or_id-->
<!--#else-->
 <IMG SRC="<!--#var SCRIPT_NAME-->/HelpSys/hs_dnode" ALIGN="TOP" BORDER="0"
width=16 height=16>
 <A HREF="<!--#var
SCRIPT_NAME-->/guide/introduction/starting/Outline/<!--#var tree-item-url-->">
 <!--#var title_or_id--></a>
<!--#/if-->
</SPAN>
<!--#/tree-->

Explenation

Tree expression :

<!--#tree Outline branches_expr="objectValues(['Folder', 'DTML Document'])"
nowrap=1-->

With the tree-tag we can very easely create a tree. All the heavy work is
already done by the creators of Zope. The tag can contain several
parameters, but we use only two of them. Here we say that Zope has to
create a tree-view of the contents of the 'Outline' folder. As tree
branches, Zope will use the 'Folder' and 'DTML Document' items, inside
'Outline' folder. This is achieved by the 'objectValues' call.

<!--#/tree-->

First 'if' expression :

<!--#if expr="meta_type == 'Folder'"-->

If the object is of type 'Folder' this part will be executed.

<!--#else-->

If this is not the case, then this part will be executed.

<!--#/if-->

Second 'if' expression : 

 <!--#if tree-item-expanded-->
  <IMG SRC="<!--#var SCRIPT_NAME-->/HelpSys/hs_obook" ALIGN="TOP"
BORDER="0" width=16 height=16>

 If this brached is expanded, then an image of an open book will be used.

 <!--#else-->
  <IMG SRC="<!--#var SCRIPT_NAME-->/HelpSys/hs_cbook" ALIGN="TOP"
BORDER="0" width=16 height=16>

 When the branche is collapsed, we display a closed book.

 <!--#/if-->

Other DTML code :

The variable 'tree-item-url' contains the url to the specific branche.
Offcourse, we've to add the parent branch to this url to get a ligitimed one.


Mmmmm... now how comes that the table-layout is preserved when you click on
a tree branch?... For this look at the contents of one of our chapters :

<!--#var standard_html_header-->
<h2><!--#var title_or_id--></h2>
<p>
 blablabla
</p>
<!--#var standard_html_footer-->

Do you get it? Well, it this we say that the 'standard_html_header' and
'standard_html_footer' contents have to be included... and if you now look
back at the contents of these two, I think a small light is going to
glow.... yes! this is ZOPE!


Next tutorials comming :

Finishing touch of our ZBook :

Printing it as one text by Martijn Pieters Code :-)
Using Cookies by Martijn Pieters Code :-)

Then, using Membership system ???

What is the Membership system, by the way?

Tom.