From bf0c730f53a8e2692eed6991f5a04351b62eb820 Mon Sep 17 00:00:00 2001 From: Manushi Majumdar Date: Fri, 23 Jan 2026 18:43:56 -0500 Subject: [PATCH] intro to briefings guide 3/4 --- .../storymap-briefings.ipynb | 858 ++++++++++++++++++ 1 file changed, 858 insertions(+) create mode 100644 guide/13-managing-arcgis-applications/storymap-briefings.ipynb diff --git a/guide/13-managing-arcgis-applications/storymap-briefings.ipynb b/guide/13-managing-arcgis-applications/storymap-briefings.ipynb new file mode 100644 index 0000000000..9bdb511a8c --- /dev/null +++ b/guide/13-managing-arcgis-applications/storymap-briefings.ipynb @@ -0,0 +1,858 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "d6a9d27e-eb8d-48e8-85ca-e0a16ce0c224", + "metadata": {}, + "source": [ + "## Introduction to Briefings (ArcGIS StoryMaps)\n", + "\n", + "Using the ArcGIS API for Python you can build Briefings in ArcGIS StoryMaps. Briefings offer a slide-based output ideal for delivering presentations that integrate maps and data from your organization. You can now create elegant and interactive slide-based presentations called briefings for succinct storytelling and offline sharing with ArcGIS StoryMaps. " + ] + }, + { + "cell_type": "code", + "execution_count": 25, + "id": "80ee349f-f60d-479e-a6ec-f2d6d72055e1", + "metadata": {}, + "outputs": [], + "source": [ + "from arcgis.gis import GIS\n", + "from arcgis.apps import storymap\n", + "from arcgis.apps.storymap import Briefing, Themes, Text, TextStyles, Image, BriefingSlide, SlideLayout, Map" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "1fd881a8-484b-4d72-a7d8-6e8cb5a427a7", + "metadata": {}, + "outputs": [], + "source": [ + "gis = GIS(profile='your_online_profile')" + ] + }, + { + "cell_type": "markdown", + "id": "508effbe-360c-4074-9a31-d7a6cadac2d0", + "metadata": {}, + "source": [ + "We will start by creating a `Briefing` and then updating the `Cover` and `Theme` for this Briefing. " + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "91b76e7c-9dff-4efe-8568-9a19259c74ac", + "metadata": {}, + "outputs": [], + "source": [ + "my_briefing = Briefing()" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "2b0c9b04-3519-492f-a793-0f4d6da7a6fd", + "metadata": {}, + "outputs": [], + "source": [ + "img = Image(\"https://www.nps.gov/npgallery/GetAsset/69680c29-caa3-42da-93d9-32925e9ed409/proxy/hires\")" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "id": "ccdd188c-e99a-48b8-9fb5-5a21639f66d1", + "metadata": {}, + "outputs": [], + "source": [ + "cover = my_briefing.slides[0].cover\n", + "cover.title = \"Nature Presentation\"\n", + "cover.summary = \"Briefing about nature created programmatically\"\n", + "cover.by_line = \"Nature Briefing\"\n", + "cover.media = img" + ] + }, + { + "cell_type": "code", + "execution_count": 10, + "id": "6217344d-c57b-4647-9b56-0b9f0f445ed4", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "True" + ] + }, + "execution_count": 10, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.theme(Themes.SLATE)" + ] + }, + { + "cell_type": "code", + "execution_count": 11, + "id": "e2f4ba54-445b-42a8-8552-41562301d13b", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "True" + ] + }, + "execution_count": 11, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.set_logo('D:/Github Projects/geosaurus/tests/resources/storymap/storymap_image_river.jpg')" + ] + }, + { + "cell_type": "markdown", + "id": "e536ae50-bbe2-4eef-a27d-f301932dc681", + "metadata": {}, + "source": [ + "We will now save this Briefing and verify these updates." + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "id": "98099b78-7d3f-4f87-ac03-07e76edbf5f4", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Nature themed Briefing slides\n", + " \n", + "

StoryMap by MMajumdar_geosaurus\n", + "
Last Modified: January 23, 2026\n", + "
0 comments, 0 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 13, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.save(title = \"Nature themed Briefing slides\")" + ] + }, + { + "cell_type": "markdown", + "id": "837f3c04-ddce-4663-912b-8e30c908e30c", + "metadata": {}, + "source": [ + "![cover](https://github.com/user-attachments/assets/1c80f060-285e-46a8-aee0-d82cc552f74b)\n", + "\n", + "We have successfully updated the Cover or opening slide of the Briefing. " + ] + }, + { + "cell_type": "markdown", + "id": "f37309ed-b92c-4a1e-86ea-6fbc2b62316a", + "metadata": {}, + "source": [ + "### Concept of slides and blocks\n", + "\n", + "Similar to traditional presentations with slides, `Briefing`s come with `BriefingSlide`s to add structured content to your Briefing.\n", + "\n", + "Each slide within has one or more blocks, and the number of blocks need to be specified during slide creation using the `num_blocks` parameter. A block represents a section that holds individual content elements. \n", + "\n", + "To learn more about ArcGIS StoryMaps content elements supported within the ArcGIS API for Python, please refer to the [Introduction to StoryMaps](../introduction-to-storymaps) guide.\n", + "\n", + "We start by creating three slides below." + ] + }, + { + "cell_type": "code", + "execution_count": 14, + "id": "a92538dd-7c88-4c77-a034-952ae5c49e2c", + "metadata": {}, + "outputs": [], + "source": [ + "new_slide = BriefingSlide(layout=SlideLayout.FLEXIBLE, num_blocks=1)\n", + "slide1 = my_briefing.add(slide=new_slide)" + ] + }, + { + "cell_type": "code", + "execution_count": 15, + "id": "62cfcb07-9566-42fc-a59f-c779d96460fb", + "metadata": {}, + "outputs": [], + "source": [ + "new_slide = BriefingSlide(layout=SlideLayout.FLEXIBLE, num_blocks=2)\n", + "slide2 = my_briefing.add(slide=new_slide)" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "id": "1f451cc0-5c03-4ccb-a2f0-50527963b9ac", + "metadata": {}, + "outputs": [], + "source": [ + "new_slide = BriefingSlide(layout=SlideLayout.SINGLE)\n", + "slide3 = my_briefing.add(slide=new_slide)" + ] + }, + { + "cell_type": "markdown", + "id": "17ad8a51-70e7-4b95-aba9-5192b0624d24", + "metadata": {}, + "source": [ + "### Adding text to a block in a slide\n", + "\n", + "Our first slide has one block. We will update it with a text summary of the contents of this `Briefing`." + ] + }, + { + "cell_type": "code", + "execution_count": 22, + "id": "3ae8aff5-b88c-4ab9-b426-b38a87371614", + "metadata": {}, + "outputs": [], + "source": [ + "block_1 = slide1.blocks[0]" + ] + }, + { + "cell_type": "code", + "execution_count": 26, + "id": "bc660ae4-0463-434f-95e3-0b59397706db", + "metadata": {}, + "outputs": [], + "source": [ + "quote = Text(\n", + " text=\"This Briefing will have images related to nature, and a map about the coverage of Forests in the US.\",\n", + " style=TextStyles.QUOTE,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 27, + "id": "104bb391-e384-4f7f-bf5e-46db064db402", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "Text(text=This Briefing will have images related to nature, and a map about the coverage of Forests in the US.)" + ] + }, + "execution_count": 27, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "block_1.add_content(quote)" + ] + }, + { + "cell_type": "code", + "execution_count": 28, + "id": "638807de-fda4-4067-8cdb-9dc0f86c4570", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Nature themed Briefing slides\n", + " \n", + "

StoryMap by MMajumdar_geosaurus\n", + "
Last Modified: January 23, 2026\n", + "
0 comments, 3 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 28, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.save()" + ] + }, + { + "cell_type": "markdown", + "id": "7be3828d-9f64-4398-b68b-4bc0b5022a20", + "metadata": {}, + "source": [ + "The first slide is successfully updated with text. \n", + "\n", + "![text](https://github.com/user-attachments/assets/9042ce80-e481-465f-b3b7-a5c8f0450555)" + ] + }, + { + "cell_type": "markdown", + "id": "3e5d6945-c33a-4895-91bf-955aab1407f4", + "metadata": {}, + "source": [ + "### Add images to blocks in a slide\n", + "\n", + "Our second slide has two blocks. Let's add images to each of those blocks. " + ] + }, + { + "cell_type": "code", + "execution_count": 18, + "id": "62602c2d-bd82-4121-890b-a3dfc8eea747", + "metadata": {}, + "outputs": [], + "source": [ + "block1 = slide2.blocks[0]\n", + "block2 = slide2.blocks[1]" + ] + }, + { + "cell_type": "code", + "execution_count": 19, + "id": "eaf69ddb-f632-45e0-8970-f56bdd3a82bf", + "metadata": {}, + "outputs": [], + "source": [ + "image1 = Image(\n", + " \"https://www.nps.gov/npgallery/GetAsset/36106ED0-1DD8-B71C-07ED73544EA246C7/proxy/hires\"\n", + ")\n", + "image2 = Image(\n", + " \"https://www.nps.gov/npgallery/GetAsset/0022D3FF-1DD8-B71B-0BE3AD4C48F96FF9/proxy/hires\"\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": 20, + "id": "0db4a47d-3479-44a7-97ad-ea252c93e8bd", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "Image(image='https://www.nps.gov/npgallery/GetAsset/0022D3FF-1DD8-B71B-0BE3AD4C48F96FF9/proxy/hires')" + ] + }, + "execution_count": 20, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "block1.add_content(image1)\n", + "block2.add_content(image2)" + ] + }, + { + "cell_type": "code", + "execution_count": 21, + "id": "49d8264b-0d49-4185-829f-1eef5123ec44", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Nature themed Briefing slides\n", + " \n", + "

StoryMap by MMajumdar_geosaurus\n", + "
Last Modified: January 23, 2026\n", + "
0 comments, 1 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 21, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.save()" + ] + }, + { + "cell_type": "markdown", + "id": "86b4a9b6-2c6f-4d94-ab24-315cb0a5c287", + "metadata": {}, + "source": [ + "Our briefing has now updated the two blocks with images.\n", + "\n", + "![image](https://github.com/user-attachments/assets/beda5a54-ffe5-4c78-8e07-12a7f510d807)" + ] + }, + { + "cell_type": "markdown", + "id": "db7ac1e2-7f4c-4c74-bb48-d909e6656c74", + "metadata": {}, + "source": [ + "### Adding a Map to a block in a slide\n", + "\n", + "We will now fetch a map item and add it to the third slide." + ] + }, + { + "cell_type": "code", + "execution_count": 32, + "id": "e2277d72-810d-4123-a3b9-69e03ad4fedd", + "metadata": {}, + "outputs": [], + "source": [ + "map1 = gis.content.get('dd3e4259b7434f1ebd488c09a8611ddf')\n", + "map1_for_storymap = storymap.Map(map1)" + ] + }, + { + "cell_type": "code", + "execution_count": 33, + "id": "5e79e925-bca9-4089-94a0-f3f99e3f2aac", + "metadata": {}, + "outputs": [], + "source": [ + "block_3 = slide3.blocks[0]" + ] + }, + { + "cell_type": "code", + "execution_count": 34, + "id": "6a09110a-b5dc-41fc-b168-f7d4e457af0a", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "Map(item='dd3e4259b7434f1ebd488c09a8611ddf', type='Web Map')" + ] + }, + "execution_count": 34, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "block_3.add_content(map1_for_storymap)" + ] + }, + { + "cell_type": "code", + "execution_count": 35, + "id": "6182f734-905b-4821-8ca8-33d4435eba6f", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Nature themed Briefing slides\n", + " \n", + "

StoryMap by MMajumdar_geosaurus\n", + "
Last Modified: January 23, 2026\n", + "
0 comments, 4 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 35, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.save()" + ] + }, + { + "cell_type": "markdown", + "id": "7a4c5970-0f88-4bad-bf14-c60a8001befa", + "metadata": {}, + "source": [ + "The slide now displays this map.\n", + "\n", + "![map_block](https://github.com/user-attachments/assets/91cdd96f-ca8a-4d43-ae9c-497ff579ad2b)" + ] + }, + { + "cell_type": "markdown", + "id": "80882be3-aa40-4e43-93ef-86083dab395b", + "metadata": {}, + "source": [ + "### Duplicate this briefing\n", + "\n", + "Similar to a `StoryMap`, you can also `duplicate()` a `Briefing`. \n", + "\n", + "Note: The `duplicate()` function will create a copy of the `Briefing` item alone. To copy the deep dependencies of the Briefing (e.g., maps, scenes, layer, tables), you will need to use the `clone_items()` function. Please refer to the [Cloning and Editing of StoryMaps](../cloning-editing-storymaps) guide to learn more about these differences. " + ] + }, + { + "cell_type": "code", + "execution_count": 36, + "id": "3e343595-89bd-45a3-bf2e-a4a9f96d85f9", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Copy of my Nature themed Briefing\n", + " \n", + "

StoryMap by MMajumdar_geosaurus\n", + "
Last Modified: January 23, 2026\n", + "
0 comments, 0 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 36, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "duplicate = my_briefing.duplicate(\"Copy of my Nature themed Briefing\")\n", + "duplicate" + ] + }, + { + "cell_type": "markdown", + "id": "834de06d-5e7f-45c7-b96c-e969c3419858", + "metadata": {}, + "source": [ + "### Move a slide to the end\n", + "\n", + "You can also [`move()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.apps.storymap.html#arcgis.apps.storymap.briefing.Briefing.move) or re-position slides in a Briefing. Let's see a few examples below. \n", + "\n", + "If no value is provided for the `position` parameter, it moves the slide to the end. \n", + "\n", + "Note: Cover slide (index 0) cannot be moved." + ] + }, + { + "cell_type": "code", + "execution_count": 37, + "id": "d45ea02c-0588-4cc4-9831-219b98ceb8e2", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "True" + ] + }, + "execution_count": 37, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.move(slide=2)" + ] + }, + { + "cell_type": "markdown", + "id": "87c72896-763d-4b35-ab32-cb9f35211fd0", + "metadata": {}, + "source": [ + "### Move a slide to the top" + ] + }, + { + "cell_type": "code", + "execution_count": 38, + "id": "1a2029ea-db78-4fa7-8e6a-6fe274dd9f24", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "True" + ] + }, + "execution_count": 38, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.move(slide=2, position=1)" + ] + }, + { + "cell_type": "code", + "execution_count": 39, + "id": "1df39d2a-eda2-4966-843d-501ce9c601a9", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Nature themed Briefing slides\n", + " \n", + "

StoryMap by MMajumdar_geosaurus\n", + "
Last Modified: January 23, 2026\n", + "
0 comments, 5 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 39, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.save()" + ] + }, + { + "cell_type": "markdown", + "id": "cda9fee9-ebec-4a45-900e-621b52925ae9", + "metadata": {}, + "source": [ + "### Copy updated content over to the duplicated Briefing" + ] + }, + { + "cell_type": "markdown", + "id": "45a09b27-9b12-4f33-98ff-2948c05e3329", + "metadata": {}, + "source": [ + "The ArcGIS API for Python also allows for copying selective sections of a Briefing over to another using the [`copy_content()`](https://developers.arcgis.com/python/latest/api-reference/arcgis.apps.storymap.html#arcgis.apps.storymap.briefing.Briefing.copy_content) method if you do not wish to clone all the content of a Briefing. \n", + "\n", + "This capability can be beneficial in a few cases. \n", + "1. You may already have another Briefing item in your organization with relevant slides and information that you need to add to your current Briefing, without cloning the entire Briefing.\n", + "2. You may have cloned an existing Briefing, updated it with a few more slides and would like to copy those over back to the original Briefing.\n", + "\n", + "We will explore the first use-case through an example below. \n", + "\n", + "Note: If you wish to copy all the slides of a Briefing, you need to ensure that you are not copying the `Cover` slide of one Briefing over to another. We can remove that slide by excluding its index, as shown below. " + ] + }, + { + "cell_type": "code", + "execution_count": 40, + "id": "11aa97b5-cfa0-4838-bcdc-c7f1fcff6030", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Sea Otter Habitat StoryMap Briefing\n", + " \n", + "

StoryMap by ssong_geosaurus\n", + "
Last Modified: July 16, 2024\n", + "
0 comments, 1 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "https://storymaps.arcgis.com/briefings/203ca5e1ffc141528cbdf7bced801274" + ] + }, + "execution_count": 40, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "source_briefing_item = gis.content.get('203ca5e1ffc141528cbdf7bced801274')\n", + "source_briefing = Briefing(source_briefing_item)\n", + "source_briefing" + ] + }, + { + "cell_type": "code", + "execution_count": 46, + "id": "95349085-9584-4a94-a993-cacc9183e7c4", + "metadata": {}, + "outputs": [], + "source": [ + "content = source_briefing.slides[1:]" + ] + }, + { + "cell_type": "code", + "execution_count": 42, + "id": "387dd074-6979-4688-bd00-3a7acf2da729", + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "True" + ] + }, + "execution_count": 42, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "source_briefing.copy_content(target_briefing = my_briefing, content = content)" + ] + }, + { + "cell_type": "markdown", + "id": "fdfad894-8b70-4466-a79e-c406101b9b20", + "metadata": {}, + "source": [ + "### Publish the Briefing\n", + "\n", + "We will now publish this Briefing by setting `publish=True` in the `save()` function." + ] + }, + { + "cell_type": "code", + "execution_count": 43, + "id": "4bc9b954-ee30-4b50-9f96-82257fbff4bc", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
\n", + "
\n", + " \n", + " \n", + " \n", + "
\n", + "\n", + "
\n", + " Nature themed Briefing slides\n", + " \n", + "

StoryMap by MMajumdar_geosaurus\n", + "
Last Modified: January 23, 2026\n", + "
0 comments, 5 views\n", + "
\n", + "
\n", + " " + ], + "text/plain": [ + "" + ] + }, + "execution_count": 43, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "my_briefing.save(publish=True)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.11" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}