Create new content for Apps Structure topic (#1111)

* Update Apps Structure Manifest topic; Update styles to not break words in links of table cells; Fix trailing space when newtabref shortcode is rendered * Update existing content in Apps Structure topic; Fix missing CSS styles for h4, h5, and h6 headings; Modify CSS to not break words used in links in a table cell * Add support for Compass Icons; Move FontAwesome files from fonts directory to font directory since compass-icons.css expects its files there; Update Apps structure main topic, manifest, and calls topics; Moved call metadata (expand) to its own topic * Add image to Apps Structure topic homepage which illustrates call handlers binding to locations * More improvements to App Calls topic * Remove unimplemented or unsupported struct fields; Improve context example * Pull compass icons assets once and commit instead of pulling with each build; Update Makefile dist target to not pull compass icons; Update Structure topic homepage diagram with simplified version; Update Call metadata topic * Start updating Bindings sub topic * Further updates to Bindings, call, and call metadata topics; Update CSS styles to not word-break monospaced text in a table cell * Finish up changes to Bindings topic; Use star icon as the symbol to denote extra information instead of a different symbol for each case * Improve support for collapsable blocks using existing Bootstrap components and Compass icons; Update collapsable blocks in bindings topic * Add content in Static assets topic * Apply suggestions from code review Co-authored-by: Carrie Warner (Mattermost) <[email protected]> * Apply suggestions from code review Co-authored-by: Carrie Warner (Mattermost) <[email protected]> * Changes based on PR feedback * Apply suggestions from code review Co-authored-by: Carrie Warner (Mattermost) <[email protected]> * Update site/content/integrate/apps/functionality/_index.md Co-authored-by: Carrie Warner (Mattermost) <[email protected]> * Modify collapse, compass-icon, newtabref, and note shortcodes to use alt text and screen reader support for all icons; Add alt text and screen reader support for icons in the Structure section * Update description of Bindings * Apply suggestions from code review Co-authored-by: Lev <[email protected]> * Apply suggestions from code review Co-authored-by: Lev <[email protected]> * Apply changes from PR reviews Co-authored-by: Carrie Warner (Mattermost) <[email protected]> Co-authored-by: Andrew Zigler <[email protected]> Co-authored-by: Lev <[email protected]>
mattermost · Oct 12, 2022 · bcbdd3e · bcbdd3e
1 parent 552d6b5
commit bcbdd3e
Show file tree

Hide file tree

Showing 31 changed files with 1,139 additions and 376 deletions.
diff --git a/Makefile b/Makefile
@@ -27,3 +27,10 @@ run:
 build:
 	rm -rf ./dist
 	hugo -s site --verbose --destination ../dist/html --printUnusedTemplates --printPathWarnings --gc
+
+.PHONY: compass-icons
+compass-icons:
+	mkdir -p site/static/css
+	mkdir -p site/static/font
+	curl --no-progress-meter -o site/static/css/compass-icons.css https://mattermost.github.io/compass-icons/css/compass-icons.css
+	curl --no-progress-meter -o "site/static/font/compass-icons.#1" "https://mattermost.github.io/compass-icons/font/compass-icons.{eot,woff2,woff,ttf,svg}"
diff --git a/site/config.toml b/site/config.toml
@@ -19,6 +19,13 @@ pygmentsStyle = "manni"
   email = ""
   ghrepo = "https://github.com/mattermost/mattermost-developer-documentation/"
 
+  # Parameters controlling collapsable blocks
+  [params.collapse]
+    collapsedIcon = "icon-chevron-right"  # Icon to show when the block is collapsed
+    expandedIcon = "icon-chevron-down"    # Icon to show when the block is expanded
+    collapseShowClass = "show"            # CSS class to add when expanding the block
+    toggleClass = "collapseToggle"        # CSS class to control icon attributes (e.g. size)
+
   [params.mailinglist]
     enable = false
 

diff --git a/site/content/integrate/apps/functionality/_index.md b/site/content/integrate/apps/functionality/_index.md
@@ -3,6 +3,16 @@ title: Functionality
 description: Apps API functionality
 weight: 60
 ---
+In addition to the {{<newtabref title="Mattermost REST APIs" href="https://api.mattermost.com">}}, the Apps framework provides additional functionality:
 
-### Coming soon!
-In the future this section will explore additional functionality that Apps provide. For example, event subscriptions.
+- [KV Store]({{< ref "kv-store" >}}) - a simple key-value store for App-specific data.
+
+- [OAuth2 Store]({{< ref "mattermost-api#apps-api" >}}) - store, expand, and retrieve user and App OAuth2 configuration data.
+
+- [Calling other Apps]({{< ref "mattermost-api#apps-api" >}}) - use the Call API to invoke other Apps (experimental).
+
+- [Subscriptions]({{< ref "subscriptions" >}}) learn how to subscribe to notifications about Mattermost events. For example: have your App notified whenever a message is posted in a channel that mentions your @bot account.
+
+- [External webhooks]({{< ref "external-webhooks" >}}) learn how to subscribe to webhooks from third-party systems.
+
+See [Authenticating with Mattermost]({{< ref "/integrate/apps/authentication/app-to-mattermost" >}}) to learn how to authenticate to all these services.
diff --git a/site/content/integrate/apps/structure/_index.md b/site/content/integrate/apps/structure/_index.md
@@ -9,54 +9,14 @@ aliases:
 
 Apps consist of three kinds of assets:
 
-- [manifest.json]({{< ref "manifest" >}}) file
+1. A [manifest]({{< ref "manifest" >}}), which contains App details such as name, version, requested permissions, and deployment methods.
 
-- [Call]({{< ref "call" >}}) handlers, starting with `/bindings` (see
-  [Bindings]({{< ref "bindings" >}})) and `/on_install` (see
-  [Manifest]({{< ref "manifest" >}})). Call handlers are typically source files
-  in a programming language like JavaScript, Python, or Go.
+2. [Call]({{< ref "call" >}}) handlers, which are functions that handle incoming requests from the Mattermost server.
 
-- Static assets, currently solely icon files
+3. [Static assets]({{<ref "static-assets">}}), such as images.
 
-## Interactivity: Bindings and forms
+To interact with users, an App must [bind]({{< ref "bindings" >}}) a call handler to a [location]({{<ref "manifest#locations">}}) in the Mattermost user interface. These locations may be slash commands, toolbar and menu items, or embedded in posts.
 
-- To interact with users an App must [bind]({{< ref "bindings" >}}) a call to a
-  location in the Mattermost user interface. These locations may be
-  `/`-commands, toolbar and menu items, and embedded in posts.
+![image](apps-calls_bindings_locations_v2.svg)
 
-- A [binding]({{< ref "bindings" >}}) may display a [Form]({{< ref
-  "interactivity" >}}), or it may invoke a `Call` that will return a `Form`.
-  Forms allow to gather fields with limited dynamic behavior
-  (dynamically-populated selects, form refresh on field changes). A Form invokes
-  a `Call` when it is submitted. A `/`-command is just another way of filling
-  out a `Form` and submitting it.
-
-## Use Mattermost APIs
-
-Apps can use all general [Mattermost REST API]({{< ref "mattermost-api" >}})s,
-as well as special services that are provided to the apps.
-
-See [Authenticating with Mattermost]({{< ref "app-to-mattermost" >}}) for how
-to authenticate to all these services.
-
-App services:
-
-- [KV Store]({{< ref "mattermost-api#apps-api" >}}) - store and retrive app-specific data.
-
-- [OAuth2 Store]({{< ref "mattermost-api#apps-api" >}}) - store, expand, and retrieve user and
-  app OAuth2 configuration data.
-
-- [Calling other Apps]({{< ref "mattermost-api#apps-api" >}}) - use the `Call` API to invoke
-  other apps (experimental).
-
-## Other
-
-- [Subscriptions]({{< ref "subscriptions" >}}) covers how to subscribe to
-  notifications abdout Mattermost events. Examples of a subscription include having your App notified whenever a message is posted in a channel that mentions your @bot account.
-
-- [External webhooks]({{< ref "/integrate/apps/functionality/external-webhooks" >}}) covers subscribing to
-  webhooks from third-party systems.
-
-- [Lifecycle]({{< ref "lifecycle" >}}) covers lifecycle callback API, i. e.
-  `on_install`. This is useful for calling your app when it is first installed, or the user is attempting to uninstall it and gives you a chance to initialize or clean up data (such as from the KV store) before uninstalling your app.
-
+A [Binding]({{< ref "bindings" >}}) may display a [Form]({{< ref "interactivity" >}}), or it may invoke a call that will return a form. Forms allow the user to input information with limited dynamic behavior, such as dynamically-populated pick lists, or form refreshes on field changes.