Attachment J11 - Template-Package-4-Resources-for-web-applications.pdf

OADC – DPA – Digital Media Branch 7/31/19

TEMPLATE PACKAGE

4 RESOURCES FOR

WEB APPLICATIONS

Digital Media Branch (DMB) Office of the Associate Director of Communications (OADC)

Version 1.1 July, 2019

GETTING STARTED

GUIDANCE

TP4 Template Resources for Web Applications

CDC.GOV GETTING STARTED GUIDANCE

TABLE OF CONTENTS

CDC.gov Getting Started Guidance

Purpose of this Document

Audience for this Document

Before You Start Checklist ✔

✔ Understand the CDC Policies and Standards

✔ Understand Your Developer Needs

✔ Understand the Web Application Resource Options

Specific Template Asset Package and Examples

App Template Examples and Location

Template Package Releases

✔ Ensure Developers Read the Required Documentation

✔ Understand Support

✔ Additional Guidance

Appendix A: Template Asset Package Table

✔ Required Features

✔ Optional Wrapper Features

✔ Optional Content Features

✔ Other Template Features

Appendix B: Terminology

Appendix C: Page Options

✔ Fourth Level Navigation

✔ Additional Left-Nav, Section Nav, and Bottom Nav OPtions

✔ Breadcrumb OPtions

PURPOSE OF THIS DOCUMENT

In order for application teams to adhere to the Web Template Use & Policy, DMB provides multiple template asset packages, using Bootstrap 4 to enable responsive functionality. This document contains Getting Started information on locating the appropriate Responsive Design (RD) template asset package and prepping/moving forward for successful template use.

This document applies to all Web application development teams that develop applications for CDC. This includes applications that are hosted at CDC as well as externally-hosted applications that fall under any CDC.gov domain or sub-domain. All Web applications supporting CDC are required to comply with CDC.gov Web policies and follow CDC.gov Web guidance and standards.

AUDIENCE FOR THIS DOCUMENT

This document is targeted for application team leads, Point of Contacts (POCs), and those who provide template guidance to application development teams (third-party vendors, Web teams, etc.) In addition, we recommend that application teams using the information need to have a basic understanding of application development in general, and application development at the CDC specifically.

BEFORE YOU START CHECKLIST ✔

✔ UNDERSTAND THE CDC POLICIES AND STANDARDS

As an application team lead, or a Point of Contacts (POC), ensure your developer(s) are knowledgeable and understand the CDC policies and standards. The CDC Web Policy mandates that CDC websites and Web applications adhere to the standards and guidance below. The following list provides the standards and policies.

508 compliance

CDC Web Policy

Policies

Per CDC Web Policy, CDC Web Applications do not have to use the Web Content Management System (WCMS);

however, they must adhere to the standard CDC Web template guidance to ensure a consistent look and feel for CDC websites. This requires that applications adhere to the Persistent features and follow the Adaptable and Optional features in the RD Template that are listed in Appendix A. All features, including new features that may be introduced in your application, should adhere to the OADC Style Guidance (WCMS Built)

The Persistent features, such as header, footer, fonts, and colors, are available through the application template assets described below. If you are creating new features or modules for your application, then you should try to make them conform to the existing features and modules in the CDC templates in accordance with template guidance. If you want to design a new feature in your application, at a minimum you must adhere to the font and color guidance if you cannot find examples or other style guidance as part of the CDC template guidance.

If you need more information on this policy or the use of Web assets available as part of the CDC templates, please reach out to your Template/WCMS POC or contact Lisa Richman at LRichman@cdc.gov.

✔ UNDERSTAND YOUR DEVELOPER NEEDS

OADC recommends that you consult with an application developer to help decide which application resources work best with the technologies that are employed in your application as well as ensuring it meets your technical requirements. Based on the functionality of your application, you may also need front end development support such as JavaScript and CSS development expertise to create and/or adapt these resources for use in your application.

✔ UNDERSTAND THE WEB APPLICATION RESOURCE OPTIONS

The Template Package is a set of assets, styles, and code to support the standard look & feel and functionality for CDC’s digital content. The main purpose of the Web Application template and resources are to provide application developers with the page structure, references, options, and guidance for building CDC compliant applications.

The Digital Media Branch provides the following packages to support application development:

Full, installable template – Due to extensive use of .Net for applications we have produced a .Net template to assist developers. It is installed in Visual Studio as C# or VB and currently is version 4.6.1 of .Net.

Asset packages – We provide example pages and local includes for PHP and ASP developers to not only help application developers using that language, but also to provide examples of application project structure and page structure for other languages to follow. If there are additional languages that require examples for developers to follow, your Web POC can request them through the WCMS HelpDesk.

Note: In support of the previous version of Template Package (Template Package 3) we offered template that use Bootstrap 2 and Bootstrap 3. These templates and asset packages have been retired with the release of the new Template Package.

SPECIFIC TEMPLATE ASSET PACKAGE AND EXAMPLES

The following section details the available Template Asset Packages.

APP TEMPLATE EXAMPLES AND LOCATION

The Template Package application templates and their location are listed below.

.Net App Template o A reference implementation of a .Net C# template can be found in the CDC GitLab instance at:

https://git.cdc.gov/agencytemplatedevs/tp4genericnetwebapp

PHP Template Assets o A reference implementation of a PHP app can be found in GitLab at https://git.cdc.gov/agencytemplatedevs/templatepackage/tree/master/PHP

ASP Template Assets o A reference implementation of an ASP app can be found in GitLab at https://git.cdc.gov/agencytemplatedevs/templatepackage/tree/master/ASP

Intranet Template Assets o A reference implementation of an Intranet app can be found in GitLab at https://git.cdc.gov/agencytemplatedevs/templatepackage/tree/master/PHP.

o This is intended to provide a developer with a set of reference pages to show the markup and includes required to create a TP4 Intranet page. These PHP examples can be used for ASP if you change the syntax to include SSI’s.

o The example pages in that directory are: intranetNav.php (fixed width, contains left-nav), intranetNoNav.php (fixed width, does not contain left-nav), and intranetWide.php (fluid layout that expands to the width of the screen).

TEMPLATE PACKAGE RELEASES

These application template examples make use of the full RD Template Package v4.0, which is located at:

\\cdc.gov\ahb_apps\wwwdev_cdc_gov\TemplatePackage\releases.

Locate the latest version, which has a name similar to CDC_TemplatePackage_v4.x.x.x.

The ZIP file contains assets such as images, JavaScript libraries, and CSS libraries. All of these assets assist you to style and present your content on the Web.

✔ ENSURE DEVELOPERS READ THE REQUIRED DOCUMENTATION

Use the contents of the following site to assist your developer to implement the template: WCMS & Templates

As an application team lead or a Point of Contacts (POC), focus your reading on the following:

Overview: Web Applications overview

Responsive Design Overview: Responsive Design concepts

Template Package 4 Design Overview: Template Package 4: What you need to know

Design Gallery: WCMS RD Template Feature Gallery

Additional Information: CDC.gov Template Documentation

✔ UNDERSTAND SUPPORT

OADC fully supports the core CDC.gov templates which includes the markup, images, fonts, style, and functionality associated with the overall page layout and common elements of a page (e.g., header, footer, search, left navigation, modules, and gadgets) supporting a fully responsive design. Applications that follow the template markup and use of the provided assets (CSS, images, fonts, and JavaScript) in accordance with the CDC.gov Application Template Guidance can get support from OADC for issues related directly to the templates using the same support ticket mechanism that is available for users of the WCMS.

OADC does not offer support for customizations made to the CDC.gov template markup or assets and also does not support use of other JavaScript libraries and/or custom code used by applications. Additionally, OADC supports resolution of issues around security and Section 508 compliance only related to the templates and template features themselves – not application-specific features or functionality.

Examples of use of the CDC.gov templates for .NET, PHP and ASP are available from OADC as well as the complete set of template assets and these can be used as a starting point for applications.

✔ ADDITIONAL GUIDANCE

It is recommended that application developers reference the global Server Side Includes, or SSIs directly from within the Template Package. They are located in /TemplatePackage/Includes. Time-to-time OADC is required by policy or to address issues to add, update, or remove certain references from Global SSIs and if your applications are not using the Global SSIs then the changes will be missed

When building your applications in generally, and when customizing optional/customizable portions of the Template, use local SSIs where ever possible. This allows you to more easily adapt any templates/master pages/themes/etc. in the event there are page/grid layout/navigation/metric/etc. changes to the CDC.gov templates

It is also critical to make sure to have a mechanism in place to keep the /TemplatePackage assets updated and current with the latest releases as they become available. You can have your own process or contact us to see if we can deploy directly to your environments (or have AHB setup replication).

APPENDIX A: TEMPLATE ASSET PACKAGE TABLE

The table below provide details, persistent features, adaptable features, optional features and other features of the currently, available template asset packages. Preview this table to assist you in making a decision which template package to use.

Template Use Creating responsive Web applications Applications that may require the use of Customizible or Optional template features Existing RD Template UI elements can be more easily implemented in these templates Custom UI elements should be developed using OADC style guidance

✔ REQUIRED FEATURES

These features are required in compliant applications

CDC Logo Site Title (bar and text) o Create a local copy of /TemplatePackage/4.0/includes/site-title.html and adjust the text

CDC Footer Fonts and font sizes (CSS for basic styling)

Color palettes Global Alerts o Must be included in compliant applications so that global alerts will be displayed in applications as well o Notification of a government shutdown is an example of a global alert

✔ OPTIONAL WRAPPER FEATURES

These items are optional for the wrapper (header, left-nav, footer area). Included with each item is the approach to remove or customize.

Left-Nav o Each template or page example referenced above provided in SVN includes a full width page and a page with left-nav. Choose the page example that matches your need

CDC Search and CDC A-Z o Both CDC Search and CDC A-Z index can be removed or customized by creating a local copy of

/TemplatePackage/4.0/includes/header-search.html and clearing out the contents of customizing

“Share” Controls o Create a local copy of /TemplatePackage/4.0/includes/page-share.html and clear out the contents

Sticky Mobile “Share” Controls o Create a local copy of /TemplatePackage/4.0/includes/social-media-footer.html and clear out the contents

Breadcrumbs o Create a local copy of /TemplatePackage/4.0/includes/nav-breadcrumb.html and clear out the contents or use pageOptions that programmatically adjust the breadcrumbs as described in Appendix C.

Section Nav o Options to suppress the the SectionNav are described in Appendix C.

✔ OPTIONAL CONTENT FEATURES

These items are optional for the content area. Included with each item is the approach to remove or customize.

Page Title o Review pages in the WCMS Feature Gallery for examples and markup of content elements.

Feature Area o Review pages in the WCMS Feature Gallery for examples and markup of content elements, including Feature Area.

Persistent Content Area o This is an include that can be used to have the same content appear on every page. Create a local copy of /TemplatePackage/4.0/includes/persistent-content-area.html Content Source and Date Stamp o Review pages in the WCMS Feature Gallery for examples and markup of content elements

Content Under Left Navigation o This is an include that can be used to have the same content appear under the left-nav on every page. Create a local copy of /TemplatePackage/4.0/includes/under-nav-left.html Icons o SVG Icons are used in the new Template Package. To have them appear in standard features you should include the following:

<!--#include virtual="/TemplatePackage/4.0/includes/svg-symbols.html" --> <!--#include virtual="/TemplatePackage/4.0/includes/svg-round-social.html" --> <!--#include virtual="/TemplatePackage/4.0/includes/svg-white-social.html" --> <!--#include virtual="/TemplatePackage/4.0/includes/svg-audio.html" --> <!--#include virtual="/TemplatePackage/4.0/includes/svg-other.html" -->

Feature Players (sliders) o Review pages in the WCMS Feature Gallery for examples and markup of content elements

Cards o Review pages in the WCMS Feature Gallery for examples and markup of content elements

Maps o Maps and other ways to display data are included in the Template Package as widgets, but may not meet the needs of your application. However, if the map and charting solutions in the WCMS meet your needs, you may be able to present your data on static web pages

✔ OTHER TEMPLATE FEATURES

These items are additional features related to the Template Package.

Automatic display of External Link icons o Not Included. Apps need to add support o In the new Template Package, the addition of external link icons was left for the WCMS and

Applications to assign to links. For more information see https://www.cdc.gov/wcms/4.0/cdc-wp/navigation/external-links.html

Automatic display of non-HTML file icons and associated File Format help section o Not Included. Apps need to add support o In the new Template Package, the addition of external link icons was left for the WCMS and

Applications to assign to links. For more information see https://www.cdc.gov/wcms/4.0/cdc-wp/navigation/external-links.html. This page includes examples of SVG icons used with non-html format links

Standard SiteCatalyst metrics code o Provided within /TemplatePackage/4.0/includes/metrics.html. Make sure window.CDC.tp4.public.appInit(window.pageOptions); is called within your page to initialize metrics Standard ACSI survey code o Provided within /TemplatePackage/4.0/includes/scripts.html

APPENDIX B: TERMINOLOGY

The following table details Terms and their Definitions that are found in this document.

Bootstrap is a free and open-source collection of tools for creating websites and Web applications. It contains HTML- and CSS-based design templates for typography, forms, buttons, navigation and other interface components, as well as optional JavaScript extensions. Bootstrap aims to ease the development of dynamic websites and Web applications. Bootstrap is a front-end framework, that is, an interface for the user, unlike the server-side code which resides on the "back end" or server

Responsive Design is a strategy for providing an optimal Web user experience regardless of the device, platform, or browser used to access the site.

APPENDIX C: PAGE OPTIONS

The following section should assist you in using Template Package features that can be optionally controlled.

✔ FOURTH LEVEL NAVIGATION

The left nav only shows three levels. If any third level items have a fourth level below them, they will not be shown in the left-nav, but they will be shown on the content page in desktop and in the Section Nav in mobile.

To suppress the fourth level items from showing in the Desktop viewports (L, XL, and XXL), you can use the showFourthLevelNav pageOptions.

<script> window.pageOptions = window.pageOptions || {};

………Other Page Options……… window.pageOptions.navigation = window.pageOptions.navigation || { showFourthLevel: false };

………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

To customize the Title of the Fourth Level Nav table in Desktop, you can use the fourthLevelNavTitle pageOption.

<script> window.pageOptions = window.pageOptions || {};

………Other Page Options……… window.pageOptions.navigation = window.pageOptions.navigation || { fourthLevelNavTitle: 'Custom Title Here' };

………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

To customize the style of the Fourth Level Nav table in Desktop, you can use the fourthLevelNavStyle pageOption.

<script> window.pageOptions = window.pageOptions || {};

………Other Page Options……… window.pageOptions.navigation = window.pageOptions.navigation || { fourthLevelNavStyle: ordered-list };

………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

The second option for fourthLevelNavStyle is “block-list” which provides an unordered list.

✔ ADDITIONAL LEFT-NAV, SECTION NAV, AND BOTTOM NAV OPTIONS

Contents of the left-nav controls a number of other page elements including the Breadcrumbs, Section Nav, and Bottom Nav. Breadcrumb options will be discussed in the next section. We first will review the pageOptions for Left-nav, Section Nav and Bottom Nav.

To highlight an existing navigation item use the pathToSelect pageOptions.

<script> window.pageOptions = window.pageOptions || {};

………Other Page Options……… window.pageOptions = window.pageOptions || {}; window.pageOptions.navigation = window.pageOptions.navigation || { pathToSelect:

'/ExamplePath/exampleLeftNavItem.html' };

………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

Where /ExamplePath/exampleLeftNavItem.html is an exact match for an item in the left-nav. This is just an example page and should be replaced by the URL for an item in your left-nav you want to highlight.

To inject an item into the navigation menu, add the addNavigation pageOptions.

<script> window.pageOptions = window.pageOptions || {};

………Other Page Options……… window.pageOptions = window.pageOptions || {}; window.pageOptions.navigation = window.pageOptions.navigation || { pathToSelect:

'/ExamplePath/exampleLeftNavItem.html', addNavigation: true };

………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

This will cause the current page to be inserted below the pathToSelect page in the navigation menu.

To customize the text or URL of the injected item use addNavigationText and/or addNavigationURL pageOptions.

<script>

………Other Page Options……… window.pageOptions = window.pageOptions || {}; window.pageOptions.navigation = window.pageOptions.navigation || { pathToSelect:

'/ExamplePath/exampleLeftNavItem.html', addNavigation: true , addNavigationText:

'Hello, new link!', addNavigationHref: '/ExamplePath/examplePage.html' };

………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

This will cause a link with text ‘Hello, new link!’ to be inserted below the pathToSelect page in the navigation menu, that links to /ExamplePath/examplePage.html.

To turn off SectionNav use the mobileSectionNav pageOption.

<script> window.pageOptions = window.pageOptions || {};

………Other Page Options……… window.pageOptions = window.pageOptions || {}; window.pageOptions.navigation = window.pageOptions.navigation || {}; window.pageOptions.navigation.mobileSectionNav = window.pageOptions.navigation.mobileSectionNav || {};

window.pageOptions.navigation.mobileSectionNav.enabled = false;

………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

To turn off BottomNav use the mobileBottomNav pageOption.

<script> window.pageOptions = window.pageOptions || {};

………Other Page Options……… window.pageOptions = window.pageOptions || {}; window.pageOptions.navigation = window.pageOptions.navigation || {}; window.pageOptions.navigation.mobileBottomNav = window.pageOptions.navigation.mobileBottomNav || {};

window.pageOptions.navigation.mobileBottomNav.enabled = false;

………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

There are pageOptions for mobileSectionNav.title and navSelector, but these have not been documented yet.

Contact the WCMS Help Desk for more information on these.

✔ BREADCRUMB OPTIONS

Breadcrumbs are driven by the contents of the navigation menu, but can be adjusted using the following pageOptions.

To have the Breadcrumbs automatically populated based on the navigation menu (left-nav) use the breadcrumbs.mode pageOption.

<script>

………Other Page Options……… window.pageOptions.navigation = window.pageOptions.navigation || {};

window.pageOptions.navigation.breadcrumbs = { mode: 'auto' };

………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

To add a prefix to the breadcrumbs use the prefix pageOption.

<script> window.pageOptions = window.pageOptions || {};

………Other Page Options……… window.pageOptions.navigation = window.pageOptions.navigation || {};

window.pageOptions.navigation.breadcrumbs = { mode: 'auto', prefix: [{ text: 'My Prefix', href: 'www.cdc.gov/test-url.html' text: 'My Second Prefix', href: 'www.cdc.gov/test-url-two.html' ………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>

To show the current page in the breadcrumbs, use the showCurrentPage pageOption.

<script> window.pageOptions = window.pageOptions || {};

………Other Page Options……… window.pageOptions.navigation = window.pageOptions.navigation || {};

window.pageOptions.navigation.breadcrumbs = { mode: 'auto', showCurrentPage: true ………Other Page Options……… window.CDC.tp4.public.appInit(window.pageOptions);

</script>