feat: allow customization of external URLs

Create the getExternalLinkUrl function and make it available for
use in frontend apps. It checks for a `customExternalUrls` object
in the config to see if a custom URL has been provided for a given
URL.

Use getExternalLinkUrl in the example app for this package. One
link is overridden with a custom URL while the other is not.

Author: Taylor Payne

env.config.js

@@ -3,6 +3,9 @@
 // Also note that in an actual application this file would be added to .gitignore.
 const config = {
   JS_FILE_VAR: 'JS_FILE_VAR_VALUE_FOR_EXAMPLE_APP',
+  externalLinkUrlOverrides: {
+    "https://github.com/openedx/docs.openedx.org/": "https://docs.openedx.org/",
+  }
 };
 
 export default config;

example/ExamplePage.jsx

@@ -5,7 +5,9 @@ import { Link } from 'react-router-dom';
 import { injectIntl, useIntl } from '@edx/frontend-platform/i18n';
 import { logInfo } from '@edx/frontend-platform/logging';
 import { AppContext } from '@edx/frontend-platform/react';
-import { ensureConfig, mergeConfig, getConfig } from '@edx/frontend-platform';
+import {
+  ensureConfig, mergeConfig, getConfig, getExternalLinkUrl,
+} from '@edx/frontend-platform';
 /* eslint-enable import/no-extraneous-dependencies */
 import messages from './messages';
 
@@ -49,6 +51,8 @@ function ExamplePage() {
       <AuthenticatedUser />
       <p>EXAMPLE_VAR env var came through: <strong>{getConfig().EXAMPLE_VAR}</strong></p>
       <p>JS_FILE_VAR var came through: <strong>{getConfig().JS_FILE_VAR}</strong></p>
+      <p>External link to <a href={getExternalLinkUrl('https://github.com/openedx/docs.openedx.org/')}>Open edX docs</a> (customized link).</p>
+      <p>External link to <a href={getExternalLinkUrl('https://open-edx-proposals.readthedocs.io/en/latest/')}>Open edX OEPs</a> (non-customized link).</p>
       <p>Visit <Link to="/authenticated">authenticated page</Link>.</p>
       <p>Visit <Link to="/error_example">error page</Link>.</p>
     </div>

src/config.js

@@ -307,6 +307,34 @@ export function ensureConfig(keys, requester = 'unspecified application code') {
   });
 }
 
+/**
+ * Get an external link URL based on the URL provided. If the passed in URL is overriden in the
+ * `externalLinkUrlOverrides` object, it will return the overridden URL. Otherwise, it will return
+ * the provided URL.
+ *
+ *
+ * @param {string} url - The default URL.
+ * @returns {string} - The external link URL. Defaults to the input URL if not found in the
+ * `externalLinkUrlOverrides` object. If the input URL is invalid, '#' is returned.
+ *
+ * @example
+ * import { getExternalLinkUrl } from '@edx/frontend-platform';
+ *
+ * <Hyperlink
+ *   destination={getExternalLinkUrl(data.helpLink)}
+ *   target="_blank"
+ * >
+ */
+export function getExternalLinkUrl(url) {
+  // Guard against non-strings or whitespace-only strings
+  if (typeof url !== 'string' || !url.trim()) {
+    return '#';
+  }
+
+  const overriddenLinkUrls = getConfig().externalLinkUrlOverrides || {};
+  return overriddenLinkUrls[url] || url;
+}
+
 /**
  * An object describing the current application configuration.
  *

src/index.js

@@ -37,6 +37,7 @@ export {
   setConfig,
   mergeConfig,
   ensureConfig,
+  getExternalLinkUrl,
 } from './config';
 export {
   initializeMockApp,