More on admin

The administrative interface provides additional functionality that we briefly review here.

Site

This page is the main administrative interface of web2py. It lists all installed applications on the left, while on the right side there are some special action forms.

The first of them shows the web2py version and proposes to upgrade it if new versions are available. Of course, before upgrading be sure to have a full working backup! Then there are two other forms that allow the creation of a new application (simple or by using an online wizard) by specifying its name.

The following form allows uploading an existing application from either a local file or a remote URL. When you upload an application, you need to specify a name for it (using different names allows you to install multiple copies of the same application). You can try, for example, to upload the Movuca Social Networking application app created by Bruno Rocha:

https://github.com/rochacbruno/Movuca

or Instant Press CMS created by Martin Mulone:

http://code.google.com/p/instant-press/

or one of the many example applications available at:

http://web2py.com/appliances

Web2py files are packages as .w2p files. These are tar gzipped files. Web2py uses the .w2p extension instead of the .tgz extension to prevent the browser from unzipping on download. They can be uncompressed manually with tar xzvf [filename] although this is never necessary.

Upon successful upload, web2py displays the MD5 checksum of the uploaded file. You can use it to verify that the file was not corrupted during upload. The application name will appear in the list of installed applications.

If you run web2py from source and you have gitpython installed (if necessary, set it up with ‘easy_install gitpython’), you can install applications directly from git repositories using the .git URL in the upload form. In this case you will also be enabled to use the admin interface to push changes back into the repository, but this is an experimental feature.

For example, you can locally install the application that shows this book on the web2py site with the URL:

https://github.com/web2py/web2py-book.git

That repository hosts the current, updated version of this book (which could be different from the stable version you can see on the web site). You are warmly invited to use it for submitting improvements, fixes and corrections in the form of pull requests.

For each application installed you can use the site page to:

• Go directly to the application by clicking on its name.
• Uninstall the application.
• Jump to the about page (read below).
• Jump to the edit page (read below).
• Jump to the errors page (read below).
• Clean up temporary files (sessions, errors, and cache.disk files).
• Pack all. This returns a tar file containing a complete copy of the application. We suggest that you clean up temporary files before packing an application.
• Compile the application. If there are no errors, this option will bytecode-compiles all models, controllers and views. Because views can extend and include other views in a tree, before bytecode compilation, the view tree for every controller is collapsed into a single file. The net effect is that a bytecode-compiled application is faster, because there is no more parsing of templates or string substitutions occurring at runtime.
• Pack compiled. This option is only present for bytecode-compiled applications. It allows packing the application without source code for distribution as closed source. Note that Python (as any other programming language) can technically be decompiled; therefore compilation does not provide complete protection of the source code. Nevertheless, de-compilation can be difficult and can be illegal.
• Remove compiled. It simply removes the byte-code compiled models, views and controllers from the application. If the application was packaged with source code or edited locally, there is no harm in removing the bytecode-compiled files, and the application will continue to work. If the application was installed form a packed compiled file, then this is not safe, because there is no source code to revert to, and the application will no longer work.

All the functionality available from the web2py admin site page is also accessible programmatically via the API defined in the module gluon/admin.py. Simply open a python shell and import this module.

If the Google App Engine SDK is installed the admin site page shows a button to push your applications to GAE. If python-git is installed, there is also a button to push your application to Open Shift. To install applications on Heroku or other hosting system you should look into the “scripts” folder for the appropriate script.

About

The about tab allows editing the description of the application and its license. These are written respectively in the ABOUT and LICENSE files in the application folder.

You can use MARKMIN, or gluon.contrib.markdown.WIKI syntax for these files as described in ref.[markdown2] .

Design

You have used the edit page already in this chapter. Here we want to point out a few more functionalities of the edit page.

• If you click on any file name, you can see the contents of the file with syntax highlighting.
• If you click on edit, you can edit the file via a web interface.
• If you click on delete, you can delete the file (permanently).
• If you click on test, web2py will run tests. Tests are written by the developer using Python doctests, and each function should have its own tests.
• You can add language files, scan the app to discover all strings, and edit string translations via the web interface.
• If the static files are organized in folders and subfolders, the folder hierarchy can be toggled by clicking on a folder name.

The image below shows the output of the test page for the welcome application.

The image below show the languages tab for the welcome application.

The image below shows how to edit a language file, in this case the “it” (Italian) language for the welcome application.

Integrated web-based debugger

(requires Python 2.7 or later)

The web2py admin includes a web-based debugger.

Using the provided web-based editor you can add breakpoints to the Python code and, from the associated debugger console, you can inspect the system variables at those breakpoints and resume execution. This is illustrated in the following screenshot: The interactive console also serves as a python scratchpad.

This functionality is based on the Qdb debugger created by Mariano Reingart. It uses multiprocessing.connection to communicate between the backend and frontend, with a JSON-RPC-like stream protocol. [qdb]

Setting breakpoints via code

Include this:

from gluon.debug import dbg

and to drop into the debugger, put this in the desired location:

dbg.set_trace()

The debugger app has a breakpoint manager.

Notes: web2py does not know whether you actually have a debug window open in your browser; execution suspends regardless. IDEs usually have their own inter-process debugger, e.g. PyCharm or PyDev. They may complain if you include the gluon library.

Web-based Python shell

If you click on the “shell” link under the controllers tab in edit, web2py will open a web based Python shell and will execute the models for the current application. This allows you to interactively talk to your application.

Be careful using the web based shell - because different shell requests will be executed in different threads. This easily gives errors, especially if you play with databases creation and connections. For activities like these (i.e. if you need persistence) it’s much better to use the python command line.

Crontab

Also under the controllers tab in edit there is a “crontab” link. By clicking on this link you will be able to edit the web2py crontab file. This follows the same syntax as the Unix crontab but does not rely on Unix. In fact, it only requires web2py, and it works on Windows. It allows you to register actions that need to be executed in background at scheduled times. For more information about this, see the next chapter.

Errors

When programming web2py, you will inevitably make mistakes and introduce bugs. web2py helps in two ways: 1) it allows you to create tests for every function that can be run in the browser from the edit page; and 2) when an error manifests itself, a ticket is issued to the visitor and the error is logged.

Intentionally introduce an error in the images application as shown below:

def index():
    images = db().select(db.image.ALL, orderby=db.image.title)
    1/0
    return dict(images=images)

When you access the index action, you get the following ticket:

Only the administrator can access the ticket:

The ticket shows the traceback, and the content of the file that caused the problem, and the complete state of system (variables, request, session, etc.) If the error occurs in a view, web2py shows the view converted from HTML into Python code. This allows to easily identify the logical structure of the file.

By default tickets are stored on filesystem and displayed grouped by traceback. The administrative interface provides an aggregate views (type of traceback and number of occurrence) and a detailed view (all tickets are listed by ticket id). The administrator can switch between the two views.

Notice that everywhere admin shows syntax-highlighted code (for example, in error reports, web2py keywords are shown in orange). If you click on a web2py keyword, you are redirected to a documentation page about the keyword.

If you fix the divide-by-zero bug in the index action and introduce one in the index view:

{{extend 'layout.html'}}
<h1>Current Images</h1>
<ul>
{{for image in images:}}
{{1/0}}
{{=LI(A(image.title, _href=URL("show", args=image.id)))}}
{{pass}}
</ul>

you get the following ticket:

Note that web2py has converted the view from HTML into a Python file, and the error described in the ticket refers to the generated Python code and NOT to the original view file:

This may seem confusing at first, but in practice it makes debugging easier, because the Python indentation highlights the logical structure of the code that you embedded in the views.

The code is shown at the bottom of the same page.

All tickets are listed under admin in the errors page for each application:

Mercurial

If you are running from source, the administrative interface shows one more menu item called “Versioning”.

Entering a comment and pressing the “commit” button in the resulting page will commit the current application. With the first commit, a local Mercurial repository for the specific application will be created. Under the hood, Mercurial stores information about changes you make in your code into a hidden folder “.hg” in your app subfolder. Every app has its own “.hg” folder and its own “.hgignore” file (tells Mercurial which files to ignore). In order to use this feature, you must have the Mercurial version control libraries installed (at least version 1.9):

pip install mercurial

The Mercurial web interface does allow you to browse previous commit and diff files but we do recommend you use Mercurial directly from the shell or one of the many GUI-based Mercurial clients since they are more powerful. For example they will allow you to sync your app with a remote source repository.

You can read more about Mercurial here:

http://mercurial.selenic.com/

Git integration

The admin app also includes git integration. Python git libraries are required, e.g.

pip install gitpython

and then per application, you must clone or otherwise configure a git repository.

After these steps, the Manage menu for each git-managed application will show git push and git pull. Applications which are not managed by git are ignored. You can pull and push apps from the default remote repository.

Application Wizard (experimental)

The admin interface includes a Wizard that can help you create a new applications. You can access the wizard from the “site” page as shown in the image below.

The wizard will guide you through a series of steps involved in creating a new application:

• Chose a name for the application
• Configure the application and choose required plugins
• Build required models (it will create CRUD pages for each model)
• Allow you to edit the views of those pages using MARKMIN syntax

The image below shows the second step of the process.

You can see a dropdown to select a layout plugin (from web2py.com/layouts), a multiple choice dropdown to check other plugins (from web2py.com/plugins) and a “login config” field where to put the Janrain “domain:key”.

The other steps are pretty much self-explanatory.

The Wizard works well for what it does but it is considered an experimental feature for two reasons:

• Applications created with the wizard and edited manually, cannot later be modified by the wizard.
• The interface of the wizard will change over time to include support for more features and easier visual development.

In any case the wizard is a handy tool for fast prototyping and it can be used to bootstrap a new application with an alternate layout and optional plugins.

Configuring admin

Normally there is no need to perform any configuration of admin but a few customizations are possible. After you login into admin you can edit the admin configuration file via the URL:

http://127.0.0.1:8000/admin/default/edit/admin/models/0.py

Notice that admin can be used to edit itself. In fact admin is an app as any other one.

The file “0.py” is more or less self documented, anyway, here are some of the most important possible customizations:

GAE_APPCFG = os.path.abspath(os.path.join('/usr/local/bin/appcfg.py'))

This should point to the location of the “appcfg.py” file that comes with the Google App Engine SDK. If you have the SDK you may want to change these config parameters to the correct value. It will allow you to deploy to GAE from the admin interface.

You can also set web2py admin in demo mode:

DEMO_MODE = True
FILTER_APPS = ['welcome']

And only the apps listed in FILTER_APPS will be accessible and they will be only accessible in read-only mode.

If you are a teacher and want to expose the administrative interface to students so that students can share one administrative interface for their projects (think of a virtual lab), can do it by setting:

MULTI_USER_MODE = True

In this way students will be required to login and will only be able to access their own apps via admin. You, as first user/teacher, will be able to access them all.

In multi user mode, you can register students using the “bulk register” link in admin and manage them using the “manage students” link. The system also keeps track of when students login and how many lines of code they add/remove to/from their code. This data is presented to the administrator as charts under the application “about” page.

Mind that this mechanism still assumes all users are trusted. All the apps created under admin run under the same credentials on the same filesystem. It is possible for an app created by a student to access the data and the source of an app created by another student. It is also possible for a student to create an app that locks the server.

Mobile admin

Notice that the admin application includes “plugin_jqmobile” which packages jQuery Mobile. When admin is accessed from a mobile device, this is detected by web2py and the interface is displayed using a mobile-friendly layout: