thalassa/examples/Smoky/smoky_readme.txt

                               Thalassa CMS
                ``S M O K Y''   S I T E   T E M P L A T E



== OVERVIEW

Smoky is a site template for Thalassa CMS.  It provides a site with a main
page, a feed (either a news feed or a blog, whichever better fits your
needs) exported to RSS, a contact form and a guestbook; more pages can be
added to it by the user.  Smoky supports several color schemes and allows
for other customizations.

The official site of Thalassa CMS is created with this template, using the
``cloudy'' color scheme.

Please note that the ``thalassa.ini'' file and the ``base/'' subdirectory
with all its contents should be considered a part of the template, not
intended to be customized by the user.  Certainly, they still can be
altered to fit yor needs, but such alteration may require deep
understanding of Thalassa (as well as XHTML and CSS) and is generally not
recommended; if you really understand how Thalassa works, and your
understanding is deep enough, you might want to create your site from
scratch, not using any templates.  If you use the template, please note
that editing its basic files can make it too complicated to migrate to
future versions of the template.

Except these ``thalassa.ini'' and ``base/'', all files in the Smoky
template root directory are customizable; most of them (with the exception
for ``config.ini'' and ``feedback.ini'') provide useful defaults for all
aspects of your site configuration, so you can tune the template to your
needs step by step.



== PREPARE THE TEMPLATE

The template needs to be (kind of) put together before you can use it.
The source files reside under $thalassa/examples/Smoky and
$thalassa/examples/Common; the trick here is that the Common directory's
contents is used by other templates as well.  Besides that, the template
supports different message languages, but only one per copy.  As of
present, ``en'' (for English), ru_koi (for Russian, koi8-r encoding) and
ru_utf (for Russian, utf-8 encoding) are supported.

To prepare a fresh copy of the template, change to the $thalassa/examples
directory and type one of the following commands, as desired:

    make _smoky_en
    make _smoky_ru_koi
    make _smoky_ru_utf

Afterwards, be sure to *COPY* the directory you've just made to a location
outside of the Thalassa source tree.  Don't customize the template right in
the $thalassa/examples/_smoky_XXX directory, because ``make clean'' issued
for the Thalassa source will simply rm-rf it, wiping out all your work.

The rest of the text is written in assumption you do it in your copy
outside of the Thalassa tree.



== QUICK START

First of all, *EDIT* THE config.ini FILE!  Some of the parameters
configured there have no defaults; for instance, if you don't set all the
required file paths correctly, then your site generation will likely fail.
The file is self-documented and is relatively short.

Once you're done with your config.ini file, it is strongly recommended
to try generating the site; to do so, run

    thalassa gen -a

in the root directory of (your modified copy of) the template.  Sometimes a
more sophisticated command like

    thalassa -c path/to/your/template/copy gen -a

may be useful.

Please note that HTML files generated using the Smoky template refer a lot
of things (such as the CSS file and service images) by absolute URIs, so
the whole thing will not work if you just point your browser to the local
directory with your generation results.  A working HTTP server, such as
Apache, is required for the generated site to work properly.



== ADDING PAGES

Pages are normally added to your site by creating source files for them
within the ``db/pages/'' subdirectory.  These files have the ``headed text''
format, which is described in the Thalassa CMS documentation on a dedicated
page named ``headed_text.html''.  You can view it online at

    http://thalassa.croco.net/doc/headed_text.html

or locally in the ``doc/'' subdirectory contained within the official
Thalassa source tarball (just point your browser at it to view the file).

The Smoky template recognizes three page types: ``page'' (the default),
``story'' and ``feed''; the default ``page'' type is the simplest, it only
displays the title and the body; ``story'' differs from the ``page'' in
that it also displays the creation date, and ``feed'' also has a
navigation panel with arrows for previous/next items of the feed and for
the position of the current feed item in the feed digest (the ``news'' or
``blog'' page or page series).

The content generator adds the ``.html'' suffix, so if you add a source
file named ``foobar'', you'll get a page named ``foobar.html'' right in
the root directory of your tree.  Please note Smoky is incapable of placing
pages in subdirectories (well, Thalassa itself lets you build whatever
directory trees you want, but Smoky is too simple for that).

Initially there are five sample source files, for a page, a story and three
feed items; viewing them will give you the basic idea on what the files
should look like.  Feel free to remove the sample files once you don't need
them anymore.

To add a page or a story, it is sufficient just to add the file and
rebuild.  To create another item in your feed (be it a blog or a news
feed), add the source file, be sure to set its type to ``feed'' and add its
name to the list within the ``pages/_feed'' file.




== ADDING ARBITRARY FILES

Make a subdirectory ``files/'' in your site source directory (the directory
where the thalassa.ini file resides).  Everything you place in that
subdirectory (including its own subdirectories, if any, with all their
content) will be copied into your website tree, under ``files/'' subdir,
and will be available by ``files/...'' URIs.

Please note that in the present version of the template, hidden files (the
files with names starting with a dot ``.'') as well as symlinks are ignored
within the ``files/'' subdirectory.



== FURTHER CUSTOMIZATION

1. Edit the ``mainmenu.ini'' to modify the main menu of the site to fit
your needs.

2. Replace the files ``logo.png'' and ``favicon.png'' with your own images.
Please note that the favicon.png file should contain an image of exactly
32x32 pixels.  As of the ``logo.png'', it can have any size you want, but
the Smoky template displays the image having at most 100 pixels at each of
the two dimensions.

3. Edit the ``feedback.ini'' file to set up your contact form.

4. Edit the ``srvtexts.ini'' file to customize the texts shown on various
static pages of the site; edit the ``cgitexts.ini'' file to customize some
of the texts that appear on interactive pages.

5. Edit the ``db/pages/premod'' file to customize the premod.html page of
your site.  Or, if you don't need this page, then remove the file and be
sure to remove the link to it from the ``srvtexts.ini'' file (see the
text_premod_note parameter in the file; you might want to make it empty).

6. Once your guestbook attracted a lot of comments, edit the file
``guestbook.ini'' to change the page with the comments into the ``archive''
state (either with disabled comments, or with comments kept enabled, on
your option), and create a new (empty) guestbook page.  The file is
self-documented.



== ADVANCED CUSTOMIZATION (EXPERTS ONLY)

If you want to add your own sections to the configuration, please create a
separate file for that purpose (e.g., local.ini), then edit the config.ini
file, uncomment the line

  # inifiles =

within the [general] section and add your file name to it, so it becomes

  inifiles = local.ini

Please don't use the thalassa.ini for this purpose.  It is better to keep
strongly visible the border between the template's implementation and the
customizing changes you make, e.g., for the case you once want to update
the version of the template.


In case you need to add more CSS rules, e.g., for your own classes or
objects, then just create a file named ``local.css'' and add all the
desired CSS code there.  The generator will pick the file's content
automatically; you can check if everything's okay by viewing the
(generated) ``style.css'' file found in the root of your web tree.


In case you're not satisfied with the .htaccess file the template
generates, or if you don't need it at all (e.g. if you set all necessary
options right in your HTTP server's configuration), then edit the
``htaccess.ini'' file to fit your needs (make the file empty to avoid the
``.htaccess'' file generation altogether).



== MANAGING USER PERMISSIONS

The following ``roles'' are defined by the Smoky template:

   * ``admin'' - permitted to do everything the CGI is capable of;
   * ``moderator'' - permitted to see hidden comments, show and hide
     comments, remove comments from the premoderation queue, but not
     delete nor edit comments;
   * ``poster'' - permitted to post comments without moderator's
     approvement;
   * ``superposter'' - permitted to post comments without moderator's
     approvement and to edit/delete their own comments, including
     older ones.

In the present version of the Smoky template there's no way to prevent
anonymous users from posting comments (but only through the premoderation
queue).  If this is a problem for you, please contact the author; Thalassa
itself readily allows this, the only problem is to add the appropriate
option to the template.

Once the user signs up for an account, (s)he automatcally obtains the
possibility to see his/her own comments, even hidden, and to edit the own
comments for 30 minutes since the comment is posted.

To grant a user one of the roles mentioned above, go to your CGI user db
directory (the one specified as [options cgi]/userdbdir in your
config.ini), change to the ``_users/NNNN'' subdirectory (where NNNN is the
login name of the user), open the file named ``_data'' in your preferred
text editor and add a line like

   roles = admin

or

   roles = moderator, superposter

BTW, this is the simplest way to create the ``administrator'' (privileged)
account for yourself: just register it as an ordinary user through the
web-interface, then add the ``admin'' role as explained above.