App Module Configuration - NCIOCPL/clinical-trials-listing-app GitHub Wiki

Config sections

Setting up the config for a dynamic listing page requires two parts.

drupalConfig -- this is configuration for Drupal to know how to load the app.
frontEndConfig -- this is configuration for the app itself. This will be passed into the initialize method. (It will be combined with some other Drupal path information.)

Config format

Config Format

{
  "drupalConfig": {
     "appName": "your-apps-name-here",
     "rootId": "NCI-app-root",
     "initFnName": "window.appModuleInit",
     "appCssUri": "https://someserver/app-name/app-name.vX.Y.Z.css",
     "appJsUri": "https://someserver/app-name/app-name.vX.Y.Z.js",
     "removeHeadElements" : [
       ...
     ],
     "validAppPaths": [
       ".*"
     ]
  },
  "frontEndConfig": {
    ...This will be passed into the initialize function...
  }
}

Drupal config

The drupalConfig is made up of the following:

appName -- This is a unique ID for your app. (e.g. 'clinical-trials-listing-app-disease') try and make multiple instances of the app have a unique name please. NOTE: This must be appropriate for being the key of an array.
rootId -- This is the ID of the div tag for this instance, and what will get passed into the initialize function.
initFnName -- This is the full name of the init function, we assume the app's init function will be attached to the window, but please include that too.
pathToCss -- This is the full URL to the CSS file for the app. Make sure it has a version number, and never update that asset. (Or caching issues will occur)
pathToJs -- This is the full URL to the JS file for the app. Make sure it has a version number, and never update that asset. (Or caching issues will occur)
removeHeadElements -- The Drupal head elements your module will handle and should not be generated by Drupal lest Google get the wrong information. This list maps to keys in $attachments['#attached']['html_head'], except for alternate which will remove any <link rel="alternate"> elements. Use the key title_tag, for the <title> tag. NOTE: Old apps had added react-helmet attributes to meta tags so that the App/Helmet would not generate duplicate metatags, but at this point, just use removeHeadElements to prevent Drupal from generating them and then have your App/Helmet add them in normally.
validAppPaths -- This is a list of regular expressions that will ensure that your app has a route for that path. '/' is always allowed, so this is for any URL OTHER than '/'. If the requested path does not match, then a 404 is retured. The path is RELATIVE TO YOUR APP. So if the url of your app is /foo/bar and the route is /chicken/:someID, then enter "\\/chicken\\/.*". (NOTE: You need to escape backslashes in JSON)

We have created 3 directives for processing config variables to help support referencing Drupal things, or javascript variables. (The config is JSON which only allows strings, bools, ints, arrays, objects)

@@LITERAL@@ - This is a literal string, when the JS settings object is created, the double quotes will not be added. e.g "apiBase": "@@LITERAL@@window.CDEConfig.apiBase" becomes apiBase: window.CDEConfig.apiBase
@@NOENC_DIRECTIVE - Normally strings will be JSON encoded on output. This directs us to not encode the strings. Use this for URLS like pathToCss and pathToJs...
- Note: Under the hood the JSON you paste into the Drupal editor is converted into a PHP Array. That PHP Array is then JSON encoded for use on the web page, which is why this is needed... if you were wondering.
@@TOKEN@@ - Pass this string off to the token service's replace method. The token context will contain the node so you can do things like "title": "@@TOKEN@@[node:title] => title: "The node title".
- Note: if you really want to know what you can do, you should check out the Token service

Frontend config

The frontend config is made up of the following:

analyticsChannel -- This is the channel used for analytics values.
analyticsContentGroup -- This is the content group used for analytics values.
analyticsPublishedDate -- This is the published date used for analytics values.
cisBannerImgUrlLarge -- This is the full URL to the CIS Banner XL image file for the app. Make sure it has a fingerprint (usually the version number), and never update that asset. (Or caching issues will occur)
cisBannerImgUrlSmall -- This is the full URL to the CIS Banner Smartphone image file for the app. Make sure it has a fingerprint (usually the version number), and never update that asset. (Or caching issues will occur)
ctsApiHostname -- This is the hostname to be used in setting up the URL for requests made to the Clinical Trials API. This value is taken from the frontend globals config.
ctsPort -- This is the port number to be used in setting up the URL for requests made to the Clinical Trials API. This can be null.
ctsProtocol -- This is the protocol to be used in setting up the URL for requests made to the Clinical Trials API. This should be "https".
dynamicListingPatterns -- This is an object containing the different patterns within the app, and the different values for fields used within that pattern. The five fields are browserTitle, introText, metaDescription, noTrialsHtml, and pageTitle.
- For Disease, there are three patterns:
  - Disease
  - DiseaseTrialType
  - DiseaseTrialTypeIntervention
- For Intervention, there are two patterns:
  - Intervention
  - InterventionTrialType
detailedViewPagePrettyUrlFormatter -- This is the format for result links (to the clinical trial view page) found on a dynamic listing page.
itemsPerPage -- This is the number of results to display per page.
language -- This is the language of the app. Always "en".
listingApiEndpoint -- This is the URL to use for requests to the listing support API.
liveHelpUrl -- This is the URL for Cancer.gov's Live Help.
siteName -- This is the sitename used for analytics values.
title -- This is the title used for analytics values.
trialListingPageType -- This is the type of dynamic listing page for this instance of the app module. Can be Disease, Intervention, or Manual.

Examples

Disease:

{
    "drupalConfig": {
        "appName": "clinical-trials-listing-app-disease",
        "rootId": "NCI-trial-listing-app-root",
        "initFnName": "window.ClinicalTrialsListingApp",
        "appCssUri": "https:\/\/react-app-dev.cancer.gov\/clinical-trials-listing-app\/develop\/static\/css\/main.css",
        "appJsUri": "https:\/\/react-app-dev.cancer.gov\/clinical-trials-listing-app\/develop\/static\/js\/main.js",
        "removeHeadElements": [
            "canonical_url",
            "robots",
            "title_tag",
            "og_title",
            "og_url",
            "og_description",
            "description"
        ],
        "validAppPaths": []
    },
    "frontEndConfig": {
        "analyticsChannel": "@@TOKEN@@[cgov_tokens:cgov-analytics-channel]",
        "analyticsContentGroup": "@@TOKEN@@[cgov_tokens:cgov-analytics-group]",
        "analyticsPublishedDate": "@@TOKEN@@[node:field_date_posted:date:short]",
        "cisBannerImgUrlLarge": "https:\/\/react-app-dev.cancer.gov\/clinical-trials-listing-app\/develop\/images\/cts-cis-banner-xl.jpeg",
        "cisBannerImgUrlSmall": "https:\/\/react-app-dev.cancer.gov\/clinical-trials-listing-app\/develop\/images\/cts-cis-banner-smartphone.jpeg",
        "ctsApiHostname": "@@LITERAL@@window.CDEConfig.ctsConfig.apiServer",
        "ctsPort": null,
        "ctsProtocol": "https",
        "dynamicListingPatterns": {
            "Disease": {
                "browserTitle": "{{disease_label}} Clinical Trials",
                "introText": "<p>Clinical trials are research studies that involve people. The clinical trials on this list are for {{disease_normalized}}. All trials on the list are NCI-supported clinical trials, which are sponsored or otherwise financially supported by NCI.<\/p><p>NCI’s <a href=\"\/about-cancer\/treatment\/clinical-trials\/what-are-trials\">basic information about clinical trials<\/a> explains the types and phases of trials and how they are carried out. Clinical trials look at new ways to prevent, detect, or treat disease. You may want to think about taking part in a clinical trial. Talk to your doctor for help in deciding if one is right for you.<\/p>",
                "metaDescription": "NCI supports clinical trials studying new and more effective ways to detect and treat cancer. Find clinical trials for {{disease_normalized}}.",
                "noTrialsHtml": "<p>There are no NCI-supported clinical trials for {{disease_normalized}} at this time. You can try a <a href=\"\/about-cancer\/treatment\/clinical-trials\/search\">new search<\/a> or <a href=\"\/contact\">contact our Cancer Information Service<\/a> to talk about options for clinical trials.<\/p>",
                "pageTitle": "{{disease_label}} Clinical Trials"
            },
            "DiseaseTrialType": {
                "browserTitle": "{{trial_type_label}} Clinical Trials for {{disease_label}}",
                "introText": "<p>Clinical trials are research studies that involve people. The clinical trials on this list are for {{disease_normalized}} {{trial_type_normalized}}. All trials on the list are NCI-supported clinical trials, which are sponsored or otherwise financially supported by NCI.<\/p><p>NCI’s <a href=\"\/about-cancer\/treatment\/clinical-trials\/what-are-trials\">basic information about clinical trials<\/a> explains the types and phases of trials and how they are carried out. Clinical trials look at new ways to prevent, detect, or treat disease. You may want to think about taking part in a clinical trial. Talk to your doctor for help in deciding if one is right for you.<\/p>",
                "metaDescription": "NCI supports clinical trials studying new and more effective ways to detect and treat cancer. Find {{trial_type_normalized}} clinical trials for {{disease_normalized}}.",
                "noTrialsHtml": "<p>There are no NCI-supported clinical trials for {{disease_normalized}} {{trial_type_normalized}} at this time. You can try a <a href=\"\/about-cancer\/treatment\/clinical-trials\/search\">new search<\/a> or <a href=\"\/contact\">contact our Cancer Information Service<\/a> to talk about options for clinical trials.<\/p>",
                "pageTitle": "{{trial_type_label}} Clinical Trials for {{disease_label}}"
            },
            "DiseaseTrialTypeIntervention": {
                "browserTitle": "{{trial_type_label}} Clinical Trials for {{disease_label}} Using {{intervention_label}}",
                "introText": "<p>Clinical trials are research studies that involve people. The clinical trials on this list are testing {{trial_type_normalized}} methods for {{disease_normalized}} that use {{intervention_normalized}}. All trials on the list are NCI-supported clinical trials, which are sponsored or otherwise financially supported by NCI.<\/p><p>NCI’s <a href=\"\/about-cancer\/treatment\/clinical-trials\/what-are-trials\">basic information about clinical trials<\/a> explains the types and phases of trials and how they are carried out. Clinical trials look at new ways to prevent, detect, or treat disease. You may want to think about taking part in a clinical trial. Talk to your doctor for help in deciding if one is right for you.<\/p>",
                "metaDescription": "NCI supports clinical trials studying new and more effective ways to detect and treat cancer. Find clinical trials testing {{intervention_normalized}} in the {{trial_type_normalized}} of {{disease_normalized}}.",
                "noTrialsHtml": "<p>There are no NCI-supported clinical trials for {{disease_normalized}} {{trial_type_normalized}} using {{intervention_normalized}} at this time. You can try a <a href=\"\/about-cancer\/treatment\/clinical-trials\/search\">new search<\/a> or <a href=\"\/contact\">contact our Cancer Information Service<\/a> to talk about options for clinical trials.</p>",
                "pageTitle": "{{trial_type_label}} Clinical Trials for {{disease_label}} Using {{intervention_label}}"
            }
        },
        "detailedViewPagePrettyUrlFormatter": "\/clinicaltrials\/{{nci_id}}",
        "itemsPerPage": 25,
        "language": "en",
        "listingApiEndpoint": "@@LITERAL@@window.CDEConfig.ctsConfig.listingApiServer",
        "liveHelpUrl": "https://livehelp.cancer.gov/app/chat/chat_landing?_icf_22=92",
        "siteName": "@@TOKEN@@[cgov_tokens:cgov-trans-org-name]",
        "title": "@@TOKEN@@[node:field_browser_title:value]",
        "trialListingPageType": "Disease"
    }
}

Intervention:

{
    "drupalConfig": {
        "appName": "clinical-trials-listing-app-intervention",
        "rootId": "NCI-trial-listing-app-root",
        "initFnName": "window.ClinicalTrialsListingApp",
        "appCssUri": "https:\/\/react-app-dev.cancer.gov\/clinical-trials-listing-app\/develop\/static\/css\/main.css",
        "appJsUri": "https:\/\/react-app-dev.cancer.gov\/clinical-trials-listing-app\/develop\/static\/js\/main.js",
        "removeHeadElements": [
            "canonical_url",
            "robots",
            "title_tag",
            "og_title",
            "og_url",
            "og_description",
            "description"
        ],
        "validAppPaths": []
    },
    "frontEndConfig": {
        "analyticsChannel": "@@TOKEN@@[cgov_tokens:cgov-analytics-channel]",
        "analyticsContentGroup": "@@TOKEN@@[cgov_tokens:cgov-analytics-group]",
        "analyticsPublishedDate": "@@TOKEN@@[node:field_date_posted:date:short]",
        "cisBannerImgUrlLarge": "https:\/\/react-app-dev.cancer.gov\/clinical-trials-listing-app\/develop\/images\/cts-cis-banner-xl.jpeg",
        "cisBannerImgUrlSmall": "https:\/\/react-app-dev.cancer.gov\/clinical-trials-listing-app\/develop\/images\/cts-cis-banner-smartphone.jpeg",
        "ctsApiHostname": "@@LITERAL@@window.CDEConfig.ctsConfig.apiServer",
        "ctsPort": null,
        "ctsProtocol": "https",
        "dynamicListingPatterns": {
            "Intervention": {
                "pageTitle": "Clinical Trials Using {{intervention_label}}",
                "browserTitle": "Clinical Trials Using {{intervention_label}}",
                "metaDescription": "NCI supports clinical trials that test new and more effective ways to treat cancer. Find clinical trials studying {{intervention_normalized}}.",
                "introText": "<p>Clinical trials are research studies that involve people. The clinical trials on this list are studying {{intervention_normalized}}. All trials on the list are NCI-supported clinical trials, which are sponsored or otherwise financially supported by NCI.<\/p><p>NCI’s <a href=\"\/about-cancer\/treatment\/clinical-trials\/what-are-trials\">basic information about clinical trials<\/a> explains the types and phases of trials and how they are carried out. Clinical trials look at new ways to prevent, detect, or treat disease. You may want to think about taking part in a clinical trial. Talk to your doctor for help in deciding if one is right for you.<\/p>",
                "noTrialsHtml": "<p>There are no NCI-supported clinical trials studying {{intervention_normalized}} at this time. You can try a <a href=\"\/about-cancer\/treatment\/clinical-trials\/search\">new search<\/a> or <a href=\"\/contact\">contact our Cancer Information Service<\/a> to talk about options for clinical trials.<\/p>"
            },
            "InterventionTrialType": {
                "pageTitle": "{{trial_type_label}} Clinical Trials Using {{intervention_label}}",
                "browserTitle": "{{trial_type_label}} Clinical Trials Using {{intervention_label}}",
                "metaDescription": "NCI supports clinical trials studying new and more effective ways to treat cancer. Find clinical trials testing {{trial_type_normalized}} methods that use {{intervention_normalized}}.",
                "introText": "<p>Clinical trials are research studies that involve people. The clinical trials on this list are testing {{trial_type_normalized}} methods that use {{intervention_normalized}}. All trials on the list are NCI-supported clinical trials, which are sponsored or otherwise financially supported by NCI.<\/p><p>NCI’s <a href=\"\/about-cancer\/treatment\/clinical-trials\/what-are-trials\">basic information about clinical trials<\/a> explains the types and phases of trials and how they are carried out. Clinical trials look at new ways to prevent, detect, or treat disease. You may want to think about taking part in a clinical trial. Talk to your doctor for help in deciding if one is right for you.<\/p>",
                "noTrialsHtml": "<p>There are no NCI-supported clinical trials for {{trial_type_normalized}} using {{intervention_normalized}} at this time. You can try a <a href=\"\/about-cancer\/treatment\/clinical-trials\/search\">new search<\/a> or <a href=\"\/contact\">contact our Cancer Information Service<\/a> to talk about options for clinical trials.<\/p>"
            }
        },
        "detailedViewPagePrettyUrlFormatter": "\/clinicaltrials\/{{nci_id}}",
        "itemsPerPage": 25,
        "language": "en",
        "listingApiEndpoint": "@@LITERAL@@window.CDEConfig.ctsConfig.listingApiServer",
        "liveHelpUrl": "https://livehelp.cancer.gov/app/chat/chat_landing?_icf_22=92",
        "siteName": "@@TOKEN@@[cgov_tokens:cgov-trans-org-name]",
        "title": "@@TOKEN@@[node:field_browser_title:value]",
        "trialListingPageType": "Intervention"
    }
}