Before we dive in to the details of building a web application with Moya, it is worth creating an example project to have a look it. This is especially true if you are the 'show me the code' type of developer (as the author is).
The Moya command line application contains a command line wizard that can build a project framework for us. If you run
moya start project without any additional arguments, it will ask you for information regarding your project and what applications you want to enable (auth, feedback, blog etc). For the purposes of this demonstration we are going to enter the title on the command line and accept all defaults (with the
Enter the following from the command line to build the test project:
Moya will ask you for a few details, then if all goes well you should see confirmation that the project files were written. If you now navigate to the newly created
intendedforhumans/ directory, you can begin working with the project.
If you don't want to have to re-enter basic information in the wizard every time you use it, you can create a configuration file containing these defaults. This file should be called
.moyarc and should be in your home directory. If you are on linux, you can create this file with
nano ~/.moyarc. Here is an example of a moyarc file:
[author]name = John Crichtonemail = firstname.lastname@example.org = Moya Projecturl = http://example.org
See MoyaRC for more information.
Moya now has all the information it needs to run a database driven web application, but before it can run successfully we first need to initialize the database. The first step we need is to create tables in the database. Navigate to the project directory (
intendedforhumans/) and enter the following at the command line:
The above command will create the tables for the project in the database. You should see a confirmation for each application that was synced with the database.
The tables now exist in the database, but no information is stored there. The authorization library (users and permissions) first needs to store some objects in the database, such as a user account for yourself. We can do this by invoking a command in the auth library, as follows:
This will ask you to create a super user account – you can accept the default username of 'superuser' or enter a more personalized username. Moya will then ask you for a password. On a production site, you would of course use a secure password here. Since this is just a test, feel free to enter 'password' or something memorable. Finally, Moya will ask you for an email address. Enter your email address, or a fake one.
At this point everything should be set up to run your application. When developing, use the following command to run the server:
This will read the files from your project and run the server. You should see a stream of log information followed by confirmation that the server is running. You can now visit http://127.0.0.1:8000 to view your web application. Feel free to look around.
The site should be empty, but fully functional. If you want to add content, click the 'Login' link on the top right, and log in with your superuser account. You can now edit pages / post blogs etc and view the Admin site from the Admin dropdown (top left).
Let's look at the files and directories that the wizard has created. You should find a
readme.txt in most directories containing a brief description of the directory contents.
In the top level directory you should see a file called simply
moya. This file tells Moya that this directory contains a project. The command line application will look for this file when running the development server, or other commands that require a project. If Moya doesn't find the
moya file in the current directory, it will look for it in the parent directories. This means that
moya runserver will work even if you are in a sub-directory.
Also in the top directory are some
ini files. These will be explained in detail in later chapters, but feel free to have a look at these – they are in a simple text format.
If you have run the project, you should also see a directory called
__moyacache__ which contains temporary files when running, and
basic.sqlite which is your database. You may configure both in settings.
In your top level directory, you should also find the following sub-directories:
server.xml, containing a server definition. It is this server that runs when you do
All new functionality you write will be done in a library of some sort. If you want to add content specific a single site, then you could work with the library in
/site/, but generally you will want to create a library for each distinct feature set in your site.
moya start command can create libraries, in much the same way as projects. To do this you will need to be in your project directory. let's add a new library to our test project. We'll pretend we are going to start a new app that locates the finest sushi in your area. Enter the following from the command line:
This will ask you about some basic author information (see section on MoyaRC if you don't like repeating yourself).
The wizard will ask you for a 'long name' to give to the library. A long name consists of two or more identifiers separated by dots. The first identifier should be your organization. The second identifier should be the name of your project. You can add further identifiers if you want more fine-grained categorization.
After the long name, the wizard will ask you for a URL for the library. This URL should be a link to documentation, or some information regarding the library. You may leave this field blank if you aren't going to distribute your library.
The next thing the wizard will ask for is an XML namespace, which should be a fully qualified (including http://) URL. This URL doesn't have to exist; the only requirement is that it should be unique to you. Using a domain you own is the best way to ensure that this is the case. If you don't have a domain, you are welcome to use a URL in this format:
Moya will then ask you if you want to mount the library. Mounting a library allows it to generate responses to requests. Select
y for this, and accept the default of
sushifinder for the mount location.
The final piece of information Moya will ask you for is a name for your application (an application in Moya terminology is a mounted library). This should be relatively short, lower case, and contain no periods. Enter a value of
sushi for this.
If all goes well, Moya will generate a skeleton library in the
/local/ directory. It will also modify
server.xml so the new libray will be loaded.
If you now run the development server (
moya runserver), you should see a few references to the new library in the logs. And if you visit http://127.0.0.1:8000/sushifinder/ in the browser, you will see the new application in action.
The new application doesn't do anything particularly interesting, but does contain most of the elements you might use in a more functional project. Feel free to examine the auto-generated code and tweak it.
Let's look at the directory structure of the new library we just created. Navigate to the library, which you will find in
/local/ (inside the project directory).
At the top level you will find a
__init__.py file. This is necessary if you would like to distribute your library as a Python module. Also at the top level is a file called
lib.ini. This contains information regarding the library, and the locations of additional files.
There is probably no good reason to change the defaults, so most libraries will contain the following directories.
A project consists of a number of directories where the top level is denoted by a filed called
moya. This file lets the
moya command line application know the location of the root of the project.
All functionality for generating and serving content is contained within libraries which have a globally unique name (or long name) consisting of two or more identifiers separated by dots. There are three directories for libraries in a typical project;
/local/ contains libraries authored by yourself,
/external/ contains third party libraries, and
/site/ contains a library to customize the site.
When a library is installed, it is given a short identifier which contains no spaces or periods. Once installed, a library is known as an application. There may be more than once application installed for any given library.