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.