Coding Guidelines

General Notes

  • Naming: Be consistent, give meaningful names, and avoid abbreviations (unless the purpose is clear and an abbreviation wouldn't obscure it)
  • Columns: Try and keep lines down to 80 columns, though for readability/maintainability, going above 80 is acceptable.
  • Variables: Make sure your variables are descriptive and avoid using numbers (i.e. var1, var2).
  • Comments: Leave comments at every major section describing what is being done (if not obvious)
  • Tabbing: When formatting code, use 2 space soft tabs. Do not use hard tabs. When code is pasted into dotCMS' WYSIWYG field, it converts tabs to spaces and can make code ugly and hard to read. Make sure your code is readable!
  • Document Header: Keep the top simple and include a description only when necessary (lengthy descriptions, variables, and settings should be on the documentation page).

Naming Conventions

# Type Usage Example
1 Files/Folders lowercase, hyphens phy-directory
env-detect
ce-logic.vtl
2 HTML/CSS IDs and Classes lowercase, hyphens
(use 'webq' as the prefix)
webq-calfeed
webq-phylist
webq-bpg
3 Velocity/JavaScript Variables lowercase, underscores*
(use 'webq' as the prefix)
(*helps differentiate our custom variables from dotCMS variables)
service_item
physician_list

Velocity

  • Velocity code should be free of should be free of <script> tags, <style> tags, and inline styles, unless absolutely necessary. These should be placed in the associated JS/CSS files and included in the pre-execute of the widget (or before the velocity is parsed).
  • Avoid HTML comments as they will show up in the final HTML (ok for debugging)
  • Use macros sparingly and only when they can help reduce code duplication
  • Make sure to name your macro VERY SPECIFICALLY maybe even including the name of the velocity file in the name. The reason is that all macros in the system are global and we don't want to overwrite any of the dotCMS macros.
  • A comment block should be included at the top of velocity code with these items:
    • title
    • version
    • author
    • date created
    • date modified
    • description
    • parameters
    • default settings

Example Velocity


#********************
* video-gallery-widget.vtl
*
* Title:        Video Gallery Widget
* Version:      0.1
* Author:       Cody Merrill
* Date Created: 04/04/2016
* Date Modified: 05/13/2016
* Description:  A Video Gallery for HCA WebQ.
* Parameters: N/A
* Default Settings: N/A
*
*#dotParse("//web-q-hospital.prod.ehc.com/global/hut/widgets/video-gallery-widget/v1.0/video-gallery-widget.vtl")*
*
********************#

#********************
* STYLES
********************#

#********************
* SCRIPTS
********************#

#********************
* HTML
********************#

View Example

CSS

  • As stated in the velocity section, CSS code should be free of <script> tags, <style> tags, and inline styles. These should be placed in the associated JS/CSS files and included in the pre-execute of the widget (or before the velocity is parsed).
  • If there are several styles, include comments to break them into sections.
  • Avoid using IDs in your HTML, since two of the same IDs on a page will break the JavaScript and your widget.
  • Be specific when naming your styles, as many sites have very generic styles that could overwrite those you are creating.
  • A comment block should be included at the top of the CSS code with the following items:
    • title
    • author
    • description

Example CSS


/*‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐*/
/*    Title: Master App CSS
/*    Author: Cody Merrill
/*    Description: Styles for the HCA WebQ Video Gallery.
/*‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐‐*/
* {
  box-sizing: border-box; }

#webq-vg-top {
  background-color: #eaeaea;
  padding: 20px 5px; }

.webq-vg-phy, .webq-vg-player {
  padding: 15px 0;
  height: 100%; }

.webq-vg-phy {
  text-align: center;
  border-bottom: 1px solid #aaa; }
  .webq-vg-phy h3, .webq-vg-phy h4 {
    font-weight: normal; }
  .webq-vg-phy h3 {
    font-size: 20px; }
  .webq-vg-phy h4 {
    font-size: 14px; }

@media (min-width: 768px) {
  .webq-vg-item {
    width: 33.33%; } }

View Example

JavaScript

  • Use the following style guide as your main reference: https://github.com/airbnb/javascript/tree/es5-deprecated/es5
  • Use the Webq namespace
  • Try to follow the module concept of the //web-q-hospital.prod.ehc.com/global/hut/widgets/wireframe/v1/wireframe.js
  • Use existing third party JS libraries (https://core.secure.ehc.com/design/lib/) if possible
  • Add non-existing third party libraries to the //web-q-hospital.prod.ehc.com/global/lib folder

View Example




Creating Apps & Widgets

Apps vs. Widgets

  • Apps require their own template(s) and almost always need their own custom title, meta, canonical URL, etc. handling
  • Widgets don't require their own template(s) and are added to a HUT template page container

Wireframes (Templates for App and Widget Builds)

  • To start building a new app or widget, use the following wireframes:
    • /global/hut/widgets/wireframe/
    • /global/hut/apps/wireframe/
  • The velocity files within the wireframes contain the required, optional, and code snippet sections and use the following naming conventions:
Velocity File Naming Conventions
# Name Notes
1 |widgetName|.vtl ---
2 |widgetName|-template.vtl optional
3 |widgetName|-logic.vtl optional
4 |widgetName|-preexecute.vtl ---
5 |widgetName|.less ---
6 |widgetName|-eb.less |widgetName|-eb.css.vtl
7 |widgetName|.js |widgetName|.min.js

Folder Structure

The folder structure for an app or widget using HUT on the web-q-hospital.prod.ehc.com host should conform to the following:

# Element Formatting/Example
1 Path
Example
/global/hut/[component]/[widgetName]/[versionNumber]/
/global/hut/widgets/birth-plan-generator/v1/
2 [component]
Example
indicates app or widget
/apps/ or /widgets/
3 [widgetName]
Example
title of the app or widget
/birth-plan-generator/
4 [versionNumber]
Example
version of the app or widget
/v1/
5 Files All files go in the version number folder (/img/, /js/, /css/ folders should not be created under the version number folder)

Documentation

For each app or widget that is created, corresponding documentation is required. Our documentation contains three elements: 1) instructions, 2) a demonstration, and 3) a snippet generator. Each item should be given its own page within the /global/hut/ section to house these pieces of documentation.

# Element Formatting/Example
1 Instructions
Example
/global/hut/[component]/[widgetName]/[versionNumber]/instructions.dot
/global/hut/widgets/birth-plan-generator/v1/instructions.dot
2 Demonstration
Example
/global/hut/[component]/[widgetName]/[versionNumber]/demo.dot
/global/hut/widgets/birth-plan-generator/v1/demo.dot
3 Snippet Generator
Example
/global/hut/[component]/[widgetName]/[versionNumber]/snippet.dot
/global/hut/widgets/birth-plan-generator/v1/snippet-generator.dot
Instructions Template Demo Template Snippet Generator Template

Browser Testing

You absolutely have to test your website in multiple browsers to ensure that visitors to your site do not receive a broken experience. We recommend testing in the following browsers for compatibility:




Global Files

General Notes

Our widgets use static and dynamic global CSS files to load their styles. These files are separate from the widgets themselves and load from the /util/custom/start.vtl on every host. Their purpose is to collect all of the base styles and custom Entity Branding (EB) styles for the widgets into two global files.

To utilize these files,

  • Include the widgets' static .less file to the master .less file (/global/hut/widgets/css/webq-widgets.less) and compile
  • dotParse the widgets' widgetname-eb.css.vtl in the master file (/global/hut/widgets/css/webq-widgets-eb.vtl)
  • See the global/hut/widgets/wireframe/v1/wireframe-eb.less file for more information about how to build dynamic CSS for your widget

Static CSS (Base Styles)

The Static CSS holds all of the base styles for our widgets.

Dynamic CSS (Entity Branding Styles)

The Dynamic CSS holds all of the custom EB styles for our widgets.

Compiling

When compiling your CSS, adhere to the following guidelines:

  • Compiling is mainly used when a new widget is rolled out and the global CSS needs to be updated
  • Notify other colleagues prior to compiling the master file in order to avoid overriding their includes

How to Compile WebQ CSS Guide