Getting Started

Introduction

This section contains the first steps of getting started with CoralUI.

What browsers can I use?

CoralUI is designed to support the following browsers

Chrome (latest)
Safari (latest)
Firefox (latest)
Edge (latest)
IE 11
iOS 7+
Android 4.4+

Getting Started with 3.x

The following information is intended to get you up and running quickly with CoralUI.

The easiest way to start experimenting with CoralUI is to download the zip archive of the latest full release of all components. After you've unzipped the downloaded zip archive, follow the steps below.

Note: the full release download suggested above contains a pre-built set of all the components covered in this documentation. In production, you will likely use a custom build of CoralUI that includes only the sub-set of components used in your design.

You may also need a custom Typekit configuration for your development environment. See Using Typekit for more information.

What do I do with the files?

Put coral.css in the css/ directory of your project.
Put coral.min.js in the js/ or scripts/ directory of your project.
Put jquery.js and moment.js in the /js/libs or scripts/libs directory of your project.
Also put the content of the /resources folder in the /resources directory of your project. This is required for icons and other assets to work.

In the <head> section of your HTML, add the following:

<link rel="stylesheet" href="css/coral.min.css">
<script src="js/libs/jquery.js"></script>
<script src="js/libs/moment.js"></script>
<script src="js/coral.min.js"></script>

Add coral--light to a parent DOM element (e.g. body). This will enable default typographic text styles, and enable the CSS styling below.
```
<body class="coral--light">
```
That's it. Now you're ready to use CoralUI.

How do I work with CoralUI Components?

Most components in CoralUI are JavaScript components, which offer more functionality and are often more complex. CoralUI has a large number of components that you can view in the Components section.

Alert Example

Below are some examples of how to use Coral.Alert, which is a typical CoralUI component. The markup for an Alert is as follows:

Markup Example

 <coral-alert>
   <coral-alert-header>INFO</coral-alert-header>
   <coral-alert-content>This is is an alert.</coral-alert-content>
 </coral-alert>

Result

INFO

This is an alert

Alternately, you can instantiate components using the JavaScript new operator or by calling document.createElement().

JavaScript Examples

Using document.createElement:

var alert = document.createElement('coral-alert');

Using document.createElement:

var alert = new Coral.Alert();

Extending Native Elements

A few CoralUI components use the is attribute to extend a native element. Here is an example using <button> via markup. The resulting DOM element is the identical to one instantiated with JavaScript and will have the same methods and properties.

Markup Example

 <button is="coral-button">Default Button</button>

Result

Instantiation using createElement is a bit special for these type of components due to the fact that Coral.Button extends the native HTMLButtonElement. The createElement function takes the is attribute as a second parameter.

var button = document.createElement('button', 'coral-Button');

You may still use the new operator for these components:

var button = new Coral.Button();

In some cases, you may need to wait for a component to be upgraded. Do this by passing a callback to Coral.commons.nextFrame(). It is advised that you use the new operator or createElement when building elements in JavaScript. If you are rendering a template, be sure to pass attributes for anything that needs to be set dynamically and wait until the next animation frame before setting or getting the element's properties.

Tabs in CoralUI

Here is an example of how create tabs in CoralUI. This requires a Coral.TabView container, which holds a Coral.TabList and a Coral.PanelStack.

Markup Example

<coral-tabview>
  <coral-tablist target="coral-demo-panel-1">
    <coral-tab>Tab 1
    </coral-tab>
    <coral-tab>Tab 2
    </coral-tab>
    <coral-tab>Tab 3
    </coral-tab>
    <coral-tab>Tab 4
    </coral-tab>
  </coral-tablist>
  <coral-panelstack id="coral-demo-panel-1">
    <coral-panel class="coral-Well">Tab 1 Content
    </coral-panel>
    <coral-panel class="coral-Well">Tab 2 Content
    </coral-panel>
    <coral-panel class="coral-Well">Tab 3 Content
    </coral-panel>
    <coral-panel class="coral-Well">Tab 4 Content
    </coral-panel>
  </coral-panelstack>
</coral-tabview>

Result

Tab1

Tab2

Tab3

Tab4 (disabled)

Tab 1 Content

Tab 2 Content

Tab 3 Content

Tab 4 Content (disabled)

You can also initialize a tabbed UI directly in JavaScript. First, the Coral.TabList and Coral.PanelStack are created. Finally, a Coral.TabView is created to contain the first two elements.

JavaScript example

  // new Coral.TabList()
  var tablist = new Coral.TabList().set({
    target: 'coral-demo-panel-3'
  });
  tablist.items.add({
    label: {
      innerHTML: 'Tab 1'
    }
    selected: true
  });
  tablist.items.add({
    label: {
      innerHTML: 'Tab 2'
    }
  });
  tablist.items.add({
    label: {
      innerHTML: 'Tab 3'
    }
  });
  tablist.items.add({
    label: {
      innerHTML: 'Tab 4 (disabled)'
    }
    disabled: true
  });
  // new Coral.PanelStack()
  var panelstack = new Coral.PanelStack().set({
    id: 'coral-demo-panel-3'
  });
  panelstack.items.add({
    content.innerHTML: 'Tab 1 Content.',
  });
  panelstack.items.add({
    content.innerHTML: 'Tab 2 Content.',
  });
  panelstack.items.add({
    content.innerHTML: 'Tab 3 Content.',
  });
  panelstack.items.add({
    content.innerHTML: 'Tab 4 Content.',
  });
  // new Coral.TabView()
  var tabview = new Coral.TabView().set({
    panelStack: panelstack,
    tabList: tablist
  });

How do I work with CoralUI Styles?

There are still some CoralUI components that are markup and CSS only. These are documented in the Styles section of this site. They are not custom elements, and as such are used by setting CSS selectors on normal HTML markup. An example of this would be the Well component:

Markup Example

 <section class="coral-Well">Well content goes here.</section>

Result

Well content goes here.

Can I customize a CoralUI build?

Custom builds are possible, allowing you to limit the number of components that are bundled with CoralUI. This can reduce the size of the CoralUI dependencies in your project. To do this, simply follow the documentation in our custom builds documentation.

Want to Learn More?

The Styles and Components sections provide detailed information on consuming each component in CoralUI, including the different attributes available and the API methods and events for the JavaScript enabled components.

The Docs & Guide section provide detailed information about developing and contribution to CoralUI

This should get you started, but there is a lot more to CoralUI. For more information or specific questions, please contact the CoralUI mailing list.

CSS Themes

CoralUI has CSS theme support, and the theme used by a build of CoralUI is determined by what theme is included when CoralUI is built. There are currently only two themes available for CoralUI; the original CloudUI theme that CoralUI has always been based on, and the new Spectrum theme. At this time, the default build of CoralUI will continue to use CloudUI, but this will be switched and default to Spectrum at some point in 2016.

To change the theme of CoralUI, you will need a custom build, which will allow you to modify the included theme. The Styles documentation also includes more background on how themes work.

CoralUI does not support a mixed build that contains multiple themes.

Using Typekit

CoralUI uses Typekit to securely deliver the Adobe Clean corporate font.

Default Configuration

CoralUI comes preconfigured with a kit that is limited to the following domains.

Domains

If you are using CoralUI on a server on a domain other than these, you will need to request and configure your own Typekit kit. Otherwise, you will get a Javascript error on page load.

*.adobe.com
*.demdex.com
*.acrobat.com
*.omniture.com
*.day.com
localhost
127.0.0.1
0.0.0.0

Requesting a Kit for Additional Domains

If you need to enable CoralUI on additional domains, you will need to obtain a voucher for Adobe Clean from the Typekit team.

Create a generic Adobe account to use as your Typekit account. (recommended)
Visit Adobe TypeKit Wiki for further help on Adobe TypeKit accounts.
Configure your kit per the Kit Configuration settings below.
Configure CoralUI to use your default kit per the instructions below.

Kit Configuration

Your Kit should be configured with following font variations included.

Adobe Clean - Light
Adobe Clean - Regular
Adobe Clean - Bold
Adobe Clean - Italic
Adobe Clean Condensed - Bold
Adobe Clean Condensed - Italic

Choose default language support for both families.

Using a Custom Kit with CoralUI

Include your Typekit ID as a CoralUI option before CoralUI gets loaded.

<script>
  window.Coral = window.Coral || {};
  Coral.options = { typeKitId: 'xwm7izk'};
</script>

Font Loading, FOUT, and CoralUI

Typekit typically relies on a .wf-loading selector to hide content and prevent the Flash Of Unstyled Text (FOUT) that is associated with web fonts.

.wf-loading {
  visibility: hidden;
}

That selector would work in conjunction with the function in the typekit.js JavaScript file to remove the selector from the DOM when Typekit has loaded. However, experience has shown that hiding content and blocking until Typekit loads can can make the page or app unresponsive on initial load. There is a lot of reading around alternate solutions for this problem the web, including this article about the upcoming FontEvents API. CoralUI has removed our implementation of a solution in favor of remaining agnostic. Consumers must implement their own solution to avoid Flash Of Unstyled Text during font loading.

What about framework support?

CoralUI is a library of UI Components and supporting usage of different frameworks.

Torq

One well-supported option is using Torq together with CoralUI out-of-the-box.

AngularJS

Another option is AngularJS, supported via the coralui-support-angular project.

React

We are also looking into React, which will be supported via the coralui-support-react project.

Is there a demo app to reference?

The CoralUI team has provided a demo application for helping understand the usage of CoralUI. This application also provides an example of different variations that might be needed when implementing CoralUI.

See the Demo Apps documentation for more detail.

Problem?

Does any of this not make sense, or was too hard to follow? Do you have a question or concern? CoralUI has an active DL for providing support to the community. Just introduce yourself on <DL-CoralUI>coralui@adobe.com and ask your questions there. There is also a Slack channel, just sign up at `coralui.slack.com`.

If you have discovered a problem with CoralUI, you can file an issue in our JIRA project.

When creating a new issue, be sure to include:

The correct issue type (we use 'bug' or 'story').
A short, sensible summary.
A realistic priority: don't put "Blocker" or "Critical" without a valid justification.
The CoralUI component that is affected.
Ideally an affects version (CoralUI version you are using).
Some environment information (what browsers have the issue).
A detailed description.
An example (using the bug template), a screenshot or steps to reproduce the issue.
If the issue is blocking another project, link the CUI issue to the corresponding one in the other project.

Chrome (latest)

Safari (latest)

Firefox (latest)

Edge (latest)

IE 11

iOS 7+

Android 4.4+

Alert Example

JavaScript Examples

Extending Native Elements

Tabs in CoralUI

Domains