Skip to content

CodeCoupler Costa Components Launcher

Visualizes a Component Registry and can trigger loading the components defined in the registry.

It creates a list of the components in the form:

1
2
3
4
5
6
7
8
9
<ul>
  <li>
    <div tabindex="0">
      <div class="icon">manifest.iconHtml</div>
      <div class="name">manifest.name</div>
    </div>
  </li>
  <!-- Further <li> elements  -->
</ul>

The manifest name is by default initially hidden. The user can click on an expand button to show the names. Otherwise the names will be shown in tooltips.

Groups will be displayed in popovers.

The overall inner structure of the component consists of the ul list shown above and two additional div elements that provide buttons to show and hide the names:

1
2
3
4
5
6
7
8
9
<div class="[collapsed][empty]">
  <ul>...</ul>
  <div class="toggler-expand">
    <a><!-- icon --></a>
  </div>
  <div class="toggler-collapse">
    <a><!-- icon --></a>
  </div>
</div>

Depending on its state, the root element can have the class collapsed. The div elements with the classes toggler-collapse and toggler-expand are shown and hidden in turn.

The root element gets the class empty if no li element exists or all elements are not visible to the current user because of authentication restrictions. The two toggle elements are hidden if the root element has the empty class.

Authentication

The identity parameter can be used to pass a reactive object from an authentication module. This object is monitored for changes. Any li elements that the user does not have access to are assigned the restricted class and are hidden by default:

1
2
3
4
5
<ul>
  <li class="restricted">
    <!-- ...  -->
  </li>
</ul>

Styling

The component provides only the bare minimum of styling. It simply ensures that names are shown and hidden, that the correct toggle button is displayed (or both hidden if empty), and that the mouse pointer changes when you hover over the list items or the toggle button. You will need to style it yourself to display it as desired.

CSS Classes

The internal HTML structure can be accessed as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
& .toggler-collapse,
& .toggler-expand {
  & a {}
}
&:not(.empty) ul {
  & li.restricted {}
  & li {
    & a {
      & .name {}
      & .icon {
        & svg {}
      }
    }
  }
}
/* Other possible root classes: */
&.empty {}
&.collapsed {}
Example Vertical List Styling

Here's an example of how to display the list vertically, which you could use for example in a sidebar. We use here SCSS by defining it in a placeholder (%) that is inserted in two places using @extend to avoid redundancy.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
%launcher-ul {
  flex-grow: 1;
  margin: 0;
  padding-left: 0;
  list-style: none;
  display: flex;
  flex-direction: column;

  & li {
    padding: 0.3em;

    & a {
      align-items: center;
      display: flex;
      flex-direction: row;

      & .name {
        white-space: nowrap;
        padding-left: 0.4em;
        flex-grow: 1;
      }

      & .icon {
        flex-grow: 0;

        & svg {
          width: 1.5em;
          height: 1.5em;
          display: block; /* make svg and outer div equal in size */
        }
      }
    }
  }
}

:local(.class-for-popover) {
  max-width: unset;

  & .popover-body {
    & ul {
      @extend %launcher-ul;
    }
  }
}

:local(.class-for-your-component) {
  min-height: 100%;
  width: 100%;
  display: flex;
  flex-direction: column;

  &:not(.empty) ul {
    @extend %launcher-ul;

    margin: 20px 10px 0;
  }

  & .toggler-collapse,
  & .toggler-expand {
    text-align: end;

    & svg {
      width: 1.5em;
      height: 1.5em;
    }
  }
}

Popover

The popovers will be rendered into the body of the document. For this reason, in addition to the popover class, you can assign an additional class to the popovers using the popoverClasses prop to target it more precisely.

Use this class in conjunction with the popover class to access the inner HTML elements. Otherwise, Bootstrap's predefined styles may override yours if the Bootstrap stylesheet is loaded after your own:

1
2
3
.your-class.popover {
  /* For more styling options, see below */
}

Popovers contains specific inner elements.

Header:

1
& .popover-header {}

Body:

1
& .popover-body {}

Colorizing using Bootstrap variables (example):

1
2
3
4
5
& {
  --bs-popover-arrow-border: var(--bs-green);
  --bs-popover-bg: var(--bs-green);
  --bs-popover-body-color: var(--bs-white);
}

Colorizing arrow depending on placement using plain CSS:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
&[data-popper-placement^="bottom"] > .popover-arrow::after,
&[data-popper-placement^="bottom"] > .popover-arrow::before {
  border-bottom-color: #your-color-here;
}

&[data-popper-placement^="left"] > .popover-arrow::after,
&[data-popper-placement^="left"] > .popover-arrow::before {
  border-left-color: #your-color-here;
}

&[data-popper-placement^="top"] > .popover-arrow::after,
&[data-popper-placement^="top"] > .popover-arrow::before {
  border-top-color: #your-color-here;
}

&[data-popper-placement^="right"] > .popover-arrow::after,
&[data-popper-placement^="right"] > .popover-arrow::before {
  border-right-color: #your-color-here;
}

List inside body:

Essentially, the same ul list structure is used here as in the component itself (see the previous chapter). If possible, this should be handled in SCSS by defining it in a placeholder (%) that is inserted in both places using @extend to avoid redundancy. See example above.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
& .popover-body {
  & ul {
    & li.restricted {}
    & li {
      & a {
        & .name {}
        & .icon {
          & svg {}
        }
      }
    }
  }
}

Tooltips

The tooltips will be rendered into the body of the document. For this reason, in addition to the tootip class, you can assign an additional class to the popovers using the tooltipClasses prop to target it more precisely.

Use this class in conjunction with the tooltip class to access the inner HTML elements. Otherwise, Bootstrap's predefined styles may override yours if the Bootstrap stylesheet is loaded after your own:

1
2
3
.your-class.tooltip {
  /* For more styling options, see below */
}

Tooltips contains specific inner elements.

Body:

1
& .tooltip-inner {}

Colorizing using Bootstrap variables (example):

1
2
3
4
& {
  --bs-tooltip-bg: var(--bs-green);
  --bs-tooltip-color: var(--bs-white);
}

Colorizing arrow depending on placement using plain CSS:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
&[data-popper-placement^="right"] .tooltip-arrow::before {
  border-right-color: #your-color-here;
}

&[data-popper-placement^="left"] > .popover-arrow::before {
  border-left-color: #your-color-here;
}

&[data-popper-placement^="top"] > .popover-arrow::before {
  border-top-color: #your-color-here;
}

&[data-popper-placement^="right"] > .popover-arrow::before {
  border-right-color: #your-color-here;
}

Reference

Options

identity

Reactive identity object aof an authentication module. This identity will be used to check restrictions. If a component have restrictions that do not match the identity, the component will not be shown.

registry

The registry to visualize

popoverClasses and tooltipClasses

The popoivers and tooltips will be rendered into the body of the document. For this reason, you can assign an additional classes to the popver and tooltip elements to target them more precisely.

loadOverrides

Override for every start definition object that will be used to load a component.

defaultGroupManifest: { name: String, iconHtml: String }

The default name and icon for groups.

collapsed

Is by default true. If set to false the list will be shown expanded initaially.

toggler: { enabled: Boolean, collapse: String, expand: String }

enabled is by default true. If set to false the toggle button to expand/collapse the list will be hidden.

With the properties collapse and expand you can specify the icons of the toggler which are by default SVG graphics.

hookIdentificationChange

It can be a function that is called every time the identity changes. This function receives one object as an argument with the following properties:

  • launcher: Instance of the launcher component.
  • rootListEmptyBefore: true if the list was empty before the identity change.
  • rootListEmpty: true if the list is empty after the identity change.
  • toFinalState: A function that can be called to set all classes to the final state after the identity change.
  • toInitialState: A function that reverts the class changes to the state before the identity change.
debug

If set to true the tooltips will open on click (not hover) and will never close. Popvers will never close. Useful for debuging styling.

Instance Getter

toggleCollapse, toggleExpand, rootUl

Points to the main elements <ul> and the both divs of the toggler.

allListElement

Array of all <li> elemnts. Each element has an attached data object named meta, which can be retrieved using the data function of the @codecoupler/js-bundle package.

The data object have the following properties:

  • isGroup: true if it is an element with subgroups.
  • selfRestrictedBefore: true if the element was restricted before the last identity change.
  • selfRestricted: true if the element is currently restricted.
  • restrictions: The restriction object that will be used.
  • parent: Points to the parent element if it is in a subgroup, otherwise it is set to null.
  • position: Position within a group.