Portal Setup

About Portals

A Portal is an org with special privileges that serves two purposes. First, it provides a space for your organization to showcase projects with special data sets, tools that you've published, news and highlights or other important links. Second, the Portal has customized branding that follows the end-user throughout the site with a curated view of projects and tools.

Initial Portal Setup by DNAnexus

To configure a new Portal for your org, contact with the DNAnexus Professional Services team. The Partner specifies the org that hosts the Portal. The Portal is tied to exactly one org.

You need to provide the initial configuration requirements and assets (logos or other images, brand colors, text, and links) listed below.

The Portal becomes ready for testing after providing all configuration requirements and assets. The DNAnexus Professional Services team then provides a link to the Portal along with a brief training to orient the Org Admin to using the portal.

Features of a Portal and Configuration Options

This section describes configurations that the Org Admin can make by editing and uploading new JSON files or new images.

Login Page (branding.json)

• Logo (no size limit, but it's recommended to stay under 200px high)

• (Optional) Login button color that must be conducive to white text

• (Optional) Whether to hide the registration link

• (Optional) Text to display under login button

Register Page (branding.json)

• Logo (max 100x100px)

• (Optional) Register button color that must be conducive to white text

• (Optional) Can disable registration page, redirecting directly back to login

• (Optional) Markdown text to display under register buttons

• (Optional) Add default region for users who register with this page

• (Optional) Add short sentence indicating terms of acceptance

Header (branding.json and navigation.json)

The branding.json controls the colors in the Header. The navigation.json controls the navigation links and menus (except for the logo navigation).

These are the items you can configure:

• Header corner Logo (min 15x15px, max 50x30px)

• (Optional) Logo link destination, defaults to Home page (configure in the branding.json file)

• (Optional) Whether the logo link opens in a new tab (configure in the branding.json file)

• (Optional) Support page (used when the user clicks on "Get Help" in the Help menu, default is DNAnexus Support Form)

• (Optional) Color for the navigation bar, text, background, nav hover background color, landing page button color and color array for the user bubble. Icons do NOT change color, so do not make the background bar a dark color or text may not be visible.

• (Optional) Navigation customization. You can add custom items to the ends of our Projects, Tools, and Help menus, remove those menus entirely, or add new menus and links to the nav header.

• (Optional) Filters for the projects list, for example, when the users navigate to Projects > All Projects.

• (Optional) Whether to hide the community switcher, that is, lock the user into the current community

Landing Page (home.json)

The main page is a customizable landing page with the ability to showcase in any order with any amount of widgets:

• Specific projects

• Specific tools

• Links to external websites

• Images (PNG, JPEG, TIFF, BMP, etc)

• Markdown text

The home.json file contains a list of widgets to display, and the order in which to display them.

Text Widget

• Title

• id property of "markdown"

• Minimum width

• Markdown text

Image Widget

• Minimum width

• id property of "image"

• Image resource or location (image can be any type, for example, PNG, JPEG, TIFF, BMP)

• Alt text (when image can't be displayed)

Link List Widget

• Title

• id property of "link"

• Minimum width

• List of link destinations and their titles

Project List Widget

• Title

• id property of project or projectCards

• Minimum width

• Project filter criteria - To have projects displayed here, set up a search using the system/findProjects API method. To make all projects visible to all users who can access the Portal, set the level parameter to "VIEW."

• Project sub-page destination

Tool List Widget

• Title

• id property of "tool"

• Minimum width

• Tool filter criteria - To have available tools displayed here, set up a search using the /system/findApps API method.

A list of icons available to use on home.json is available in the Font Awesome v4 cheatsheet. DNAnexus supports the use of icons introduced in version 4.3 and earlier.

Managing, Modifying, and Updating Portal Assets

Portal assets are stored with the JSON files. Upload JSON and PNG files using the GUI on the main portal home page. The sections for each JSON file describe the access permissions that each file requires.

Validating JSON files Before Upload

JSON is easy for humans to read and write. However, it can be difficult to understand. Validate your JSON portal assets using tools such as JSON lint or JSON formatter, before using them to update the community portal.

Viewing changes in the browser

Clear your browser cache after updating your portal assets with a revised JSON file.

Depending on your browser, you can clear the cache through the Privacy or History section in Settings/Options menu, or by using keyboard shortcuts:

• Windows/Linux: Ctrl+Shift+Del

• Mac: Command+Shift+Del

While that hotkey combo works in most non-mobile browsers, the exact steps involved in clearing your browser's cache depend entirely on what web browser you're using. If the suggested steps don't work, refer to your browser's documentation.

As an alternative to clearing your cache, you can use 'private' browsing (a.k.a 'privacy' mode or 'incognito' mode) to view the asset updates. This is a privacy feature in some web browsers to disable browsing history and the web cache allowing a person to browse the Web without storing local data that could be retrieved later. To launch your browser in 'incognito' mode, refer to your browser's documentation.

Making Updates via the Command-Line Interface (CLI)

DNAnexus can also provide you with CLI scripts to update your assets. This provides an alternative to the UI, which can become disabled if a flawed JSON is inadvertently uploaded. Contact DNAnexus Support for more information and to request access to the scripts for CLI updating.

Compiling Portal Assets

Portal assets are split into many different files, all loaded at different times by different components. These samples show file formats and structure. Files can contain references to images. For communities, either prepend a pound sign (#) to denote an image fetched from community assets or use a normal URL to fetch an image from an external source. For example, "#logo.png" fetches the file "logo.png" stored in the community.

branding.json

In the header, logoOpensNewTab is optional and if true opens a new tab when the user clicks on the logo in the upper left. hideCommunitySwitch is also optional and, if true, hides the community selector in the upper left (essentially locking the user into the current community).

In the login and registration sections, logo specifies a logo to be used at the top of the given page and text can be Markdown which is rendered at the bottom of the page (below the button but above the footer).

The registration section has optional attributes:

• disable: When set to true, hides the "Create Account" link on the login page and redirects users to the login page if they try to manually visit the registration page

• agreeToText: A plain text string (not Markdown) with a checkbox that users must check before registering

• region: Specifies a fixed default region for all users created through this login page, rather than letting users select a region

homeURL and supportURL are optional and are the URLs used for the main community site (destination when clicking on the logo in the upper left) and support pages (destination when a user selects "Get Help" from the Help menu), respectively. description is shown in the community selector menu.

{
 "header": {
   "logo": "#logo_header.png",
   "logoOpensNewTab": true,
   "hideCommunitySwitch": true,
   "colors": {
     "background": "#123456",
     "border": "#123456",
     "text": "#123456",
     "hoverBackground": "#123456",
     "userColors": ["#123456", "#234567", "#345678"],
     "button": {"success": {"border-color": "green", "background":
      "pink", "hover": {"background": "dusk"}}}
   }
 },
 "login": {
   "logo": "#logo_login.png",
   "text": "#Title\n\nThis is Markdown text.",
   "colors": {
     "loginButton": "#123456"
   }
 },
 "register": {
   "disable": true,
   "logo": "#logo_register.png",
   "text": "#Title\n\nThis is more Markdown text.",
   "agreeToText": "Plain text you need to agree to before registering",
   "region": "aws:us-east-1",
   "colors": {
     "registerButton": "#123456"
   }
 },
 "homeURL": "http://example.com",
 "supportURL": "http://example.com/support",
 "hideCommunitySwitch": true,
 "description": "A short description of two or three lines for the community selector"
}

home.json

This file must be at least accessible to community members.

{
 "order": ["hero-image", "featured-projects", "featured-tools", "reference-links", "help-text"],
 "components": {
   "help-text": {
     "type": "markdown",
     "id": "help-text",
     "title": "Useful Advice",
     "content": "# Always wear sunscreen\nIt's really important.",
     "minWidth": "400px"
   },
   "unused-table-component": {
     "type": "markdown",
     "id": "unused-table-component",
     "title": "A table for you",
     "content": "| Tables | Are | Cool  |\n| --- | --- | --- |\n| a | b | $1600 |\n| c | d | $12 |\n| e | f | $1 |",
     "minWidth": "100px"
   },
   "hero-image": {
     "type": "image",
     "id": "hero-image",
     "src": "#my_awesome_image.png",
     "alt": "Heroes are great"
   },
   "unused-image": {
     "type": "image",
     "id": "unused-image",
     "src": "https://example.com/image.png",
     "alt": "Alt text"
   },
   "reference-links": {
     "type": "link",
     "id": "reference-links",
     "title": "Help and News",
     "links": [
       {
         "name": "Getting Started",
         "subname": "First steps with your new account",
         "href": "https://www.dnanexus.com",
         "icon": "fa-question-circle"
       },
       {
         "name": "Some Helpful News or Docs Link",
         "subname": "Come here for useful information",
         "href": "https://www.dnanexus.com",
         "icon": "fa-question-circle"
       }
     ],
     "footer": {
       "name": "Visit Help Center...",
       "href": "https://www.dnanexus.com/help"
     },
     "minWidth": "300px"
   },
   "featured-projects": {
     "type": "project",
     "id": "featured-projects",
     "title": "Featured Projects",
     "query": {
       "tags": "community-tag",
       "limit": 5
     },
     "columns": [
       {
         "property": "name",
         "label": "Name"
       },
       {
         "property": "modified",
         "formatter": "date",
         "label": "Modified"
       },
       {
         "property": "createdBy.user",
         "formatter": "userHandle",
         "label": "Created By"
       }
     ],
     "viewMore": "/panx/communities/communityname-without-org/projects",
     "minWidth": "400px"
   },
   "featured-tools": {
     "type": "tool",
     "id": "featured-tools",
     "title": "Featured Tools",
     "query": {
       "category": "community-tag"
     }
   },
   "project-destination": {
     "type": "projectCards",
     "id": "project-destination",
     "title": "Project Destinations (Samples)",
     "destination": "samples",
     "query": {
       "properties": {
         "dashboard_config_project": true
       }
     },
     "minWidth": "400px"
   },
 }
}

navigation.json

This file must be at least accessible to community members. Applies to the header. _filters is optional and contains information about how to alter the query sent to the server to fetch the main and featured lists of projects. _projects, _tools, and supportURL are all optional and can be:

• null to remove the item from the header

• An array of objects with the following format to add items to the end of the corresponding menu:

  • text is the text of the menu item

  • url is the destination to take the user to

  • newTab is optional and indicates that the link should be opened in a new tab

Additional entries in this file indicate new navigation items. These are defined by a key (in the example below, "A New Menu" and "A New Link"). Configure them in one of two ways:

• As an object with url and optional newTab values (rendered as a simple link in the navigation header)

• As an array of objects with keys text, url, and optionally newTab (rendered as a dropdown menu with the listed items)

{
  "_filters": {
    "projects": {
      "featured": {
        "id": ["project-1234", "project-2345"]
      },
      "all": {
        "tags": "community-demo",
        "billTo": "org-demo"
      }
    },
    "_projects": null,
    "_tools": [
      { "text": "Custom Menu Item", "url": "http://example.com" },
      {
        "text": "Opens in New Tab",
        "url": "http://example.com",
        "newTab": true
      }
    ],
    "_help": null,
    "A New Menu": [{ "text": "New Menu Item", "url": "http://example.com" }],
    "A New Link": { "url": "http://example.com", "newTab": true }
  }
}