Merge pull request #187124 from dlepow/devportal

[APIM] Developer portal HTML injection

Author: jborsecnik

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

@@ -175,7 +175,7 @@ To make your portal and its latest changes available to visitors, you need to *p
 ### Publish from the administrative interface
 
 1. Make sure you saved your changes by selecting the **Save** icon.
-1. In the **Operations** section of the menu, select **Publish website** . This operation may take a few minutes.  
+1. In the **Operations** section of the menu, select **Publish website**. This operation may take a few minutes.  
 
     :::image type="content" source="media/api-management-howto-developer-portal-customize/publish-portal.png" alt-text="Publish portal" border="false":::
 

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

@@ -8,7 +8,7 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: article
-ms.date: 04/15/2021
+ms.date: 02/02/2022
 ms.author: danlep 
 ms.custom: devx-track-azurepowershell
 ---
@@ -30,15 +30,23 @@ As introduced in this article, you can customize and extend the developer portal
 
 Migration to the new developer portal is described in the [dedicated documentation article](developer-portal-deprecated-migration.md).
 
-## Customization and styling
+## Customization and styling of the managed portal
 
-The developer portal can be customized and styled through the built-in, drag-and-drop visual editor. See [this tutorial](api-management-howto-developer-portal-customize.md) for more details.
+Your API Management service includes a built-in, always up-to-date, **managed** developer portal. You can access it from the Azure portal interface.
 
-## <a name="managed-vs-self-hosted"></a> Extensibility
+Customize and style the managed portal through the built-in, drag-and-drop visual editor: 
 
-Your API Management service includes a built-in, always up-to-date, **managed** developer portal. You can access it from the Azure portal interface.
+* 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.
+
+## <a name="managed-vs-self-hosted"></a> Extensibility
 
-If you need to extend it with custom logic, which isn't supported out-of-the-box, you can modify its codebase. The portal's codebase is [available in a GitHub repository](https://github.com/Azure/api-management-developer-portal). For example, you could implement a new widget, which integrates with a third-party support system. When you implement new functionality, you can choose one of the following options:
+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.
@@ -48,7 +56,7 @@ For extensibility details and instructions, refer to the [GitHub repository](htt
 
 ## Next steps
 
-Learn more about the new developer portal:
+Learn more about the developer portal:
 
 - [Access and customize the managed developer portal](api-management-howto-developer-portal-customize.md)
 - [Set up self-hosted version of the portal](developer-portal-self-host.md)

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

@@ -8,7 +8,7 @@ author: dlepow
 
 ms.service: api-management
 ms.topic: troubleshooting
-ms.date: 07/30/2021
+ms.date: 02/04/2022
 ms.author: danlep 
 ms.custom: devx-track-azurepowershell
 ---
@@ -17,8 +17,15 @@ ms.custom: devx-track-azurepowershell
 
 ## What if I need functionality that isn't supported in the portal?
 
-You can open a feature request in the [GitHub repository](https://github.com/Azure/api-management-developer-portal) or [implement the missing functionality yourself](developer-portal-implement-widgets.md). Learn more about developer portal [extensibility](api-management-howto-developer-portal.md#managed-vs-self-hosted).
+You have the following options:
 
+* For certain situations, you can [add custom HTML](#how-do-i-add-custom-html-to-my-developer-portal) to add functionality to the portal.
+
+* Open a feature request in the [GitHub repository](https://github.com/Azure/api-management-developer-portal).
+
+* [Implement the missing functionality yourself](developer-portal-implement-widgets.md). 
+
+Learn more about developer portal [extensibility](api-management-howto-developer-portal.md#managed-vs-self-hosted).
 
 ## Can I have multiple developer portals in one API Management service?
 
@@ -68,7 +75,7 @@ You can check the status of the CORS policy in the **Portal overview** section o
 
 ![Screenshot that shows where you can check the status of your CORS policy.](media/developer-portal-faq/cors-azure-portal.png)
 
-Automatically apply the CORS policy by clicking on the **Enable CORS** button.
+Automatically apply the CORS policy by clicking the **Enable CORS** button.
 
 You can also enable CORS manually.
 
@@ -127,7 +134,7 @@ This error is shown when a `GET` call to `https://<management-endpoint-hostname>
 
 If your API Management service is in a VNet, refer to the [VNet connectivity question](#do-i-need-to-enable-additional-vnet-connectivity-for-the-managed-portal-dependencies).
 
-The call failure may also be caused by an TLS/SSL certificate, which is assigned to a custom domain and is not trusted by the browser. As a mitigation, you can remove the management endpoint custom domain API Management will fall back to the default endpoint with a trusted certificate.
+The call failure may also be caused by an TLS/SSL certificate, which is assigned to a custom domain and is not trusted by the browser. As a mitigation, you can remove the management endpoint custom domain. API Management will fall back to the default endpoint with a trusted certificate.
 
 ## What's the browser support for the portal?
 
@@ -189,10 +196,32 @@ You can generate *user-specific tokens* (including admin tokens) using the [Get
 > [!NOTE]
 > The token must be URL-encoded.
 
+## How do I add custom HTML to my developer portal?
+
+The managed developer portal includes a **Custom HTML code** widget that enables you to insert HTML code for small portal customizations. For example, use custom HTML to embed a video or to add a form. The portal renders the custom widget in an inline frame (iframe). 
+  
+1. In the administrative interface for the developer portal, go to the page or section where you want to insert the widget. 
+1. Select the grey "plus" (**+**) icon that appears when you hover the pointer over the page.
+1. In the **Add widget** window, select **Custom HTML code**.
+    
+    :::image type="content" source="media/developer-portal-faq/add-custom-html-code-widget.png" alt-text="Add widget for custom HTML code":::
+1. Select the "pencil" icon to customize the widget.
+1. Enter a **Width** and **Height** (in pixels) for the widget.
+1. To inherit styles from the developer portal (recommended), select **Apply developer portal styling**.
+    > [!NOTE]
+    > If this setting isn't selected, the embedded elements will be plain HTML controls, without the styles of the developer portal.
+   
+    :::image type="content" source="media/developer-portal-faq/configure-html-custom-code.png" alt-text="Configure HTML custom code":::
+1. Replace the sample **HTML code** with your custom content.
+1. When configuration is complete, close the window.
+1. Save your changes, and [republish the portal](api-management-howto-developer-portal-customize.md#publish).
+
+> [!NOTE]
+> Microsoft does not support the HTML code you add in the Custom HTML Code widget.
 
 ## Next steps
 
-Learn more about the new developer portal:
+Learn more about the developer portal:
 
 - [Access and customize the managed developer portal](api-management-howto-developer-portal-customize.md)
 - [Set up self-hosted version of the portal](developer-portal-self-host.md)