Merge pull request #207120 from dlepow/dpcustom

[APIM] Custom widget scaffold/upload

Author: jborsecnik

.openpublishing.redirection.json

@@ -1,10 +1,15 @@
 {
 	"redirections": [
-		{
+{
     "source_path":  "articles/api-management/zone-redundancy.md",
     "redirect_url":  "/azure/availability-zones/migrate-api-mgt",
     "redirect_document_id":  false
 },
+{
+    "source_path":  "articles/api-management/developer-portal-implement-widgets.md",
+    "redirect_url":  "/azure/api-management/developer-portal-extend-custom-functionality",
+    "redirect_document_id":  false
+},
 {
     "source_path":  "articles/virtual-machines/linux/find-unattached-nics.md",
     "redirect_url":  "/previous-versions/azure/virtual-machines/linux/find-unattached-nics",

articles/api-management/TOC.yml

@@ -313,12 +313,18 @@
               items:
                   - name: Understand the developer portal
                     href: api-management-howto-developer-portal.md
-                  - name: Frequently asked questions
+                  - name: Frequently asked questions - developer portal
                     href: developer-portal-faq.md
                   - name: Automate portal deployments
                     href: automate-portal-deployments.md
                   - name: Migrate from deprecated to new developer portal
                     href: developer-portal-deprecated-migration.md
+                  - name: Extend portal with custom functionality
+                    href: developer-portal-extend-custom-functionality.md
+                  - name: Contribute widgets
+                    href: developer-portal-widget-contribution-guidelines.md
+                  - name: Use community widgets
+                    href: developer-portal-use-community-widgets.md
                   - name: Enable console OAuth support
                     href: api-management-howto-oauth2.md
                   - name: Integrate Application Insights
@@ -331,12 +337,6 @@
                   href: developer-portal-self-host.md
                 - name: Alternative approaches to self-hosting
                   href: developer-portal-alternative-processes-self-host.md
-                - name: Implement widgets
-                  href: developer-portal-implement-widgets.md
-                - name: Contribute widgets
-                  href: developer-portal-widget-contribution-guidelines.md
-                - name: Use community widgets
-                  href: developer-portal-use-community-widgets.md
                 - name: Test self-hosted portal
                   href: developer-portal-testing.md
             - name: Export APIs to the Power Platform

articles/api-management/api-management-howto-developer-portal-customize.md

@@ -205,3 +205,4 @@ Learn more about the developer portal:
 
 - [Azure API Management developer portal overview](api-management-howto-developer-portal.md)
 - [Migrate to the new developer portal](developer-portal-deprecated-migration.md) from the deprecated legacy portal.
+- Learn more about [customizing and extending](developer-portal-extend-custom-functionality.md) the functionality of the developer portal.

articles/api-management/api-management-howto-developer-portal.md

@@ -34,36 +34,32 @@ Migration to the new developer portal is described in the [dedicated documentati
 
 Your API Management service includes a built-in, always up-to-date, **managed** developer portal. You can access it from the Azure portal interface.
 
-Customize and style the managed portal through the built-in, drag-and-drop visual editor: 
+[Customize and style](api-management-howto-developer-portal-customize.md) the managed portal through the built-in, drag-and-drop visual editor: 
 
 * Use the visual editor to modify pages, media, layouts, menus, styles, or website settings. 
 
 * Take advantage of built-in widgets to add text, images, buttons, and other objects that the portal supports out-of-the-box. 
 
-* [Add custom HTML](developer-portal-faq.md#how-do-i-add-custom-html-to-my-developer-portal) - for example, add HTML for a form or to embed a video player. The custom code is rendered in an inline frame (iframe).
-
-See [this tutorial](api-management-howto-developer-portal-customize.md) for example customizations.
-
 > [!NOTE]
 > The managed developer portal receives and applies updates automatically. Changes that you've saved but not published to the developer portal remain in that state during an update.
 
-## <a name="managed-vs-self-hosted"></a> Extensibility
-
-In some cases you might need functionality beyond the customization and styling options supported in the managed developer portal.  If you need to implement custom logic, which isn't supported out-of-the-box, you can modify the portal's codebase, available on [GitHub](https://github.com/Azure/api-management-developer-portal). For example, you could create a new widget to integrate with a third-party support system. When you implement new functionality, you can choose one of the following options:
-
-- **Self-host** the resulting portal outside of your API Management service. When you self-host the portal, you become its maintainer and you are responsible for its upgrades. Azure Support's assistance is limited only to the [basic setup of self-hosted portals](developer-portal-self-host.md).
-- Open a pull request for the API Management team to merge new functionality to the **managed** portal's codebase.
-
-For extensibility details and instructions, refer to the [GitHub repository](https://github.com/Azure/api-management-developer-portal) and the tutorial to [implement a widget](developer-portal-implement-widgets.md). The tutorial to [customize the managed portal](api-management-howto-developer-portal-customize.md) walks you through the portal's administrative panel, which is common for **managed** and **self-hosted** versions.
+## <a name="managed-vs-self-hosted"></a> Options to extend portal functionality
+In some cases you might need functionality beyond the customization and styling options provided in the managed developer portal. If you need to implement custom logic, which isn't supported out-of-the-box, you have [several options](developer-portal-extend-custom-functionality.md):
+* [Add custom HTML](developer-portal-extend-custom-functionality.md#use-custom-html-code-widget) directly through a developer portal widget designed for small customizations - for example, add HTML for a form or to embed a video player. The custom code is rendered in an inline frame (iframe).
+* [Create and upload a custom widget](developer-portal-extend-custom-functionality.md#create-and-upload-custom-widget) to develop and add more complex custom portal features.
+* [Self-host the portal](developer-portal-self-host.md), only if you need to make modifications to the core of the developer portal [codebase](https://github.com/Azure/api-management-developer-portal). This option requires advanced configuration. Azure Support's assistance is limited only to the basic setup of self-hosted portals.
 
+> [!NOTE]
+> Because the API Management developer portal codebase is maintained on [GitHub](https://github.com/Azure/api-management-developer-portal), you can open issues and make pull requests for the API Management team to merge new functionality at any time.
+>
 
 ## Next steps
 
 Learn more about the developer portal:
 
 - [Access and customize the managed developer portal](api-management-howto-developer-portal-customize.md)
+- [Extend functionality of the managed developer portal](developer-portal-extend-custom-functionality.md)
 - [Set up self-hosted version of the portal](developer-portal-self-host.md)
-- [Implement your own widget](developer-portal-implement-widgets.md)
 
 Browse other resources: