Coral.ColumnView

Current Version: 3.1.0
Note:Any Coral CSS classes and attributes not explicitly mentioned in the public documentation are private and subject to change. Their direct use is not recommended and at high risk of breaking after subsequent updates of CoralUI library. For technical details of how to use Coral safely, please refer to the CoralUI Architecture.
Github: @coralui/coralui-component-columnview

A ColumnView displays and allows the user to browse and select items in a dynamic tree structure (e.g. a filesystem or multi-level navigation).

Markup Examples

Notice: The examples created via pure markup will not respond to user interaction. For multi-level navigation, please checkout the JavaScript examples.

Basic ColumnView

English Français Document
Show Markup 
<coral-columnview>
  <coral-columnview-column>
    <coral-columnview-column-content>
      <coral-columnview-item variant="drilldown" icon="folder">English</coral-columnview-item>
      <coral-columnview-item variant="drilldown" icon="folder">Français</coral-columnview-item>
      <coral-columnview-item variant="drilldown" icon="file">Document</coral-columnview-item>
    </coral-columnview-column-content>
  </coral-columnview-column>
</coral-columnview>

ColumnView with preview

English Français Document Name document.txt Title The Document File Size 5MB Modified 2 hours ago Type application/vnd.oasis.opendocument.text-web Publish Status References 2
Show Markup 
<coral-columnview class="guide-columnview-example">
  <coral-columnview-column>
    <coral-columnview-column-content>
      <coral-columnview-item variant="drilldown" icon="folder">English</coral-columnview-item>
      <coral-columnview-item variant="drilldown" icon="folder">Français</coral-columnview-item>
      <coral-columnview-item variant="drilldown" icon="file">Document</coral-columnview-item>
    </coral-columnview-column-content>
  </coral-columnview-column>
  <coral-columnview-preview>
    <coral-columnview-preview-content>
      <coral-columnview-preview-asset>
        <coral-icon icon="file" size="L"></coral-icon>
      </coral-columnview-preview-asset>
      <coral-columnview-preview-label>Name</coral-columnview-preview-label>
      <coral-columnview-preview-value>document.txt</coral-columnview-preview-value>
      <coral-columnview-preview-label>Title</coral-columnview-preview-label>
      <coral-columnview-preview-value>The Document</coral-columnview-preview-value>
      <coral-columnview-preview-label>File Size</coral-columnview-preview-label>
      <coral-columnview-preview-value>5MB</coral-columnview-preview-value>
      <coral-columnview-preview-label>Modified</coral-columnview-preview-label>
      <coral-columnview-preview-value>2 hours ago</coral-columnview-preview-value>
      <coral-columnview-preview-label>Type</coral-columnview-preview-label>
      <coral-columnview-preview-value>application/vnd.oasis.opendocument.text-web</coral-columnview-preview-value>
      <coral-columnview-preview-separator></coral-columnview-preview-separator>
      <coral-columnview-preview-label>Publish Status</coral-columnview-preview-label>
      <coral-columnview-preview-value>
        <coral-icon icon="check" size="XS"></coral-icon>
      </coral-columnview-preview-value>
      <coral-columnview-preview-separator></coral-columnview-preview-separator>
      <coral-columnview-preview-label>References</coral-columnview-preview-label>
      <coral-columnview-preview-value>
        <coral-icon icon="link" size="XS"></coral-icon>2
      </coral-columnview-preview-value>
    </coral-columnview-preview-content>
  </coral-columnview-preview>
</coral-columnview>

JavaScript Examples

The following examples demonstrate usage of the JavaScript API's for Coral.ColumnView.

JS Class Initialization

The following is an example of the ColumnView, which is manually initialized on page initialization, added to the DOM and navigates via the coral-columnview:loaditems event.

Notice: The individual columns and preview are loaded from html snippets. 

<script>
  $(document).ready(function() {
    var columnView = new Coral.ColumnView().set({
      id: 'guide-columnView-multiple-0',
      selectionMode: 'multiple'
    });
    var columnViewColumn = new Coral.ColumnView.Column().set({
      id: 'guide-columnViewColumn-multiple-0'
    })
    // Add the data-src attribute, which is red in the loaditems event-listener
    columnViewColumn.setAttribute('data-src', 'resources/columnview/content.html');
    columnView.appendChild(columnViewColumn);
  
    var constructorExample = document.getElementById('constructorExample');
    constructorExample.appendChild(columnView);
  });
</script>
<coral-columnview class="coral3-ColumnView" role="tree" tabindex="0" id="guide-columnView-multiple-0"><coral-columnview-column class="coral3-ColumnView-column" role="group" id="guide-columnViewColumn-multiple-0" data-src="resources/columnview/content.html"><coral-columnview-column-content></coral-columnview-column-content></coral-columnview-column></coral-columnview>

Loading remote data

The following shows how to listen for the coral-columnview:loaditems event and use setNextColumn. 

<script>
  $(document).ready(function() {
    var eventLog = $('#columnViewLog');
  
    document.addEventListener('coral-columnview:loaditems', function(event) {
      var cv = event.target;
      var item = event.detail.item;
      var column = event.detail.column;
    
      // if item is set, it means we load the item content
      var url = item ? $(item).attr('data-src') : $(column).attr('data-src');
    
      // there is no information on additional items
      if (typeof url === 'undefined') {
        return;
      }
    
      console.log('Loading: %s', url);
    
      $.ajax({
        url: url
      }).done(function(data) {
        var $data = $(data);
      
        // if it is a preview column we add it directly
        if ($data.is('coral-columnview-preview')) {
          cv.setNextColumn($data[0], column);
        }
        else {
          // otherwise we treat it as a normal column
          var $contentWrapper = $data.find('coral-columnview-column-content').first();
          var $columnWrapper = $contentWrapper.closest('coral-columnview-column');
        
          if ($contentWrapper.length > 0) {
            if (item) {
              // adds an unique id to be able to identify the column
              $data[0].id = Coral.commons.getUID();
              // we add the new column and scroll to it
              cv.setNextColumn($data[0], column);
            }
            // we load data in the current column
            else {
              // update the source of the current column (so that lazyloading does work)
              var nextSrcToLoad = $($columnWrapper).attr('data-src');
              if (!nextSrcToLoad) {
                column.removeAttribute('data-src');
              }
              else {
                column.setAttribute('data-src', nextSrcToLoad);
              }
            
              // update the content
              $(column.content).append($contentWrapper.html());
            }
          }
        }
      });
    });
  });
</script>

Responding to user interaction

The following shows how to listen for events generated by the ColumnView above. 

<script>
  $(document).ready(function() {
    var eventLog = $('#columnViewLog');
    var columnView = document.getElementById('guide-columnView-multiple-0');
    columnView.on('coral-columnview:change', function(e) {
      eventLog.log(e.type);
    });
    columnView.on('coral-columnview:loaditems', function(e) {
      eventLog.log(e.type + ' ' + ' start: ' + event.detail.start + ' column: ' + event.detail.column.id);
    });
    columnView.on('coral-columnview:activeitemchange', function(e) {
      var logMessage = e.type + ' new: "' + $(event.detail.activeItem).text() + '" old: "' + $(event.detail.oldActiveItem).text();
      eventLog.log(logMessage);
    });
  });
</script>

Log

Coral.ColumnView API

Constructor

JavaScript:

new Coral.ColumnView() or document.createElement('coral-columnview')

HTML Tag:

<coral-columnview>

Extends

Sub-components

Static Properties

Coral.ColumnView.selectionMode {String}

Enumeration representing the ColumnView selection modes.

Properties:

Name Type Value Description
NONE String none None is default, selection of items does not happen based on click
SINGLE String single Single selection mode, only one item per column can be selected.
MULTIPLE String multiple Multiple selection mode, multiple items per column can be selected.

Instance Properties

instance.activeItem {HTMLElement}

Readonly
Active Item that corresponds to the last item in the path.

instance.columns {Coral.Collection}

Readonly
Collection that holds all the columns inside the ColumnView. See Coral.Collection for more details.

instance.hidden {Boolean}

Reflected
Whether this component is hidden or not.
Inherited From:
Default Value:
  • false
HTML Attribute:
  • hidden

instance.selectedItem {HTMLElement}

Readonly
First selected item of the ColumnView.

instance.selectedItems {Array.<HTMLElement>}

Readonly
Array containing the set selected items. The items will match only one column since selection across columns is not allowed.

instance.selectionMode {Coral.ColumnView.selectionMode}

Selection mode of the ColumnView.
Default Value:
  • Coral.ColumnView.selectionMode.NONE
HTML Attribute:
  • selectionmode

Methods

instance.get

Get the value of a property.
Parameters:
Name Type Description
property String The name of the property to fetch the value of.
Returns:
Property value. {*}
Inherited From:

instance.hide

Hide this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.off

Remove an event listener.
Parameters:
Name Type Optional Description
eventName String No
 The event name to stop listening for.
selector String Yes
 The selector that was used for event delegation.
func function No
 The function that was passed to on().
useCapture Boolean Yes
 Only remove listeners with useCapture set to the value passed in.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.on

Add an event listener.
Parameters:
Name Type Optional Default Description
eventName String No
 The event name to listen for.
selector String Yes
 The selector to use for event delegation.
func function No
 The function that will be called when the event is triggered.
useCapture Boolean Yes
 Whether or not to listen during the capturing or bubbling phase.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.remove

Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
Inherited From:

instance.set

Set a single property.
Parameters:
Name Type Description
property String The name of the property to set.
value * The value to set the property to.
silent Boolean If true, events should not be triggered as a result of this set.
Returns:
this, chainable. {Coral.Component}
Inherited From:

instance.setNextColumn

Sets the next column given a reference column. This will handle cleaning the DOM and removing any columns as required.
Parameters:
Name Type Optional Default Description
newColumn HTMLElement No
 The new column to add to the column view. It will be placed next to the referenceColumn if provided.
referenceColumn HTMLElement No
 The column that will be used as a reference to place the new column. This column needs to be already inside the DOM.
scrollToColumn Boolean Yes
 Whether the columnview show scroll to have the newColumn visible.
Fires:
  • Coral.ColumnView#event:coral-columnview:navigate

instance.show

Show this component.
Returns:
this, chainable {Coral.Component}
Inherited From:

instance.trigger

Trigger an event.
Parameters:
Name Type Optional Default Description
eventName String No
 The event name to trigger.
props Object Yes
 Additional properties to make available to handlers as event.detail.
bubbles Boolean Yes
 Set to false to prevent the event from bubbling.
cancelable Boolean Yes
 Set to false to prevent the event from being cancelable.
Returns:
CustomEvent object {CustomEvent}
Inherited From:

Events

coral-component:attached

Triggered when the component is attached to the DOM.
Callback Parameters:
Name Type Description
event Object Event object.
Inherited From:
Deprecated:
  • since 1.14.0, use MutationObserver instead.

    coral-component:detached

    Triggered when the component is detached to the DOM.
    Callback Parameters:
    Name Type Description
    event Object Event object.
    Inherited From:
    Deprecated:
    • since 1.14.0, use MutationObserver instead.

      coral-component:ready

      Triggerred when the component has been upgraded and is ready for use.
      Callback Parameters:
      Name Type Description
      event Object Event object.
      Inherited From:
      Deprecated:
      • since 1.9.0, use Coral.commons.ready() instead.

        Coral.ColumnView.Item API

        Constructor

        JavaScript:

        new Coral.ColumnView.Item() or document.createElement('coral-columnview-item')

        HTML Tag:

        <coral-columnview-item>

        Extends

        Sub-components

        Static Properties

        Coral.ColumnView.Item.variant {String}

        Enum for item variants.

        Properties:

        Name Type Value Description
        DEFAULT String default Default item variant. Contains no special decorations.
        DRILLDOWN String drilldown An item with a right arrow indicating that the navigation will go one level down.

        Instance Properties

        instance.active {Boolean}

        Reflected
        Whether the item is active.
        Default Value:
        • false

        instance.content {HTMLElement}

        The content of the item.

        instance.hidden {Boolean}

        Reflected
        Whether this component is hidden or not.
        Inherited From:
        Default Value:
        • false
        HTML Attribute:
        • hidden

        instance.icon {String}

        Specifies the icon that will be placed inside the thumbnail. The size of the icon is always controlled by the component.
        Default Value:
        • ""
        HTML Attribute:
        • icon

        instance.selected {Boolean}

        Reflected
        Whether the item is selected.
        Default Value:
        • false
        HTML Attribute:
        • selected

        instance.thumbnail {HTMLElement}

        The thumbnail of the item. It is used to hold an icon or an image.

        instance.variant {Coral.ColumnView.Item.variant}

        Reflected
        The item's variant.
        Default Value:
        • Coral.ColumnView.Item.variant.DEFAULT
        HTML Attribute:
        • variant

        Methods

        instance.get

        Get the value of a property.
        Parameters:
        Name Type Description
        property String The name of the property to fetch the value of.
        Returns:
        Property value. {*}
        Inherited From:

        instance.hide

        Hide this component.
        Returns:
        this, chainable {Coral.Component}
        Inherited From:

        instance.off

        Remove an event listener.
        Parameters:
        Name Type Optional Description
        eventName String No
        		 The event name to stop listening for.
        selector String Yes
        		 The selector that was used for event delegation.
        func function No
        		 The function that was passed to on().
        useCapture Boolean Yes
        		 Only remove listeners with useCapture set to the value passed in.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.on

        Add an event listener.
        Parameters:
        Name Type Optional Default Description
        eventName String No
        		 The event name to listen for.
        selector String Yes
        		 The selector to use for event delegation.
        func function No
        		 The function that will be called when the event is triggered.
        useCapture Boolean Yes
        		 Whether or not to listen during the capturing or bubbling phase.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.remove

        Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
        Inherited From:

        instance.set

        Set a single property.
        Parameters:
        Name Type Description
        property String The name of the property to set.
        value * The value to set the property to.
        silent Boolean If true, events should not be triggered as a result of this set.
        Returns:
        this, chainable. {Coral.Component}
        Inherited From:

        instance.show

        Show this component.
        Returns:
        this, chainable {Coral.Component}
        Inherited From:

        instance.trigger

        Trigger an event.
        Parameters:
        Name Type Optional Default Description
        eventName String No
        		 The event name to trigger.
        props Object Yes
        		 Additional properties to make available to handlers as event.detail.
        bubbles Boolean Yes
        		 Set to false to prevent the event from bubbling.
        cancelable Boolean Yes
        		 Set to false to prevent the event from being cancelable.
        Returns:
        CustomEvent object {CustomEvent}
        Inherited From:

        Events

        coral-component:attached

        Triggered when the component is attached to the DOM.
        Callback Parameters:
        Name Type Description
        event Object Event object.
        Inherited From:
        Deprecated:
        • since 1.14.0, use MutationObserver instead.

          coral-component:detached

          Triggered when the component is detached to the DOM.
          Callback Parameters:
          Name Type Description
          event Object Event object.
          Inherited From:
          Deprecated:
          • since 1.14.0, use MutationObserver instead.

            coral-component:ready

            Triggerred when the component has been upgraded and is ready for use.
            Callback Parameters:
            Name Type Description
            event Object Event object.
            Inherited From:
            Deprecated:
            • since 1.9.0, use Coral.commons.ready() instead.

              Coral.ColumnView.Column API

              Constructor

              JavaScript:

              new Coral.ColumnView.Column() or document.createElement('coral-columnview-column')

              HTML Tag:

              <coral-columnview-column>

              Extends

              Sub-components

              Instance Properties

              instance.activeItem {HTMLElement}

              Readonly
              The current active item.

              instance.content {HTMLElement}

              The content of the column. This container is where the items should be added and is responsible for handling the scrolling.

              instance.hidden {Boolean}

              Reflected
              Whether this component is hidden or not.
              Inherited From:
              Default Value:
              • false
              HTML Attribute:
              • hidden

              instance.items {Coral.Collection}

              Readonly
              The Collection Interface that allows interacting with the items that the component contains. See Coral.Collection for more details.

              instance.selectedItem {HTMLElement}

              Readonly
              Returns the first selected item in the ColumnView. The value null is returned if no element is selected.

              instance.selectedItems {Array.<HTMLElement>}

              Readonly
              Returns an Array containing the set selected items inside this Column.

              Methods

              instance.get

              Get the value of a property.
              Parameters:
              Name Type Description
              property String The name of the property to fetch the value of.
              Returns:
              Property value. {*}
              Inherited From:

              instance.hide

              Hide this component.
              Returns:
              this, chainable {Coral.Component}
              Inherited From:

              instance.off

              Remove an event listener.
              Parameters:
              Name Type Optional Description
              eventName String No
              		 The event name to stop listening for.
              selector String Yes
              		 The selector that was used for event delegation.
              func function No
              		 The function that was passed to on().
              useCapture Boolean Yes
              		 Only remove listeners with useCapture set to the value passed in.
              Returns:
              this, chainable. {Coral.Component}
              Inherited From:

              instance.on

              Add an event listener.
              Parameters:
              Name Type Optional Default Description
              eventName String No
              		 The event name to listen for.
              selector String Yes
              		 The selector to use for event delegation.
              func function No
              		 The function that will be called when the event is triggered.
              useCapture Boolean Yes
              		 Whether or not to listen during the capturing or bubbling phase.
              Returns:
              this, chainable. {Coral.Component}
              Inherited From:

              instance.remove

              Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
              Inherited From:

              instance.set

              Set a single property.
              Parameters:
              Name Type Description
              property String The name of the property to set.
              value * The value to set the property to.
              silent Boolean If true, events should not be triggered as a result of this set.
              Returns:
              this, chainable. {Coral.Component}
              Inherited From:

              instance.show

              Show this component.
              Returns:
              this, chainable {Coral.Component}
              Inherited From:

              instance.trigger

              Trigger an event.
              Parameters:
              Name Type Optional Default Description
              eventName String No
              		 The event name to trigger.
              props Object Yes
              		 Additional properties to make available to handlers as event.detail.
              bubbles Boolean Yes
              		 Set to false to prevent the event from bubbling.
              cancelable Boolean Yes
              		 Set to false to prevent the event from being cancelable.
              Returns:
              CustomEvent object {CustomEvent}
              Inherited From:

              Events

              coral-component:attached

              Triggered when the component is attached to the DOM.
              Callback Parameters:
              Name Type Description
              event Object Event object.
              Inherited From:
              Deprecated:
              • since 1.14.0, use MutationObserver instead.

                coral-component:detached

                Triggered when the component is detached to the DOM.
                Callback Parameters:
                Name Type Description
                event Object Event object.
                Inherited From:
                Deprecated:
                • since 1.14.0, use MutationObserver instead.

                  coral-component:ready

                  Triggerred when the component has been upgraded and is ready for use.
                  Callback Parameters:
                  Name Type Description
                  event Object Event object.
                  Inherited From:
                  Deprecated:
                  • since 1.9.0, use Coral.commons.ready() instead.

                    Coral.ColumnView.Preview API

                    Constructor

                    JavaScript:

                    new Coral.ColumnView.Preview() or document.createElement('coral-columnview-preview')

                    HTML Tag:

                    <coral-columnview-preview>

                    Extends

                    Sub-components

                    Instance Properties

                    instance.content {HTMLElement}

                    The content of the Preview.

                    instance.hidden {Boolean}

                    Reflected
                    Whether this component is hidden or not.
                    Inherited From:
                    Default Value:
                    • false
                    HTML Attribute:
                    • hidden

                    Methods

                    instance.get

                    Get the value of a property.
                    Parameters:
                    Name Type Description
                    property String The name of the property to fetch the value of.
                    Returns:
                    Property value. {*}
                    Inherited From:

                    instance.hide

                    Hide this component.
                    Returns:
                    this, chainable {Coral.Component}
                    Inherited From:

                    instance.off

                    Remove an event listener.
                    Parameters:
                    Name Type Optional Description
                    eventName String No
                    		 The event name to stop listening for.
                    selector String Yes
                    		 The selector that was used for event delegation.
                    func function No
                    		 The function that was passed to on().
                    useCapture Boolean Yes
                    		 Only remove listeners with useCapture set to the value passed in.
                    Returns:
                    this, chainable. {Coral.Component}
                    Inherited From:

                    instance.on

                    Add an event listener.
                    Parameters:
                    Name Type Optional Default Description
                    eventName String No
                    		 The event name to listen for.
                    selector String Yes
                    		 The selector to use for event delegation.
                    func function No
                    		 The function that will be called when the event is triggered.
                    useCapture Boolean Yes
                    		 Whether or not to listen during the capturing or bubbling phase.
                    Returns:
                    this, chainable. {Coral.Component}
                    Inherited From:

                    instance.remove

                    Non-destructively remove this element. It can be re-added by simply appending it to the document again. It will be garbage collected if there are no more references to it.
                    Inherited From:

                    instance.set

                    Set a single property.
                    Parameters:
                    Name Type Description
                    property String The name of the property to set.
                    value * The value to set the property to.
                    silent Boolean If true, events should not be triggered as a result of this set.
                    Returns:
                    this, chainable. {Coral.Component}
                    Inherited From:

                    instance.show

                    Show this component.
                    Returns:
                    this, chainable {Coral.Component}
                    Inherited From:

                    instance.trigger

                    Trigger an event.
                    Parameters:
                    Name Type Optional Default Description
                    eventName String No
                    		 The event name to trigger.
                    props Object Yes
                    		 Additional properties to make available to handlers as event.detail.
                    bubbles Boolean Yes
                    		 Set to false to prevent the event from bubbling.
                    cancelable Boolean Yes
                    		 Set to false to prevent the event from being cancelable.
                    Returns:
                    CustomEvent object {CustomEvent}
                    Inherited From:

                    Events

                    coral-component:attached

                    Triggered when the component is attached to the DOM.
                    Callback Parameters:
                    Name Type Description
                    event Object Event object.
                    Inherited From:
                    Deprecated:
                    • since 1.14.0, use MutationObserver instead.

                      coral-component:detached

                      Triggered when the component is detached to the DOM.
                      Callback Parameters:
                      Name Type Description
                      event Object Event object.
                      Inherited From:
                      Deprecated:
                      • since 1.14.0, use MutationObserver instead.

                        coral-component:ready

                        Triggerred when the component has been upgraded and is ready for use.
                        Callback Parameters:
                        Name Type Description
                        event Object Event object.
                        Inherited From:
                        Deprecated:
                        • since 1.9.0, use Coral.commons.ready() instead.