Tethys Platform 1.4.0¶

Generate Scaffold¶

To generate a new app using the scaffold, open a terminal, press CTRL-C to stop the development server if it is still running, and execute the following commands:

         $ . /usr/lib/tethys/bin/activate
(tethys) $ mkdir ~/tethysdev
(tethys) $ cd ~/tethysdev
(tethys) $ tethys scaffold my_first_app

The final command from the code block above is provided by the Tethys Command Line Interface. It will prompt you to enter metadata about your app such as, proper name, version, author, and description. All of these metadata are optional and you can accept the default value by pressing enter.

The commands you entered did the following tasks:

1. activated the Tethys Python virtual environment,
2. created a new directory called “tethysdev” in your home directory,
3. changed your working directory into the tethysdev directory, and
4. executed the tethys scaffold command to create the new app.

In a file browser change into your Home directory and open the tethysdev directory. If the scaffolding worked, you should see a directory called tethysapp-my_first_app. All of the source code for your app is located in this directory. Open the tethysapp-my_first_app and explore the contents. The main directory of your app project, my_first_app, is located within a namespace directory called tethysapp. Each part of the app project will be explained throughout these tutorials. For more information about the app project structure, see App Project Structure.

Development Installation¶

Now that you have a new Tethys app project, you need to install the app into Tethys Platform. In a terminal, change into the tethysapp-my_first_app directory and execute the python setup.py develop command. Be sure to activate the Tethys Python virtual environment if it is not already activated (see line 1 of the first code block):

(tethys) $ cd ~/tethysdev/tethysapp-my_first_app
(tethys) $ python setup.py develop

View Your New App¶

Use start up the database Docker (postgis) and the development server:

(tethys) $ tethys docker start -c postgis
(tethys) $ tethys manage start

Browse to http://127.0.0.1:8000/apps. If all has gone well, you should see your app listed on the app library page. Exploring your new app won’t take long, because there is only one page. Familiarize yourself with different parts of the app interface (see below).

Parts of a Tethys app interface: (1) app navigation toggle, (2) exit button, (3) app navigation, (4) actions, and (5) app content.

(tethys) $ tethys docker stop

Model View Controller¶

Tethys apps are developed using the Model View Controller (MVC) software architecture pattern. Following the MVC pattern will make your app project easier to develop and maintain in the future. Most of the code in your app will fall into one of the three MVC categories. The Model represents the data of your app, the View is composed of the representation of the data, and the Controller consists of the logic to prepare the data for the view and any other logic your app needs. In the next few tutorials, you will be introduced to how the MVC development paradigm is used to develop Tethys apps. For more information about MVC, see Key Concepts.

App Project Paths¶

Throughout the tutorial, you will be asked to open various files. Most of the files will be located in your app package directory which shares the name of your app: “my_first_app”. If you generated your scaffold exactly as above, this directory will be located at the following path:

# Path to App Package Directory
~/tethysdev/tethysapp-my_first_app/tethysapp/my_first_app/

For convenience, all paths in the following tutorials will be given relative to the app package directory. For example:

# Relative App Package Directory Notation
my_first_app/controllers.py

Register a Persistent Store¶

The Tethys Portal provides the Persistent Stores API to streamline the use of SQL databases in apps. To register a new persistent store database add the persistent_stores() method to your app class, which is located in your app configuration file. This method must return a list or tuple of PersistentStore objects.

Open the app configuration file for your app located at my_first_app/app.py in your favorite text editor. Import the PersistentStore object at the top of the file, add the persistent_stores() method to your app class, and save the changes:

from tethys_sdk.base import TethysAppBase, url_map_maker
from tethys_sdk.stores import PersistentStore


class MyFirstApp(TethysAppBase):
    """
    Tethys app class for My First App.
    """

    name = 'My First App'
    index = 'my_first_app:home'
    icon = 'my_first_app/images/icon.gif'
    package = 'my_first_app'
    root_url = 'my-first-app'
    color = '#e74c3c'
    description = ''
    tags = ''
    enable_feedback = False
    feedback_emails = []


    def url_maps(self):
        """
        Add controllers
        """
        UrlMap = url_map_maker(self.root_url)

        url_maps = (UrlMap(name='home',
                           url='my-first-app',
                           controller='my_first_app.controllers.home'),
        )

        return url_maps

    def persistent_stores(self):
        """
        Add one or more persistent stores
        """
        stores = (PersistentStore(name='stream_gage_db',
                                  initializer='my_first_app.init_stores.init_stream_gage_db',
                                  spatial=True
                ),
        )

        return stores

A persistent store database will be created for each PersistentStore object that is returned by the persistent_stores() method of your app class. In this case, your app will have a persistent store named “stream_gage_db”. The initializer argument points to a function that you will define in a later step. The spatial argument can be used to add spatial capabilities to your persistent store. Tethys Platform provides PostgreSQL databases for persistent stores and PostGIS for the spatial database capabilities.

Create an SQLAlchemy Data Model¶

After your database is created, you will need to create the tables that will store the data for your app. The plan for your database tables or schema is called a data model. SQLAlchemy provides an Object Relational Mapper (ORM) that allows you to create data models using Python code and issue queries using an object-oriented approach. In other words, you are able to harness the power of SQL databases without writing SQL. As a primer to SQLAlchemy ORM, we highly recommend you complete the Object Relational Tutorial.

In this step, you will use SQLAlchemy to create a data model for the tables that will store the data for your app. Open the model.py file located at my_first_app/model.py in a text editor.

First, add the following import statements to your model.py file:

from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column, Integer, Float
from sqlalchemy.orm import sessionmaker

from .app import MyFirstApp

Next, add these lines to your model.py file:

# DB Engine, sessionmaker and base
engine = MyFirstApp.get_persistent_store_engine('stream_gage_db')
SessionMaker = sessionmaker(bind=engine)
Base = declarative_base()

The get_persistent_store_engine() method that is used here accepts the name of a persistent store as an argument and returns an SQLAlchemy engine object. The engine object contains the connection information needed to connect to the persistent store database. Anytime you want to query or modify your persistent store data, you will do so with an SQLAlchemy session object. As the name implies, the SessionMaker can be used to create new session objects. The Base object is used in the next step when we define our data model. Add these lines to your model.py file:

# SQLAlchemy ORM definition for the stream_gages table
class StreamGage(Base):
    '''
    Example SQLAlchemy DB Model
    '''
    __tablename__ = 'stream_gages'

    # Columns
    id = Column(Integer, primary_key=True)
    latitude = Column(Float)
    longitude = Column(Float)
    value = Column(Integer)

    def __init__(self, latitude, longitude, value):
        """
        Constructor for a gage
        """
        self.latitude = latitude
        self.longitude = longitude
        self.value = value

Each class in an SQLAlchemy data model defines a table in the database. The model you defined above consists of a single table called “stream_gages”, as denoted by the __tablename__ property of the StreamGage class. The StreamGage class inherits from the Base class that we created in the previous lines. This inheritance notifies SQLAlchemy that the StreamGage class is part of the data model.

The class defines four other properties that are SQLAlchemy Column objects: id, latitude, longitude, and value. These properties define the columns of the “stream_gages” table. The column type and options are defined by the arguments passed to the Column constructor. For example, the latitude column is of type Float while the id column is of type Integer and is also flagged as the primary key for the table. The StreamGage class also has a simple constructor method called __init__().

This class is not only used to define the tables for your persistent store, it will also be used to create objects for interacting with your data.

Be sure to save the changes to model.py and close before proceeding.

Create an Initialization Function¶

Now that you have created a data model, the next step is to write a database initialization function. This function will be called during the initialization phase of your persistent store database and will be used to create the tables in your database and add any initial data that you may need in the database for your app to work.

Open the my_first_app/init_stores.py in a text editor. At the top of this file, import the engine, SessionMaker, Base, and StreamGage from your data model:

from .model import engine, SessionMaker, Base, StreamGage

Next, create a new function called init_stream_gage_db() with a single argument called first_time and the following code:

def init_stream_gage_db(first_time):
    """
    An example persistent store initializer function
    """
    # Create tables
    Base.metadata.create_all(engine)

    # Initial data
    if first_time:
        # Make session
        session = SessionMaker()

        # Gage 1
        gage1 = StreamGage(latitude=40.23812952992122,
                           longitude=-111.69585227966309,
                           value=1)


        session.add(gage1)

        # Gage 2
        gage2 = StreamGage(latitude=40.238784729316215,
                           longitude=-111.7101001739502,
                           value=2)

        session.add(gage2)

        # Gage 3
        gage3 = StreamGage(latitude=40.23650788415366,
                           longitude=-111.73278093338013,
                           value=3)

        session.add(gage3)

        # Gage 4
        gage4 = StreamGage(latitude=40.242519244799816,
                           longitude=-111.68254852294922,
                           value=4)

        session.add(gage4)

        session.commit()

The Base.metedata.create_all(engine) line is all that is needed to create the tables in your persistent store database. Every class that inherits from the Base class is tracked by a metadata object. The metadata.create_all() method issues the SQL that is needed to create the tables associated with the Base class. Notice that you must give it the engine object for connection information.

The first_time parameter that is passed to all persistent store initialization functions is a boolean that is True if the function is being called after the tables have been created for the first time. This is provided as a mechanism for adding initial data only the first time. Notice the code that adds initial data to your persistent store database is wrapped in a conditional statement that uses the first_time parameter.

This initial data code adds four stream gages to your persistent store database. Creating a new record in the database using SQLAlchemy is achieved by creating a new StreamGage object and adding it to the session object using the session.add() method. To persist the new records to the persistent store database, the session.commit() method is called. You will learn how to query the persistent store database using SQLAlchemy in the The Controller tutorial.

Save your changes to init_stores.py and close before moving on.

Register Initialization Function¶

Recall that when you registered the persistent store in your app configuration file, you specified the initializer function for the persistent store. This argument accepts a string representing the path to the function using dot notation and a colon to delineate the function (e.g.: “app_name.module.function”). Check your app configuration file (app.py) to ensure the path to the initializer function is correct: 'my_first_app.init_stores.init_stream_gage_db'.

Persistent Store Initialization¶

The Tethys command line utility provides a command for initializing persistent stores. Save all changes to the files you edited and stop your development server using CTRL-C if it is still running. It is possible that your server may have crashed during editing and is displaying errors; ignore these errors. Execute the following command in the terminal:

(tethys) $ tethys syncstores my_first_app

The database will be initialized and you will see text printed to the terminal that will indicate this:

Loading Tethys Apps...
Tethys Apps Loaded: my_first_app

Provisioning Persistent Stores...
Creating database "stream_gage_db" for app "my_first_app"...
Enabling PostGIS on database "stream_gage_db" for app "my_first_app"...
Initializing database "stream_gage_db" for app "my_first_app" using initializer "init_stream_gage_db"...

If you have a graphical database client like PGAdmin III, you may wish to connect to your PostgreSQL database server and confirm that the database was created. You can use the credentials for tethys_super database user that you defined during installation to connect to the database. The name of the database will be a combination of the name of your app and the name of the persistent store: (e.g.: my_first_app_stream_gage_db). For a more detailed explanation of connecting to your database using PGAdmin III, see the PGAdmin III Tutorial.

Example of graphical database client PGAdmin III.

Templating¶

The Django template language is a simple, but powerful templating language. This section will provide a crash course in Django template language basics, but we highly recommend a review of the Django Template Language documentation.

Browse to the your templates directory located at my_first_app/templates/. By convention, all the templates for your app are stored in a directory with the same name of your app package inside the templates directory (e.g.: templates/my_first_app). This will prevent potential conflicts with the templates of other apps. You will find two templates in this directory: base.html and home.html. Refer to these templates as the Django template concepts are introduced.

Base Template¶

Tethys apps generated from the scaffold come with a base.html template which has the following contents:

{% extends "tethys_apps/app_base.html" %}

{% load staticfiles %}

{% block title %}- {{ tethys_app.name }}{% endblock %}

{% block styles %}
  {{ block.super }}
  <link href="{% static 'my_first_app/css/main.css' %}" rel="stylesheet"/>
{% endblock %}

{% block app_icon %}
  {# The path you provided in your app.py is accessible through the tethys_app.icon context variable #}
  <img src="{% static tethys_app.icon %}">
{% endblock %}

{# The name you provided in your app.py is accessible through the tethys_app.name context variable #}
{% block app_title %}{{ tethys_app.name }}{% endblock %}

{% block app_navigation_items %}
  <li class="title">App Navigation</li>
  <li class="active"><a href="">Home</a></li>
  <li><a href="">Jobs</a></li>
  <li><a href="">Results</a></li>
  <li class="title">Steps</li>
  <li><a href="">1. The First Step</a></li>
  <li><a href="">2. The Second Step</a></li>
  <li><a href="">3. The Third Step</a></li>
  <li class="separator"></li>
  <li><a href="">Get Started</a></li>
{% endblock %}

{% block app_content %}
{% endblock %}

{% block app_actions %}
{% endblock %}

{% block scripts %}
  {{ block.super }}
  <script src="{% static 'my_first_app/js/main.js' %}" type="text/javascript"></script>
{% endblock %}

The base.html template is intended to be used as the parent template for all your app templates via the extends tag. It contains several block tags that your app templates can override or extend. The block tags you will use most often are app_navigation_items, app_content, and, app_actions. These blocks correspond with different parts of the app interface (shown in the figure below). As a rule, content that you would like to be present in all your templates should be included in the base.html template and content that is specific to a certain template should be included in that template.

The block tags of the base.html template correspond with different parts of the interface: (1) app_navigation_items, (2) app_content, and (3) app_actions.

Tip

For an explanation of the blocks in the base.html template see the App Templating API.

Public Files and Resources¶

Most apps will use files and resources that are static–meaning they do not need to be preprocessed before being served like templates do. Examples of these files include images, CSS files, and JavaScript files. Tethys Platform will automatically register static files that are located in the public directory of your app project. Use the static tag in templates to load the resource URLs. The base.html template provides examples of how to use the static tag. See the Django documentation for the static tag for more details.

Make a New Template¶

Now that you know the basics of templating, you will learn how to create new templates that extend the base template and use the block tags. Create a new template in your templates directory (my_first_app/templates/my_first_app/) and name it map.html. Open this file in a text editor and copy and paste the following code into it:

{% extends "my_first_app/base.html" %}

{% load tethys_gizmos %}

{% block app_content %}
  <h1>Stream Gages</h1>
  {% gizmo map_view map_options %}
{% endblock %}

{% block app_actions %}
  <a href="{% url 'my_first_app:home' %}" class="btn btn-default">Back</a>
{% endblock %}

The map.html template that you created extends the base.html template. It also overrides the app_content, app_actions`, and scripts blocks. An action called “Back” is added to the app_actions block. It uses a new tag, the url tag, to provide a link back to the home page of the app. The url tag will be discussed in more detail in the URL Mapping tutorial.

The map is inserted into the app_content block using one of the Tethys Gizmos called map_view. Gizmos are an easy way to insert common user interface elements in to your templates with minimal code. The map is configured via a dictionary called map_options, which is defined in the controller. This will be discussed in the next tutorial. For more information on Gizmos, refer to the Template Gizmos API documentation.

Make a New Controller¶

Recall that in The Model and Persistent Stores tutorial you created an SQLAlchemy data model to store information about stream gages. You also created an initialization function that loaded some dummy data into your database. You will now add some logic to your controller to retrieve this data and pass it to the template.

Open your controllers.py file located at my_first_app/controllers.py. This file should contain a function called home. This function is the controller for the home page of your app. All controller functions must accept a request object and they must return a response object. The request object contains information about the HTTP request, including any form data that is submitted (more on this later). There are several ways to return a response object, but the most common way is to use the render() function provided by Django. This function requires three arguments: the request object, the template to be rendered, and the context dictionary.

Add the following imports to the top of the file:

from .model import SessionMaker, StreamGage
from tethys_sdk.gizmos import MapView, MVLayer, MVView

Then add a new controller function called map after the home function:

@login_required()
def map(request):
    """
    Controller for map page.
    """
    # Create a session
    session = SessionMaker()

    # Query DB for gage objects
    gages = session.query(StreamGage).all()

    # Transform into GeoJSON format
    features = []

    for gage in gages:
        gage_feature = {
          'type': 'Feature',
          'geometry': {
            'type': 'Point',
            'coordinates': [gage.longitude, gage.latitude]
          }
        }

        features.append(gage_feature)

    geojson_gages = {
      'type': 'FeatureCollection',
      'crs': {
        'type': 'name',
        'properties': {
          'name': 'EPSG:4326'
        }
      },
      'features': features
    }

    # Define layer for Map View
    geojson_layer = MVLayer(source='GeoJSON',
                            options=geojson_gages,
                            legend_title='Provo Stream Gages',
                            legend_extent=[-111.74, 40.22, -111.67, 40.25])

    # Define initial view for Map View
    view_options = MVView(
        projection='EPSG:4326',
        center=[-111.70, 40.24],
        zoom=13,
        maxZoom=18,
        minZoom=2
    )

    # Configure the map
    map_options = MapView(height='500px',
                          width='100%',
                          layers=[geojson_layer],
                          view=view_options,
                          basemap='OpenStreetMap',
                          legend=True)

    # Pass variables to the template via the context dictionary
    context = {'map_options': map_options}

    return render(request, 'my_first_app/map.html', context)

The new map controller queries the persistent store for the stream gages, converts the data into GeoJSON format for the map, and configures the map options for the Map View Gizmo that is used in the template.

To query the database, an SQLAlchemy session object is needed. It is created using the SessionMaker object imported from the model.py file. Querying is accomplished by using the query() method on the session object. The result is a list of StreamGage objects representing the records in the database.

The map is capable of consuming spatial data in a few formats including GeoJSON, so the map controller handles the job of converting the data from the list of StreamGage objects to GeoJSON format.

The map Gizmo that is used in the map.html template requires a dictionary of configuration options called “map_options”. This is created in the controller and the input_overlays option is used to give the GeoJSON formatted stream gage data to the map.

Next, a template context dictionary is defined that contains all of the variables that you wish to be available for use in the template.

Finally, the render() function is used to create the response object. It is in the render() function that you specify the template that is to be rendered by the controller. In this case, the map.html that you created in the last tutorial. Note that the path you provide to the template is relative to the template directory of your app: my_first_app/map.html.

Save controllers.py before going on.

Map Controller to URL¶

Mapping a controller to a URL is performed in the app configuration file (app.py). Open your app configuration file located at my_first_app/app.py. Your app class will already have a method called url_maps(). This method must return a list or tuple of UrlMap objects. UrlMap objects require three attributes: name, url, and controller.

Your app class will already have one UrlMap for the home page called “home”. Add a new UrlMap object for the map controller that you created in the previous step. Give it a name of “map”, a url of “my-first-app/map”, and a path to the controller of “my_first_app.controllers.map”. The url_maps() method for your app should look something like this when you are done:

def url_maps(self):
    """
    Add controllers
    """
    UrlMap = url_map_maker(self.root_url)

    url_maps = (UrlMap(name='home',
                       url='my-first-app',
                       controller='my_first_app.controllers.home'),
                UrlMap(name='map',
                       url='my-first-app/map',
                       controller='my_first_app.controllers.map'),
    )

    return url_maps

Now that you have created the URL map for your new map page, you can create a link to it from the home page. Open the home.html template located at my_first_app/templates/my_first_app/home.html. Replace the app_actions template block with the following:

{% block app_actions %}
  <a href="{% url 'my_first_app:map' %}" class="btn btn-default">Go To Map</a>
{% endblock %}

In this code, the url template tag is used to provide the url to the map page. It accepts a string with the following pattern: "name_of_app:name_of_url_map". The advantage of using the url tag as opposed to hard coding the URL is that if the URL ever needs to be changed, you will only need to change it in your app configuration file and not in every template that references that URL.

View New Map Page¶

At this point, your app should be ready to run again. Save all changes in the files you edited and restart the development server using the tethys manage start command in the terminal (stop it using CTRL-C if necessary). Browse to your app home page at http://127.0.0.1:8000/apps/my-first-app. Use the “Go To Map” action to browse to your new map page. Click on the “Provo Stream Gages” layer in the legend to zoom to that layer. Your map page should look similar to this:

New URL Map and URL Variables¶

You can add variables to your URLs to make your controllers and web pages more dynamic. URL variables are denoted by single curly braces in the URL string like this: /example/url/{variable}. Open the my_first_app/app.py file in a text editor. Modify the url_maps() method by adding a new UrlMap object named “map_single” with a URL variable called “id”. Your url_maps() method should look like this when you are done:

def url_maps(self):
    """
    Add controllers
    """
    UrlMap = url_map_maker(self.root_url)

    url_maps = (UrlMap(name='home',
                       url='my-first-app',
                       controller='my_first_app.controllers.home'),
                UrlMap(name='map',
                       url='my-first-app/map',
                       controller='my_first_app.controllers.map'),
                UrlMap(name='map_single',
                       url='my-first-app/map/{id}',
                       controller='my_first_app.controllers.map_single'),
    )

    return url_maps

New Controller¶

Notice that the map_single UrlMap object points to a controller named “map_single”. This controller doesn’t exist yet, so we will need to create it. Open the my_first_app/controllers.py in a text editor and add the map_single controller function to it:

@login_required
def map_single(request, id):
    """
    Controller for map page.
    """
    # Create a session
    session = SessionMaker()

    # Query DB for gage objects
    gage = session.query(StreamGage).filter(StreamGage.id==id).one()

    # Transform into GeoJSON format
    gage_feature = {
      'type': 'Feature',
      'geometry': {
        'type': 'Point',
        'coordinates': [gage.longitude, gage.latitude]
      }
    }

    geojson_gages = {
      'type': 'FeatureCollection',
      'crs': {
        'type': 'name',
        'properties': {
          'name': 'EPSG:4326'
        }
      },
      'features': [gage_feature]
    }

    # Define layer for Map View
    geojson_layer = MVLayer(source='GeoJSON',
                            options=geojson_gages,
                            legend_title='Provo Stream Gages',
                            legend_extent=[-111.74, 40.22, -111.67, 40.25])

    # Define initial view for Map View
    view_options = MVView(
        projection='EPSG:4326',
        center=[-111.70, 40.24],
        zoom=13,
        maxZoom=18,
        minZoom=2
    )

    # Configure the map
    map_options = MapView(height='500px',
                          width='100%',
                          layers=[geojson_layer],
                          view=view_options,
                          basemap='OpenStreetMap',
                          legend=True)

    context = {'map_options': map_options,
               'gage_id': id}

    return render(request, 'my_first_app/map.html', context)

The map_single controller function is slightly different than the map controller you created earlier. It accepts an additional argument called “id”. The id URL variable value will be passed to the map_single controller making the id variable available for use in the controller logic.

Anytime you create a URL with variables in it, the variables need to be added to the arguments of the controller function it maps to.

The map_single controller is similar but different from the map controller you created earlier. The SQLAlchemy query searches for a single stream gage record using the id variable via the``filter()`` method. The stream gage data returned by the query is reformatted into GeoJSON format as before and the map_options for the Gizmo are defined.

The context is expanded to include the id variable, so that it will be available for use in the template. The same map.html template is being used by this controller as was used by the map controller. However, it will need to be modified slightly to make use of the new gage_id context variable.

Modify the Template¶

Open the map.html template located at my_first_app/templates/my_first_app/map.html. Modify the template so that it matches this:

{% extends "my_first_app/base.html" %}

{% load tethys_gizmos %}

{% block app_navigation_items %}
  <li class="title">Gages</li>
  <li{% if not gage_id %} class="active"{% endif %}>
    <a href="{% url 'my_first_app:map' %}">All Gages</a>
  </li>
  <li{% if gage_id == '1' %} class="active"{% endif %}>
    <a href="{% url 'my_first_app:map_single' id=1 %}">Stream Gage 1</a>
  </li>
  <li{% if gage_id == '2' %} class="active"{% endif %}>
    <a href="{% url 'my_first_app:map_single' id=2 %}">Stream Gage 2</a>
  </li>
  <li{% if gage_id == '3' %} class="active"{% endif %}>
    <a href="{% url 'my_first_app:map_single' id=3 %}">Stream Gage 3</a>
  </li>
  <li{% if gage_id == '4' %} class="active"{% endif %}>
    <a href="{% url 'my_first_app:map_single' id=4 %}">Stream Gage 4</a>
  </li>
{% endblock %}

{% block app_content %}
  {% if gage_id %}
    <h1>Stream Gage {{gage_id}}</h1>
  {% else %}
    <h1>Stream Gages</h1>
  {% endif %}

  {% gizmo map_view map_options %}
{% endblock %}

{% block app_actions %}
  <a href="{% url 'my_first_app:home' %}" class="btn btn-default">Back</a>
{% endblock %}

There are two changes to the map.html template that are worth noting. First, the template now overrides the app_navigation_block to provide links for each of the stream gages in the navigation. The if template tag is used in each of the nav items to highlight the appropriate link based on the gage_id. Notice that all if tags must also end with a endif tag. The text between the two tags is displayed only if the conditional statement evaluates to True. The href for each link is provided using the url, but this time the id variable is also provided as an argument.

The other change to the template is the heading of the page (<h1>) is wrapped by if, else, and endif tags. The effect is to display “Stream Gage id#” when viewing only one stream gage and “Stream Gages” when viewing all of them.

View Updated Map Page¶

Just like that, you added a new page to your app using MVC. Save the changes to any files you edited and start up the development server using the tethys manage start command and browse to your app. Use the “Go To Map” action on the home page to browse to your new map page and use the options in the navigation pane to view the different gages. It should look like this (although you may need to pan and zoom some):

Variable URLs¶

Take note of the URL as you are viewing the different gages. You should see the ID of the current gage. For example, the URL for the gage with an ID of 1 would be http://127.0.0.1:8000/apps/my-first-app/map/1/. You can manually change the ID in the URL to request the gage with that ID. Visit this URL http://127.0.0.1:8000/apps/my-first-app/map/3/ and it will map the gage with ID 3.

Try this URL: http://127.0.0.1:8000/apps/my-first-app/map/100/. You should see a lovely error message, because you don’t have a gage with ID 100 in the database. This uncovers a bug in your code that we won’t take the time to fix in this tutorial. If this were a real app, you would need to handle the case when the ID doesn’t match anything in the database so that it doesn’t give you an error.

This exercise also exposes a vulnerability with using integer IDs in the URL–they can be guessed easily. For example if your app had a delete method, it would be very easy for an attacker to write a script that would increment through integers and call the delete method–effectively clearing your database. It would be a much better practice to use a UUID (see Universally unique identifier) or something similar for IDs.

New URL Map¶

The form will be created on a new page, which means you will need to create a new URL map and controller. Open your my_first_app/app.py and add a new UrlMap object called “echo_name” to the url_maps() method of your app class. The url_maps() method of your app class should look like this now:

def url_maps(self):
    """
    Add controllers
    """
    UrlMap = url_map_maker(self.root_url)

    url_maps = (UrlMap(name='home',
                       url='my-first-app',
                       controller='my_first_app.controllers.home'),
                UrlMap(name='map',
                       url='my-first-app/map',
                       controller='my_first_app.controllers.map'),
                UrlMap(name='map_single',
                       url='my-first-app/map/{id}',
                       controller='my_first_app.controllers.map_single'),
                UrlMap(name='echo_name',
                       url='my-first-app/echo-name',
                       controller='my_first_app.controllers.echo_name'),
    )

    return url_maps

New Template¶

Create a new template called “echo_name.html” in your templates directory (my_first_app/templates/my_first_app/echo_name.html). Open the file and add the following contents:

{% extends "my_first_app/base.html" %}

{% load tethys_gizmos %}

{% block app_navigation_items %}
  <li class="active"><a href="{% url 'my_first_app:echo_name' %}">Name Echoer</a></li>
{% endblock %}

{% block app_content %}
  <form method="post">
      {% csrf_token %}
      {% gizmo text_input text_input_options %}
      <input type="submit" name="name-form-submit" class="btn btn-default">
  </form>

  {% if name %}
    <h1>Hello, {{ name }}!</h1>
  {% endif %}
{% endblock %}

{% block app_actions %}
  <a href="{% url 'my_first_app:home' %}" class="btn btn-default">Back</a>
{% endblock %}

The form is denoted by the HTML <form> tag and it contains a text input (created by a template Gizmo) and a submit button. Also note the use of the csrf_token tag. This is a security precaution that is required to be included in all the forms of your app (see the Cross Site Forgery protection article in the Django documentation for more details).

Also note that the method attribute of the <form> element is set to post. This means the form will use the HTTP method called POST to submit the data to the server. For an introduction to HTTP methods, see The Definitive Guide to GET vs POST.

New Controller¶

Now you need to create the echo_name controller function. First, add the following import statement to the top of my_first_app/controllers.py` file:

from tethys_sdk.gizmos import TextInput

Then add the following function to your my_first_app/controllers.py file:

@login_required
def echo_name(request):
    """
    Controller that will echo the name provided by the user via a form.
    """
    # Default value for name
    name = ''

    # Define Gizmo Options
    text_input_options = TextInput(display_text='Enter Name',
                                   name='name-input')

    # Check form data
    if request.POST and 'name-input' in request.POST:
       name = request.POST['name-input']

    # Create template context dictionary
    context = {'name': name,
               'text_input_options': text_input_options}

    return render(request, 'my_first_app/echo_name.html', context)

There are a few features to point out in this controller. First, the Gizmo options for the text input are defined in this controller via the text_input_options dictionary. The text input must have a name assigned to it for its value to be sent with the form data. In this case the name of the text input is “name-input”. See the Template Gizmos API.

Next, the data that is submitted with HTML forms is returned through the request object. For forms submitted using the “post” method, the data will be accessible in the request.POST attribute. Similarly, form data submitted using the “get” method will be available via the request.GET attribute. Both request.GET and request.POST are dictionary like objects where the keys are the names of the fields from the form.

The controller contains logic that checks the request.POST for data with the name of the text input field, “name-input”. If it exists (which it will after the user submits the form), the name variable is replaced with the value of the text input. The name variable is passed to template where it renders a nice greeting.

Link to New Page¶

Create a link to the new page from the home page using the url tag. Open the my_first_app/templates/my_first_app/home.html file and replace the contents with this:

{% extends "my_first_app/base.html" %}

{% block app_navigation_items %}
  <li><a href="{% url 'my_first_app:echo_name' %}">Name Echoer</a></li>
{% endblock %}

{% block app_content %}
  <h1>Welcome!</h1>
  <p>Congratulations on creating a new Tethys app!</p>
{% endblock %}

{% block app_actions %}
  <a href="{% url 'my_first_app:map' %}" class="btn btn-default">Go To Map</a>
{% endblock %}

View New Page¶

The app is ready to be tested. Run the tethys manage start command in the terminal and browse to your app. Use the “Name Echoer” link in the navigation to access the new page. Enter your name, press submit, and enjoy the greeting. Your new page should look something like this:

Setup Script¶

When you generate your app using the scaffold, it will automatically generate a setup script (setup.py). Open the setup script for your app located at ~/tethysdev/tethysapp-my_first_app/setup.py. It should look something like this:

import os
import sys
from setuptools import setup, find_packages
from tethys_apps.app_installation import custom_develop_command, custom_install_command

### Apps Definition ###
app_package = 'my_first_app'
release_package = 'tethysapp-' + app_package
app_class = 'my_first_app.app:MyFirstApp'
app_package_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'tethysapp', app_package)

### Python Dependencies ###
dependencies = []

setup(
    name=release_package,
    version='0.0',
    tags='',
    description='',
    long_description='',
    keywords='',
    author='',
    author_email='',
    url='',
    license='',
    packages=find_packages(exclude=['ez_setup', 'examples', 'tests']),
    namespace_packages=['tethysapp', 'tethysapp.' + app_package],
    include_package_data=True,
    zip_safe=False,
    install_requires=dependencies,
    cmdclass={
        'install': custom_install_command(app_package, app_package_dir, dependencies),
        'develop': custom_develop_command(app_package, app_package_dir, dependencies)
    }
)

As a general rule, you should never modify the parameters under the “Apps Definition” heading. These parameters are used by the setup script to find the source code for your app and changing their values could result in your app not working properly. If you use Python libraries that are external to your app or Tethys Platform, you will need add the library name to the dependencies list in the setup script. These libraries will automatically be installed when your app is installed.

The final part of the setup script makes a call to the setup() function that is provided by the setuptools library. You will see the metadata that you defined during the scaffold process listed here. As you release subsequent versions of your app, you may wish to increment the version parameter of this function.

Setup Script Installation¶

The setup script is used to install your app and there are two types of installation that can be performed: install and develop. The install type of installation hard copies the source code of your app into the site-packages directory of your Python installation. The site-packages directory is where Python keeps all of the code for external modules and libraries that have been installed.

This is the type of installation you would use for a completed app that is being installed in a production environment. To perform this type of installation, open a terminal, change into the release package directory of your app, and run the install command on the setup script as follows:

cd ~/tethysdev/tethysapp-my_first_app
python setup.py install

The install type of installation is not well suited for working with your app during development, because you would need to reinstall it (i.e.: run the commands above) every time you made a change to the app source code. This is why the develop type of installation exists. When an app is installed with the develop command, the source code for your app is only linked to the site-packages directory. This allows you to change your code and test the changes without reinstalling the app.

You already performed this type of installation on your app during the Create a New Tethys App Project tutorial. To perform this type of installation, open a terminal, change into the release package directory, and run the develop command on the setup script like so:

cd ~/tethysdev/tethysapp-my_first_app
python setup.py develop

Start GeoServer Docker¶

Start up your GeoServer Docker container:

$ tethys docker start -c geoserver

Register GeoServer Docker¶

Get the endpoint for your GeoServer Docker container:

$ tethys docker ip

Register the GeoServer with Tethys in the Portal admin page. Select the dropdown menu next to your username in the top right-hand corner of the screen and select the “Site Admin” link. Select the “Spatial Dataset Servics” link from the “Tethys Services” section and then press the “Add Spatial Dataset Service” button. Create a new Spatial Dataset Service named “default” of type GeoServer, enter the endpoint and public endpoint as the same from the print out in the terminal, and fill out the username and password.

GeoServer Web Admin Interface¶

Explore the GeoServer web admin interface by visiting link: http://localhost:8181/geoserver/web/.

Scaffold New App¶

Create a new app and install it:

$ tethys scaffold geoserver_app
$ cd tethysapp-geoserver_app
$ python setup.py develop

Download Test Files¶

Download the sample shapefiles that you will use to test your app:

geoserver_app_data.zip

Add Form to Home Page¶

Replace the contents of the existing home.html template with:

{% extends "geoserver_app/base.html" %}

{% block app_content %}
  <h1>Upload a Shapefile</h1>
  <form action="" method="post" enctype="multipart/form-data">.
    {% csrf_token %}
    <div class="form-group">
        <label for="fileInput">Shapefiles</label>
        <input name="files" type="file" multiple class="form-control" id="fileInput" placeholder="Shapefiles">
    </div>
    <input name="submit" type="submit" class="btn btn-default">
  </form>
{% endblock %}

Handle File Upload in Home Controller¶

Add these imports to the top of the controllers.py module:

import random
import string

from django.shortcuts import render
from django.contrib.auth.decorators import login_required

from tethys_sdk.gizmos import *
from tethys_sdk.services import get_spatial_dataset_engine


WORKSPACE = 'geoserver_app'
GEOSERVER_URI = 'http://www.example.com/geoserver-app'

Modify the home() controller so that it can handle the file upload event like so:

@login_required
def home(request):
    """
    Controller for the app home page.
    """
    # Retrieve a geoserver engine
    geoserver_engine = get_spatial_dataset_engine(name='default')

    # Check for workspace and create workspace for app if it doesn't exist
    response = geoserver_engine.list_workspaces()

    if response['success']:
        workspaces = response['result']

        if WORKSPACE not in workspaces:
            response = geoserver_engine.create_workspace(workspace_id=WORKSPACE,
                                                         uri=GEOSERVER_URI)

    # Case where the form has been submitted
    if request.POST and 'submit' in request.POST:
        # Verify files are included with the form
        if request.FILES and 'files' in request.FILES:
            # Get a list of the files
            file_list = request.FILES.getlist('files')

            # Upload shapefile
            store = ''.join(random.choice(string.ascii_lowercase + string.digits) for _ in range(6))
            store_id = WORKSPACE + ':' + store
            response = geoserver_engine.create_shapefile_resource(
                        store_id=store_id,
                        shapefile_upload=file_list,
                        overwrite=True,
                        debug=True
            )

    context = {}

    return render(request, 'geoserver_app/home.html', context)

Test Shapefile Upload¶

Go to the home page of your app located at http://localhost:8000/apps/geoserver-app/. You should see a form with a file input (“Browse” button or similar) and a submit button. To test this page, select the “Browse” button and upload one of the shapefiles from the data that you downloaded earlier. Remember that for the shapefile to be valid, you need to select at least the files with the extensions “shp”, “shx”, and “dbf”. Press submit to upload the files.

Use the GeoServer web admin interface (http://localhost:8181/geoserver/web/) to verify that the layers were successfully uploaded. Look for layers belonging to the workspace ‘geoserver_app’.

Map Page UrlMap¶

Add a new UrlMap to the url_maps method of the app.py module:

UrlMap(name='map',
       url='geoserver-app/map',
       controller='geoserver_app.controllers.map'),

Map Page Controller¶

Add a new controller to the controller.py module:

@login_required
def map(request):
    """
    Controller for the map page
    """
    geoserver_engine = get_spatial_dataset_engine(name='default')

    options = []

    response = geoserver_engine.list_layers(with_properties=False)

    if response['success']:
        for layer in response['result']:
            options.append((layer.title(), layer))

    select_options = SelectInput(display_text='Choose Layer',
                                 name='layer',
                                 multiple=False,
                                 options=options)

    map_layers = []

    if request.POST and 'layer' in request.POST:
        selected_layer = request.POST['layer']
        legend_title = selected_layer.title()

        geoserver_layer = MVLayer(
            source='ImageWMS',
            options={'url': 'http://localhost:8181/geoserver/wms',
                   'params': {'LAYERS': selected_layer},
                   'serverType': 'geoserver'},
            legend_title=legend_title,
            legend_extent=[-114, 36.5, -109, 42.5],
            legend_classes=[
                MVLegendClass('polygon', 'County', fill='#999999'),
        ])

        map_layers.append(geoserver_layer)


    view_options = MVView(
        projection='EPSG:4326',
        center=[-100, 40],
        zoom=4,
        maxZoom=18,
        minZoom=2
    )

    map_options = MapView(height='500px',
                          width='100%',
                          layers=map_layers,
                          legend=True,
                          view=view_options)

    context = {'map_options': map_options,
               'select_options': select_options}

    return render(request, 'geoserver_app/map.html', context)

Map Page Template¶

Create a new map.html template in your template directory and add the following contents:

{% extends "geoserver_app/base.html" %}
{% load tethys_gizmos %}

{% block app_content %}
    <h1>GeoServer Layers</h1>
    <form action="" method="post">
        {% csrf_token %}
        {% gizmo select_input select_options %}
        <input name="submit" type="submit" value="Update" class="btn btn-default">
    </form>
    {% gizmo map_view map_options %}
{% endblock %}

Test Map Page¶

Navigate to the map page (http://localhost:8000/apps/geoserver-app/map/). Use the select box to select a layer to display on the map. Press the submit button to effect the change.

Spatial Input Page UrlMap¶

Add a new UrlMap to the url_maps method of the app.py module:

UrlMap(name='draw',
       url='geoserver-app/draw',
       controller='geoserver_app.controllers.draw'),

Spatial Input Controller¶

Add a new controller to the controller.py module:

@login_required
def draw(request):

    user = request.user
    drawing_options = MVDraw(
        controls=['Modify', 'Move', 'Point',
                  'LineString', 'Polygon', 'Box'],
        initial='Polygon'
    )

    map_options = MapView(height='450px',
                          width='100%',
                          layers=[],
                          draw=drawing_options)

    geometry = ''

    if request.POST and 'geometry' in request.POST:
        geometry = request.POST['geometry']

    context = {'map_options': map_options,
               'geometry': geometry}

    return render(request, 'geoserver_app/draw.html', context)

Spatial Input Template¶

Create a new draw.html template in your template directory and add the following contents:

{% extends "geoserver_app/base.html" %}
{% load tethys_gizmos %}

{% block app_content %}
    <h1>Draw on the Map</h1>

    {% if geometry %}
        <p>{{ geometry }}</p>
    {% endif %}

    <form action="" method="post">
        {% csrf_token %}
        {% gizmo map_view map_options %}
        <input name="submit" type="submit">
    </form>
{% endblock %}

Add Navigation Links¶

Replace the app_navigation_items block of the base.html template with:

{% block app_navigation_items %}
  <li class="title">App Navigation</li>
  <li><a href="{% url 'geoserver_app:home' %}">Upload Shapefile</a></li>
  <li><a href="{% url 'geoserver_app:map' %}">GeoServer Layers</a></li>
  <li><a href="{% url 'geoserver_app:draw' %}">Draw</a></li>
{% endblock %}

Test Spatial Input Page¶

Navigate to the spatial input page using the “Draw” link in your navigation (http://localhost:8000/apps/geoserver-app/draw/). Use the drawing controls to add features to the map, then press the submit button. The GeoJSON encoded spatial data should be displayed when the page refreshes.