Welcome to ProxiMap’s documentation!

Proximap is a responsive web app for finding nearby public infrastructure, and uses drinking fountains as a showcase example. It is being developed in conjunction with Datablue, a tool for collecting and aggregating data from open government data repositories and the Wikicommons websites. Check out water-fountains.org for more information on the overall project.

The project is open source under the GNU Affero General Public License, with a profit contribution agreement applying under restricted conditions. See COPYING for information.

Contents

Why this is important

Open data are increasingly available from both government and crowd-sourced platforms. However, the data often needs to be processed and presented visually to be of direct value to the general public.

ProxiMap is a showcase that illustrates the value of open data for the general public. As an open-source project, the code can easily be reused for other projects.

Roadmap

Milestones

1. The scaffolding

• [ ] Sketch out application API
  • what data does each component consume and in what format
  • what services need to be set up to provide the data
• [ ] Create a reactive scaffolding for the app
  • [ ] decide which Angular UI to use, if any
  • [ ] create pages, menu bars, panels
  • [ ] link display to URL routes
  • [ ] make sure everything is responsive
• [ ] Implement language changing

2. The flesh

• [ ] Create a dummy dataset to work with
• [ ] Implement data management service
• [ ] Impement essential components
  • [ ] main menu
  • [ ] map
  • [ ] search list
  • [ ] mini detail view

3. Embellishments

• [ ] navigation
• [ ] full details view
• [ ] advanced search
• [ ] …

ProxiMap Architecture

State and Data Management

Application State and Data is managed by a service, the stateManager and dataManager. The flow of information is uni-directional: Events trigger state changes which can trigger data changes (or not). The components watch the state and data for changes and react accordingly.

Changes to make

• Adjust data management pattern to use Redux
• Linking the Redux store to the router can be done with: https://github.com/angular-redux/router

Proximap services

The following services work in the background of the app:

App manager

Properties

The application’s state is stored in an object. See application state variables for complete list of state properties.

Methods

parse_url()

Checks and corrects url params and variables, and updates app state variables accordingly.

update_state(variable_name, new_value)

Updates the state variable, first checking if the new value is valid. If so, the app state variables are updated and the URL is updated as well.

Data manager

Properties

Properties store the data. Data …. fountains

All fountains of selected city.

fountains_filtered

filtered fountains.

fountain_selected

fountain selected by user.

user_location

coordinates

user_preferences

user preferences, like preferred mode of transport

route_data

routing data as acquired by routing service

Actions

• fetch_fountain_data()
• fetch_route()
• filter_data()
• set_fountain()
• geolocate_user()
• set_user_location()

Proximap components

Note: Each component that is not always visible has a method to update its visibility based on the app state.

Map

The map is the main component of the app, and is always visible (though sometimes in the background).

Private Methods

update()

This function updates the map to display desired information. It watches: appManager.mode to determine whether to show filtered fountains, a route, or just a single fountain dataManager.fountains_filtered, fountain_selected, and route_data in order to update the data displayed in the map

update_user_location(user_location)

This function displays the user’s current location on the map.

display_route(route_data)

If the app is in route mode, this function displays the route on the map.

display_fountains(fountains_filtered)

If the app is in map mode, this function displays the filtered fountains on the map.

display_selected_fountain(fountain_selected)

If the app is in details mode, this function displays the selected fountain on the map.

Public Methods

Public methods can be called from the DOM or from other components/services.

select(fountain_id)

The user can select a fountain in the map. The function modifies the URL parameter accordingly.

set_user_location(coordinates)

The user can set their location via the map as an alternative to automatic localization.

refresh()

Force the map to refresh

Search

The search filter is accessed in the menu, floating over the map or at the top of the list (to be defined). It just allows easy modification of the fountain search criteria via the URL variables.

Private Methods

Question: are the styles directly bound to the app state variables?

Public Methods

toggle_cat(category_name, value)

This toggles a category for the filter in the search_cat state variable. Examples of categories are:

• well: fountains with wellwater
• historical: fountains of historical value.

text_filter(search_text)

Updates the full text for search in the search_txt state variable. Beware to sanitize the text!.

reset_filters()

Removes all filters.

List

Features

Sort list elements by proximity, name, or construction date.

Private Methods

update()

This function updates the list when the fountains_filtered data in the dataManager has been modified. It is triggered by a subscription to that data.

Public Methods

select(fountain_id)

The user can select a fountain in the list. The function modifies the URL parameter accordingly.

Navigation pane

[low priority] This pane shows step-by-step navigation instructions.

Private Methods

update()

This function updates the route info when the route_data data in the dataManager has been modified. It is triggered by a subscription to that data.

Public Methods

change_travel_mode(new_mode)

Updates travel mode.

Details pane

This pane displays information about the selected fountain. Information included in this pane depends on what is made available from the data sets, but it could include: - Construction year of fountain (e.g. 1951) - Type of water (e.g. Well water) - Water quality (e.g. drinking water/not drinking water) The pane also shows information available from Wikidata and/or Wikimedia, including a detailed description and photos of the fountain.

Private Methods

update()

This function updates the displayed information when the fountain_selected data in the dataManager has been modified. It is triggered by a subscription to that data.

Public Methods

show_route()

This function changes the mode of the app to route and triggers a route search between the user’s current location and the selected fountain. The route search is managed in the dataManager.

Menu

The menu bar contains logo, search bar, information button, language selection and city selection. On mobile devices it is replaced with a menu button and slide-out menu on the right.

Public Methods

change_lang(new_lang)

This function changes the language of the app.

change_city(new_city)

This function changes the city of the app.

Application state variables

The following variables define the application state and are set in the url of the web page.

state variable name	location	type	example	default	description
city	param	string	zurich	zurich	city for which data is being shown
fountain_id	var	string	q72592	none	unique identifier for fountain selected, if any
mode	var	string	map/details/route	map	application mode (determines which panels are visible)
search_txt	var	string	kluspla	none	filter text
search_cat	var	list	[well, favorite]	[]	filter categories that can be toggled on/off
hide_list	var	bool	true/false	true	in mobile mode, hide list by default
lang	var	string	en/de/fr	en	language of app

App state propagation

A service watches the url parameters and updates the internal state variables. The application data manager and view manager watch the state variables for changes and make modifications to the view and data, respectively. Individual components watch the data for changes and update independently.