Awesome

hub-ready-apps

documentation for creating civic tech apps that scale (working draft)

Table of Contents

• What is a Hub?

• What is a Hub Ready App?

• Required

  • Configurable
  • Indicator Aware
  • ArcGIS Identity
  • Shared Theme
  • Accessible
  • Mobile Responsive

• Best Practices

  • Localized (i18n)
  • Durable State
  • Data Citation
  • Telemetry

• Optional

  • Open License?

• Tools

What is a Hub?

ArcGIS Hub provides a two-way engagement platform to connect government and citizens.

An interactive platform to organize people, processes, and technology. ArcGIS Hub comes with built-in event creation and allows you to gather feedback from inside and outside your organization to find or create new solutions to existing problems.

What is a Hub Ready App?

check out the talk from Dev Summit 2018! :point_left:

Hub-Ready Apps integrate with the Hub administrative and community user experience and provide simple workflows to inform, listen and monitor important initiatives.

Hub-Ready Apps extend the ArcGIS configurable app pattern to share and re-use solutions that integrate directly with the Hub architecture and organization datasets and branding.

Note: Your own app doesn't need to implement each and every pattern described in our checklist to be considered Hub Ready.

Configurable

using Item config and Group Permissions (with Configurable ArcGIS Content)

Apps should be centrally managed, but reusable through dynamic configurations that are loaded at runtime. This supports many organizations each maintaining configured versions of the app using a single deployment. This minimizes development, deployment, and operational overhead. Read more about the configurable app specification

A Configurable App Template defines its configurationSettings, and a Configured App stores its values.

• StoryMap Template

A Template can also include default values.

Using the same StoryMap template, we have configured versions for two cities:

• StoryMap: Los Angeles
• StoryMap Configuration
• StoryMap: Albany
• StoryMap Configuration

Our Configurable App Examples leverage a helper called ApplicationBase to handle configuration JSON.

Indicator Aware

for Initiative configuration

ArcGIS Identity

ArcGIS Hub includes ArcGIS Identity, a web-based user authentication and personal content management system. Apps may require authentication (sign in) and authorization (permission) to access sensitive data or services such as spatial analysis. Additionally, users may want to save information that can be reused or shared.

ArcGIS Identity allows a person to create an account or sign in with social media credentials (e.g. Google and Facebook), an email address, or with enterprise credentials provided through services such as LDAP or Active Directory. Once an account is created, it can be used in any web app, mobile app, website, or other service that requires authentication. This makes it simple for users to maintain one account that can be reused across multiple experiences.

Learn more

Shared Theme

Hub Ready Apps should have a consistent theme and branding, that gives awareness and confidence to users about the source of the app. This theme is typically the branding of the organization such as the government or agency, but can also be the theme for a specific program, interest group or community.

• Introducing Shared Themes
• Using Shared Themes in StoryMaps

In this vein, Esri has also open sourced our HTML/CSS framework Calcite Web to make it easy to build responsive websites that look and feel like part of the family.

Organization Theme

ArcGIS Hub includes a configurable theme for organizations to set their logo, colors, fonts and other brand styling. This theme is then available via the API for automatic use in any app that is configured for the organization. The result is centralized management of the brand theme that is consistent across all apps.

Get https://www.arcgis.com/sharing/rest/portals/{org.id}?f=json or https://{orgkey}.maps.arcgis.com/sharing/rest/portals/self?f=json

{
  "portalProperties": {
    "sharedTheme": {
      "header": {
        "background": "#002b49",
        "text": "#ffffff"
      },
      "body": {
        "text": "#1a1a1a",
        "background": "#ebebeb",
        "link": "#005ce6"
      },
      "button": {
        "text": "#002673",
        "background": "#ffffff"
      },
      "logo": {
        "small": "https://cityx.maps.arcgis.com/sharing/rest/content/items/5c9e486b701e4222bf5386da64908ae1/data",
        "link": "https://cityx.maps.arcgis.com/sharing/rest/content/items/5c9e486b701e4222bf5386da64908ae1/data"
      }
    }
  }
}

Site & Initiative Themes

Each Hub site can also have its own theme, which allows for apps to be branded for individual departments or initiatives.

https://www.arcgis.com/sharing/rest/content/items/{item.id}/data?f=json

{
  "values": {
    "theme": {
      "header": {
        "background": "#012c3b",
        "text": "#ffffff"
      },
      "body": {
        "background": "#fafafa",
        "text": "#586370",
        "link": "#136fbf"
      },
      "button": {
        "background": "#136fbf",
        "text": "#ffffff"
      },
      "logo": {
        "small": "http://octo.dc.gov/sites/default/files/dc/sites/octo/multimedia_content/images/OpenData-HeaderLogo-WhiteText-2.png"
      },
      "fonts": {
        "base": {
          "url": "",
          "family": "Avenir Next"
        },
        "heading": {
          "url": "",
          "family": "Avenir Next"
        }
      }
    }
  }
}

Accessible

Hub Ready Apps are inclusive for all users. This includes people who use supportive devices such as screen-readers or keyboard navigation. Standards such as Web Content Accessibility Guidelines (WCAG) and Section 508 prescribe patterns and practices for ensuring proper accessibility.

Hub Ready Apps should support accessibility guidelines.

Mobile Responsive

"The share of Americans that own smartphones is now 77%, up from just 35% ... in 2011." - Pew Research

"Today just over one-in-ten American adults are “smartphone-only” internet users – meaning they own a smartphone, but do not have traditional home broadband service." - Pew Research

Building a mobile friendly application should be considered a requirement if your goal is to reach anyone with internet access.

Localized

Besides making it more likely that your application could be deployed in more than one location, providing translations for languages other than english broadens the reach of your application within a city by including a more diverse collection of stakeholders.

Open source frameworks like Dojo and JQuery have provided tooling to help create i18n applications for many years. These days there are compact, framework agnostic options like Polyglot as well.

Durable State

When using an Hub Ready App, it's important that the user can easily share the current URL to others or refresh their browser and the app will reload with the current view the user sees. This also applies to mobile apps that can be opened with an app URL. Additionally, it's important to keep the URL to application consistent over time so that users or sites that link to the app continue to work, even with new versions of the app.

This is commonly referred to as Durable State - meaning that the current app state is maintained in the URL.

Besides gracefully handling browser refreshing, the a URL can be created the directs new visitors to a specific feature, geographic location, page location, or other state that shows a particular view.

Here are the current list of URL parameters which should be supported:

• Location: ?find=<location string>
  • example: ?find=380 new york street, redlands, ca
• Zoom/Center: ?center=<longitude>,<latitude>&level=<zoom>
• Extent: ?extent=<longitude_west>,<latitude_south>,<longitude_east>,<latitude_north>
  • example: ?extent=-117.20,34.055,-117.19,34.06
• Configuration: ?id=<item.id>
  • example: ?id=da80a448ac9246192da0811bddc18c94
• Theme/Org
• Selected features: ?query=<layer name>,<field name>,<field value> or ?query=<layer name>, <where clause>
  • example: ?query=Census_8491,STATE_NAME='California'
• Additional Layers
• Language locale: ?locale=<two-letter country code>
  • example: ?locale=es

Learn more about URL parameters

Data Citation

For transparency it is absolutely crucial that you attribute the providers of the data your application consumes to acknowledge the original source.

• Link to Open Data
• Link to Item Page
• Link to Service

Telemetry

'That which is measured, improves' - Thomas S Monson

A Hub Ready App should provide the option for an organization to measure its own usage and efficacy to help judge impact and improve content usability. By logging information on visits, usage, performance, errors and the successful completion of pre-defined user workflows organization managers can report on usage and continually improve the app configuration to meet user needs.

In the future, ArcGIS Hub will include libraries for integrating app telemetry with the Hub for comparison of app engagement with real-world engagement and outcomes.

Tools

• https://github.com/Esri/arcgis-rest-js
• https://github.com/Esri/ember-arcgis-portal-services
• https://github.com/Esri/configurable-app-examples-4x-js
• https://github.com/Esri/maps-app-javascript

License

For Open Data, a license is a must. For Hub Ready Apps, an Open License is optional.

For the projects Esri shares on GitHub, we usually choose Apache-2.0.

Copyright 2018 Esri

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's LICENSE file.