StoryMap Implementation
The StoryMap
is the main entry point into the Story Map module.
StoryMap
-
class
arcgis.apps.storymap.story.
StoryMap
(item=None, gis=None) Bases:
object
A Story Map is a web map that has been thoughtfully created, given context, and provided with supporting information so it becomes a stand-alone resource. It integrates maps, legends, text, photos, and video and provides functionality, such as swipe, pop-ups, and time sliders, that helps users explore this content.
ArcGIS StoryMaps is the next-generation storytelling tool in ArcGIS, and story authors are encouraged to use this tool to create stories. The Python API can help you create and edit your stories.
Create a Story Map object to make edits to a story. Can be created from an item of type ‘Story Map’, an item id for that type of item, or if .nothing is passed, a new story is created from a generic draft.
If an Item or item_id is passed in, only published changes or new drafts are taken from the Story Map. If you have a story with unpublished changes, they will not appear when you construct your story with the API. If you start to work on your Story that has unpublished changes and save from the Python API, your unpublished changes on the GUI will be overwritten with your work from the API.
Parameter
Description
item
Optional String or Item. The string for an item id or an item of type ‘Story Map’. If no item is passed, a new story is created and saved to your active portal.
gis
Optional instance of
GIS
. If none provided the active gis is used.-
add
(content=None, caption=None, alt_text=None, display=None, position=None) Use this method to add content to your StoryMap. content can be of various class types and when you add this content you can specify a caption, alt_text, display style, and the position at which it will be in your story. Not passing in any content means a separator will be added.
Parameter
Description
content
Optional content of type:
Image
,Gallery
,Video
,Audio
,Embed
,Map
,Text
,Button
,Timeline
,Sidecar
Swipe
,Separator
,Code
,Table
caption
Optional String. Custom text to caption the webmap.
alt_text
Optional String. Custom text to be used for screen readers.
display
Optional String. How the item will be displayed in the story map.
For Image, Video, Audio, or Map object. Values: “standard” | “wide” | “full” | “float”
For Gallery: Values: “jigsaw” | “square-dynamic”
For Embed: Values: “card” | “inline”
For Swipe: Values: “small” | “medium” | “large”
position
Optional Integer. Indicates the position in which the content will be added. To see all node positions use the
node
property.- Returns
A String depicting the node id for the content that was added.
new_story = StoryMap() # Example with Image >>> image1 = Image("<image-path>.jpg/jpeg/png/gif ") >>> new_node = new_story.add(image1, position = 2) # Example with Map >>> my_map = Map(<item-id of type webmap>) >>> new_node = new_story.add(my_map, "A map caption", "A new map alt-text") # Example to add a Separator >>> new_node = new_story.add() >>> print(new_story.nodes)
-
property
content_list
Get a list of all the content instances in order of appearance in the story. This returns a list of class instances for the content in the story.
-
copy_content
(target_story, node_list) Copy the content from one story to another. This will copy the content indicated to the target story in the order they are provided. To change the order once the nodes are copied, use the move() method on the target story.
Note
Do not forget to save the target story once you are done copying and making any further edits.
Note
This method can take time depending on the number of resources. Each resource coming from a file must be copied over and heavy files, such as videos or audio, can be time consuming.
Parameter
Description
target_story
Required StoryMap instance. The target story that the content will be copied to.
node_list
Required list of strings. The list of node ids indicating the content that will be copied to the target story.
- Returns
True if all nodes have been successfully copied over.
-
cover
(title=None, type=None, summary=None, by_line=None, image=None) A story’s cover is at the top of the story and always the first node. This method allows the cover to be edited by updating the title, byline, image, and more. Changing one part of the story cover will not change the rest of the story cover. If just the image is passed in then only the image will change.
Note
To change the date seen on the story cover, use the
cover_date
property.Parameter
Description
title
Optional string. The title of the StoryMap cover.
type
Optional string. The type of story cover to be used in the story.
Values: "full" | "sidebyside" | "minimal"
summary
Optional string. The description of the story.
by_line
Optional string. Crediting the author(s).
image
Optional url or file path or
Image
object. The cover image for the story cover.- Returns
Dictionary representation of the story cover node.
story = StoryMap(<story item>) story.cover(title="My Story Title", type="minimal", summary="My little summary", by_line="python_dev") story.save()
-
property
cover_date
Get/Set the date type shown on the story cover.
Parameter
Description
date_type
Optional String. Set the desired date type for the story cover.
Values: "first-published" | "last-published" | "none"
-
credits
(content=None, attribution=None, heading=None, description=None) Credits are found at the end of the story and thus are always the last node.
To create a credit, add the text that should be shown on each side of the divider. content represents the text seen on the left side and attribution is in line with content on the right side of the divider. (i.e. ‘content’ | ‘attribution’)
Adding
content
andattribution
will add a new line to the credits and will not change previous credits.Adding
heading
anddescription
will change what is currently in place.Parameter
Description
content
Optional String. The content to be added. (Seen on the left side of the credits.)
Make sure text has ‘<strong> </strong>’ tags. Adds to the existing credits.
attribution
Optional String. The attribution to be added. (Seen on right side of the credits.) Adds to the existing credits.
heading
Optional String. Replace current heading for credits.
description
Optional String. Replace current description for credits.
- Returns
A list of strings that are the node ids for the text nodes that belong to credits.
#Example >>> story = StoryMap() >>> story.credits("Python Dev" , "Python API Team", "Thank You", "A big thank you to those who contributed")
-
duplicate
(title=None) Duplicate the story. All items will be duplicated as they are. This allows you to create a story template and duplicate it when you want to work with it.
It is highly recommended that once the duplicate is created, open it in Story Maps builder to ensure the issue checker finds any issues before editing.
Note
Can be used with ArcGIS Online or with ArcGIS Enterprise starting 10.8.1
Parameter
Description
title
Optional string. The title of the duplicated story. Only available for ArcGISOnline.
- Returns
The Item that was created.
# Example for ArcGIS Online >>> story = StoryMap(<story item>) >>> story.duplicate("A Story Copy") # Example for ArcGIS Enterprise >>> story = StoryMap(<story item>) >>> story.duplicate()
-
get
(node=None, type=None) Deprecated since version 2.2.0: Removed in: 3.0.0. get method has been deprecated, use content_list property instead.
Get node(s) by type or by their id. Using this function will help grab a specific node from the story if a node id is provided. Set this to a variable and this way edits can be made on the node in the story.
Parameter
Description
node
Optional string. The node id for the node that should be returned. This will return the class of the node if of type story content.
type
Optional string. The type of nodes that user wants returned. If none specified, list of all nodes returned.
Values: image | video | audio | embed | webmap | text | button | separator | expressmap | webscene | immersive | code
- Returns
If type specified: List of node ids and their types in order of appearance in the story map.
If node_id specified: The node itself.
>>> story = StoryMap(<story item>) # Example get by type >>> story.get(type = "text") Returns a list of all nodes of type text # Example by id >>> text = story.get(node= "<id for text node>") >>> text.properties Returns a specific node of type text
-
move
(node_id, position=None, delete_current=False) Move a node to another position. The node currently at that position will be moved down one space. The node at the current position can be deleted instead of moved if delete_current is set to True.
Parameter
Description
node_id
Required String. The node id for the content that will be moved. Find a list of node order by using the
nodes
property.position
Optional Integer. Indicates the position in which the content will be added. If no position is provided, the node will be placed at the end.
delete_current
Optional Boolean. If set to True, the node at the current position will be deleted instead of moved down one space. Default is False.
new_story = StoryMap() # Example with Image >>> image1 = Image("<image-path>.jpg/jpeg/png/gif") >>> image2 = Image("<image-path>.jpg/jpeg/png/gif") >>> new_node = new_story.add(image1, "my caption", "my alt-text", "float", 2) >>> new_story.add(image2) >>> new_story.move(new_node, 3, False)
Story navigation is a way for authors to add headings as links to allow readers to navigate between different sections of a story. The story navigation node takes
TextStyle.HEADING
text styles as its only allowed children. You can only have 30Text
child nodes as visible and act as links within a story.The text nodes must already exist in the story. Pass the list of node ids for the heading text nodes to assign them to the navigation.
Parameter
Description
nodes
Optional list of nodes to include in the navigation. These nodes can only be of style heading (“h2”). Include in order. This will override current list and order.
To see current list use
navigation_list
property.hidden
Optional boolean. If True, the navigation is hidden.
- Returns
List of nodes in the navigation.
#Example >>> story = StoryMap("<existing story id>") >>> story.navigation_list >>> story.navigation(["<header node id>", "<header node id>"], False)
Get a list of the nodes that are linked in the navigation.
-
nodes
Deprecated since version 2.2.0: Removed in: 3.0.0. nodes property has been deprecated, use content_list property instead.
Get main nodes in order of appearance in the story. This will return a list of dictionaries specifying the node ids and the class content they correspond to. If there is no class for the content, a string is returned with the content type.
-
save
(title=None, tags=None, access=None, publish=False) This method will save your Story Map to your active GIS. The story will be saved with unpublished changes unless publish parameter is specified to True.
The title only needs to be specified if a change is wanted, otherwise existing title is used.
Warning
Publishing your story through the Python API means it will not go through the Story Map issue checker. It is recommended to publish through the Story Maps builder if you want your story to go through the issue checker.
Warning
Changes to the published story may not be visible for up to one hour. You can open the story in the story builder to force changes to appear immediately and perform other optimizations, such as updating the story’s social/SEO metadata.
Parameter
Description
title
Optional string. The title of the StoryMap.
tags
Optional string. The tags of the StoryMap.
access
Optional string. The access of the StoryMap. If none is specified, the current access is kept. This is used when publish parameter is set to True.
Values: private | org | public
publish
Optional boolean. If True, the story is saved and also published. Default is false so story is saved with unpublished changes.
- Returns
The Item that was saved to your active GIS.
-
show
(width=None, height=None) Show a preview of the story. The default is a width of 700 and height of 300.
Parameter
Description
width
Optional integer. The desired width to show the preview.
height
Optional integer. The desired height to show the preview.
- Returns
An Iframe display of the story map if possible, else the item url is returned to be clicked on.
-
property
story_locale
Get/Set the locale and language of the story.
If your story was created with the Python API then the default is “en-US”
-
theme
(theme=<Themes.SUMMIT: 'summit'>) Each story has a theme node in its resources. This method can be used to change the theme. To add a custom theme to your story, pass in the item_id for the item of type Story Map Theme.
Parameter
Description
theme
Required Themes Style or custom theme item id. The theme to set the story to.
Values: SUMMIT | TIDAL | MESA | RIDGELINE | SLATE | OBSIDIAN | <item_id>
>>> from arcgis.apps.storymap import Themes >>> story = StoryMap() >>> story.theme(Themes.TIDAL)
-
Image
-
class
arcgis.apps.storymap.story_content.
Image
(path=None, **kwargs) Bases:
object
Class representing an image from a url or file.
Warning
Image must be smaller than 10 MB to avoid having issues when saving or publishing.
Note
Once you create an Image instance you must add it to the story to be able to edit it further.
Parameter
Description
path
Required String. The file path or url to the image that will be added.
-
property
alt_text
Get/Set the alternate text property for the image.
Parameter
Description
alt_text
String. The new alt_text for the Image.
- Returns
The alternate text that is being used.
Get/Set the caption property for the image.
Parameter
Description
caption
String. The new caption for the Image.
- Returns
The caption that is being used.
-
property
Video
-
class
arcgis.apps.storymap.story_content.
Video
(path=None, **kwargs) Bases:
object
Class representing a video from a url or file
Note
Once you create a Video instance you must add it to the story to be able to edit it further.
Parameter
Description
path
Required String. The file path or embed url to the video that will be added.
Note
URL must be an embed url. Example: “https://www.youtube.com/embed/G6b7Kgvd0iA”
-
property
alt_text
Get/Set the alternate text property for the video.
Parameter
Description
alt_text
String. The new alt_text for the Video.
- Returns
The alternate text that is being used.
Get/Set the caption property for the video.
Parameter
Description
caption
String. The new caption for the Video.
- Returns
The caption that is being used.
-
property
display
Get/Set display for the video.
Values: small | wide | full | float
Note
Cannot change display when video is created from a url
-
property
Audio
-
class
arcgis.apps.storymap.story_content.
Audio
(path=None, **kwargs) Bases:
object
This class represents content that is of type audio. It can be created from a file path and added to the story.
Note
Once you create an Audio instance you must add it to the story to be able to edit it further.
Parameter
Description
path
Required String. The file path to the audio that will be added.
-
property
alt_text
Get/Set the alternate text property for the audio.
Parameter
Description
alt_text
String. The new alt_text for the Audio.
- Returns
The alternate text that is being used.
-
property
audio
Get/Set the audio path.
Parameter
Description
audio
String. The new audio path for the Audio.
- Returns
The audio that is being used.
Get/Set the caption property for the audio.
Parameter
Description
caption
String. The new caption for the Audio.
- Returns
The caption that is being used.
-
property
Embed
-
class
arcgis.apps.storymap.story_content.
Embed
(path=None, **kwargs) Bases:
object
Class representing a webpage or embedded audio. Embed will show as a card in the story.
Note
Once you create an Embed instance you must add it to the story to be able to edit it further.
Parameter
Description
path
Required String. The url that will be added as a webpage, video, or audio embed into the story.
-
property
alt_text
Get/Set the alternate text property for the embed.
Parameter
Description
alt_text
String. The new alt_text for the Embed.
- Returns
The alternate text that is being used.
Get/Set the caption property for the webpage.
Parameter
Description
caption
String. The new caption for the Embed.
- Returns
The caption that is being used.
-
property
link
Get/Set the link property.
Parameter
Description
link
String. The new url for the Embed.
- Returns
The embed that is being used.
-
property
Map
-
class
arcgis.apps.storymap.story_content.
Map
(item=None, **kwargs) Bases:
object
Class representing a webmap or webscene for the story
Note
Once you create a Map instance you must add it to the story to be able to edit it further.
Parameter
Description
item
An Item of type
WebMap
orWebScene
or a String representing the item id to add to the story map.-
property
alt_text
Get/Set the alternate text property for the map.
Parameter
Description
alt_text
String. The new alt_text for the Map.
- Returns
The alternate text that is being used.
Get/Set the caption property for the map.
Parameter
Description
caption
String. The new caption for the Map.
- Returns
The caption that is being used.
-
property
display
Get/Set the display type of the map.
Values: standard | wide | full | float right | float left
-
property
legend_pinned
Get/Set the legend pinned toggle. True if enabled and False if disabled.
Note
If set to True, make sure show_legend is also True. Otherwise, you will not see the legend pinned.
-
property
map
Get/Set the map property.
Parameter
Description
map
One of three choices:
String being an item id for an Item of type
An
Item
of type
Note
Only replace a Map with a new map of same type. Cannot replace a 2D map with 3D.
- Returns
The item id for the map that is being used.
-
property
offline_media
Get/Set the offline media. This is an alternative version of this media for offline viewing using the ArcGIS StoryMaps Briefings app.
Note
This property is only available for ArcGIS StoryMaps Briefings and the map must be part of the Briefing before setting this property.
Parameter
Description
offline_media
The new offline media for the Map or Scene. This can either be the item of a Mobile Map Package or Mobile Scene Package or it can be an item of type Image or Video from Story Contents.
-
property
properties
Get properties for the Map.
- Returns
A dictionary depicting the node dictionary and resource dictionary for the map. The resource dictionary depicts the original map settings. The node dictionary depicts the current map settings. If nothing it returned, make sure the content is part of the story.
Note
To change various properties of the Map use the other property setters.
-
set_viewpoint
(extent=None, scale=None) Set the extent and/or scale for the map in the story.
If you have an extent to use from a bookmark, find this extent by using the bookmarks property in the
WebMap
Class. The map property on this class will return the Web Map Item being used. By passing this item into theWebMap
Class you can retrieve a list of all bookmarks and their extents with the bookmarks property.To see the current viewpoint call the properties property on the Map node.
Parameter
Description
extent
Optional dictionary representing the extent of the map. This will update the extent, center and viewpoint accordingly.
- Example:
- {‘spatialReference’: {‘latestWkid’: 3857, ‘wkid’: 102100},‘xmin’: -609354.6306080809,‘ymin’: 2885721.2797636474,‘xmax’: 6068184.160383142,‘ymax’: 6642754.094035632}
scale
Optional Scales enum class value or dict with ‘scale’ and ‘zoom’ keys.
Scale is a unit-less way of describing how any distance on the map translates to a real-world distance. For example, a map at a 1:24,000 scale communicates that 1 unit on the screen represents 24,000 of the same unit in the real world. So one inch on the screen represents 24,000 inches in the real world.
- Returns
The current viewpoint dictionary
-
property
Text
-
class
arcgis.apps.storymap.story_content.
Text
(text=None, style=<TextStyles.PARAGRAPH: 'paragraph'>, color=None, size=None, **kwargs) Bases:
object
Class representing a text and a style of text.
Note
Once you create a Text instance you must add it to the story to be able to edit it further.
Properties of the different text types:
Type
Text
paragraph
String can contain the following tags for text formatting: <strong>, <em>, <a href=”{link}” rel=”noopener noreferer” target=”_blank” and a class attribute to indicate color formatting: class=sm-text-color-{values} attribute in the <strong> | <em> | <a> | <span> tags
Values: themeColor1 | themeColor2 | themeColor3 | customTextColors
heading
String can only contain <em> tag
subheading
String can only contain <em> tag
bullet-list
String can contain the following tags for text formatting: <strong>, <em>, <a href=”{link}” rel=”noopener noreferer” target=”_blank” and a class attribute to indicate color formatting: class=sm-text-color-{values} attribute in the <strong> | <em> | <a> | <span> tags
Values: themeColor1 | themeColor2 | themeColor3 | customTextColors
numbered-list
String can contain the following tags for text formatting: <strong>, <em>, <a href=”{link}” rel=”noopener noreferer” target=”_blank” and a class attribute to indicate color formatting: class=sm-text-color-{values} attribute in the <strong> | <em> | <a> | <span> tags
Values: themeColor1 | themeColor2 | themeColor3 | customTextColors
quote
String can only contain <strong> and <em> tags
-
add_attachment
(content, text=None) Add a text action to your text. You can specify the data of the action. This can only be used within a Briefing
Parameter
Description
content
Required content that can be added as an attachment. Content can be: * An Item object of type: Web Map, Image, StoryMap, Collection, Dashboard, Web Experience, or other arcgis Apps. * A story content of type Image or Video
text
Optional String. The part of the text that the attachment will be linked to. The text must already exist in the text node.
For example, if the entire text is “Look at this dog.” and you want to link the word “dog” to the attachment, then the text parameter would be “dog”.
- Returns
True if successful.
-
property
properties
Get the properties for the text.
- Returns
The Text dictionary for the node. If nothing is returned, make sure the content is part of the story.
-
remove_attachment
(text=None) Remove an attachment from the text. If text_to_remove is None, remove all attachments. This can only be used within a Briefing.
Parameter
Description
text
Optional String. The part of the text that the attachment will be removed from. The text must already exist in the text class. If text is None, then all attachments will be removed.
- Returns
True if successful.
-
property
size
Get/Set the size for the text node.
Parameter
Description
size
Optional String. The new size to be displayed. Applicable for Paragraph, Bullet List, and Numbered List.
Values: small | medium | large
Note
“small” can only be used in a Briefing.
- Returns
The size for the node. If nothing is returned, make sure the content is part of the story.
-
Button
-
class
arcgis.apps.storymap.story_content.
Button
(link=None, text=None, **kwargs) Bases:
object
Class representing a button.
Note
Once you create a Button instance you must add it to the story to be able to edit it further.
Parameter
Description
link
Required String. When user clicks on button, they will be brought to the link.
text
Required String. The text that shows on the button.
-
property
link
Get/Set the link for the button.
Parameter
Description
link
Optional String. The new path for the button.
- Returns
The link being used. If nothing is returned, make sure the content is part of the story.
-
property
Gallery
-
class
arcgis.apps.storymap.story_content.
Gallery
(**kwargs) Bases:
object
Class representing an image gallery
To begin with a new gallery, simply call the class. Once added to the story, you can add up to 12 images.
Note
Once you create a Gallery instance you must add it to the story to be able to edit it further.
# Images to add to the gallery. >>> image1 = Image(<url or path>) >>> image2 = Image(<url or path>) >>> image3 = Image(<url or path>) # Create a gallery and add to story before adding images to it. >>> gallery = Gallery() >>> my_story.add(gallery) >>> gallery.add_images([image1, image2, image3])
-
property
alt_text
Get/Set the alternate text property for the swipe.
Parameter
Description
alt_text
String. The new alt_text for the Gallery.
- Returns
The alternate text that is being used.
Get/Set the caption property for the swipe.
Parameter
Description
caption
String. The new caption for the Gallery.
- Returns
The caption that is being used.
-
delete_image
(image) The delete_image method is used to delete one image from the gallery. To see a list of images used in the gallery, use the
images()
property.Parameter
Description
image
Required String. The node id for the image to be removed from the gallery or the Image instance.
- Returns
The current list of images in the gallery.
-
property
images
Get/Set list of image nodes in the image gallery. Setting the lists allows the images to be reordered.
Parameter
Description
images
List of node ids for the images in the gallery. Nodes must already be in the gallery and this list will adjust the order of the images.
- To add new images to the gallery use:
Gallery.add_images(images)
- To delete an image from a gallery use:
Gallery.delete_image(node_id)
- Returns
A list of node ids in order of image appearance in the gallery. If nothing is returned, make sure the gallery is part of the story.
-
property
Swipe
-
class
arcgis.apps.storymap.story_content.
Swipe
(**kwargs) Bases:
object
Create a Swipe node.
Note
Once you create a Swipe instance you must add it to the story to be able to edit it further.
Parameter
Description
node_id
Required String. The node id for the swipe type.
story
Required
StoryMap
that the swipe belongs to.>>> my_story.nodes #use to find swipe node id # Method 1: Use the Swipe Class >>> swipe = Swipe() # Method 2: Use the get method in story >>> swipe = my_story.get(node = <node_id>)
-
property
alt_text
Get/Set the alternate text property for the swipe.
Parameter
Description
alt_text
String. The new alt_text for the Swipe.
- Returns
The alternate text that is being used.
Get/Set the caption property for the swipe.
Parameter
Description
caption
String. The new caption for the Swipe.
- Returns
The caption that is being used.
-
edit
(content=None, position='right') Edit the media content of a Swipe item. To save your edits and see them in the StoryMap’s builder, make sure to save the story.
Use this method to add new content if your swipe is empty. You can specify the content to add and which side of the swipe it should be on.
Parameter
Description
content
Required story content of type:
Image
orMap
. Must be the same media type on both panels.position
Optional String. Either “right” or “left”. Default is “right” so content will be added to right panel.
- Returns
True if successful
-
property
Sidecar
-
class
arcgis.apps.storymap.story_content.
Sidecar
(style=None, **kwargs) Bases:
object
Create an Sidecar immersive object.
A sidecar is composed of slides. Slides are composed of two sub structures: a narrative panel and a media panel. The media node can be a(n): Image, Video, Embed, Map, or Swipe. The narrative panel can contain multiple types of content including Image, Video, Embed, Button, Text, Map, and more.
Note
Once you create a Sidecar instance you must add it to the story to be able to edit it further.
Parameter
Description
style
Optional string that depicts the sidecar style. Values: ‘floating-panel’ | ‘docked-panel’ | ‘slideshow’
>>> my_story.nodes #use to find sidecar node id # Method 1: Use the Sidecar Class >>> sidecar = Sidecar("floating-panel") # create from scratch # Method 2: Use the get method in story >>> sidecar = my_story.content_list()[3] # sidecar is fourth item in story
-
add_action
(slide_number, text, viewpoint, extent=None, map_layers=None) Add a map action button to a slide. You can specify the data of the action.
Parameter
Description
slide_number
Required Integer. The slide that the map action will be added to. First slide is 1.
text
Required String. The map action button text
viewpoint
Required Dictionary. The viewpoint to be set. The minimum keys to include are an x and y center point in the target geometry.
- Example:
- viewpoint = {
“rotation”: 0, “scale”: 18055.954822, “targetGeometry”: {
- “spatialReference”: {
“latestWkid”: 3857, “wkid”: 102100
}, “x”: -8723429.856341356, “y”: 4019095.847955684
}
}
extent
Optional Dictionary. The extent of the map that will be shown when the action button is used.
- Example:
- extent = {
- “spatialReference”: {
“latestWkid”: 3857, “wkid”: 102100
}, “xmin”: -8839182.968379805, “ymin”: 3907027.5240857545, “xmax”: -8824335.075635428, “ymax”: 3915378.269425899
}
map_layers
Optional list of dictionaries. Each dictionary represents a map layer and the parameters set on the map layer.
- Example:
- map_layers = [
- {
“id”: “18511776c33-layer-2”, “title”: “USA Forest Type”, “visible”: true
}
]
- Returns
The node id for the action that was added to the slide
-
add_slide
(contents=None, media=None, slide_number=None) Add a slide to the sidecar. You are able to specify the position of the slide, the content of the narrative panel and the media of the slide.
Parameter
Description
contents
Optional list of story content item(s). The instances of story content that will be added to the narrative panel such as Text, Image, Embed, etc.
media
Optional item that is a story content item. Item type for the media node can be: Image, Video, Map, Embed, or Swipe.
slide_number
Optional Integer. The position at which the new slide will be. If none is provided then it will be added as the last slide.
First slide is 1.
# Get sidecar from story and see the properties sc = story.get(<sidecar_node_id>) sc.properties >> returns a dictionary structure of the sidecar # create the content we will add to narrative_panel_nodes parameter im = Image(<img_url_or_path>) txt = Text("Hello World") embed = Embed(<url>) narrative_nodes = [im, txt, embed] mmap = Map(<item_id webmap>) # Add new slide with the content: sc.add_slide(narrative_nodes, mmap, 4) >> New slide added with the content at position 4
-
property
content_list
Get a list of all the content within the sidecar in order of appearance. The content will be displayed in the following order: A list of the content in slide 1, a list of the content in slide 2, etc. Each sub-list will contain content found in the narrative panel, if any, and the media content, if any.
-
edit
(content, slide_number) Edit method can be used to edit the type of media in a slide of the Sidecar. This is done by specifying the slide number and the media content to be added. The media can only be of type: Image, Video, Map, or Embed.
Note
This method should not be used to edit the narrative panel of the Sidecar. To better edit both the media and the narrative panel, it is recommended to use the
get()
method in the Sidecar class. The get method can be used to change media if the content is of the same type as what is currently present and preserve the node_id.Parameter
Description
content
Required item that is a story content item. Item type for the media node can be:
Image
,Video
,Map
Embed
,Swipe
slide_number
Required Integer. The slide that will be edited. First slide is 1.
# Get sidecar from story and see the properties sc = story.get(<sidecar_node_id>) sc.properties >> returns a dictionary structure of the sidecar # If a slide 2 contains a map and you want to change it to an image im = Image(<img_url_or_path>) sc.edit(im, 2) sc.properties >> notice slide 2 now has an image # If I want to update the image then 2 methods: # OPTION 1 im2 = Image(<img_url_or_path>) sc.edit(im2, 2) # OPTION 2 (only applicable if content is of same type as existing) im2 = sc.get(im.node_id) im2.image = <img_url_or_path>
-
get
(node_id) The get method is used to get the node that will be edited. Use sidecar.properties to find all nodes associated with the sidecar.
Parameter
Description
node_id
Required String. The node id for the content that will be returned.
- Returns
An class instance of the node type.
# Find the nodes associated with the sidecar sc = story.get(<sidecar_node_id>) sc.properties >> returns a dictionary structure of the sidecar # Get a node associated with the sidecar, in this example an image, and change the image im = sc.get(<node_id>) im.image = <new_image_path> # Save the story to see changes applied in Story Map builder story.save()
-
Timeline
-
class
arcgis.apps.storymap.story_content.
Timeline
(style=None, **kwargs) Bases:
object
Create a Timeline object from a pre-existing timeline node.
A timeline is composed of events. Events are composed of maximum three nodes: an image, a sub-heading text, and a paragraph text.
Note
Once you create a Timeline instance you must add it to the story to be able to edit it further.
Parameter
Description
style
Required string, the style type of the timeline. If the timeline will be added to a Sidecar, then only waterfall and single-sided are allowed.
Values: ‘waterfall’ | ‘single-side’ | ‘condensed’
>>> my_story.nodes #use to find timeline node id # Method 1: Use the Timeline Class >>> timeline = Timeline(my_story, <node_id>) # Method 2: Use the get method in story >>> timeline = my_story.get(node = <node_id>)
-
add_event
(contents=None, position=None) Add event or spacer to the timeline.
Parameter
Description
contents
Optional item list that will be in the event. Need to be passed in by order of appearance. Item type can be
Image
orText
.Text can only be of style TextStyles.SUBHEADING or TextStyles.PARAGRAPH
Note
To create timeline spacer, do not pass in any value for this parameter.
position
Optional Integer. The position at which the even will be added. First event is 1. If None, then the event will be added to the end.
-
edit
(content, event) Edit event text or image content. To add a new event use the add_event method.
Parameter
Description
content
Required content to replace current content. Item type can be
Image
orText
.Text can only be of style TextStyles.SUBHEADING or TextStyles.PARAGRAPH
event
Required Integer. The event that will be edited. First event is 1.
-
property
properties
List all events and their children
- Returns
A list where the first item is the node id for the timeline. Next items are dictionary of events and their children.
-
MapTour
-
class
arcgis.apps.storymap.story_content.
MapTour
(**kwargs) Bases:
object
Create a MapTour object from a pre-existing maptour node.
Note
Once you create a MapTour instance you must add it to the story to be able to edit it further.
>>> my_story.nodes #use to find map tour node id # Method 1: Use the MapTour Class >>> maptour = MapTour(my_story, <node_id>) # Method 2: Use the get method in story >>> maptour = my_story.get(node = <node_id>)
-
get
(node_id) The get method is used to get the node that will be edited. Use maptour.properties to find all nodes associated with the sidecar.
Parameter
Description
node_id
Required String. The node id for the content that will be returned.
- Returns
An class instance of the node type.
# Find the nodes associated with the map tour mt = story.get(<maptour_node_id>) mt.places >> returns places of the map tour # Get a node associated with the map tour, in this example an image, and change the image im = mt.get(<node_id>) im.image = <new_image_path> # Save the story to see changes applied in Story Map builder story.save()
-
Code
-
class
arcgis.apps.storymap.story_content.
Code
(content=None, language=None, **kwargs) Bases:
object
Class representing a code content card. Code will show as a block of code in your Storymap.
Note
Once you create a Code instance you must add it to the story to be able to edit it further.
Parameter
Description
content
Required String. The code content to have in the block.
language
Required Language or String. The coding language of the content provided. For values see Language Enum Class.
-
property
content
Get/Set the content property.
Parameter
Description
content
String. The new content for the code block.
- Returns
The content that is being used.
-
property
Briefing
-
class
arcgis.apps.storymap.briefing.
Briefing
(item=None, gis=None) Bases:
object
Synthesize critical information and maintain mission readiness with briefings, a new slide-based presentation style now available as a type of ArcGIS StoryMap. Make data-driven decisions and provide meaningful context to your audience by infusing your presentations with real-time data and dynamic maps. Briefings also allow you to unify images, videos, and other multimedia in your presentation to create a cohesive experience for both you and your viewers.
Example use cases include on-the-ground disaster briefings, budget numbers presented in real-time, and daily leadership briefings. After the briefings mobile app launches in September, you’ll be able to securely connect with your stakeholders wherever they are with a tablet app that works on- and offline.
Create a StoryMap Briefing object to make edits to a story. Can be created from an item of type ‘StoryMap Briefing’, an item id for that type of item, or if nothing is passed, a new story is created from a generic draft.
If an Item or item_id is passed in, only published changes or new drafts are taken from the StoryMap Briefing. If you have a story with unpublished changes, they will not appear when you construct your story with the API. If you start to work on your Briefing that has unpublished changes and save from the Python API, your unpublished changes on the GUI will be overwritten with your work from the API.
Parameter
Description
item
Optional String or Item. The string for an item id or an item of type ‘StoryMap Briefing’. If no item is passed, a new story is created and saved to your active portal.
gis
Optional instance of
GIS
. If none provided the active gis is used.-
property
actions
Get list of action nodes. These are nodes that trigger an action to occur, for example when text is linked to an image, map, etc.
-
add
(layout, *, sublayout=None, title=None, subtitle=None, section_position=None, position=None) Use this method to add content to your StoryMap. content can be of various class types and when you add this content you can specify a caption, alt_text, display style, and the position at which it will be in your story. Not passing in any content means a separator will be added.
Parameter
Description
layout
Required LayoutType or string, the layout type of the slide.
sublayout
Optional SubLayoutType or string, the sublayout type of the slide. Only applicable when the layout is “double” or “titleless-double”.
title
Optional string or
Text
object, the title of the slide. Text can only be of type heading (h2).subtitle
Optional string or
Text
object, the subtitle of the slide. Text can only be of type paragraph.section_position
Optional string, the title panel position of the section slide. Only applicable for “section-double”. Values: ‘start’ | ‘end’
position
Optional Integer. Indicates the position in which the slide will be added. If no position is provided, the slide will be placed at the end.
- Returns
The new slide that was added to the story
-
copy_content
(target_briefing, content) Copy the content from one briefing to another. This will copy the content indicated to the target briefing in the order they are provided.
Note
Do not forget to save the target briefing once you are done copying and making any further edits.
Note
This method can take time depending on the number of resources. Each resource coming from a file must be copied over and heavy files, such as videos or audio, can be time consuming.
Parameter
Description
target_briefing
Required Briefing instance. The target briefing that the content will be copied to.
content
Required list of content. The list of content that will be copied to the target briefing.
- Returns
True if all content has been successfully copied over.
-
cover
(title=None, type=None, summary=None, by_line=None, media=None) A briefing’s cover is the first slide. This method allows the cover to be edited by updating the title, byline, media, and more. Changing one part of the briefing cover will not change the rest of the cover. If just the media is passed in then only the media will change.
Parameter
Description
title
Optional string. The title of the Briefing cover.
type
Optional string. The type of briefing cover to be used in the story.
Values: "full" | "sidebyside" | "minimal"
summary
Optional string. The description of the story.
by_line
Optional string. Crediting the author(s).
media
- Returns
True if the cover was updated successfully.
briefing = Briefing(<briefing item>) briefing.cover(title="My Briefing Title", type="sidebyside", summary="My little summary", by_line="python_dev") briefing.save()
-
duplicate
(title=None) Duplicate the story. All items will be duplicated as they are. This allows you to create a briefing template and duplicate it when you want to work with it.
It is highly recommended that once the duplicate is created, open it in StoryMap Briefing builder to ensure the issue checker finds any issues before editing.
Note
Can be used with ArcGIS Online or with ArcGIS Enterprise starting 10.8.1.
Note
To duplicate into another organization, use the
clone_items()
method.Parameter
Description
title
Optional string. The title of the duplicated story. Only available for ArcGIS Online.
- Returns
The Item that was created.
# Example for ArcGIS Online >>> briefing = Briefing(<briefing item>) >>> briefing.duplicate("A Briefing Copy")
-
move
(slide, position=None, delete_current=False) Move a slide to another position. The slide currently at that position will be moved down one space. The slide at the current position can be deleted instead of moved if delete_current is set to True.
Parameter
Description
slide
Required integer. The slide number to move. The cover is slide 0 and this cannot be moved.
position
Optional Integer. Indicates the position in which the slide will be added. If no position is provided, the slide will be placed at the end.
delete_current
Optional Boolean. If set to True, the slide at the current position will be deleted instead of moved down one space. Default is False.
- Returns
True if the slide was moved successfully.
-
save
(title=None, tags=None, access=None, publish=False) This method will save your Story Map to your active GIS. The story will be saved with unpublished changes unless publish parameter is specified to True.
The title only needs to be specified if a change is wanted, otherwise existing title is used.
Warning
Publishing your story through the Python API means it will not go through the Story Map issue checker. It is recommended to publish through the Story Maps builder if you want your story to go through the issue checker.
Warning
Changes to the published story may not be visible for up to one hour. You can open the story in the story builder to force changes to appear immediately and perform other optimizations, such as updating the story’s social/SEO metadata.
Parameter
Description
title
Optional string. The title of the StoryMap.
tags
Optional string. The tags of the StoryMap.
access
Optional string. The access of the StoryMap. If none is specified, the current access is kept. This is used when publish parameter is set to True.
Values: private | org | public
publish
Optional boolean. If True, the story is saved and also published. Default is false so story is saved with unpublished changes.
- Returns
The Item that was saved to your active GIS.
-
show
(width=None, height=None) Show a preview of the briefing. The default is a width of 700 and height of 300.
Parameter
Description
width
Optional integer. The desired width to show the preview.
height
Optional integer. The desired height to show the preview.
- Returns
An Iframe display of the briefing if possible, else the item url is returned to be clicked on.
-
property
slides
Get a list of all the content instances in order of appearance in the story. This returns a list of class instances for the content in the story.
-
theme
(theme=<Themes.SUMMIT: 'summit'>) Each briefing has a theme node in its resources. This method can be used to change the theme. To add a custom theme to your story, pass in the item_id for the item of type Story Map Theme.
Parameter
Description
theme
Required Themes Style or custom theme item id. The theme to set on the briefing.
Values: SUMMIT | TIDAL | MESA | RIDGELINE | SLATE | OBSIDIAN | <item_id>
>>> from arcgis.apps.storymap import Themes, Briefing >>> briefing = Briefing() >>> briefing.theme(Themes.TIDAL)
-
property
Block
-
class
arcgis.apps.storymap.story_content.
Block
(block_index, slide, story) Bases:
object
Represents a block in a briefing slide.
Note
Blocks are automatically created when you create a new slide. You can access the blocks through the blocks property of the slide. Do not create this class directly.
-
add_content
(content) Add content to the block.
Parameter
Description
content
Required content object to be added to the block. The content object can be of type Text, Image, Video, Embed, Map, or Swipe. There can be more than one Text contents in the same block but only one of the other types of content. Setting an Image, Video, Embed, Map, or Swipe content will overwrite the current content. Setting a Text content will add the text to the block.
- Returns
The Content object that was added to the block.
-
Table
-
class
arcgis.apps.storymap.story_content.
Table
(rows=None, columns=None, **kwargs) Bases:
object
Class representing a table block. Table will show as a gridded table in your Storymap.
Note
Once you create a Table instance you must add it to the story to be able to edit it further.
Parameter
Description
rows
Optional int. The number of rows in the table. Table supports a maximum of 10 rows. Minimum of 2 rows supported.
columns
Optional int. The number of columns in the table. Table supports a maximum of 8 columns. Minimum of 1 column supported.
-
property
content
Get the content of the table as a panda’s DataFrame. Each cell content is held within a dictionary where the ‘value’ key is the text of the cell. The other key that can be included in the dictionary is the ‘textAlignment’ key.
Parameter
Description
content
Required pandas DataFrame. The content of the table as a pandas DataFrame. The index of the DataFrame will be the row headers and the columns of the DataFrame will be the column headers.
-
property
ExpressMap
Collection
-
class
arcgis.apps.storymap.collection.
Collection
(item=None, gis=None) Bases:
object
Parameter
Description
item
Optional String or Item. The string for an item id or an item of type ‘StoryMap Collection’. If no item is passed, a new story is created and saved to your active portal.
gis
Optional instance of
GIS
. If none provided the active gis is used.-
add
(item, title=None, thumbnail=None, position=None) Add an item to the collection. Specify this item with the item object. The item can be a portal item, file resource, or a story content of type Image, Video, or Embed.
Parameter
Description
item
Required object. Either an Image, Video, or Embed content type object.
title
Optional string. The title of the item to add under the thumbnail in the collection.
thumbnail
Optional string. The image file path to use as the thumbnail for the item.
position
Optional integer. The position in the collection to add the item. If none is specified, the item is added to the end of the collection.
-
cover
(title=None, type=None, summary=None, by_line=None) A collection’s cover is the first slide. This method allows the cover to be edited by updating the title, byline, media, and more. Changing one part of the collection cover will not change the rest of the cover. If just the media is passed in then only the media will change.
Parameter
Description
title
Optional string. The title of the Collection cover.
type
Optional string. The type of collection cover to be used in the story.
Values: "full" | "sidebyside" | "minimal"
summary
Optional string. The description of the story.
by_line
Optional string. Crediting the author(s).
- Returns
True if the cover was updated successfully.
collection = Collection(<collection item>) collection.cover(title="My Collection Title", type="sidebyside", summary="My little summary", by_line="python_dev") collection.save()
-
remove
(index) Remove an item from the collection. Specify this item with the index position of the item in the collection. The list of items in the collection can be found by using the content property. The index position is the position of the item in the list.
Parameter
Description
index
Required integer. The index position of the item to remove.
- Returns
True if the item was removed successfully.
-
save
(title=None, tags=None, access=None, publish=False) This method will save your Story Map to your active GIS. The story will be saved with unpublished changes unless publish parameter is specified to True.
The title only needs to be specified if a change is wanted, otherwise exisiting title is used.
Warning
Publishing your story through the Python API means it will not go through the Story Map issue checker. It is recommended to publish through the Story Maps builder if you want your story to go through the issue checker.
Warning
Changes to the published story may not be visible for up to one hour. You can open the story in the story builder to force changes to appear immediately and perform other optimizations, such as updating the story’s social/SEO metadata.
Parameter
Description
title
Optional string. The title of the StoryMap.
tags
Optional string. The tags of the StoryMap.
access
Optional string. The access of the StoryMap. If none is specified, the current access is kept. This is used when publish parameter is set to True.
Values: private | org | public
publish
Optional boolean. If True, the story is saved and also published. Default is false so story is saved with unpublished changes.
- Returns
The Item that was saved to your active GIS.
-
show
(width=None, height=None) Show a preview of the collection. The default is a width of 700 and height of 300.
Parameter
Description
width
Optional integer. The desired width to show the preview.
height
Optional integer. The desired height to show the preview.
- Returns
An Iframe display of the collection if possible, else the item url is returned to be clicked on.
-
theme
(theme=<Themes.SUMMIT: 'summit'>) Each collection has a theme node in its resources. This method can be used to change the theme. To add a custom theme to your story, pass in the item_id for the item of type Story Map Theme.
Parameter
Description
theme
Required Themes Style or custom theme item id. The theme to set on the collection.
Values: SUMMIT | TIDAL | MESA | RIDGELINE | SLATE | OBSIDIAN | <item_id>
>>> from arcgis.apps.storymap import Themes, Collection >>> collection = Collection() >>> collection.theme(Themes.TIDAL)
-
Enumerations
Language
Scales
-
class
arcgis.apps.storymap.story_content.
Scales
(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None) Bases:
enum.Enum
Scale is a unit-less way of describing how any distance on the map translates to a real-world distance. For example, a map at a 1:24,000 scale communicates that 1 unit on the screen represents 24,000 of the same unit in the real world. So one inch on the screen represents 24,000 inches in the real world.
This can be used for methods involving viewpoint in the Map Content.
TextStyles
SlideLayout
SlideSubLayout
-
class
arcgis.apps.storymap.story_content.
SlideSubLayout
(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None) Bases:
enum.Enum
Depicts the various subtypes for a BriefingSlide. For example, if the layout type is DOUBLE then the sublayout type can be THREE_SEVEN or SEVEN_THREE or ONE_ONE.