Configuration details

Each Mapseed flavor contains a config.yml file that is used to configure application behavior. There are many configuration options, and this section of the wiki is intended to be a (work in progress) catalog of those options and how to use them.

Map configuration

...

Dynamic form configuration

The dynamic form allows users to create new pieces of geometry on the map. The form supports numerous input types and options, described in this section. Below is an example of a dynamic form configuration, found under the place section of the config:

place:
  adding_supported: true
  default_basemap: satellite
  add_button_label: _(Add Report)
  show_list_button_label: _(See All Reports)
  show_map_button_label: _(Show the Map)
  action_text: _(added)
  anonymous_name: _(Someone)
  submit_button_label: _(Put it on the map!)
  place_detail: ...

Property	Description
adding_supported	A boolean which controls whether or not the dynamic form is available to map users.
default_basemap	Optional. The name of a basemap layer which will automatically become active when the reporting form is open.
add_button_label	The message that appears on the button which opens the dynamic form.
show_list_button_label	The message that appears on the button which opens the list view.
show_map_button_label	The message that appears on the button which opens the map form.
action_text	The phrase incorporated into place detail views which describes the action taken to create a new place.
anonymous_name	The name given to anonymous submitters in action text.
submit_button_label	The message that appears on the button which submits data from the dynamic form and creates a new place on the map.
place_detail	An array containing field configuration information for all location_types on the map. See below for details.

Dynamic form location_type configuration

All map location_types require configuration in the place_detail section of the config. This is true whether or not a given location_type appears as a category on the dynamic form. Below is an example of a location_type configuration:

place_detail:
  - category: featured_place
    admin_only: true
    includeOnForm: true
    showMetadata: false
    suppressAttachments: true
    horizontal_rule: true
    name: location_type
    dataset: duwamishfeatured
    icon_url: /static/css/images/markers/marker-star.png
    value: featured_place
    label: _(Featured Place)
    fields:
      - name: published
        type: publishControl
      - name: geometry
        type: geometryToolbar
        content:
          - url: /static/css/images/markers/marker-bike.png
          - url: /static/css/images/markers/marker-construction.png
          - url: /static/css/images/markers/marker-foodforest.png
      - name: title
        type: text
        prompt: _(Title of this featured site:)
        display_prompt: _( )
        placeholder: _(Enter title...)
        optional: false
      - name: description
        type: richTextarea 
        prompt: _(Description:)
        display_prompt: _( )
        placeholder: _( )
      - name: url-title
        type: url-title
        prompt: _(Choose a custom URL for this place:)
        placeholder: "my-new-featured-place"
        optional: true
  - category: idea
    includeOnForm: true
    name: location_type
    dataset: duwamish
    icon_url: /static/css/images/markers/marker-idea.png
    value: idea
    label: _(Idea)
    fields:
      - name: title
        type: text
        prompt: _(Title of your idea:)
        placeholder: _(Enter title...)
        display_prompt: _(Title:)
        optional: false
      - name: description
        type: textarea
        prompt: _(Describe your idea below:)
        display_prompt: "_(Here's my idea:)"
        placeholder: _(Description...)
        optional: false
      - name: submitter_name
        type: text
        prompt: _(Your name)
        placeholder: _(Name)
        optional: true

Property	Description
category	This is equivalent to location_type, and the name supplied here should match top-level names used in the layer style section of the config.
includeOnForm	Defaults to true. A boolean which controls whether or not this location_type appears as a category option on the dynamic form. If set to true, users will be able to add instances of this location_type via the form.
admin_only	Defaults to false. A boolean which controls whether this location_type appears only for logged-in administrators. If set to true, and assuming includeOnForm is also set to true, the dynamic form category for this location_type will only be accessible to logged-in administrator. See here for a description of how to grant administrator status to users.
showMetadata	Defaults to true. A boolean which controls whether a place detail view's metadata block (containing the avatar and place creation information) appears.
suppressAttachments	Defaults to false. A boolean which controls whether or not attached images appear above field information in place detail views. Useful if a form category allows image attachments via the rich text editor, in which case suppressAttachments should be set to true to prevent duplicate attachments from being rendered.
name	This should always be set to the string location_type. TODO: needs further explanation
dataset	The name of the dataset to which data from this category writes.
icon_url	The relative path to an icon image to display with to this category's dynamic form button.
value	An internal name for this category. TODO: is this redundant? Does it always just match category?
label	The name for this category that appears on the dynamic form.
fields	An array of configuration information for all the form fields that appear under a given category. See below for information on field types.

Right-clinging sidebar configuration

...

Leaflet sidebar configuration

...

Layer style rules configuration

Layer style rules, found under the place_types section of the config, control how icons, polygons, and linestrings appear on the map. Style rules define conditions (such as a map zoom level) and associate style rules with those conditions.

Below is an example of a typical style rule. The top-level key, (construction and featured in the example below), should match the name of the location_type to which the affiliated rules apply:

construction:
    rules:
      - condition: 'this.layer.focused === true'
        icon:
          iconSize: [50, 50]
          iconAnchor: [25, 25]
      - condition: 'this.map.zoom < 15'
        icon:
          iconUrl: /static/css/images/markers/marker-construction-dot.png
          iconSize: [10, 10]
          iconAnchor: [0, 0]
      - condition: 'this.map.zoom <= 18'
        icon:
          iconUrl: /static/css/images/markers/marker-construction.png
          iconSize: [30, 30]
          iconAnchor: [15, 15]

featured:
    rules:
      - condition: 'this.geometry.type == "LineString"'
        style:
          color: "this.style.color"
          opacity: "this.style.opacity"
          weight: "this.style.weight"

Style rules are evaluated each time the map zoom level changes, and once for each piece of geometry on the map. When style rules are evaluated, each condition listed under the rules section is evaluated, in order, until a condition returns true. Once a condition returns true, the style rule for that condition is used. If no condition returns true, then the affiliated geometry will not appear on the map under the current conditions.

Style rule configuration options

Property	Description
condition	A string containing a javascript expression which can be evaluated for true/false status. When writing style rule expressions, you can incorporate any of a model's properties using the this. syntax. Additionally, you can incorporate the map's current zoom level with this.map.zoom, and whether a given layer is currently focused by using this.layer.focused.
icon	(For Marker geometry). An object containing settings for the icon affiliated with this Marker geometry. Any of an icon's properties can be set. See here for full documentation.
style	(For GeoJSON polygon and linestring geometry). An object containing path options for this GeoJSON geometry. Any GeoJSON path properties can be set. See here for full documentation.

Story mode configuration

The story section of the config.yml file configures the behavior of a flavor's story mode. You can control which points on your map appear in a story, which zoom level and centerpoint are used for individual story points, whether the spotlight overlay appears when visiting a story point, and so forth.

Below is an example of a typical story configuration, followed by an explanation of all options used:

story:
  budget-priorities:
    tagline: _(Next budget priority)
    default_zoom: 17
    default_basemap: satellite
    default_visible_layers:
      - 2015-budget-priorities
      - city-council-districts
    order: 
      - url: street-paving
        spotlight: false
        visible_layers:
          - streets
        basemap: dark
      - url: report/214
        zoom: 10
        panTo:
          lat: -122.24877834320068
          lng: 47.731328313742345
      - url: park-improvements
        spotlight: false
        sidebar_icon_url: /static/css/images/markers/map-pin-marker.png

Story configuration options

Property	Description
tagline	A string that appears in the story control bar at the bottom of a place detail view.
default_zoom	A map zoom level that will be used for all story points unless a story point sets its own zoom level.
default_basemap	The basemap that will be shown for all story points unless a story point sets its own basemap.
default_visible_layers	An array of map layers that will be shown for all story points unless a story point sets its own array of visible layers.
order	An array of urls and optional configuration details that defines the in-order content of a story.

Story item configuration options

NOTE: these options should appear in array entries under the order property, described above.

Property	Description
url	Required. The relative url of a story point.
spotlight	Optional. A boolean value indicating whether or not to display the map spotlight overlay. Defaults to true.
visible_layers	Optional. An array of layers that will be shown for this story point. Completely overrides default_visible_layers.
basemap	Optional. The basemap that will be shown for this story point. Overrides default_basemap.
zoom	Optional. The map zoom level that will be used for this story point. Overrides default_zoom.
panTo	Optional. An object of lat and lng coordinates to use as the map centerpoint for this story item. Overrides the centerpoint of the underlying geometry.
sidebar_icon_url	Optional. The path to an icon image to use for this story point in the sidebar. If not supplied, the sidebar icon used will be derived from the place section of the config.