The 20 Minute Wiki by Kevin Dangoor

There is a printable version of this document.

This is the text version of the "20 Minute Wiki" video (40MB QuickTime). (See video help for more information about viewing the videos.)

To go through this tutorial, you'll want:

1. docutils 0.3.9 or later, which is used for formatting. You could get away with not having docutils, but it's not as much fun. easy_install docutils should get you what you need. 2. A web browser 3. Your favorite editor 4. Two command line windows (you only need one, but two is nicer.) 5. A database. If you don't have one, your best bet is sqlite 3.2+ with pysqlite 2.0+.

This tutorial doesn't cover Python at all. Check the docs section for more coverage of Python. The Quickstart TurboGears has a command line tool with a few features that will be touched upon in this tutorial. The first is "quickstart", which will get us up and running quickly.

tg-admin quickstart

You'll be prompted for the name of the project (this is the pretty name that human beings would appreciate), and the name of the package (this is the less-pretty name that Python will like). For this tutorial, we'll be using these values:

Enter project name: Wiki 20 Enter package name [wiki20]: wiki20 Do you need Identity (usernames/passwords) in this project? [no] no

This creates a few files in a directory tree just below your current directory. Let's go in there and you can take a look around.

cd Wiki-20 Now Serving: Number 1 You may have spotted a file called start-wiki20.py. This is the startup script for the built-in web server. Let's run it!

python start-wiki20.py

Point your browser at http://localhost:8080/, and you'll see a nice little welcome page with the current time. (If you're on a Mac and have Bonjour bookmarks turned on in Safari, you'll see your new server show up there!) That was easy! Easy indeed. And, if you take a look at the code that the quickstart created, you'll see that there isn't much involved in getting up and running. Two interesting things to look at:

wiki20/controllers.py has the code that's generating the welcome page. CherryPy makes things very easy... you just write methods and expose them to the web! TurboGears adds the automatic template processing to go from a dictionary of values to HTML for the browser. wiki20/templates/welcome.kid is the template you view on the welcome screen. Did you notice that it's standard XHTML with some simple namespaced attributes? Very designer-friendly. You can even open it directly in your browser! Let's make a wiki! If you're not familiar with a Wiki, you might want to check out the Wikipedia entry. The whole idea is that it's an easily-editable web content system that makes it trivial to link to pages and create new pages.

TurboGears follows the Model-View-Controller paradigm, as do most web frameworks these days. Kid templates are your view, your CherryPy classes are your controllers and basically any object can be your model. In practice, since we're in a database-driven world, your model objects will be SQLObjects.

Since this is all about pages, why don't we go ahead and set up a place to store our pages. TurboGears quickstart gave us a "model.py" module with enough in it to start creating model classes. Here's our Page class:

view plain | print | ? 1 class Page(SQLObject): 2 pagename = UnicodeCol(alternateID= True , length=30) 3 data = UnicodeCol()

My own personal preference is to work with objects (and not SQL) as much as possible. SQLObject does support creating objects based on the database definition. I prefer to work the other way and create the database definition based on the objects.

For the pagename, we specified alternateID=True, which will guarantee that the column is unique and allow us to easily do searches on pagename. Some databases require the length to be specified on columns you want indexed, we'll just use the arbitrary length of 30 here.

Continue on to page 2 http://www.turbogears.org/preview/docs/tutorials/wiki20/printable.html 24.08.2006 15:39 Pointing to a database TurboGears has a minimum of required configuration. It does need to know where your database lives. The quickstart creates a couple of simple config files for you.

If you have sqlite installed, you can get started in development without configuring anything (skip the rest of this section).

Since we're working in a development environment and not a production deployment one, edit the "dev.cfg" file. You'll just need to uncomment the sqlobject.dburi line that corresponds to your database and provide the proper connection info.

Restart the web server by hitting control-C and running the startup script again:

python start-wiki20.py Creating the Database Since we've created, in Python code, the schema for our simple database and we've also told TurboGears where to look for the database, we're ready to actually create it.

tg-admin sql create

The "tg-admin sql" command is a wrapper around SQLObject's sqlobject-admin command. It looks in the config file to figure out where to find the database. Let's display a wiki page! Hard to believe it, but we're already ready to start displaying pages. The first step, is to rename our template. "welcome.kid" just won't do. Rename the template using whatever commands do the trick for your operating system:

cd wiki20/templates mv welcome.kid page.kid cd ../..

Now, let's replace the body of the template with something more reasonable for a wiki page:

view plain | print | ? 1

2 Viewing Page Name Goes Here 3
4 You can return to the FrontPage . 5 6 7

Page text goes here.

Notice that you can open page.kid in your web browser, and it is still perfectly viewable. That placeholder text can really help see a layout before it's put in action!

TurboGears greatly reduces the amount of code you need to write, but it does not eliminate it. Let's add a couple of imports to the top of controllers.py:

view plain | print | ? 1 from wiki20.model import Page 2 from docutils.core import publish_parts

Then, we'll replace the index method with one that:

1. Sets the template to our newly named "page" (line 1) 2. Has a default pagename of "FrontPage" (line 2) 3. Retrieves the page from the database (line 3) 4. Formats the text as HTML (line 4) 5. Deals with unicode properly (always a good habit, on line 5) 6. Returns the data for the template to use (line 6)

view plain | print | ? 1 @expose( "wiki20.templates.page" ) 2 def index (self , pagename= "FrontPage" ): 3 page = Page.byPagename(pagename) 4 content = publish_parts(page.data, writer_name= "html" )[ "html_body" ] 5 return dict (data=content, page=page)

All that in six, very readable lines. The dictionary that we're returning at the end provides the data that populates the template and has other magical powers that we'll see later. The "." at the beginning of the template name says that this name is relative to the controller's package. In other workds, this is referring to the full name of "wiki20.templates.page".

If you get a KeyError on the publish_parts line when you try to access the page, you are using an older version of docutils and should upgrade to the latest.

Previous Page | Continue on to page 3 Let's check out that first page! The code is in place... Point your browser to http://localhost:8080/ and let's see what we've got!

Oh, we've got an error. Since we're in development mode, CherryPy gives us the whole traceback, which is very convenient. The traceback is telling us that we got an SQLObjectNotFound exception. D'oh! We forgot to put a page in the database! Let's do that using CatWalk, the model browser

tg-admin toolbox http://www.turbogears.org/preview/docs/tutorials/wiki20/printable.html 24.08.2006 15:39 A new browser window will open with the TurboGears toolbox. Click on the CatWalk model browser. You'll see "Page" listed on the left. Click on that, select the "Add Page" tab and create a page with the name "FrontPage" and with whatever text you want for the data.

That's all there is to it. We just created a new page in the database.

Reload your browser window, and you'll see our beautiful page. How do we make a better page? One of the hallmarks of wikis is that you can edit the page just by clicking "Edit This Page". That and the wikispam that follows... hopefully, spammers won't find your Wiki 20 before we're done with it!

Let's start by creating a template for editing. Let's start with a copy of "page.kid":

cd wiki20/templates cp page.kid edit.kid cd ../..

In edit.kid, change the text at the top from "Viewing" to "Editing" and replace the

for the data with:

view plain | print | ? 1

2 3 4 <input type ="submit" name ="submit" value ="Save" /> 5 </ form > </p><p>We need something to use this template now. We'll add an "edit" method to our controller:</p><p> view plain | print | ? 1 @expose( "wiki20.templates.edit" ) 2 def edit( self , pagename): 3 page = Page.byPagename(pagename) 4 return dict (page=page) 5 6 </p><p>This method is very similar to our index method. The main difference is that the index method renders the wiki content as HTML, and this one returns the straight text.</p><p>We need a way to get to our edit method, so we'll edit page.kid to add this to the bottom:</p><p> view plain | print | ? 1 <p><a href ="${tg.url('/edit', pagename=page.pagename)}" >Edit this page </ a></ p> </p><p>That should do it! Reload the page in your browser, and you'll see the edit link. Follow that link, and you'll get a page that lets you edit. Don't click that save button, yet! We still need to write that method. Saving our edits When we displayed our wikiform in the last section, the action was "save". So, we need to make a method called save in our controller. Here's what it looks like:</p><p> view plain | print | ? 1 @expose() 2 def save( self , pagename, data, submit): 3 page = Page.byPagename(pagename) 4 page.data = data 5 turbogears.flash( "Changes saved!" ) 6 raise turbogears.redirect( "/" , pagename=pagename) </p><p>Interesting things to note about this:</p><p>1. Unlike the previous methods we've made, this one is just exposed without any template specified. That's because we're only redirecting the user back to the viewing page. 2. A transaction is set up for us implicitly, if our database supports transactions. You can see for yourself... if you add "raise ValueError" after page.data is set in that method, you'll see that the data is not actually saved in the database. If no exception is raised, the data is committed. If an exception is raised, the changes are rolled back. The exception to this rule is with redirects: they short-circuit execution of the method, but they don't count as "errors." 3. The "page.data = data" is all it takes to run the UPDATE SQL statement. 4. The turbogears.flash() call is setting a notification message to appear in the user's browser on the next screen. You'll see a reference to the "tg_flash" variable in the master.kid template. 5. Since an redirect is raised as an exception, all other processing is short circuited. Very handy!</p><p>Go ahead and try it out! You can make changes and save the page we were editing. Pretty wiki-like, no?</p><p>Previous Page | Continue on to page 4 Friendlier URLs Something that bothers me about the current setup is that the URLs are not as nice as they could be. Rather than "/?pagename=Foo", wouldn't "/Foo" be nicer? Luckily, this is really easy to do. We just add a default method that CherryPy will call whenever no other method matches:</p><p> http://www.turbogears.org/preview/docs/tutorials/wiki20/printable.html 24.08.2006 15:39 view plain | print | ? 1 @expose() 2 def default( self , pagename): 3 return self .index (pagename) </p><p>And now, we can change the HTTPRedirect in the save method to turbogears.url("/%s" % pagename). What about WikiWords? WikiWords have also been described as WordsSmashedTogether. A typical wiki will automatically create links for these words when it finds them. Sounds like a good idea, and this sounds like a job for a regular expression. Start by adding an import to our controller:</p><p> import re</p><p>A WikiWord is a word that starts with an uppercase letter, has a collection of lowercase letters and numbers followed by another uppercase letter and more letters and numbers. Here's a regular expression that meets that requirement:</p><p> wikiwords = re.compile(r"\b([A-Z]\w+[A-Z]+\w+)")</p><p>Put that line just above the Root controller class. Then, we need to use this regex. Just below the publish_parts line of the index method (that's the one that generates the HTML), add this:</p><p> root = str(turbogears.url("/")) content = wikiwords.sub(r'<a href="%s\1">\1</a>' % root, content)</p><p>Go ahead and edit your front page to include a WikiWord. When the page is displayed, you'll see that it's now a link. You probably won't be surprised to find that clicking that link produces an error. Hey, where's the page? It's time to add a check for pages that don't exist. I'll keep the approach here simple: if the page doesn't exist, you get an edit page to use to create it. In the index method, we'll check to see if the page exists. If it doesn't, we'll redirect to a new notfound method. Change the index method like this:</p><p> view plain | print | ? 1 try : 2 page = Page.byPagename(pagename) 3 except SQLObjectNotFound: 4 raise redirect( "/notfound" , pagename = pagename) </p><p>We'll need to import the exception as well. Add this to the top of the file:</p><p> view plain | print | ? 1 from sqlobject import SQLObjectNotFound </p><p>And, we'll add the not found method. We'll just reuse the edit template.</p><p> view plain | print | ? 1 @expose( "wiki20.templates.edit" ) 2 def notfound( self , pagename): 3 page = Page(pagename=pagename, data= "" ) 4 return dict (page=page) </p><p>With SQLObject, just instantiating an object is enough to insert it in the database, so this method will create a brand new page in our database.</p><p>Give it a try! You should be able to create new pages now.</p><p>Previous Page | Continue on to page 5 Adding a page list Most wikis have a feature that lets you view an index of the pages. We can add that to our wiki easily, so let's do it!</p><p>We'll start with a new template, pagelist.kid. To make things easy, we'll start with the page.kid template as a starter again:</p><p> cd wiki20/templates cp page.kid pagelist.kid cd ../..</p><p>Change the body of the pagelist.kid template to look like this:</p><p> view plain | print | ? 1 <body > 2 <h1 >All Of Your Pages </ h1 > 3 <ul > 4 <li py: for ="pagename in pages" ><a href ="${std.url('/' + pagename)}" py: content ="pagename" >Page Name Here. </ a></ li > 5 </ ul > 6 </ body > </p><p>Feel free to add "Are Belong To Us" to the heading, if you feel you must.</p><p>Just as with the other templates, you can open pagelist.kid directly in a browser. You can see that we'll get a bulleted list of links to the pages. This is our first use of py:for, and you can see it's straightforward. The li element will be repeated for each iteration of the for loop, and the for loop is specified just as it is in Python. http://www.turbogears.org/preview/docs/tutorials/wiki20/printable.html 24.08.2006 15:39 Let's add a link at the bottom of the master.kid template to get to the complete list of pages:</p><p><p>View the <a href="${tg.url('/pagelist')}">complete list of pages.</a></p></p><p>Since we're referring to a "pagelist" method, we should probably create it!</p><p> view plain | print | ? 1 @expose( "wiki20.templates.pagelist" ) 2 def pagelist( self ): 3 pages = [page.pagename for page in Page. select (orderBy=Page.q.pagename)] 4 return dict (pages=pages) </p><p>This is our first use of Page.select. We're not doing anything fancy. We're just selecting all of the Page objects from the database, putting them in order by pagename. The "Page.q.pagename" represents the "pagename" attribute as a query parameter. Page.select returns a SelectResults object which you can iterate over, making the one liner above easy.</p><p>You can see your pagelist by clicking the link at the bottom of your pages or going directly to http://localhost:8080/pagelist.</p><p>Previous Page | Continue on to page 6 You want AJAX? We got AJAX! This part of the tutorial is not technically AJAX. The "X" in AJAX stands for XML. I'm going to use JSON instead. JSON is easy and lightweight and efficient to use for all browsers. To use JSON for this TurboGears example, we just have to tell TurboGears that we want to use it. Just below the expose decorator, let's add another:</p><p>@expose("json")</p><p>Now, point your browser at http://localhost:8080/pagelist?tg_format=json. There's your pagelist in JSON format.</p><p>In standard CherryPy methods, you can return a string containing the rendered page. You can do that with TurboGears as well. But, if you write your code the way we have been in this tutorial, returning dicts instead of strings, you'll get JSON output for free.</p><p>For this part of the tutorial, we'll just be doing JavaScript using MochiKit. To keep things simple, we're going to change our "view complete page list" link to pull in the pagelist and include it right in the page you're viewing. Our changes will all be in master.kid.</p><p>The first thing we need to do is have MochiKit included in all of our pages. We can actually do this right from the project configuration file. This file is config/app.cfg in the Python package that quickstart created for your project. Open that up, and in your editor you'll find a commented out "VIEW" part of the config. Uncomment the line that says "tg.mochikit_all" and change the value to True. The line will end up looking like this:</p><p> tg.mochikit_all = True</p><p>This setting will tell TurboGears to include MochiKit in every page. After making this configuration change, restart the server.</p><p>Next up, we'll replace our page list link with one that will invoke a JavaScript function. We'll also add an empty container for our pagelist.</p><p> view plain | print | ? 1 <p>View the <a href ="#" onclick ="requestPageList()" >complete list of pages. </ a></ p> 2 <div id ="pagelist" > 3 </ div > </p><p>Now, we use MochiKit to retrieve the page list in requestPageList, which we'll define in a script tag in the head of the page.</p><p> view plain | print | ? 1 <script type= "text/javascript" > 2 function requestPageList() { 3 var d = loadJSONDoc( "${std.url('/pagelist', tg_format='json')}" ); 4 d.addCallback(showPageList); 5 } </p><p>MochiKit includes a function for doing an asynchronous XMLHttpRequest and converting the result from JSON into a JavaScript object. Handy!</p><p> loadJSONDoc returns a "Deferred" object. The idea with a Deferred is that we know that our request for the pagelist will happen some time in the future, but we don't know when. A Deferred is a placeholder that allows us to specify what happens when the result comes in. We have a very simple requirement here: call a function called "showPageList", which we'll write now:</p><p> view plain | print | ? 1 function showPageList(result) { 2 var currentpagelist = UL( null , map(row_display, result[ "pages" ])); 3 replaceChildNodes( "pagelist" , currentpagelist); 4 } </p><p>When loadJSONDoc gets its result, it will pass it along to showPageList. What we end up with in JavaScript is the same dictionary our pagelist method returned in Python!</p><p>MochiKit.DOM allows you to create new document elements by nesting tags in your JavaScript. We're creating a UL element, just like we had in our freestanding pagelist page. The first parameter is a mapping of attributes for the element, which is null in this case. The other parameters will all become child nodes. MochiKit's map function works just like Python's. For each element in result["pages"], we're going to call a function called row_display, which I'll come to momentarily. The last part is to replace the contents of our <div> with the id of pagelist with the new DOM elements we've just created. http://www.turbogears.org/preview/docs/tutorials/wiki20/printable.html 24.08.2006 15:39 Let's create our row_display function and close off our script tag:</p><p> view plain | print | ? 1 function row_display(pagename) { 2 return LI( null , A({ "href" : "${std.url('/')}" + pagename}, pagename)) 3 } 4 </script> </p><p>Each pagename from the pages list will get passed into row_display. We create an LI element (no attributes), and an A element with an href attribute. The A element also has the pagename as its contents.</p><p>Voila! If you go to your front page and click on the page list link, you'll see the page list right there in the page. The final files The final files for this demo are in wiki20.tgz. You'll need to edit dev.cfg to point to the database file that is included in the tarball. For further reading... If you had any problems with this tutorial, or have ideas on how to make it better, please let us know on the mailing list! Documentation patches are happily accepted.</p><p>Reference documentation that covers more details is available on the docs page.</p><p>Previous Page</p><p> http://www.turbogears.org/preview/docs/tutorials/wiki20/printable.html 24.08.2006 15:39</p> </div> </article> </div> </div> </div> <script type="text/javascript" async crossorigin="anonymous" src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-8519364510543070"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.1/jquery.min.js" crossorigin="anonymous" referrerpolicy="no-referrer"></script> <script> var docId = '19f5d490174247f277c75e744f725d29'; var endPage = 1; var totalPage = 6; var pfLoading = false; window.addEventListener('scroll', function () { if (pfLoading) return; var $now = $('.article-imgview .pf').eq(endPage - 1); if (document.documentElement.scrollTop + $(window).height() > $now.offset().top) { pfLoading = true; endPage++; if (endPage > totalPage) return; var imgEle = new Image(); var imgsrc = "//data.docslib.org/img/19f5d490174247f277c75e744f725d29-" + endPage + (endPage > 3 ? ".jpg" : ".webp"); imgEle.src = imgsrc; var $imgLoad = $('<div class="pf" id="pf' + endPage + '"><img src="/loading.gif"></div>'); $('.article-imgview').append($imgLoad); imgEle.addEventListener('load', function () { $imgLoad.find('img').attr('src', imgsrc); pfLoading = false }); if (endPage < 7) { adcall('pf' + endPage); } } }, { passive: true }); </script> <script> var sc_project = 11552861; var sc_invisible = 1; var sc_security = "b956b151"; </script> <script src="https://www.statcounter.com/counter/counter.js" async></script> </html>