A django apps to create a community based user map
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs/img
user_map
.gitignore
.travis.yml
LICENSE.txt
MANIFEST.in
README.md
create_test_package.sh
requirements.txt
setup.py
upload-to-pypi.sh

README.md

Django User Map

Django User Map is a reusable django application for making community user's map. This app relies on the active auth user model and extend that model with OneToOne relationship. Users can add themselves on the map by providing some additional information:

  1. Location on the map
  2. Roles (the choices can be configured through setting)
  3. Image, and
  4. Website

Read here for the documentation: www.akbargumbira.com/django-user-map

Installation

  • Install django-user-map with pip:
pip install django-user-map
  • Make sure you have these modules in INSTALLED_APPS of your django project settings.py:
INSTALLED_APPS = (
    'django.contrib.gis',
    'user_map',
    'leaflet',
    'bootstrapform',
    'rest_framework',
    'rest_framework_gis'
)
  • Include user-map URLconf in your project urls.py with namespace user_map (required) e.g:
url(r'^user-map/', include('user_map.urls', namespace='user_map')),
  • Configure user map with USER_MAP variable in your project's settings.py or override some templates. See Configurations section for further information.

  • Run python manage.py migrate user_map to migrate the user_map models.

  • Visit the URL that you set before to see the apps.

Configurations

You can configure Django User Map with one single USER_MAP variable in project's settings.py. The setting below is the default. Add this default to your project's setting and configure the necessary bits that you want to change:

USER_MAP = {
    'project_name': 'Django',
    'favicon_file': '',
    'login_view': 'django.contrib.auth.views.login',
    'marker': {
        # See leaflet icon valid options here:
        # http://leafletjs.com /reference.html#icon-iconurl
        'iconUrl': 'static/user_map/img/user-icon.png',
        'shadowUrl': 'static/user_map/img/shadow-icon.png',
        'iconSize': [19, 32],
        'shadowSize': [42, 35],
        'iconAnchor': [10, 0],
        'shadowAnchor': [12, 0],
    },
    'leaflet_config': {
        'TILES': [(
            # The title
            'MapQuest',
            # Tile's URL
            'http://otile{s}.mqcdn.com/tiles/1.0.0/osm/{z}/{x}/{y}.png',
            # More valid leaflet option are passed here
            # See here: http://leafletjs.com/reference.html#tilelayer
            {
                'attribution':
                    '© <a href="http://www.openstreetmap.org" '
                    'target="_parent">OpenStreetMap'
                    '</a> and contributors, under an <a '
                    'href="http://www.openstreetmap.org/copyright" '
                    'target="_parent">open license</a>. Tiles Courtesy of '
                    '<a '
                    'href="http://www.mapquest.com/">MapQuest</a> <img '
                    'src="http://developer.mapquest.com/content/osm/mq_logo'
                    '.png"',
                'subdomains': '1234'

            }
        )]
    },
    'roles': [
        {
            'id': 1,
            'name': 'Django User',
            'badge': 'user_map/img/badge-user.png'
        },
        {
            'id': 2,
            'name': 'Django Trainer',
            'badge': 'user_map/img/badge-trainer.png'
        },
        {
            'id': 3,
            'name': 'Django Developer',
            'badge': 'user_map/img/badge-developer.png'
        }
    ],
    'api_user_fields': [
        # e.g 'username', 'first_name', 'last_name'
    ],
}

Project Name

This variable (project_name) represents the project name of the apps. If this is not specified, 'Django' will be used.

Favicon

This variable (favicon_file) represents the file path to the favicon on the browser's tab. You can point it to any files in your static dirs from any apps.

Login View

Django User Map relies on the auth user model in your project. For users to be able to add (or update) themselves, they need to log in first. You can point it to the view function e.g 'login_view': 'django.contrib.auth.views.login' or even to the view name e.g 'login_view': 'fe_login'

Marker

This variable represents the marker icon on the map. You can use any valid Leaflet L.icon options. Read here for the valid options http://leafletjs.com/reference.html#icon-iconurl

An example for this variable:

'marker': {
    'iconUrl': 'static/user_map/img/user-icon.png',
    'shadowUrl': 'static/user_map/img/shadow-icon.png',
    'iconSize': [19, 32],
    'shadowSize': [42, 35],
    'iconAnchor': [10, 0],
    'shadowAnchor': [12, 0],
}

Map Configuration

You can configure the basemap of the form that uses LeafletWidget and the basemap of the homepage through leaflet_config variable in settings.py. You can also pass leaflet tile layer options (read here: http://leafletjs.com/reference.html#tilelayer):

'leaflet_config': {
    'TILES': [(
        # The title
        'MapQuest',
        # Tile's URL
        'http://otile{s}.mqcdn.com/tiles/1.0.0/osm/{z}/{x}/{y}.png',
        # More valid leaflet option are passed here
        {
            'attribution':
                '© <a href="http://www.openstreetmap.org" '
                'target="_parent">OpenStreetMap'
                '</a> and contributors, under an <a '
                'href="http://www.openstreetmap.org/copyright" '
                'target="_parent">open license</a>. Tiles Courtesy of '
                '<a '
                'href="http://www.mapquest.com/">MapQuest</a> <img '
                'src="http://developer.mapquest.com/content/osm/mq_logo'
                '.png"',
            'subdomains': '1234'

        }
    )]
},

Roles

Using roles, you can specify the user's role, its name, and its badge path. User can select multiple roles. On the map, visitors of the apps can also filter the marker (users) based on their role(s).If not specified, this variable will take this as the default:

'roles': [
        {
            'id': 1,
            'name': 'Django User',
            'badge': 'user_map/img/badge-user.png'
        },
        {
            'id': 2,
            'name': 'Django Trainer',
            'badge': 'user_map/img/badge-trainer.png'
        },
        {
            'id': 3,
            'name': 'Django Developer',
            'badge': 'user_map/img/badge-developer.png'
        }
    ],
}

User Fields

User fields are list of field from user model (AUTH_USER_MODEL) that will be shown on the popup content and will be added to the REST API. To specify which fields that should be visible from user model, you can configure it through api_user_fields as a list of fields. For example if you want to show username field from the user model, you must add this setting:`

'api_user_fields': ['username'],

Updating Roles

If in any case you need to update or change roles in settings.py after the user_map models are migrated, you must run django management command:

python manage.py update_roles

Bear in mind that you should not change the id's and just change the name or the badge path.

This command also will only update the role table, not the usermap table that uses the role table. So, adding roles is fine (as long as the new id's are unique). Removing roles has no effect (it will not remove the row in the table). Well, it could give you problems as it means that some of the users might not have valid roles defined in the role table.

Changing Template

You can change the content of the data privacy (the modal popped up when user clicks 'Data Privacy' link at the bottom left of the map) or add navigation menu. By default, there is no navigation menu - the map will use the whole screen.

Data Privacy

To modify data privacy content, create a directory user_map under templates dir of your Django project and create html file named data_privacy.html. The default content of this template looks like this:

<script id="data-privacy-content-section" type="text/template">
  The data you enter on this site may be visible to others. We suggest that
  you approximate your physical location to the nearest
  town or major center. Parts of your data will be made available for
  others to download and use. Click the REST API link to see the data that are
  available for public to use.
</script>

In the new data_privacy.html file, copy that and edit the wording yourself. Note that the <script> tag is needed completely with the same id and type.

Navigation

By default, the map showing all users does not have navigation menu. This is how it looks like without the navigation menu:

User Map without Navigation

But you can add a navigation menu so it looks like this as an example:

User Map with Navigation

To add navigation menu, add html file named navigation.html in user_map/templates/ dir under your project's directory (along with your custom data privacy content)

If you need more style or javascript resources to create this navigation menu, please add another template named extra_resources.html and save it in the same directory with the navigation.html. These additional resources will be included in the head tag, so the content could be something like:

<link rel="stylesheet" href="/static/style/new/basic.css" type="text/css" />
<link rel="stylesheet" href="/static/bootstrap/css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="/static/style/new/qgis-style.css" type="text/css" />
<link rel="stylesheet" href="/static/bootstrap/css/bootstrap-responsive.min.css" type="text/css" />
<link rel="stylesheet" href="/static/font-awesome/css/font-awesome.min.css">


<style>
  body {
    padding-top : 0px !important;
  }
  .navbar-fixed-top {
    position: relative;
  }
</style>

Testing

You can run the test suite by using django manage.py from your django project:

python manage.py test user_map

or you can do it from the root of this django apps by running:

python setup.py test

Status

Develop Branch Coverage Status