[MKDoc-users] Re: MKDoc demo, up and running...:)

Mon, 22 Oct 2001 19:07:42 +0100

--82I3+IH0IqGh5yIs
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Hi Jay,

> end). However, I went and tried them from shell, and everything went very
> smoothly :)...Thanks.

That's a good news :)

> I'm not running mod_perl, so I had to comment out everything from line 9 to
> 45 for the Apache test configuration to work. Is this OK? I also had the
> mysql/bench/run.bat problem, but it seems to have sorted out, too.

I'm afraid that won't work. I have attached a httpd.conf.tmpl file with
this email, try to erase c:\opt\mkdoc\conf\httpd.conf.tmpl with this
file. Then re-run install.pl in c:\opt\test so that it re-writes the
files. Finally, restart apache and tell me how it goes.

> Now, comes my part...Are there any docs on setting up the site content --
> templates, etc.? I'm going to check the files themselves, but if there are
> some docs lying around it might save some time.

To use the editor interface, you can find extensive help on
http://mkdoc.com/help

For the templates, I * started * writing some docs (see attached draft)
but it's not there yet. If you know HTML, you can hack the templates in
any good text editor. Make sure to backup them first.

If you use WYSIWYG editors, it's probably best for you to wait for a
week or two before you start to play with them, as I'm currently
implementing much better WYSIWYG support.

Thanks for your interest in our product!
Best regards,

-- 
Jean-Michel Hiver - Software Director
jhiver@mkdoc.com  - http://www.mkdoc.com
+44 (0) 114 221 4968

--82I3+IH0IqGh5yIs
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="httpd.conf.tmpl"

# this is the configuration for the public interface
<VirtualHost 127.0.0.1>
  ServerName  <% var name="PUBLIC_DOMAIN" %> 
  ServerAdmin <% var name="SERVER_ADMIN" %>
  CustomLog   <% var name="SITE_DIR" %>/log/access_log combined
  ErrorLog    <% var name="SITE_DIR" %>/log/error_log
  Alias /     <% var name="MKDOC_DIR" %>/cgi/mkdoc.cgi/
  <Directory <% var name="MKDOC_DIR" %>/cgi>
     # directives for mod_perl
     # you can comment that if your apache server is not
     # compiled with mod_perl
     # PerlSetEnv PERL5LIB <% var name="MKDOC_DIR" %>
     # SetHandler perl-script
     # PerlHandler Apache::Registry
     # PerlSendHeader On

     # directives for CGI. These should work everywhere
     # do not uncomment that bit of text
     Options ExecCGI
     AddHandler cgi-script .cgi
     order allow,deny
     allow from all
     AllowOverride none
   </Directory>
</VirtualHost>

# this is the configuration for the admin interface
<VirtualHost 127.0.0.1>
  ServerName  <% var name="ADMIN_DOMAIN" %> 
  ServerAdmin <% var name="SERVER_ADMIN" %>
  CustomLog   <% var name="SITE_DIR" %>/log/access_log combined
  ErrorLog    <% var name="SITE_DIR" %>/log/error_log
  Alias /     <% var name="MKDOC_DIR" %>/cgi/admin.cgi/
  <Directory <% var name="MKDOC_DIR" %>/cgi>
     # directives for mod_perl
     # you can comment that if your apache server is not
     # compiled with mod_perl
     # PerlSetEnv PERL5LIB <% var name="MKDOC_DIR" %>
     # SetHandler perl-script
     # PerlHandler Apache::Registry
     # PerlSendHeader On

     # directives for CGI. These should work everywhere
     # do not uncomment that bit of text
     Options ExecCGI
     AddHandler cgi-script .cgi
     order allow,deny
     allow from all
     AllowOverride none
   </Directory>
</VirtualHost>

# this is the configuration for the super user interface
<VirtualHost 127.0.0.1>
  ServerName  <% var name="SU_DOMAIN" %> 
  ServerAdmin <% var name="SERVER_ADMIN" %>
  CustomLog   <% var name="SITE_DIR" %>/log/access_log combined
  ErrorLog    <% var name="SITE_DIR" %>/log/error_log
  Alias /     <% var name="MKDOC_DIR" %>/cgi/su/su.cgi/
  <Directory <% var name="MKDOC_DIR" %>/cgi/su>
     # directives for .htpasswd file
     # AuthUserFile <%var name="SITE_DIR" %>/.htpasswd
     # AuthName "MKDoc super user interface"
     # AuthType Basic
     # require valid-user

     # directives for mod_perl
     # you can comment that if your apache server is not
     # compiled with mod_perl
     # PerlSetEnv PERL5LIB <% var name="MKDOC_DIR" %>
     # SetHandler perl-script
     # PerlHandler Apache::Registry
     # PerlSendHeader On

     # directives for CGI. These should work everywhere
     # do not uncomment that bit of text
     Options ExecCGI
     AddHandler cgi-script .cgi
     order allow,deny
     allow from all
     AllowOverride none
   </Directory>
</VirtualHost>

--82I3+IH0IqGh5yIs
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="syntax.pod"

=head1 Document and 404 page template customization

=head2 Introduction

The philosophy behind MKDoc is to achieve a clean separation between
content (the actual website's data), application logic (the website's
functionality) and presentation (how the website looks).

Separation of content from presentation is achieved through the use
of a template system. The way it works is the following:

1. A user requests a page (i.e. /news/2001/some-news-article/)

2. MKDoc chooses which plugin (snippet of program code) to use for
that URI. In this example, the URI is referring to a MKDoc document,
thus the 'explorer' plugin will be used.

3. On one hand, the code plugin fetches relevant objects from the database,
performs computations which are needed for the desired fonctionality,
and stores results of that computation in a special structure. It then
loads the template that it's supposed and passes it the data structure.

4. From there, the program output (including HTTP headers) is entirely
controlled by the template.

This document explains how to amend step 4, i.e. customize your the
"look and feel" of your website. It is not an HTML writing guide
(there's plenty of good books for that), but tells you what to do to
access different bits of your website from the template file.

=head2 Quickstart

Let's look at a snippet of template code:
(the line numbers are here to make things easy and should NOT appear
in the template code)

    1.  <h1><% var name="Document:Title" encode_html="1" %></h1>
    2.  
    3.  <% if name="Document:Children" %>
    4.    <p>This document has the following children documents:</p>
    5.    <ul>
    6.      <% loop name="Document:Children" %>
    7.       <li>
    8.          <a href="<% var name="URI" %>">
    9.            <% var name="Title" encode_html="1" %>
    10.         </a>
    11.       </li>
    12.     <% end-loop %>
    13.   </ul>
    14. <% else %>
    15.   <p>This document has no sub-documents</p>
    16. <% end-if %>

In this example, the plugin sends the following structure to the
template.

  CURRENT TEMPLATE OBJECT
  =======================
    Document => <document_object>
    URI      => clean URI of the current document
    Session  => When logged in admin mode: <user_session_object>
                Otherwise: undefined value

The "CURRENT TEMPLATE OBJECT" is called the "template stash".

Let's see what we can do with that template stash by starting with
something easy, the template 'var' tag.

    1. <% var name="Document:Title" encode_html="1" %>

First of all you can see that a template tag is different from an
HTML tag because it is enclosed by '<%' and '%>' delimiters. Unlike
XML, template tags do not necessarily need to be closed (it depends
on which tag you use).

In the example above we really say: take 'Title' from the 'Document'
from the template stash, encode it to html and print out its value.
Simple, huh?

Let's look at something a bit spicer:

    3.  <% if name="Document:Children" %>
          some template code to execute if the document has
          children
    14. <% else %>
          some template code to execute if the document has no
          children
    16. <% end-if %>

As you can see, the conditional 'if' tag let's you execute a bit of
template code if a variable is TRUE (in this case, if the document
has children) or another bit if it's FALSE.

Note that the <% else %> block is mandatory if you don't need it, you
could write:

    <% if name="Document:Children" %>
       some template code to execute if the document has
       children
    <% end-if %>

The following is a bit more complicated, but when you get this you'll
be - almost - ready to write your own templates, so let's take it
slowly:

    6.      <% loop name="Document:Children" %>
    7.        <li>
    8.          <a href="<% var name="URI" %>">
    9.            <% var name="Title" encode_html="1" %>
    10.         </a>
    11.       </li>
    12.     <% end-loop %>

The 'loop' tag can be used when the object which you access is an
array, which is the case for the 'Children' object from the 'Document'
object from the template stash.

As you guess, each element of the Document:Children array is a
document in itself. A document object looks like this:

  DOCUMENT OBJECT
  ===============
    Parent      => parent document object
    Children    => array of document objects
    Title       => document title
    Description => document description
    URI         => document URI

For each element in the array, the 'loop' tags creates a little
template containing the inner code, and applies the element
to the template. That means that for each element, it is parsing
a template that looks like this:

  CURRENT TEMPLATE OBJECT (for each child document)
  =======================
    Parent      => parent document object
    Children    => array of document objects
    Title       => document title
    Description => document description
    URI         => document URI

  TEMPLATE CODE
  =============
    1.  <li>
    2.    <a href="<% var name="URI" %>">
    3.      <% var name="Title" encode_html="1" %>
    4.    </a>
    5.  </li>

Which explains why in a loop you have to write
    <a href="<% var name="URI" %>">

Rather than
    <a href="<% var name="Document:URI" %>">

--82I3+IH0IqGh5yIs--