/[site-engine]/site-engine-1/README
ViewVC logotype

Contents of /site-engine-1/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.1 - (show annotations) (download)
Mon Sep 24 09:37:37 2001 UTC (22 years, 8 months ago) by slef
Branch: MAIN
CVS Tags: alpha, HEAD
Branch point for: macroland-1
Added documentation.  More bugfixes.

1 -*- text -*-
2 Web Site Engine
3 ---------------
4 Web Site Engine - server software for dynamic sites
5 Copyright (C) 2001 MJ Ray
6
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 2 of the License, or
10 (at your option) any later version.
11
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16
17 You should have received a copy of the GNU General Public License
18 along with this program; if not, write to the Free Software
19 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
21
22 Conceptually, the basic system is composed of five core parts: the
23 discussion system, the publishing system, the user registrations, the
24 section editor and the ad server.
25
26 The discussion system is using an nntp server as the backing store, as
27 it's basically an optimised network-connected database for discussions
28 and it gives easy access to people using newsreaders if you choose.
29 The other sections use the simplesql library to talk to a database.
30 We use PostgreSQL, but there's no reason why it won't work with MySQL
31 with a few tweaks, as far as I know. If you get it working, I'd love
32 to get a patch, but I have other priorities. I strongly recommend
33 PostgreSQL, though.
34
35 The typical journey through the web site is seen as something like
36 this:
37
38 Starts with the list of sections;
39 Goes to a particular section which contains a list of articles in that
40 section;
41 Goes to a particular article which contains a list of comments on that
42 article;
43 Goes to a particular comment.
44
45 At each stage, of course, the user can backtrack and pick a different
46 path at the previous list, or they can add to the available content by
47 suggesting a new comment, article or entry in a section. Whether or
48 not this is accepted and displayed by default will depend on the
49 policy of the site, but for my site, I intend comments to appear
50 automatically and everything else to wait in the chooser for an admin
51 to approve it.
52
53 The ad server, of course, will output in each page. The admin section
54 design wasn't, so it can probably be improved greatly.
55
56 It's a very simple application at present. There's under 1300 lines
57 of code in the entire system (0.8 release). Some of it isn't very
58 pretty code yet and there are some noticeable gaps (eg session
59 management, RSS feeds and the advert server module that was
60 postponed), but it does work well enough to run a site. Speed is also
61 quite poor at the moment, but we work around that for now with some
62 clever webserver tuning (which might actually be the right way to do
63 it anyway). Any help on correcting any of these problems will be
64 gladly welcomed.
65
66 Finally, a quick tour. You can look at the system as written in a
67 number of layers:
68
69 1. There are back-end modules which try to make the content modules'
70 jobs easier by handling the "grunt work" of talking to the database,
71 nntp/news server and the webserver via CGI. The CGI module also
72 handles templating, but I'm not entirely sure about whether that's the
73 right place for it. Probably is.
74
75 2. There are content modules which all provide some basic methods
76 (show, list, submit!, choose!) for interacting with them and might
77 provide extra functions (eg user module also offers valid?, priv?,
78 remind! and set-priv!).
79
80 Basically, each part has show (a single item), list (a number of items
81 in a table of contents-style thing), submit! (add an item), chooser
82 (present a list of items for administration) and choose! (update that
83 list). The specifics of how they work varies, but for example, in the
84 discussion system, show returns a reader comment, list returns a
85 summary list of comments, submit! adds a comment and chooser/choose!
86 allows the admin to remove illegal comments.
87
88 Those methods aren't actually what the user part does at all. It
89 provides three different methods: valid? which checks a username and
90 password; add! which adds a new user; remind! which sends out a
91 reminder; and two the same for admin, which are chooser and choose!.
92
93 3. There is the "glue code" which actually creates the web site that
94 users see by combining the content modules in different ways and using
95 the CGI module to communicate it to a waiting world. The glue code in
96 CVS is the stuff I've written for tsw, but if you change this layer,
97 you could have a completely different web site. This accounts for
98 about half of the current system's code, though, so replacing it is no
99 small task.
100
101 4. There are the templates, which are used by the glue code as
102 parameters to the CGI module for formatting the output from the site,
103 headers and all. I particularly like our "boom screen" which the
104 exception handler calls. I've been seeing too much of it lately.
105
106 5. There are a few helper scripts for particular tasks. For example,
107 on our site, one sends an account request to our server admins and one
108 cancels messages on the nntp server. There should also be one to send
109 out password reminders. These will hit CVS after I've tested them.
110
111 Right, that's that. If you take a look and it all seems too daunting,
112 look again after I add more comments, documentation and auxiliary
113 files. If you understand it now, then I'm here waiting for your code
114 ;-) Oh, and when hacking, reading the "TODO" would be a good idea.
115
116 The project web site is at
117 http://savannah.gnu.org/projects/site-engine ... please report any
118 bugs into the bug tracker there.
119
120 Please, ask me more questions, as after a page, I start rambling.

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26