From 465fac71be3858fbf5bf09ba5098ed49a846d099 Mon Sep 17 00:00:00 2001
From: nik <Nikolay.Chashnikov@jetbrains.com>
Date: Wed, 6 Sep 2017 15:43:25 +0200
Subject: [PATCH] platform: allow providing custom web help for plugins
 (IDEA-177906)

---
 .../openapi/help/WebHelpProvider.java         | 54 +++++++++++++++++++
 .../intellij/help/impl/HelpManagerImpl.java   | 14 +++++
 .../src/META-INF/PlatformExtensionPoints.xml  |  2 +
 3 files changed, 70 insertions(+)
 create mode 100644 platform/platform-api/src/com/intellij/openapi/help/WebHelpProvider.java

diff --git a/platform/platform-api/src/com/intellij/openapi/help/WebHelpProvider.java b/platform/platform-api/src/com/intellij/openapi/help/WebHelpProvider.java
new file mode 100644
index 000000000000..1ca5a5abbff6
--- /dev/null
+++ b/platform/platform-api/src/com/intellij/openapi/help/WebHelpProvider.java
@@ -0,0 +1,54 @@
+/*
+ * Copyright 2000-2017 JetBrains s.r.o.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.intellij.openapi.help;
+
+import com.intellij.openapi.extensions.PluginAware;
+import com.intellij.openapi.extensions.PluginDescriptor;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+/**
+ * Override this class and register the implementation in {@code plugin.xml} to provide custom context web help for your plugin:
+ * <pre>
+ * &lt;extensions defaultExtensionNs="com.intellij"&gt;
+ * &nbsp;&nbsp;&lt;webHelpProvider implementation="qualified-class-name"/&gt;
+ * &lt;/extensions&gt;
+ * </pre>
+ * After that {@link #getHelpPageUrl(String)} method will be used to show help for topics which IDs start with '&lt;plugin ID&gt;.'.
+ *
+ * @author nik
+ */
+public abstract class WebHelpProvider implements PluginAware {
+  private String myHelpTopicPrefix;
+
+  /**
+   * Return URL of page which should be opened in browser when context help for {@code helpTopicId} is invoked. The method will be called
+   * only if {@code helpTopicId} starts with '&lt;plugin ID&gt;.' prefix.
+   * @param helpTopicId full ID of help topic including '&lt;plugin ID&gt;.' prefix
+   */
+  @Nullable
+  public abstract String getHelpPageUrl(@NotNull String helpTopicId);
+
+  @Override
+  public final void setPluginDescriptor(PluginDescriptor pluginDescriptor) {
+    myHelpTopicPrefix = pluginDescriptor.getPluginId().getIdString() + ".";
+  }
+
+  @NotNull
+  public String getHelpTopicPrefix() {
+    return myHelpTopicPrefix;
+  }
+}
diff --git a/platform/platform-impl/src/com/intellij/help/impl/HelpManagerImpl.java b/platform/platform-impl/src/com/intellij/help/impl/HelpManagerImpl.java
index eb55a0c97ea3..8b5995b50fab 100644
--- a/platform/platform-impl/src/com/intellij/help/impl/HelpManagerImpl.java
+++ b/platform/platform-impl/src/com/intellij/help/impl/HelpManagerImpl.java
@@ -25,7 +25,9 @@ import com.intellij.internal.statistic.UsageTrigger;
 import com.intellij.openapi.application.ApplicationInfo;
 import com.intellij.openapi.application.ex.ApplicationInfoEx;
 import com.intellij.openapi.diagnostic.Logger;
+import com.intellij.openapi.extensions.ExtensionPointName;
 import com.intellij.openapi.help.HelpManager;
+import com.intellij.openapi.help.WebHelpProvider;
 import com.intellij.openapi.ui.Messages;
 import com.intellij.openapi.util.text.StringUtil;
 import com.intellij.reference.SoftReference;
@@ -41,6 +43,8 @@ import java.net.URL;
 
 public class HelpManagerImpl extends HelpManager {
   private static final Logger LOG = Logger.getInstance("#com.intellij.help.impl.HelpManagerImpl");
+  private static final ExtensionPointName<WebHelpProvider>
+    WEB_HELP_PROVIDER_EP_NAME = ExtensionPointName.create("com.intellij.webHelpProvider");
 
   @NonNls private static final String HELP_HS = "Help.hs";
 
@@ -51,6 +55,16 @@ public class HelpManagerImpl extends HelpManager {
     
     UsageTrigger.trigger("ide.help." + id);
 
+    for (WebHelpProvider provider : WEB_HELP_PROVIDER_EP_NAME.getExtensions()) {
+      if (id.startsWith(provider.getHelpTopicPrefix())) {
+        String url = provider.getHelpPageUrl(id);
+        if (url != null) {
+          BrowserUtil.browse(url);
+          return;
+        }
+      }
+    }
+
     if (MacHelpUtil.isApplicable() && MacHelpUtil.invokeHelp(id)) {
       return;
     }
diff --git a/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml b/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml
index 6ca6f8ce55db..02fc04b6e278 100644
--- a/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml
+++ b/platform/platform-resources/src/META-INF/PlatformExtensionPoints.xml
@@ -287,6 +287,8 @@
     <extensionPoint name="projectNameProvider" interface="com.intellij.openapi.project.ex.ProjectNameProvider"/>
     <extensionPoint name="streamProviderFactory" interface="com.intellij.configurationStore.StreamProviderFactory" area="IDEA_PROJECT"/>
 
+    <extensionPoint name="webHelpProvider" interface="com.intellij.openapi.help.WebHelpProvider"/>
+
     <extensionPoint name="reporting.sendPermission" interface="com.intellij.reporting.DataSendPermission"/>
 
     <extensionPoint name="tasks.contextProvider" interface="com.intellij.tasks.context.WorkingContextProvider" area="IDEA_PROJECT"/>