ESCO Content Menu (Lit version)

Installation

# install with npm
npm install @uportal/esco-content-menu-lit

# install with yarn
yarn add @uportal/esco-content-menu-lit

install with maven

<dependency>
    <groupId>org.webjars.npm</groupId>
    <artifactId>uportal__esco-content-menu-lit</artifactId>
    <version>{version number goes here}</version>
</dependency>

install with gradle

compile 'org.webjars.npm:uportal__esco-content-menu-lit:{version number goes here}'

Usage as Web Component

internationalization

The hamburger-menu, content-grid, and content-menu components support an internationalization mixin. This adds the additional prop messages which can be applied to override the default text messages in the various components. This property will trickle down to the PortletCard and ActionFavorites components, as well.

For example:

<esco-hamburger-menu
  messages='[{"locales": ["en", "en-US"], "messages": { "message": {"favorites": { "add": "Add me to your favorites!" } }}}]'
>
</esco-hamburger-menu>

The available messages to override are as follows:

{
  "message": {
    "services": {
      "title": "All services",
      "filter": "Find a service..."
    },
    "favorites": {
      "add": "Add to favorites",
      "remove": "Remove from favorites",
      "title": "My Favorites",
      "empty": "No favorite defined"
    },
    "filter": {
      "selectOption": "All categories"
    },
    "userInfoPortletUrl": {
      "title": "See my account informations"
    },
    "userChangeEtabUrl": {
      "title": "Select an other organization"
    },
    "buttons": {
      "logout": "Sign out",
      "menuClose": "Close menu"
    }
  }
}

The hamburger menu

This is the main component that show a hamburger menu and that open an entire page with content-menu component.

Html

<script
  src="/resource-server/webjars/uportal__esco-content-menu/dist/js/esco-content-menu.min.js"
  defer
></script>

<esco-hamburger-menu
  default-org-logo="..."
  api-url-org-info="..."
  portlet-api-url="..."
  layout-api-url="..."
  organization-api-url="..."
  user-info-api-url="..."
  context-api-url="/uPortal"
  sign-out-url="/uPortal/Logout"
  default-org-logo="https://www.toureiffel.paris/sites/default/files/styles/1440x810/public/2017-10/monument-landing-header-bg_0.jpg?itok=_dSLLBlZ"
  user-info-portlet-url="/uPortal/user-details"
  favorites-portlet-card-size="small"
  grid-portlet-card-size="auto"
  hide-action-mode="never"
>
</esco-hamburger-menu>

For some integration you could need a bit more, like into uPortal you will need to add a parent div and to apply on his closest parent section a style float: left.

Properties

• messages: type: Array of Objects, see internationalization
• context-api-url: type: String, default: /uPortal, useful to provide a different uPortal context on which to do request
• favorite-api-url: type: String, default: /uPortal/api/layout, the uri/url of the favorites api
• layout-api-url: type: String, default: /uPortal/api/v4-3/dlm/layout.json, the uri/url of the layout api to request the favorite list in the oser defined order (only needed to get favorite's order defined by the user)
• portlet-api-url: type: String, default: /uPortal/api/v4-3/dlm/portletRegistry.json, the uri/url of the portletRegistry api to obtains user authorized portlet list
• userInfo-api-url: type: String, default: /uPortal/api/v5-1/userinfo, url/uri on which the api request is done to obtain user information and the jwt token
• organization-api-url: type: String, optional, an uri/url of an api to retrieve organization informations, any json format is accepted, but configure user-org-id-attribute-name, user-all-orgs-id-attribute-name, org-logo-url-attribute-name to work with.
• sign-out-url: type: String, default: /uPortal/Logout, an uri/url to call when user logout (for a logout button),
• default-org-logo: type: String, required: true, an url/uri to provide an institutional picture when none is found from an optional api (not provided into uPortal),
• user-info-portlet-url: type: String, default: '', an url/uri to the user information application,
• switch-org-portlet-url: type: String, default: '', an optional url/url of a rest api to obtain institutional organization information
• switch-org-event: type: Boolean, default: false, open change etab modal. switch-org-portlet-url need to be change etab api url.
• favorites-portlet-card-size: type: possible value auto|large|medium|small|smaller, default: small, define the size of portlet-cards component into favorite-content component part
• grid-portlet-card-size: type: possible value auto|large|medium|small|smaller, default: medium, define the size of portlet-cards component into grid-content component part,
• hide-action-mode: type: possible value auto|always|never, default: auto, define if we should show the actions, auto don't show on small breakpoint,
• user-org-id-attribute-name: type: String, default: 'ESCOSIRENCourant[0]', the attribute object path to obtain the id of the organization to retrieve from the organization's api
• user-all-orgs-id-attribute-name: type: String, default: 'ESCOSIREN, the attribute object path to obtain all ids of the organizations linked to the user and to retrieve from the organization's api
• org-logo-url-attribute-name: type: String, default: 'otherAttributes.ESCOStructureLogo[0]', the attribute object path to obtain the organization Picture from organization details obtained from the organization's api
• force-org-logo: type: String, optional, an url/uri to provide an institutional picture overriding the default-org-logo and the institutional one obtained by an api (used to have an overview before updating change to every users from the api),
• show-favorites-in-slider: type: Boolean, default: false, tell component to show favorites list in a slider.
• debug: type: Boolean, default: false, for the demo/debug mode to be able to run in a standalone way (disable api call).

Events

Emitted

• toggle: target: component, details: fname,chanId,isFavorite, Emit when menu is open or close.

Slots

The HTML content of the component can also be modified using slots.

Menu Icon

The menu-icon slot permit to apply a custom icon replacing the default Hamburger one. As example:

<esco-hamburger-menu
  default-org-logo="..."
  api-url-org-info="..."
  portlet-api-url="..."
  layout-api-url="..."
  organization-api-url="..."
  user-info-api-url="..."
  favorites-portlet-card-size="small"
  grid-portlet-card-size="auto"
  hide-action-mode="never"
>
  <div
    slot="menu-icon"
    style="background-image:url('https://mdbootstrap.com/img/svg/hamburger3.svg?color=FFF');height:20px;width:20px;"
  ></div>
</esco-hamburger-menu>

Menu Content

The menu-content slot permit to apply an other content than the esco-content-menu sub-component.

<esco-hamburger-menu
  favorites-portlet-card-size="small"
  grid-portlet-card-size="auto"
  hide-action-mode="never"
>
  <div slot="menu-content">whatever...</div>
</esco-hamburger-menu>

The content menu

This component is a main one as it will load into one page all main elements (the user + organization information, the favorites and the list of services )

Html

<script
  src="/resource-server/webjars/uportal__esco-content-menu/dist/esco-content-menu.min.js"
  defer
></script>

<esco-content-menu
  sign-out-url="/uPortal/Logout"
  default-org-logo="https://www.toureiffel.paris/sites/default/files/styles/1440x810/public/2017-10/monument-landing-header-bg_0.jpg?itok=_dSLLBlZ"
  user-info-portlet-url="/uPortal/user-details"
  favorites-portlet-card-size="small"
  grid-portlet-card-size="auto"
  hide-action-mode="never"
>
</esco-content-menu>

Properties

This use the same properties from the hamburger-menu (see on hamburger-menu details):

• messages
• context-api-url
• favorite-api-url
• layout-api-url
• organization-api-url
• user-info-api-url
• portlet-api-url
• sign-out-url
• default-org-logo
• user-info-portlet-url
• switch-org-portlet-url
• favorites-portlet-card-size
• grid-portlet-card-size
• hide-action-mode
• user-org-id-attribute-name
• user-all-orgs-id-attribute-name
• org-logo-url-attribute-name
• force-org-logo
• debug

and with additional properties to work with the hamburger-menu:

• ~~call-on-close: type: Function, default: {}, provide to this property a callback function to call after clicking on the header-button close of the header-buttons component.~~ Deprecated, use close event instead.
• show-favorites-in-slider: type: Boolean, default: false, if present (true), show favorites in a slider.
• is-hidden: type: Boolean, default: false, used by the hamburger-menu to indicate the state of the page.
• ~~id: type: String, default: null, provide an id to be able to select the dom element, as example if you want to manage manualy an hamburger-menu~~ Deprecated.

Events

Emitted

• close: target: component, Emited when close button is clicked. Replace call-on-close attribute.

Slots

The HTML content of the component can also be modified using slots.

Content User

The content-user slot permit to apply a custom component at this place, or to remove it. As example:

<esco-content-menu
  sign-out-url="/uPortal/Logout"
  default-org-logo="https://www.toureiffel.paris/sites/default/files/styles/1440x810/public/2017-10/monument-landing-header-bg_0.jpg?itok=_dSLLBlZ"
  favorites-portlet-card-size="small"
  grid-portlet-card-size="auto"
  hide-action-mode="never"
>
  <div slot="content-user"></div>
</esco-content-menu>

Header Buttons

The header-buttons slot permit to apply a custom component at this place, or to remove it. As example:

<esco-content-menu
  sign-out-url="/uPortal/Logout"
  default-org-logo="https://www.toureiffel.paris/sites/default/files/styles/1440x810/public/2017-10/monument-landing-header-bg_0.jpg?itok=_dSLLBlZ"
  favorites-portlet-card-size="small"
  grid-portlet-card-size="auto"
  hide-action-mode="never"
>
  <div slot="header-buttons"></div>
</esco-content-menu>

The content grid

This component provide a flexbox way to show a list of portlet-card, depending on uPortal rest-api.

Html

<script
  src="/resource-server/webjars/uportal__esco-content-menu/dist/esco-content-menu.min.js"
  defer
></script>

<esco-content-grid
  portlet-card-size="gridPortletCardSize"
  hide-action="hideAction"
>
</esco-content-grid>

Properties

Standalone properties:

• messages: type: Array of Objects, see internationalization
• background-color: type: String, default: rgba(0, 0, 0, 0), to apply a different background-color
• ~~call-after-action: type: Function, default: undefined, a callback function to call into portlet-card embeding action-favorite after adding portlet to favorites,~~ Deprecate, use event toggle-favorite instead.
• context-api-url: type: String, default: /uPortal, usefull to provide a different uPortal context on which to do request,
• favorite-api-url: type: String, default: /uPortal/api/layout, the uri/url of the favorites api
• layout-api-url: type: String, default: /uPortal/api/v4-3/dlm/layout.json, the uri/url of the layout api to request the favorite list in the other defined order (only needed to get favorite's order defined by the user)
• portlet-api-url: type: String, default: /uPortal/api/v4-3/dlm/portletRegistry.json, the uri/url of the portletRegistry api to obtains user authorized portlet list
• user-info-api-url: type: String, default: /uPortal/api/v5-1/userinfo, url/uri on which the api request is done to obtain user information and the jwt token
• portlet-card-size: type: possible value auto|large|medium|small|smaller|custom, default: auto, define the size of portlet-cards component.
• hide-action: type: Boolean, default: false, define to hide or not the action-favorite button defined into portlet-card
• show-footer-categories: Boolean, default: false, define to display category dropdown filter near bottom of grid
• hide-title: Boolean, default: false, define to remove the title area from the grid, useful when a basic grid is desired
• portlet-background-is-dark: Boolean, default: false, indicate to the component that the parent background is dark and permit to the portlet-card component to show buttons like favorites in a more suitable color.
• debug: type: Boolean, default: false, for the demo/debug mode to be able to run in a standalone way (disable api call)
• card-hover-src: type: possible value none|title|desc|description, default: none, set the hover text for the grid cards to one of the portlet definition values title or description

and additional properties to work with the parent component content-menu:

• parent-screen-size: type: possible value large|medium|small|smaller|custom, default: medium, permit to indicate the breakpoint view of the parent.
• portlets: type: Array, default: [], used if the list of portlets is loaded and provided from a parent component,
• favorites: type: Array, default: [], used if the list of favorites portlets loaded and provided from a parent component,
• all-categories: type: Array, default: [], set or get the list of categories,

Events

Emited

• gridFavoritesUpdated, target : window, details: fname,chanId,isFavorite, emitted when a portlet is added to favorites.
• esco-cm-grid-filter, target : window, details: category,value, emited when portlets are filteredor when esco-cm-request-grid-filter event is received.
• esco-cm-categories, target : window, details: categories, emited when categories list is calculated or when esco-cm-request-categories event is received.
• toggle-favorite, target : component, details: fname,chanId,isFavorite, emited when a portlet is added to favorites.

Listened

• esco-cm-grid-filter, details: category,value, when received, use detail to filter portlets list.
• esco-cm-request-grid-filter, when received, emit esco-cm-grid-filter event with the filter parameters in detail.
• esco-cm-request-categories, when received, emit esco-cm-categories event with the categories list in detail.
• gridFavoritesUpdated, when received, reload portlets.

Slots

The HTML content of the component can also be modified using slots.

Header Left

The header-left slot permit to apply a custom title replacing the default "All services" one. As example:

<esco-content-grid
  background-color="grey"
  portlet-card-size="medium"
  portlet-api-url="/uPortal/api/v4-3/dlm/portletRegistry.json?category=administration"
  layout-api-url="..."
>
  <h1 slot="header-left">Administration</h1>
</esco-content-grid>

Header Right

The header-right slot permit to apply a custom title replacing the default filter on right. As example:

<esco-content-grid
  background-color="grey"
  portlet-card-size="medium"
  portlet-api-url="/uPortal/api/v4-3/dlm/portletRegistry.json?category=administration"
  layout-api-url="..."
>
  <div slot="header-rigth"></div>
</esco-content-grid>

Preamble

The preamble slot permit to add descriptive text between the headers and grid. As example:

<esco-content-grid
  background-color="grey"
  portlet-card-size="medium"
  portlet-api-url="/uPortal/api/v4-3/dlm/portletRegistry.json?category=administration"
  layout-api-url="..."
>
  <div slot="preamble">This is explanatory text for the grid.</div>
</esco-content-grid>

Footer

The footer slot permit to apply a custom title replacing the default filter on footer. As example:

<esco-content-grid
  background-color="grey"
  portlet-card-size="medium"
  portlet-api-url="/uPortal/api/v4-3/dlm/portletRegistry.json"
  layout-api-url="..."
>
  <div slot="footer"></div>
</esco-content-grid>

Theming

This component supports CSS Variables for overriding some default values. So defining the following variables will override default values.

:root {
  --content-grid-flex-grid-justify: center; // How to justify all flex grid elements, default value is center
  --content-grid-flex-grid-item-margin: 20px auto; // To set a margin on all flex items, default is `20px auto`
}

The action favorite

The component action-favorite is really simple, it show a start button that permit to add or remove from favorites a portlet.

Html

<script
  src="/resource-server/webjars/uportal__esco-content-menu/dist/esco-content-menu.min.js"
  defer
></script>

<esco-action-favorite portlet-card-size="small" hide-action="false">
</esco-action-favorite>

Properties

• messages: type: Array of Objects, see internationalization
• ~~call-on-toggle-fav: type: Function, default: {}, a callback function called after the click event on the button,~~ Deprecated, use toggle event instead.
• chan-id: type: String, required: true, the portlet id to add or remove from user favorites,
• ~~favorite-api-url: type: String, default: /uPortal/api/layout, the uri/url of the favorites api,~~ Deprecated.
• ~~user-info-api-url: type: String, default: /uPortal/api/v5-1/userinfo, url/uri on which the api request is done to obtain user information and the jwt token,~~ Deprecated.
• fname: type: String, required: true, the portlet fname that permit to identify the portlet into favorite's list, usefull for the callback function and apply a css class,
• is-favorite: type: Boolean, default: false, provide the favorite state,
• back-ground-is-dark: type: Boolean, default: false, permit to apply a style depending on background color, as the component is used as embedded,
• ~~debug: type: Boolean, default: false, for the demo/debug mode to be able to run in a standalone way (disable favorites api call)~~ Deprecated

Events

Emitted

• toggle, target : component, details: fname,chanId,isFavorite, emited when button is clicked.

Theming

This component supports CSS Variables for overriding some default values. So defining the following variables will override default values.

:root {
  --action-favorites-dark-background-icon-color: #010101; // To set a different color of the favorite svg icon when background is dark.
  --action-favorites-normal-icon-color: red; // To set a different color of the favorite svg icon when background is normal.
}

The content favorites

The component is functional only into the content-menu, it needs that a portlet list and favorite list is passed

Somme work would be needed to move on the content-carousel.

The content user

This component permit to show user information with their organization information. Few work would be need to be able to use it as a standalone component: like having a fetch service like for portlets or favorite. But some parts are institutional developpments to be able to obtain organization informations, so we are waiting new usecase before to do something.

Html

Need some work for a standalone use.

Properties

• messages: type: Array of Objects, see internationalization.
• org-display-name: type: String, default: '', organization name to display.
• org-img-url: type: String, default: '', url of the organization image to display.
• user-display-name: type: String, default: '', user name to display.
• user-avatar-url: type: String, default: '', url of the user avatar image to display.
• switch-org-portlet-url: type: String, default: '', an url/uri where the user can switch of organization when having several (tenant use part). Let empty to not show the button.
• user-info-portlet-url: type: String, default: '', an url/uri to the user information application,
• ~~org-info: type: Object, default: {}, the current user organization detail object,~~ Deprecated.
• ~~other-orgs: type: Array, default: [], all other organizations details object when the user have several,~~ Deprecated.
• ~~user-info: type: Object, required: true, the user information object,~~ Deprecated.
• ~~default-org-logo: type: String, required: true, an url/uri to provide an institutional picture when none is found from an optional api (not provided into uPortal),~~ Deprecated.
• ~~org-logo-url-attribute-name: type: String, default: 'otherAttributes.ESCOStructureLogo[0]', the attribute object path to obtain the organization Picture from organization details obtained from the organization's api.~~
• ~~force-org-logo: type: String, optional, an url/uri to provide an institutional picture overriding the default-org-logo and the institutional one obtained by an api (used to have an overview before updating change to every users from the api),~~

and additional properties to work with the parent component content-menu:

• parent-screen-size: type: possible value large|medium|small|smaller, default: medium, permit to indicate the breakpoint view of the parent.

The portlet card

This component render informations about a portlet as a card.

Html

<script
  src="/resource-server/webjars/uportal__esco-content-menu/dist/esco-content-menu.min.js"
  defer
></script>

<esco-portlet-card portlet-desc="portlet" size="small" hide-action="true">
</esco-portlet-card>

Properties

• messages: type: Array of Objects, see internationalization.
• portlet-desc: type: Object, required: true, the portlet description object
• size: type: possible value large|medium|small|smaller|custom, default: medium, the fixed size of card to apply
• css-class: type: string, default: portlet-card, class name give to the main div of the component
• card-hover-src: type: possible value none|title|desc|description, default: none, set the hover text for the grid cards to one of the portlet definition values title or description
• hide-action: type: Boolean, default: false, define to hide or not the action-favorite button
• back-ground-is-dark: type: Boolean, default: false, permit to apply a style depending on background color, as the component is used as embeded,
• is-favorite: type: Boolean, default: false, provide the favorite state (passed to the action-favorite component),
• ~~call-after-action: type: Function, default: {}, callback function to call after click on action-favorite button (passed to the action-favorite component),~~ deprecated, use toggle-favorite event instead
• icon-background-color: type: String, default: Transparent, could be used to apply a background-color behind a portlet icon - usecase if there isn't background on icon.
• ~~favorite-api-url: type: String, default: /uPortal/api/layout, the uri/url of the favorites api (passed to the action-favorite component),~~ deprecated
• ~~user-info-api-url: type: String, default: /uPortal/api/v5-1/userinfo, url/uri on which the api request is done to obtain user information and the jwt token, (passed to the action-favorite component),~~ deprecated
• debug: type: Boolean, default: false, for the demo/debug mode to be able to run in a standalone way (disable api call).

Events

Emitted

• toggle-favorite, target : component, details: fname,chanId,isFavorite, emited when toggle event of embed action-favorite is emitted.

The content grid category filter

This component is an external version of the filter built into Content Grid that allows for arbitrary placement on the page.

Html

<script
  src="/resource-server/webjars/uportal__esco-content-menu/dist/esco-content-menu.min.js"
  defer
></script>

<esco-content-grid
  portlet-card-size="gridPortletCardSize"
  hide-action="hideAction"
>
</esco-content-grid>

<esco-content-grid-filter></esco-content-grid-filter>

Properties

• categories,type: array,default: [], list of the categories, can be used to preset them
• filter-Category,type: string,default: '', current selected category, can be used to preset it

Events

Emited

• esco-cm-grid-filter, target : window, details: category, emited when category is choosen or when esco-cm-request-grid-filter event is received.
• esco-cm-request-categories, target : window, details: categories, emited when categories list is calculated or when esco-cm-request-categories event is received.

Listened

• esco-cm-grid-filter, details: category,value, when received, use detail to update the selected category.
• esco-cm-request-grid-filter, when received, emit esco-cm-grid-filter event with the filter parameters in detail.
• esco-cm-request-categories, when received, emit esco-cm-categories event with the categories list in detail.
• esco-cm-categories, when received, update categories list

The ellipsis

This component permit to apply an auto-fit/trunc or a line-clamping to a text when the div size should be limited. It avoids to apply an overflow: hidden and permit to manage an ellipsis on several line.

Html

<script src="/resource-server/webjars/uportal__esco-content-menu/dist/esco-content-menu.min.js" defer></script>

<esco-ellipsis
  message="text">
</esco-elipsis>

Properties

• message: type: String, default: '', the text to "ellipsise",
• line-clamp: type: Number, default: 0, when we want a number of line, else will apply an auto-fit on the available size (the parent should have a defined height),
• line-height: type: String, default: '22px', the line heigth of the text is required for the auto-fit,
• end-char: type: String, default: '...', a text to apply when a trunc appear,
• end-html: type: String, default: '', a text to apply at end of the html.

The header buttons

This component render a header part with some main buttons, like closing the page menu or to sign out.

Html

<script src="/resource-server/webjars/vue/dist/vue.min.js"></script>
<script
  src="/resource-server/webjars/uportal__esco-content-menu/dist/esco.min.js"
  defer
></script>

<esco-header-button call-on-close="function"> </esco-header-button>

Properties

• call-on-close: type: Function, default: {}, callback function on click on the close button,
• sign-out-url: type: String, default: /uPortal/Logout, an uri/url to call when user logout (for a logout button),

FAQ

• Q: What does "ESCO" mean?
• A: "ESCO" is an abbreviation of "e-scolaire", French for Online School.

Theming

Currently this component supports CSS Variables for overriding button colors. Defining the following variables will change the colors for the component accordingly. They will fall back to the colors described below.

NOTE: This is only supported when the size attribute is set to custom.

You should define this in your custom stylesheet.

:root {
  --content-gridcard-padding: 5px;
  --content-gridcard-border: none;
  --content-gridcard-bg-color: white;
  --content-gridcard-border-radius: 5px;
  --content-gridcard-shadow: none;
  --content-gridcard-shadow-hover: none;
  --content-gridcard-size-w: 180px;
  --content-gridcard-size-h: 180px;
  --content-gridcard-icon-size: 75px;
  --content-gridcard-icon-size: 75px;
  --content-gridcard-title-fontsize: 16px;
  --content-gridcard-description-fontsize: 16px;

  --content-griditem-margin: 20px auto;
}