Customizing theme colors in Map Journal and Map Series

The March 2017 update to ArcGIS Online includes a new feature called Shared Themes that lets an administrator set a logo and a palette of colors that can be used to apply consistent branding to web apps created by members of the organization.

For Story Map Series and Story Map Journal, the organization’s shared theme colors are used to generate an Organization Theme that is shown with the other theme options in builder.

Having an administrator configure a shared theme for your organization is the best way for most story map authors to apply branding to their stories; however, some authors may want to apply their organization’s theme colors in a different way or personalize the theme colors for individual stories.

Before the March 2017 update, the only way to use custom colors for a Map Series or Map Journal story was to download the app from GitHub, modify the code, and host the app yourself. But, as part of the work to support shared themes in these apps, the theme color values are now exposed as properties in the story configuration JSON. This means you can now specify theme colors for Map Series and Map Journal stories hosted on ArcGIS Online by editing the story JSON using a tool like ArcGIS Online Assistant.

WARNING #1 — Editing JSON can break your story!

If you’ve never edited story map JSON before it’s wise to first try it a few times on a test story until you’re comfortable with the procedure. If you choose to edit JSON for a published story, be aware of the risk you are taking and be sure to copy and save its original JSON in a text file in case something goes wrong.

WARNING #2 — If you’re not a web designer (or working with one) we strongly recommend you stick with one of the themes provided.

Here’s an example of the JSON that stores the theme for your story. The parameters you see will depend on the story type and layout (Map Series tabbed layout, Map Journal floating panel layout, etc.).

      "theme": {
        "colors": {
          "name": "side-default-1",
          "themeMajor": "white",
          "dotNav": "#777777",
          "panel": "#FFFFFF",
          "media": "#EEEEEE",
          "text": "#000000",
          "textLink": "#555",
          "softText": "#c0c0c0",
          "softBtn": "#444",
          "esriLogo": "black"
        },
   ...}

To set theme colors for your story…

1. Open ArcGIS Online Assistant and log into your ArcGIS account.
2. At the top click I want to…View an item’s JSON.
3. In the left panel, find the story map you want to customize. These instructions are for Map Journal and Map Series stories only.
4. In the Data section of the right panel, look for theme in the JSON (as shown above). As mentioned above in warning #1, now is a good time to Copy the original JSON and save it in a text file in case something goes awry. If you don’t see the theme, see the note at the end of this post.
5. Click Edit (the pencil button) to start editing the JSON.
6. Append -modified to the name property of the theme. We recommend you do not edit the name in any other way.
7. Edit the properties of the theme as you like using any valid color specification method like hex color codes, HTML color names, or RBGa values (if you need transparency).
8. Use the Save button at the top of the Data section to save your changes.
9. View your story or open it in builder (if it’s already open, reload the page) to see your shiny new theme colors!

Here are some general notes and tips for configuring theme properties:

• You can adjust the transparency of the floating panel in Map Journal using the panelOpa property. If panelOpa is not set, the floating panel will be 80% opaque.
• You can adjust the transparency of the description panel in Map Series (tabbed or bulleted layout only) by using an RGBa color value.
• themeMajor can be white or black and controls the appearance of some minor visual elements like the arrows in the legend header and dot navigation strip.
• Since you are likely using your own logo if you are customizing theme colors you can ignore esriLogo and esriLogoMobile.

You’ve edited the theme, now what?

Back in the builder under Settings > Theme you’ll see the organization theme (if configured by your administrator) and your modified theme, which is shown as the Current Theme since it’s currently applied to the story.

At this point, if you choose a theme other than Current Theme and save the story, your modified theme will not be available next time you load the story in builder. You’ll need to use the procedure above to edit the theme colors again.

Additional themes in Map Journal.

What if you don’t see JSON for the theme?

If you don’t see theme in your story JSON settings, it’s likely because you’ve never changed the theme of your story. Just choose a different theme in Settings > Theme, save your story, then refresh the JSON view in ArcGIS Online Assistant by clicking the item name in the left panel. This will write the colors to the JSON so you can edit them. Now you can proceed with the steps above.