Getting Started 2: html – markup language for web documents

This is the 2nd post in the Getting Started series.

Basic HTML

HTML(hyper text markup language) is a data representation format based on XML. It is used for formatting web documents in general, and contain all the required elements for a browser to render the tags as a website.

Basic XML

HTML(or XML in general) follows this following set of formatting and rules.

Sample XML Document (Not HTML btw)

    <title>Hello World Page</title>
    <article author="Metta Ong">Lorem Ipsum</article>

As seen from above, the document is formed by tags in the form of tags. Tags come in pairs, opening and closing tags. The opening tag is enclosed with a less than and greater than sign, and a closing tag has a / before the tag name.

Attributes are “descriptions” attached to the tags. In the above example, the author="Metta Ong" is the attribute attached to the article tag. Content placed between the open and close tags are actual text content of the tags.

XML hierachy is pretty simple to understand. In the example above, both the title and article tags are considered children of the Document root tag.

Main structure of web pages


Main structure of web document

Different versions of HTML

There are many HTML versions out there (the most recent one is HTML5). To tell the browser which version of HTML your document is, we use the DOCTYPE tag.

So, at the top of your document, incude the following line: “. This tells the browser that your document follows the HTML5 format.

For those curious few out there, there are a few different types of DOCTYPE for HTML4 document is – strict(), transitional(), etc. You can read more about doctypes here.

Main 2 components

The head tag is the place where all the information goes. Data contained in this tag is usually not rendered. By convention, all scripts and styling goes here, together with all the information of the document, like the title, description, etc.

The body tag is the place where all the rendered information go. All your headers, navigation and content goes here.

Document information

    <title>Title of Document</title>
    <link href='/path/to/stylesheet.css' type='stylesheet' />

Example head tag

All the information will be stored here, the title of the document, all the metadata (description, author, etc). The metadata can be used for search engine optimization (SEO), it gives the browser detailed information to categorize your document (more on that in other tutorial).

While styling can be done on the main html file itself, you can also attach stylesheets using the link tag. The syntax to do so is as follows: “

You can attach things like favicons (the small tiny logos for your page). Using the link tags, these images can be attached as so:

<!-- linking a style sheet -->
<link href='path/to/style.css' rel='stylesheet' />

<!-- favicon -->
<link href='path/to/icon.png' rel='icon' type='image/png' />

Basic components

In the previous post, you learnt about formatting documents using markdown, know that you know the basics about document formatting, I will now teach you how to do all that in HTML (yeah, finally :>)


In markdown, there are different kinds of headers, representing different layers of information. The highest level of all headers have the h1 tag, it all goes all the way, from h2, h3, all the way to h6.

<h1>Usually for the main title of the page.</h1>
<h2>Subheadings. Title for the different sections</h2>
<h3>Even smaller headings, content headers maybe?</h3>
<h4>Not too sure why you would go so deep...</h4>
<h5>Probably just use this for styling purposes...</h5>
<h6>When you reach here, its time to split your content...</h6>

Paragraph text

The p tag (yeah, p for paragraph) used to contain all your text. It can be can be any kind of text, its the generic text container. It is to be embedded in the new HTML5 content tags for SEO (searc engine optimization).

Text styling

Within the paragraph tags, there are some special styling tags to basic transformation to yout text. Here are some of the basic tags available for use.

<b>bold, b for bold</b>
<strong>makes the text bold</strong>

<i>italics effect, i for italics</i>
<em>also italics effect, emphasized</em>

<u>underlined text, u for underline</u>

<mark>highlight text. yep, like a highlighter.</mark>

<s>to show cancellalation (strikethrough), really...</s>
<del>strikethough, similar to the 's' tag</del>

<sub>subscript, text written close to the foot of the text</sub>
<sup>superscript, you know like in math, the power function</sup>

<code>Shows code. text will be displayed in monotype font.</code>

For more advanced styling, you can take a look at the CSS declaration specified for text..


Your pages will be boring with any visual candy. The image tags (img) contains your images. (like duh.)

<img src='' alt='a random image' />

Yes, img tags are one of those special kinds that do not need to be closed (because your browser most likely wont render anything enclosed by those tags).


The web works like a interwoven collection of pages, and linking them together will be these a tags (a for anchor). These tags have an attribute href (hyperlink reference), which points to the location you want to redirect your readers to. And this is how you use it:

<a href='' target='_blank'>
    Link to google
    <img src='path/to/img'/>

Yep, you can put images in your a tags too. Actually, you can put in anything basic tags under the sun and it will work.

Adding more structure

Most pages will have a certain page structure to it, header,content, footer, at least. The basic containers for most elements are the div and span tags.

But in html5, there are many more tags that can better segmentalized your page into the appropriate sections.

Basic containers

The most basic tags are the div and span. There are a few difference between them. div is for block elements and span is for inline elements.

Block elements refers to a whole section of the page which are displayed as blocks of content. These usually refer to section of the page, such as header, navigation bar or footer.

Inline elements as their names suggest, refers to a small portion of content, within a block to which specialized styling (usually through CSS) is applied to.

HTML5 section tags

In HTML5, there are much more section tags that helps add structure to the documents.

header is a section tag for containing the header content. It can include your logo, your page header, and whatever you plan on putting in your header section.

footer serves the same function as the header tag, a container for footer content (including copyright and contact information).

article contains the main content for the document. But if they are sections in the article, you can use the section tag to separate your content.

nav tags are for navigation. It will consist the links to the different sections of your website (home, about, etc).

aside tags are for sidebars which contain additional bits of information (description for blogs for example).

There are more of course, you can view all that here.

Special Content

In HTML5, there are many new semantics tags added to give structure to your documents.

Pre VS Code

We talk about the code tag just now. But for whole sections of codes, we use the pre tag to contain whole sections of code, preserving the newlines and whitespaces, keeping all the indentation intact.

function add(x, y){
    return x+y;


The figure tag is used to contain illustrations and pictures. The figcaption is used to add description to the figure. This all is written in the following manner:

    <img src='' />
        Some random picture from lorempixel


The audio tag is used to embed an audio resource into the page.

<audio src='test.mp3' type='audio/mpeg' />


video tag is similar to audio tag, but with videos instead of audio files.

Canvas & SVG

The canvas and svg tags are used for drawing things on the page. The canvas tag is controlled using javascript. The svg tag draws using xml. Learn more about canvas and svg.

What’s next

  • Forms (text input, form submission)
  • Tables (systematic display of info)
  • Separators (line breaks)
Advertisements Tutorial – Facebook Authentication

This is a rehash of the old tutorial after the update in the documentation.

Facebook is one of the most widely used authentication system, used especially to reduce the hassle of signing up for a new application. In this tutorial, I will be showing one way to integrating facebook authentication for your typical application.

This tutorial makes use of Facebook’s Graph API instead of the different SDKs. This method will work as long as your client is able to connect to the internet to access the APIs, be it Android, iOS or other platforms.

There are 2 phases to Facebook’s authentication system — creating a session to request an access token, and requesting for an access token. In the first part, a code is return, it is then used to request an access token. The token is used to access the information using Facebook’s Graph’s API.

For the first part, you will redirect the user to the following page: using the client_id and redirect_uri.

### Initiate first stage of the process
if not i.get('code'):
   raise web.seeother(''+client_id+'&redirect_uri='+uri)

In the second part, the access_token will be requested from The client_id and client_secret, together with the code will be used to generate the access_token. Because details of the application are required for this process, it is more to do it through the server. For that, we will make use of the python requests library.

r = requests.get(fb_graph+'oauth/access_token', params={

To test if the authentication actually works, we redirect to a site to test the Facebook Graph API. This is where we get the basic profile information about the user and the profile picture.

r = requests.get(fb_graph+'me', params={'access_token':i.get('access_token')}).json()

return "<html><h3>%s (%s)</h3><img src='%s' /><br/><a href='%s'>View Profile</a></html>"%(r['name'], r['gender'], fb_graph+r['id']+'/picture', r['link'])

For the full application, with the structure of the different pages, visit the gist below. Application – Paypal Transaction

Visit the Github repository for the full code example


Paypal is one of the most prominent online transaction platform. And there is a lot that you can do with paypal. This tutorial will bring you through using the paypal rest API with to create an application that is capable of handling paypal transaction.

In this tutorial, we will be using the paypalrestsdk to access the API which we will be using to create and execute our transactions.

Before starting

Before we start, a little about how the PayPal SDK works. You will first have to create a payment with a unique payment id. The payment will have two main stages, the authorization stage and the execution stage.

In the authorization stage, the user will review the details of the transaction and if they are happy with all the details, they will authorize it, which brings us to the next stage, execution.

In the execution stage, the transaction of the specified payment id will be carried out and only then will the transaction amount be actually transferred between the accounts.

We will be doing all the testing in the sandbox PayPal (don’t need real money), which you will need a Paypal Developer account to access.

Setting up your account

Head to Paypal Developer and create a new REST app, check that you have the client id and the client secret. Then head over to Sandbox Accounts and make sure you have 2 accounts, one for the buyer, one for the seller.

Also, make sure you have the python package installed. To get it up and running, simply run pip install paypalrestsdk

Initialization stage

The good thing about using the python package is that they handle almost everything for you. To initialize your paypal application, you have to give it your client id and client secret. As for the urls, they point to the locations where your application actually handles the execution of the transaction (more on that later).

import paypalrestsdk

PP_CLIENT_ID = '<client id>'
PP_CLIENT_SECRET = '<client secret>'

PP_URL_RETURN = 'http://localhost:8080/pay'
PP_URL_CANCEL = 'http://localhost:8080/'

    "mode": "sandbox",
    "client_id": PP_CLIENT_ID,
    "client_secret": PP_CLIENT_SECRET

For the web application, here is the basic structure of the application. In /create, the application will create the transaction where details such as the transaction amount and details will be used for the payment, and /pay will then be used for the execution of the transaction, which actually transfer the money to your seller account.

import web

urls = [
    '/create', 'PaymentCreate',
    '/pay', 'PaymentExecute'
app = web.application(urls, globals())

Creating the payment transaction

First, we will create a function createPayment that handles the API part of the code. The function will create a Payment object with the basic details, including the amount to be transferred and the description of the payment, etc…

For now, the transaction method is set to paypal account, which means that the user must have a paypal account in order to complete the transaction. You can add in the option to complete the transaction via credit cards, but you will have to add in a bit more details (information available at REST API documentation).

def createPayment(amt, description='', currency='SGD'):
    payment = paypalrestsdk.Payment({
        'intent': 'sale',
        'payer': {
            'payment_method': 'paypal'
        'transactions': [{
            'amount': {
                'total': '%.2f'%float(amt),
                'currency': currency
            'description': description

    if payment.create():
        href = [str(l.href) for l in payment.links if l.method == 'REDIRECT'][0]
        return str(href)
        return payment.error

For the web application, this class will take in the values for amt and des, then calling the createPayment function and redirecting the users to the authorization page (which is on the paypal site).

class PaymentCreate:
    def GET(self):
        i = web.input()

        if not i.get('amt') or not i.get('des'):
            return web.badrequest()
        amt = i.amt
        des = i.des

        res = createPayment(amt, des)
        if type(res) == str:
            return web.seeother(res)
            return web.notfound()

Executing the payment transaction

Assuming that the users have authorized the transaction all you have to do next is to execute the transaction and BAMM, you will have your money.

So for the executePayment function, the payment_id and the payer_id (id of the user) will be required for the execution to take place.

def executePayment(pid, uid):
    payment = paypalrestsdk.Payment.find(pid)

    if payment.execute({"payer_id": uid}):
        return str(
        return payment.error

Some of you may have notice the variable, PP_URL_RETURN in the initialization stage. This link points to the server’s payment execution handler (the class that handles the execution), which in this case, is /pay

In this class, the payment is executed using the executePayment function using the values paymentId and PayerID (all part of PayPal’s SDK redirect request).

class PaymentExecute:
    def GET(self):
        i = web.input()
        if not i.get('paymentId') or not i.get('PayerID'):
            return web.badrequest()
        id_payment = i.get('paymentId')
        id_payer = i.get('PayerID')

        res = executePayment(id_payment, id_payer)
        if type(res) is str:
            return { 'success': True }
            return { 'error': res }

How to tell that it worked

Head to SandBox PayPal, and login with your buyer account( Under the recent activity section, view the details of the transaction to ensure that the correct amount is transferred, and that the corresponding description you have entered is returned.

Things to note:

  • There are alot more details you can add to your application, visit the Paypal REST API to review all the possible details that can be included.
  • Official documentation for the python package
  • When using it for real, switch the mode in the initialization stage to live

Visit the Github repository for the full code examples.

Feel free to email me if you have any questions. Application – FB Authentication

EDIT: There are some updates to the FB documentation, it doesn’t affect the login process a lot, but I decided to rehash this tutorial anyway. Updated tutorial

Access to Github Repository


Facebook authentication is one of the easiest way of authenticating your user without them having to create a full-fledged user profile system. Here is a quick tutorial of how to integrate facebook login with your application.

Here is the basic setup of the application:

import web
import json
import time
import urllib
import urlparse

FB_APP_ID = ''

urls = [
'/', 'Index',
'/li', 'Login',
'/lo', 'Logout'
app = web.application(urls, globals())

def getURL():
return web.ctx.home + web.ctx.fullpath

Logging In

The login stage of the application requires two main stages: the authentication stage and the retrieval of the access token.

In the authentication stage, the user is redirected to where they will accept all the permissions that the application will require. What is returned will be the code which will be used to retrieve the access token for that particular session.

In the second stage, the user is redirected to for the access token. The result is read using the parse_qs function from urlparse, where the access token is extracted.

The last stage of the login will be extracting the user information for storage in the cookies. Using the access token, the user’s profile information is retrieved from, where the user id and the user name is stored for display.

class Login:
def GET(self):
i = web.input(code = None)
args = dict(client_id=FB_APP_ID, redirect_uri=getURL())

### Authentication stage
if not i.code:
web.seeother('' + urllib.urlencode(args))

### Access token stage
args['code'] = i.code
args['client_secret'] = FB_APP_SECRET
req = '' + urllib.urlencode(args)
res = urlparse.parse_qs(urllib.urlopen(req).read())
tkn = res['access_token'][-1]

### Retrieving profile information
req = '' + urllib.urlencode(dict(access_token=tkn))
res = json.load(urllib.urlopen(req))

t = time.time() + 7*86400
web.setcookie('fb_uid', res['id'], t)
web.setcookie('fb_uname', res['name'], t)


Logging Out

Since we are using cookies to store the session details, logging out will just require us to reset the cookies.

class Logout:
def GET(self):
web.setcookie('fb_uid', '', time.time() - 86400)
web.setcookie('fb_uname', '', time.time() - 86400)

Displaying the information

After the user have logged in, some of the user information will be stored in the cookies. We will make use of this by displaying the user’s name and profile picture if he is logged in. We do so by checking the state of the cookie variables fb_uid and fb_uname, if they exist, they will be printed out, else, a login link will be displayed instead.

class Index:
def GET(self):
html = "<a href="/li">FB Login</a>"

uid = web.cookies().get('fb_uid')
uname = web.cookies().get('fb_uname')

if uid and uname:
html = "<img src=""+uid+"/picture" alt="" />
<a href="/lo">Logout</a>"

return '''



There you have it, your own application with facebook authentication.

Things to note

  • To integrate a more general form of OAuth system, take a look at the python-oauth2 package
  • Never reveal your app secret and id, you never know who is looking
  • Original inspiration

Access to Github Repository Application – User Auth with token features

Visit Github Repository to view the code sample in full.


User authentication is one of the most basic system that all web application will have. For many frameworks, there is already some sort of authentication system you could use, but for, there is not such system available. But it shouldn’t stop you from using the framework, because creating one is not really that difficult.

In the past, I have written a tutorial on creating login systems for web application, but when I am working on a data API, I realized that having a token system makes work much much easier. You could integrate other authentication standards using this code, but this is just the very basic framework that you build upon for your application.

Differences from last version

In the last version of the tutorial, I used sessions to store the user’s session, but for this version, I will be designing it for a RESTful API, so, the bulk of the authentication will be done through the generation and usage of tokens.

Creating the database

This is pretty self explanatory, but this is just the most basic of the database structure, alter to fit your own needs.

app = web.application(urls, globals())
db = web.database(dbn='sqlite', db='database.db')
        uusr TEXT NOT NULL,
        upwd TEXT NOT NULL,
        utme INTEGER,
        utkn TEXT

Additional functions

These are functions that are required for the user authentication system to work, accomplishing all the backend task such as accessing the database or generating tokens.

Generating tokens

This is a simple token generating scheme that you could use. For your application, you could use a much more sophisticated scheme.

def genToken():
    r = rand.random()
    return str(hashlib.sha1('%f%s'%(r, time.ctime())).hexdigest())

Encoding the password

It is never secure to save your password as plaintext. Instead use password hash scheme such as the one implemented here.

def getPwd(usr, pwd):
    return hashlib.sha1('%s:%s'%(usr, pwd)).hexdigest()

Signing up for a new account

The section of the code ensures that the request is in the correct format and if everything is all and well, it will serve to create an user account and store the user information into the database. The most crucial error that this process is the possibility that the user account might have already been created before, hence, we got to handle that error right there.

class SignUp:
    def POST(self):
        i = web.input()
        if not i.get('usr') or not i.get('pwd'):
            return web.badrequest()
        usr = i.get('usr');
        pwd = getPwd(usr, i.get('pwd'))

        if getUser(usr):
            return {'error': 'userExist - user already exist'}

        db.insert('users', uusr=usr, upwd=pwd, utkn=genToken(), utme=int(time.time()))

        return {'sucess': True}

Signing in and getting a token

Signing into the data API would return a access token, but if the token is not accessed within 4 hours of the last use, the token is regenerated and the new token will be returned. This is just a simple scheme that is implemented here, it should be changed to suit your application’s needs.

There are a few errors that might occur during the sign in process. For one, the user account might not already exist. The password could be wrong, authentication information might be missing.

class SignIn:
    def GET(self):
        i = web.input()
        if not i.get('usr') or not i.get('pwd'):
            return web.badrequest()
        usr = i.get('usr')
        pwd = getPwd(usr, i.get('pwd'))

        user = getUser(usr)
        if not user:
            return {'error': 'userNotExist - user does not exist'}

        if not user['upwd']==pwd:
            return {'error': 'invalidPass - invalid password, try again'}
            t = int(time.time())
            ### Token expires within 4 hours of inactivity
            if user['utkn'] && t-user['utme'] > 14400:
                token = genToken()
                token = user['utkn']

            res = db.update('users', where='uid=$id', utkn=token, utme=int(time.time()), vars={'id':user['uid']})

            return {'success':True, 'token':token}

        return {'error':'loginError - cannot login'}

Signing out

For a token access system, the signing out process will just be removing the token and resetting the sign in time. And by resetting the token, the previous token will be invalidated and it will be just like signing the user out of the system.

class SignOut:
    def GET(self):

        i = web.input()
        if not i.get('tkn'):
            return web.badrequest()
        tkn = i.get('tkn')

        user = getUser(None, tkn)
        if not user:
            return {'error':'Not logged in'}

        res = db.update('users', where='uid=$id', utkn=None, vars={'id':user['uid']})

        return web.seeother('/')

Things to note

  • For testing purposes, the functions corresponds to GET request, but for product do change them to POST queries that do not make plaintext information as available
  • User authentication system should always be done using some sort of security, namely with a SSL enabled connection
  • This set of of code is just a sample proof of concept. Always alter the code to suit your own needs.
  • If you have any questions or if anything is unclear, shoot me an email.

Tutorial – Creating a webchat with

BitBucket Repository

I have previously written a tutorial on how to do long polling on webpy framework. Well, this is an updated version with a code repository that you can use to include an webchat subapp in your webpy applications.

Tools required

Frontend implementation – Layouts

For the main page, it would consist of one main area where the messages will be displayed. And an area at the bottom which consist of a type input, where the messages are submitted.

All the javascript coding will be included in the webchat.js, which will be described in more detail later.


$def with (msgs)
<script src="static/js/jquery-1.11.1.min.js"></script><script src="static/js/webchat.js"></script>
<div id="msgs">
$for msg in msgs:
<div class="msg">$msg</div>
<div id="entry"><input id="message" type="text" placeholder="Message here ..." />
<input type="submit" value="submit" /></div>

The styling is not so important for this project, but you can view the CSS style in the code repository.

Storing the messages

We will be using sqlite to store our messages. So, open up your console, and type in sqlite3 database.db, and create the table using the following schema:

msg_content TEXT NOT NULL

Simulating real-time events – Client side

To simplify our lives, we will be using jquery for the ajax calls. Everytime a call is returned, the message wrapper(#msgs) will be updated and another call is made.

Another function is needed to send the message to the server for storing into the database.

These functions will be included inside /static/js/webchat.js:

function sendMsg(){
var div = $('#message')[0];
var msg = div.value;

alert('Message cannot be blank');
div.value = '';

function longPoll(idx){
data = eval('('+data+')');
var msgs = data['msgs'];
for(var i=0; i<msgs.length; i++){
$('#msgs')[0].innerHTML += "
<div class="msg">"+msgs[i]+"</div>

Simulating real-time events – Server side

Framework for the webpy application

This is the basic framework for

import web, time, json

urls = [
'/', 'Index',
'/send', 'SendMsg',
'/get', 'GetMsg'
render = web.template.render('layouts')
app = web.application(urls, globals())
db = web.database(dbn='sqlite', db='database.db')

class Index:
def GET(self):

class SendMsg:
def GET(self):

class GetMsg:
def GET(self):

if __name__ == '__main__':

Serving the existing messages

Alter the Index class to read messages from the database and render it inside the layout:

class Index:
def GET(self):
res ='msgs')
msgs = [r for r in res]

content = [m['msg_content'] for m in msgs]
return render.index(content, msgs[-1]['msg_id'])

Add new messages to the database

Insert the content using /send into the database:

class SendMsg:
def GET(self):
i = web.input()
if i.get('msg'):
db.insert('msgs', msg_content=i.get('msg'))
return web.notfound()

Getting new messages – Long Polling

This is the important bit. The server side code for the long polling process:

class GetMsg:
def GET(self):
i = web.input().get('idx')
print i
if not i or not i.isdigit(): i = '0'

max_iter = 20; iter = 0
msgs = []
while not len(msgs) and iter'+i)
msgs = [r for r in res]
iter += 1

if len(msgs): i=msgs[-1]['msg_id']

return json.dumps({
'msgs':[m['msg_content'] for m in msgs],

A bit of explanation here. The while loop and the time.sleep is what makes the whole idea works. The server will keep the request open until it detects a change in the database.

Running the server – Gevent WSGIServer

If you are running this as a subapp. Here is all you have to know. If you are running it as a standalone application, do read on.

Webpy’s default web server is not that great for production. Instead, we will be using the Gevent WSGIServer to run the application.

from gevent import monkey, pywsgi;

''' Whatever code you have '''

if __name__ == '__main__':
print 'WSGISever on 8080'
application = app.wsgifunc()
pywsgi.WSGIServer(('', 8080), application).serve_forever()

Fixing the static directory problem

The WSGIServer does not automatically serve static file like webpy. Fortunately, there is a fix for this:

urls = [
'/static/(.*)', 'Static',
'/', 'Index',
'/send', 'SendMsg',
'/get', 'GetMsg'

class Static:
def GET(self, file):
f = open('static/'+file, 'rb')
return web.notfound()

Going on from here

If you are lost in any of the steps above, do visit the code repository. It might be helpful to have a working sample where you can follow. Any troubles, drop me an email or leave it in the comments, I will help to be the best of my abilities.

BitBucket Repository