How to properly configure my tool's Help URL

mkhtran

I can't find any documentation on the `ayx_workspace.json` file. I'm trying to figure out how the `tools > [tool_name] > configuration > help_url` configuration works. As far as I know, it's a plain string that determines what happens when the Help button is pressed.

• If `help_url` is a URL like `http://example.com`, Designer will open the URL
• If `help_url` is a local file like `C:/path/to/file`, Designer will open the file
• For anything else like `foo/bar`, Designer will open it as a URL with `https://help.alteryx.com/current/` as the base URL
  • This seems to be the same behavior as `JsEvent('OpenHelpPage', { url: help_url })`

But I would really like for my tool to have a behavior similar to the built in tools.

1. React to the user's Interface Language configuration.

I would like to be able to set the URL to something like

• http://example.com/help/[locale]/mytool.html

2. React to the user's Help > Source configuration.

For whatever reason, when Help > Source is set to "Offline", Designer bypasses all of the previous `help_url` resolution and attempts to open

• file:///C:/Program%20Files/Alteryx/bin/RuntimeData/HtmlAssets/help.alteryx.com/AlteryxCurrent/en/[help_url]

This happens even if `help_url` is already a local file.

mkhtran

I've finally found some information on exactly how the Help URL configuration works. The following comments were found in `C:\Program Files\Alteryx\bin\HtmlPlugins\JavascriptPluginExampleV2\JavascriptPluginExampleV2Config.xml.rename`:

<!-- Except for help, all paths are relative to this config file.  The variables [Engine.EngineDirectory], [Engine.PluginDirectory] and [Engine.JavaScriptPluginDirectory] can also be used. -->

<!-- There are five valid settings for the Help attribute of the GuiSettings tag. -->
<!-- No Help attribute, or empty quotes, will take the user to the Alteryx web help index. This is the default behavior. -->
<!-- A valid HTTP URL including http:// or https:// protocol will open the default browser to that URL. -->
<!-- A filename of the form file://path/FileName.html will load the specified file from this plugin's directory. -->
<!-- A filename of the form file://C:/path/FileName.html will load the specified file from an absolute path. -->
<!-- An HTML filename without a preceding path or protocol indicator will load that HTML file in the Alteryx web help. -->

The important part is that `file://path/FileName.html` will open a file relative to this config file. This gives us a way to package a local help file with the plugin and reliably open it.

1. Set the Help URL configuration to `file://help.html`.

2. Create the plugin's .yxi installer. Note that a .yxi is simply a .zip file with a certain structure.

3. Add your help file to the .yxi. For example, (a) rename the .yxi to .zip, (b) add a `help.html` file to `[ToolName]/help.html` inside the .zip archive, and (c) rename the .zip back to .yxi.

This still does not support locales or offline mode. It is assumed that Alteryx has no support for this.