# Creating an app

The Django web site has a very good tutorial to get you familiar with the Django framework. The more you know about Django, the easier you will find it working with the OmeroWeb framework.

All official OMERO applications can be installed from PyPI.

## Getting set up

In order to deploy OMERO.web in a development or testing environment, please start by following the install instructions under OMERO.web installation for developers to create a python environment with omero-py and omero-web installed.

If you want to make changes to the OMERO.web code itself, go to Editing OMERO.web.

## Create an app using cookiecutter

Follow the instructions in cookiecutter-omero-webapp to install cookiecutter, create your app and run it within your omero-web python environment.

## Exploring the app

The working of the newly created app is well-documented within the code itself.

Briefly, the app supports a single URL defined in `urls.py` which maps to the `index` function within `views.py`. This uses the connection to OMERO, `conn` to load the current user’s name and passes this to the `index.html` template to render the page.

Here we are using the OMERO python API to load data and render it into `html` using Django templates.

An alternative option is to use JavaScript to load data in the form of JSON and to generate `html` dynamically in the browser.

The sample `index.html` page also includes the static `app.js` and `app.css` files to demonstrate this approach. JavaScript is used to load the current user’s Projects` from the JSON API and display them on the page.

You may find that the JSON API or WebGateway provide some of the data you wish to load. If you wish to provide your own custom JSON api, you can add URL end-points to your own app and load the data you need in `views.py` then format it to JSON and return it as a JSON response.

## App settings

You can add settings to your app that allow configuration via the command line in the same way as for the base OMERO.web. The list of `CUSTOM_SETTINGS_MAPPINGS` in settings.py is a good source for examples of the different data types and parsers you can use.

For example, if you want to create a user-defined setting appname.foo, that contains a dictionary of key-value pairs, you can add to `CUSTOM_SETTINGS_MAPPINGS` in `appname/settings.py`:

    import json
    CUSTOM_SETTINGS_MAPPINGS = {
        "omero.web.appname.foo": ["FOO", '{"key": "val"}', json.loads]
    }

From somewhere else in your app, you can then access the settings:

    from appname import settings

    print(settings.FOO)

Users can then configure this on the command line as follows:

    $ omero config set omero.web.appname.foo '{"userkey": "userval"}'

## Linking from Webclient

If you want to add links to your app from the webclient, a number of options are described on Linking from Webclient.

## Releasing your app

The Release an app page has some useful steps to take when you are preparing to release your app.