cedar-rapids-online.html

/software/cedar-rapids-online.html

https://github.com/tjr/tjr.github.com
HTML | 231 lines | 185 code | 46 blank | 0 comment | 0 complexity | a2ed5f0e9a222437b8b756e77268ce81 MD5 | raw file

<html>
<head>
    <title>Cedar Rapids Online - a CherryPy web application</title>
    <link rel="stylesheet" href="/css/traditional.css" media="all" title="Default" charset="utf-8">
</head>

<body>
<div id="content">

<h1>Cedar Rapids Online</h1>

<p>

a web application by <a href="/">Trevis Rothwell</a>
</p>

<hr>

<a href="http://picasaweb.google.com/lh/photo/1oP34MQeXoF6KDHG3dmrrQ?feat=embedwebsite"><img src="http://lh4.ggpht.com/_IsIl4HvOgJw/R3bgPQ_05AI/AAAAAAAAA4g/PtgjABVNHak/s288/downtown-cedar-rapids-05.jpg" class="photo" align="right"/></a>

<h2>Quick Links</h2>
<ul>
<li><a href="http://github.com/tjr/CedarRapidsOnline">Get the source code</a></li>
</ul>

<h2>Background Information</h2>

<p>
Much of what I know about building web applications I learned from Philip Greenspun's
<a href="http://philip.greenspun.com/seia/">instructional materials</a>. To execute on what I
learned, I decided to build an online learning community website for residents of
Cedar Rapids, Iowa.  I originally built it using Python and PostgreSQL, running directly
on top of the <a href="http://www.modpython.org/">mod_python</a> Apache module.  Unfortunately,
either there was very little interest on the web for a Cedar Rapids online learning community,
or I did a woeful job of marketing my project.  Maybe a little of both.  In any event, after
it became clear that the vast majority of registered users were Russian spammers, I shut the
site down.

<p>
However, even if the site was not a commercial success, it was still an example of the kind
of work I can do, so I eventually decided to dust it off, polish it up, and unleash it as part
of my project portfolio.  I spent about a week of evenings recoding the application to run
in the <a href="http://www.cherrypy.org/">CherryPy</a> web framework, and released the source
code under the GNU Affero GPL.  It could still stand some code refactoring and other miscellaneous
improvements, but I'm not really interested in running it as a real user-facing website right
now, and have mostly moved on to other projects for the time being.

<p>
The remainder of this document explains the software architecture and some design decisions
from the point of view of getting ready for real users.


<h2>Design Goals</h2>

<p>
This project is a traditional online learning community website, with the target audience
of residents and potential future residents of Cedar Rapids, Iowa.  The key features are:

<ul>
<li>User accounts and authentication.</li>
<li>Article documents, with optional user comments.</li>
<li>Discussion forums, as user-generated content.</li>
<li>Event calendar, as user-generated content.</li>
</ul>

<p>
Apart from building the software, this project also requires magnet content in the form
of articles (ideally with some pertinent photography).

<h2>Implementation</h2>

<h3>The Big Picture</h3>

<ul>
<li>The web site is served simply by the built-in CherryPy web server. If this ever proves
unable to handle the user load, the CherryPy documentation includes suggestions for other
serving options.</li>
<li>The data is stored in a half-dozen PostgreSQL tables.</li>
<li>The web pages are generated using Python scripts built with the CherryPy web library
and the PyGreSQL database library. No HTML templating language is used, as most of the
HTML content is generated from data in the database, and I have no problem writing
relatively small amounts of HTML directly in Python.</li>
</ul>


<h3>The User Interface</h3>

<ul>

<li>Index Page<br>
  The main index page includes an overview text describing the purpose of the
  website, and provides links to the core functionality through a menu at the
  top of the page.  (This menu is also present on the other pages.)  Without logging
  in, the user can view the article pages, the discussion forum, and the event calendar,
  but cannot contribute any information to the site.
</li>

<br>
<li>Register Page<br>
  The user registration page lets users create a new account on the site. Users must provide
  a name (which will be displayed on most content they create on the site), an email address
  (semi-validated through regular expressions), and a password.  They may optionally provide
  the URL of their own website.  Based on past experience, full email validation, by way of
  (say) sending a site-generated password to the user's email account can be a hindrance for
  some users. While the site is new and extremely eager to attract as many new users as
  possible, this hurdle is not being presented. As the site grows, it may be optimal to
  require full email address validation.
  <br><br>
  Prior to a successful registration, the system verifies that the provided email address
  is not already in use, as email addresses serve as the user's login ID, and as such must
  be unique.
</li>

<br>
<li>Login Page<br>
  Registered users can log in by providing their email address and password.
</li>

<br>
<li>Articles<br>
  The main articles page is used to display an index of magnet content articles. The
  article index is itself an article named "map"; going to "/articles/" presents the same
  content as going to "/articles/map".
  <br><br>
  The articles themselves are accessible by passing the name (or, more precisely, the "slug")
  of the article to the "/articles/" page.  For example, an article with the slug
  "eating-out" would be viewable at the URL "/articles/eating-out". Each article can be
  optionally set to allow user comments or disallow them; users must be logged in to post
  comments.
  <br><br>
  Note also that the main index page ("/") is an article as well, named "welcome". This is
  slightly non-sensical, but easily allows the main index to be editable from the articles
  admin interface, rather than offering a separate interface just for the index.
</li>

<br>
<li>Discussions<br>
  The discussions page displays a listing of user-generated discussion threads, in
  chronologically-descending order. Like the articles page, each discussion thread is
  accessible as a sub-URL: "/discussions/" shows the index, and "/discussions/42" shows
  discussion thread #42.  (Since articles are generated only by admin users, and there
  will ostensibly be fewer articles than discussions, articles are identified by a
  memorable slug name, while discussions are identified by number. A slug could be
  generated based on discussion subject, if more SEO-friendly URLs are desired.)
  <br><br>
  Logged-in users can start new discussions from the index, and add replies to existing
  threads from that thread's page. Nested threading is not implemented, in the hopes that
  discussions will stay on topic.
</li>

<br>
<li>Events<br>
  The events page is very similar to the discussions page. Logged-in users can create new event
  listings; the main events index shows a listing of events in chronological order (with
  headers automatically inserted to separate months and years), and individual event
  details can be viewed at, e.g., "/events/42".  No comments are allowed for events.
</li>

<br>
<li>Admin Pages<br>
  The admin pages are restricted to logged-in users at the admin level (2 or higher, though
  presently there is no distinction for any user level above 2).  There are admin pages
  to create and edit articles; delete comments; delete discussions; delete events. Throughout
  the site, if the user is an admin, there are links attached to user-generated content to
  go to page to delete the specified content. For example, for every discussion and reply,
  there will be a link to delete it.  If a discussion is deleted, all replies are also deleted.
  If a reply is deleted, only that particular reply is deleted.
</li>

</ul>

<h2>Data Model</h2>

<p>
There are five tables in the data model:

<ul>
<li>users</li>
<li>articles</li>
<li>discussions</li>
<li>discussion_categories</li>
<li>events</li>
</ul>

<p>
Article replies are stored as articles with a non-null "refers_to" field pointing
to the parent article. Discussion replies are stored with a non-null "refers_to" field
pointing to the parent discussion.  The discussion categories table is currently unused;
when an online community is young, it's better to not segregate users into discussion
categories, but rather keep all discussions together so people can find each other.  As
the community grows, discussion categories may be implemented.

<p>
The SQL tables are written in PostgreSQL format, and are viewable (and documented in
more detail) in the <a href="http://github.com/tjr/CedarRapidsOnline/blob/master/sql/crdb2.sql">
code repository</a>.

<h2>Future Directions</h2>

<p>
The existing design should be a fairly robust online learning community system. This
is not a research project; online communities have existed since the mid-1990's, and
much has been tried and either proven successful or failed.  Any changes that need to be
made in this particular online community will have to be determined based on usage.

<h2>License</h2>

<p>
The software is licensed under the
<a href="http://www.gnu.org/licenses/licenses.html">GNU Affero GPL</a>.

<p>
<img src="/images/agpl.png">

<h2>References</h2>

<ul>
<li><a href="http://philip.greenspun.com/seia/">Software Engineering for Internet
Applications</a></li>
<li><a href="http://philip.greenspun.com/wtr/dead-trees/">Database-Backed Web Sites</a></li>
<li><a href="http://philip.greenspun.com/sql/">SQL for Web Nerds</a></li>
</ul>

<hr>
<i><a href="mailto:tjr@acm.org">tjr@acm.org</a></i>

</div>
</body>
</html>