.. _section-hello-world-widget-development: Hello World Widget Development ============================== This quick tutorial demonstrates how to create a simple Hello World widget for Makahiki. The following sections provide a step by step guide to developing a new widget for Makahiki. These sections document the actual steps taken to develop the Hello World Widget. Create a local installation --------------------------- The first step in theme development is to follow the local installation guide to create a running implementation on your computer, as documented in :ref:`section-installation-makahiki-local`. Set environment variables for theme development ----------------------------------------------- To simplify theme development, it is important to set the MAKAHIKI_USE_LESS and MAKAHIKI_DEBUG environment variables to true. When this is done, you can make changes to your theme file, save it, and then simply refresh the page to see the changes. There are a variety of ways to set these environment variables, but a convenient way is to set them in the ~/.virtualenvs/makahiki/bin/postactivate file. This way, whenever you `workon makahiki`, the variables will be set. Here, for example, is the contents of my postactivate file:: #!/bin/bash # This hook is run after this virtualenv is activated. MAKAHIKI_DATABASE_URL=postgres://makahiki:makahiki@localhost:5432/makahiki export MAKAHIKI_DATABASE_URL MAKAHIKI_ADMIN_INFO=admin:admin export MAKAHIKI_ADMIN_INFO MAKAHIKI_USE_LESS=True export MAKAHIKI_USE_LESS MAKAHIKI_DEBUG=True export MAKAHIKI_DEBUG Once you have edited this file, you will need to `workon makahiki` again to set these variables. To verify they are set correctly, you can do the following:: % printenv | grep MAKAHIKI MAKAHIKI_DEBUG=True MAKAHIKI_DATABASE_URL=postgres://makahiki:makahiki@localhost:5432/makahiki MAKAHIKI_ADMIN_INFO=admin:admin MAKAHIKI_USE_LESS=True Create the hello world widget package ------------------------------------- The first step to create the hello_world widget is to create the new widget package. Makahiki's manage.py supplies an easy way to start a new widget. Simply run the following command:: % manage.py startwidget hello_world The startwidget command will create the base files and directories necessary for building a new widge. The directory structure should look like:: hello_world/ templates/ index.html __init__.py tests.py views.py ``__init__.py`` describes the purpose of the widget. Edit the default description to something like.:: """The hello_world widget provides an simple example Makahiki widget showing player's name, team and current point total.""" We'll go through contents each of the rest of the files next. The Widget's User Interface ``index.html`` ------------------------------------------ Makahiki uses Django templates for the User Interface for widgets. Let's build a simple UI for our Hello World widget. Since we are going to put our widget in an existing page, the widget only needs enough ``html`` to show itself. The ``startwidget`` command gives you the following default ``index.html``::