suus.pragmagik.com ================== NOTE: this document is written before developing the actual website, and is used as part of a 'document-driven' development process, meaning that it's used as the blueprint of a to-be-developed application. Parts of this document, or the entire document, may describe things that do not yet exist, or that may be implemented differently. This document should not be considered 'final' until the application is done. What is it? ----------- This document describes the website of Suus Prook, located at http://suusprook.com. Suus is an artist, and the website serves to advertize her paintings. Quick overview -------------- The website consists of three different basic page types: * the 'room view' page This displays the picture of a room containing one of Suus' paintings, the user can select which room is displayed, and what painting hangs on the main wall. Menus are presented to choose from (initially a small set of) different rooms and (a larger set of) paintings. * the 'painting details' page This displays a single painting, along with its details (name, size, etc.). The painting menu used in the 'room view' page is used here too, so the user can select which painting is displayed. * static/text pages Along with the previously mentioned, dynamic (application) pages, there is a number of pages with static content, describing contact information, news, etc. Navigation ---------- Navigation is done from several locations in the page. There are sidebars on both sides of each page, the left one containing links to different parts of the application (one direct link to the 'painting details' page, and one for each static/text page), the one on the right containing links to the 'room view', each one leading to a different room. In the 'room view' and 'painting details view' a menu is displayed, which displays all the paintings in the database (more about that later). The result of clicking on one of the paintings varies depending on which page the menu is presented in: in the 'room view' clicking one of the paintings results in a different painting being presented in the room, in the 'painting details view' the details of the clicked painting are presented. On each page, a help link will be available that explains how the navigation works. (XXX todo) Layout ------ A quick sketch of the layout of the pages:: -------------------------------------------------------- | | | ? | <- help | | | | | | | | | | main content area | | | | displaying room, | | | | painting details | | | | or static content | | | | | | menu to -> | .... | | .... | <- menu to choose | .... |--------------------------------------| .... | choose page/view | .... | | .... | room | .... | | .... | view -------------------------------------------------------- ^ | menu to choose painting The room view ------------- When the user enters the site, (s)he is presented with the 'room view' in some default setting. This view presents a picture of a room with a nice, open back wall, on which one of Suus' paintings is presented. The 'room view' menu allows the user to choose a room, each of the room has a certain default painting, so clicking through the rooms will already present some of the paintings in different settings. The bottom of the screen harbours a menu with all available paintings, clicking one of the paintings will make that painting appear in the currently displayed room. In the painting menu there's also a link to the 'painting details' page (see below) for that particular painting. The 'painting details view' --------------------------- This is a relatively simple view, that displays the painting of choice centered and sized as large as possible in the main content area, along with (located below the painting) some information about the painting, as retrieved from the database (see below). Clicking the painting will open a popup window displaying the painting in a higher resolution. The bottom of the page again shows the painting menu like in the room view. The static/text views --------------------- Both the 'room view' and 'painting details view' are dynamic pages that are built entirely using the database/backend. The text pages, on the other hand, are simple static pages (content from simple HTML files inserted into a macro). Implementation -------------- The application consists of a set of server-side CGI scripts that present the images and rooms, along with a tiny bit of JavaScript code to improve the user's experience. (At first the idea was to write most of the logic in JavaScript, but unfortunately the current state of image handling in JS is just too poor). Back-end ++++++++ * Apache webserver * scripts written in Python, using the CGI interface in an 'API over HTTP' way (every .cgi script is basically a small function that performs a single, simple task) * there's a main HTML macro that defines the layout, the Templess templating language is used to insert data into the template * 'static' pages (containing simple text and images) are generated by converting ReST documents to HTML and placing the results inside the layout (XXX perhaps we stick with the current HTML approach, though, as the maintainer of the site is either someone who knows his HTML well enough, or someone who doesn't know ReST ;) * as database/storage, the Subversion versioning system is used, which provides a means of storage with metadata support (for storing painting details), automatic backup, remote authoring and automatic server updates (using a post-commit hook), etc,; because of the nature of the stored data (mostly images), and since querying the database is not important, a more traditional (SQL) database will not be necessary * scripts: - room.cgi returns a room with a painting pasted into it - painting.cgi returns a painting, optionally resized to a certain size (provided as a GET argument, an int stating the max width or height) Front-end +++++++++ * uses (X)HTML, CSS and JavaScript to present the pages * pages are created in a classic way, using templates on the server-side; JavaScript only serves to enrich the pages * scripts (or snippets of functionality): - change_room(event, roomid, paintingid, title, dimensions) change the room image Notes ----- * to avoid people copying the images, we have to make sure there are copyright notices everywhere, and we may want to decide to use watermarking techniques on the higher resolution images (XXX let's solve our own (c) issues first ): * originally the idea was to make the painting menu animated using e.g. Rico, but since there wasn't too much time, and the result without animation looks quite nice, we decided to discard the idea for now