About this documentation

Reading through this page will give you an overview. The real documentation of the template is in the files itself. There are only five files you must have to get a one page site up and running. I recommend you read this overview and then go through those five files and see the comments in them. So, in other words, the documentation has two parts: this page and the template files themselves.

A simple template - What does it do?

Drikatruu Omegar3 (DO3) is a simple python template for a static website hosted on Google App Engine. It allows you to put your header, sidebar and footer in a separate file from your page content. The pages of the website are formatted via an easy to customize style sheet. The same content page can be combined with different template pages and style sheets if required - for example if you want to make some pages also easy to print or easy to display on mobile devices.

The content files allow you to specify user and search engine friendly title tags, key words or page descriptions, etc. This means you can specify for example

"title" : "Hotels in Miami"

on your content page for Hotels in Miami. When the final page for display is assembled, the placeholder [[[title]]] in the template page will then be replaced by "Hotels in Miami" in the HTML head section of that page. The same logic works for any other [[[tags]]] you want to use and gives you a powerful and flexible tool to individualize all pages.

You can define tags on the template page and on the content page - DO3 does not really care. Just make sure that you use different tags. You could use this technique also to pull in adsense adds for example - into the body of the page or anywhere else.

A simple template - What does it not do?

This template does not connect to a database like MySQL or Google Bigtable, the App Engine database. Why? Because I like to keep things simple and DO3 is meant to be a template for static little websites. If you want to add database functionality, you can do that of course, but you don't need to. All the information is in static files. Configuration is done in separate files which are easily linked to the content files. Minimum complexity - maximum flexibility and portability.

What do I need to know, what do I need to do?

I am not a programmer and don't intend to become one. Python is a very easy to read language - it looks very much like pseudo code. Without being able to program in Python, you will be able to make small changes. More important than Python is to have a basic understanding of HTML and, if you want to change the style of the site, of CSS. Since I added a lot of comments into all template files, including the CSS file, you might find DO3 an easy way to get started with App Engine hosted websites. This at least was my design objective.

  • Upload the template as is and get it running on App Engine. To upload the template you need to install the App Engine SDK. FTP will not work. A few changes need to be made to the App Engine configuration file. See the App Engine Configuration section below.
  • Add content for your first page. Then customize a template file for navigation elements, header and footer. See the Content Creation section below.
  • Link your page (content plus template) to a URL. See Linking a Page to a URL section below.
  • Make changes in the style sheet to change things like font family, colors, layout of page elements, etc. See Changing the Style section below.
  • Add all other pages. Usually they will link to the same template and you need to add the new content only.

The five must have files of DO3

All in all you need only 5 files to get a very basic website running:

  • app.yaml configures the whole domain and must be in the root directory.
  • mainDrikatruu.py configures our website, which can be in a sub folder of the domain.
  • mainPage.py is the main content page and contains the body text of the page often named index.html on traditional websites.
  • t1.py is the standard template page and contains header, footer, sidebar and layout related information.
  • engine.py is the program which assembles the final pages from their two main components (content and template).
  • all other files like css, images, etc. you do not really need - the pages will look flat, but they will appear.

The repository with the files for DO3 has more files than these five - it comes among other files also with this documentation page - but all those other files and folders are not absolutely essential. Look at them and keep what you find useful.

App Engine Configuration

Not much one needs to know here. That is what I like about App Engine. If I think back how long it took me to figure out how I had to change configuration files for Apache and PHP to do the same thing on a LAMP stack, getting my first site up and running on App Engine was a breeze. And I had never used Python when I decided to try out App Engine.

I propose you read the App Engine Documentation but if you prefer it summarized, here is how it works.

The file app.yaml goes into your app engine root directory and sends all incoming requests of a certain URL pattern (e.g. all urls with a path that starts with do3 in the case of this site) to a configuration file for a specific project (mainDrikatruu.py in the case of this site). You will immediately get the idea when you look at the content of app.yaml, which also comes with a lot of comments to guide you through the few necessary changes you need to make.

In app.yaml you change 12flat (that is the name of the App Engine project this site is linked to) to your App Engine project name. This has nothing to do with the domain you are going to use in the end. Domain issues are dealt with much later. Then you need to list all subdirectories you use for your static files. It is all explained in detail in the comments of app.yaml. This is necessary for your image folder, your CSS folder, your folder for JavaScript files, etc. - all folders for files which should not be interpreted by the Python interpreter. The project folder itself (drikatruu), the folder for the content pages (contents) and the templates (templates) contain python files and are not listed as directories for static files. Then, last not least, you have a URL regex pattern to catch everything not dealt with above and direct it to mainDrikatruu.py

The file mainDrikatruu.py can stay in the drikatruu folder and is the configuration file for our template powered project on that domain. Of course you can change the name of the drikatruu folder, but you will need to change the name at a few places. Since 'drikatruu' is not exactly a common word, it's easy to find and replace. App Engine knows how to find mainDrikatruu.py through the app.yaml file, where you find it linked to requests with do3 in the URL path. You will want to change do3. It is explained in app.yaml and in mainDrikatruu.py, the two files you need to customize.

mainDrikatruu.py has two main parts: the upper part with classes and the lower part, where you find def main(). For each page on our website there need to be entries at three different places on this page:

  • in the bottom section, under def main() add a line with the URL path you want to link to a page
  • copy one of the classes in the upper section and give it the name you refer to in the step above
  • last not least, add or change a line under def main() - the two parameters point to the respective files in the folders contents and templates. By the way, best to keep the name of those two folders unchanged.

I did not want to host the Drikatruu Omega3 template on the domain root, but it is of course possible. Just modify the lower part of mainDrikatruu.py as explained in the comments of that file and don't forget to also change the URL/path pattern in the app.yaml file accordingly.

If you add new subfolders, you need to have an empty __init__.py file in each new subfolder for python to be able to find it the easy way. You can just copy paste one of the files in the template folders to your new folders.

Content Creation

  • First, take one of the pages in the contents folder and change it to what you want. The original Omega3 files come with plenty of comments, explaining what happens where. You can change the name for your content files and add as many as you want.
  • Take the t1.py template file from the templates folder and change the field names in the nav bars. Change the logo and change the content of the footer. It's all there in one file. Do not change the name of style tags like <div> etc. and do not remove any - you can do that later.
  • Tags like the title tag which are part of the header and change with every page are not set in the template itself. Here we use [[[placeholders]]] in triple square brackets and define the corresponding value on the respective content page. The replacing of the [[[placeholders]]] is done at the time of page assembly by the file engine.py, which you find in the main project folder - drikatruu in this case.
  • You will notice that I defined header, sidebar and footer in the template file itself. If you want to have a more modular setup, you will create them as separate files and call them from the template files. I like it simple and decided to keep it all together.

Changing the Style

Once you have set up a page or two, you might want to play around with the styles defined in the style sheet. The style sheet is called by the template. So if you want different styles or layouts, just link to a different style sheet from your template page. Playing around with the style sheet is probably going to eat more of your time than setting up the content and structure of the site. This is not a weakness of Omega3, but lies in the nature of cascading style sheets. I have tried to make things as easy as possible, by structuring the style sheet as clearly as I could and adding hopefully helpful comments wherever possible.

Associating the App Engine Site to your own Domain

This is well explained on the Google App Engine site. It involves opening a Google Apps account, which is free and can be done in a few minutes. You will link your own domain to the App Engine project via the administration panel of your Google Apps account. Again, check out the documentation on App Engine for details. You can do it whenever you want to. I propose you get the site up and running and check it out on your_project_name.appspot.com first and later link it to your own domain. This site can also be found on 12flat.appspot.com

Linking a Page to a URL

This you do in mainDrikatruu.py. You also set the template to be used there. In the original version as it is now, all pages link to template t1, but you can link each page to a different template, if you like or need to do so. Looking at the comments in mainDrikatruu.py will give you the idea right away.

Compare this page formatted with t1.py and then with plainVanilla.py. It is the same content file linked to different template files.