System Overview

The system running at iptel.org is powered by Drupal content management system. Drupal makes the management of the site easy and hopefully it will be easier for us to keep it up-to-date. This page should give the reader overview of the whole system, including how the pages are created, stored, and managed. After reading this page you should see the "big picture" and you should be able to lookup additional information if needed.

Nodes

In Drupal web pages are stored in MySQL database in form of nodes. Node is the basic piece of content in Drupal. When a new page is created then Drupal creates a new node and stores it in the database. For the sake of clarity you can assume that node is equivalent of page (and yes, we know this is not always true).

Each node has a unique identifier. The identifier is a number that is unique across the entire site. Every node can be accessed/updated/manipulated using its node id. For example http://iptel.org/node/343 will display the node with id 343 which happens to contain the information about our local certification authority.

Node in the system have no implicit relationship, nodes are independent of each other and their content is organized into the site hierarchy using keywords which are attached to nodes (see below). There is nothing like parent or children nodes (although it may appear so if they have URL aliases at different levels in the site hierarchy). The Drupal site is just a collection of nodes stored in the database plus some additional meta-information that is used by the system to render the contents of nodes to the user.

Each node has some contents and meta-information about the node or the contents. The content of a node can be stored in various formats. The most common one is plain HTML, but it can also be Wiki text, PHP script, simplified HTML and other formats (the list of supported formats is extensible through Drupal modules). The content management system can determine the format of the node content and render it properly to the user. The format of the node contents is determined by the user who created the node at the time of creation (but it can be changed later).

In addition to contente each node contains some meta-information about the node itself. The meta information includes (but is not limited to):

• Date and time of node creation.
• Date and time of last modification
• Author's username
• Node title
• Format of node content

and much more. See the Drupal documentation if you are interested in details.

HTTP URLs

Although each node in the system can be accessed using the node id, this approach is neither very flexible nor intuitive. The URL of form http://iptel.org/node/343 give the user no hint as what to expect from the page.

Each node in Drupal system can have one or more URL aliases attached to it. Our node 343 from the previous example has URL alias "ca" and thus http://iptel.org/node/343" is also available as http://iptel.org/ca. The alias is simply the local part of the HTTP URL. When Drupal receives such URL it will internally translate the local part to node id, lookup the corresponding node in the database and then render its contents to the user.

There are two ways how HTTP URL aliases can be created:

1. Manually

   The user can specify the URL alias to be created for the node when creating a new node. The node creation form contains field named "Path alias" and this is the place to specify the URL alias of the new node.

2. Automatically

   If the user specified no initial URL for a newly created node then the system will create one automatically. It will take the title of the node, replace spaces with underscores and use the resulting value as URL alias. For example if you create node with title "My new page" and specify no URL alias manualy then the system will create URL alias "my_new_page" which will be available as http://iptel.org/my_new_page

Keywords (a.k.a. Classification or Taxonomy)

We mentioned before that there is no implicit relationship between nodes, there is nothing like parent or children nodes. But to be able to organize nodes into site hierarchy we need to specify that one particular node is parent of several other nodes, we need to be able to place nodes at various levels document tree of the site. And this is exactly what keywords are used for.

Basically what we need to do to create the site structure is to create a bunch of keywords, define their relationship and then assign them to nodes. Keywords in Drupal are called terms and they are arranged in groups called vocabularies. A vocabulary is a collection of keywords are somehow related, for example keywords "red, gree, blue" can be arranged into vocabulary called "colors".

A simple example would not harm: Let's suppose that we would like to create a collection of pages to describe FCP (Firewall Control Protocol). There already is vocabular called "Protocol" in the system and we would create a new keyword in this vocabulary called "FCP".

As the next step you can assign your newly created keywords to nodes/pages that are somehow related to FCP. Keywords can be assigned to nodes any time using the node creation page.

Once we have the keyword and a bunch of nodes assigned to the keyword then we can let the system to do the magic and display all pages that contain something about FCP simply by typing http://iptel.org/protocol/fcp in the browser. The system would search through the list of all nodes and display the list of those that have the "FCP" keyword from "Protocol" vocabulary assigned. There is similar URL for every keyword defined in the system, the format is always http://site/vocabulary/keyword.

One can also specify more complex hierarchy of keywords, let's imagine a purely hypothetical project called SERi which contains modules, documentation, scripts, core and other. We could then define a vocabulary called "SER" and create the following hierarchy of keywords in the vocabulary:

SER
 |
 + module
 |   |
 |   +-acc_db
 |   +-acc_syslog
 |   +-mysql
 |   +-registrar
 |
 + documentation
 + core
 |   |
 |   +-transport
 |   +-parser
 |   +-memory
 + script

Later on when someone adds text/node/page related to "registrar" module he/she will assign "registrar" keyword to the node and the node will automatically pop up under http://iptel.org/seri/modules/registar and possible other places in the document hierarchy that reference the registrar module documentation.

A nice property of the keyword system is that you can just describe what comes to your mind, dump it in the system. You (or someone else) can then classify the contents later. Also someone else can easily update or change the site structure without touching nodes (created possibly by someone else).

Last, but not least, the classification/keyword system makes nice features such as automatically generated sitemaps and RSS feeds possible. The site map of the iptel.org site is generated automatically from hierarchies of keywords, for example.

Menu

You have probably noticed that there is at least one menu on the right side of each page, on some pages there are two menus. In Drupal you can create your own menu and tell the system that it should be displayed only if the HTTP URL matches some expression.

For the FCP example mentioned above I created menu called FCP and that menu is displayed on every page where the local part of HTTP URL begins with fcp/. This menu contains basic navigation for FCP related stuff. You could see it at http://iptel.org/fcp

Menus can be create at http://iptel.org/admin/menu (The link will only work if you are logged in).

Comments

Registered users can leave comments on every page, they can also react to other comments and so on. Comments are always displayed at the end of every page.

Access Control

The system also supports some sort of access control. The system is similar to UNIX users and groups. Users can be members of groups and each node can be made viewable to one or more groups only. Users that are not members of the group or unauthenticated users will be not able to see the node.

This way one could create administration related pages that are only viewable by administrators, for example.

Automatically Generated Contents

Site map

The keyword system is used to generate automatic sitemap. If you go to http://iptel.org/sitemenu then you will see a page listing all keywords and their hierarchy. If you click on a keywords then you will see nodes/pages that belong to it. This is the map of the entire iptel.org site. You, as the site administrator or user, just need to create keywords and arrange them into a tree, the system takes care of everything else.

Search Database

There is cron job which runs once per day through newly created or modified nodes and generates an index database. The index database is the used when you search for a keyword at http://iptel.org/search.

RSS Feeds

The system can also generate automatic RSS feeds. You can say, for example, that you are interested in all changes in the SER part of the site and each time somebody edits existing stuff or adds a new SER related page then the system will update the feed.

News

News page is similar to RSS feeds. Each time you edit or add something then you can create a news node and describe the changes you have done to the readers. News node is a regular node which has one of the keywords from "News" vocabulary assigned. Then there is a special page (called news agreggator) which lists all news (the most recent first): http://iptel.org/news

Glossary

If you take a look at any longer page then you may notice that some words contain tiny "i" superscript. This means that there is an entry in the site glossary for the word and if you hover your mouse over the word then you will see the explanation. If you click on the superscript then it will take you to the corresponding glossary entry. The whole glossary is available at http://iptel.org/glossary. The contents of glossary is NOT generated automatically, you need to create glossary definitions manually.

The superscripts are generated automatically and they only occur at the first occurence of any given word on the page. If you add a new entry to the glossary then it will become available on all pages on the site.