Embedded learning building blocks: Course list widget

  • Published on Sep 22, 2025
  • 14 minute(s) read
Prev Next

Introduction

Embedded learning building blocks allow you to start single widgets presenting the content of your Docebo platform as part of the layout composition of any external web page, as long as you have access to its HTML and JavaScript code.

Building blocks has the advantage of modular training by using widgets that can be seamlessly injected into your HTML code using a low-code approach to guide behavior. This is coupled with the provisioning of the content, either using simple Javascript commands or a small set of HTML tag attributes, by following the generic visibility policy rules set on the platform. The integrator building the web page will be able to create the best on-the-fly learning experience for the user based on vertical training needs by customizing the widget behavior without passing through the Embedded learning configurator page of the Docebo platform.

As with the embedded learning launcher, the user who accesses the external web page must be authenticated by the Docebo platform before seeing any content on the page. Once the connection is established by granting the proper working session on the browser, the final user can be automatically provisioned with the training so that their learning flow is not interrupted, even by the need to log in.

The embedded learning building blocks course list widget provides a vertical context of training, mainly focused on obtaining compliance in specific contexts of training such as complex scenarios of customer education by providing a specific and dynamic micro catalog of courses. It is also useful for sales enablement objectives where a specific grouping of content can be used to certify a certain type of accreditation.

Activating embedded learning

To activate embedded learning, reach out to Docebo via the Help Center, or by contacting your Account Manager (if your plan includes this option).

About the course list widget

When a course is clicked on the list the course player can be opened either as part of the navigation of the widget or it can be opened in another Embedded learning building blocks: Course player widget placed in the HTML of the integrator layout.

In the same way, also when the training material in the list is clicked, the player will be started. In that scenario, if the user has been already enrolled in the course and the course prerequisites have been met then the player will show the training material selected. In case the user is not enrolled the player will show the overview page with the option to start consuming the course, based on the enrollment and catalog policies.

The course list widget has two modes, Static and Dynamic, their differences are described here.

Static mode allows you to statically host up to 20 specific courses by presenting them in a list. When the list is based on a static number of courses, the user can see only the courses based on the visibility permissions set by the Docebo platform. For example, if the course has been set as Only the admin can enroll in this course and the user doesn't see the course as they are not yet enrolled and the course is not in any visible catalog, the course will not be shown.

Dynamic mode lets you dynamically return a list of courses based on the current capability of the Docebo platform's Global Search by filtering them for numerosity, courses contained in My courses and learning plans, courses contained in visible catalogs and training material available in visible courses. When the list is based on the dynamic response of the Global Search, the user can see all the courses and the training materials returned by the visibility rules applied on the Docebo platform. Exactly like the current widget in the embedded learning launcher, the widget can be parametrized to show a given number of courses or specific areas of search such as courses contained in My courses and learning plans, courses contained in visible catalogs and training materials available in visible courses.

HTML tag

The Docebo course list requires the following tag to be inserted into the HTML of the web page to display:

<dcbo-course-list
  [LIST OF ATTRIBUTES]
>
</dcbo-course-list>

List of tag attributes

The dcbo-course-list tag can accept the following list of attributes:

Please note

All values associated with the attributes should be encapsulated in double-quotation marks. All attributes are optional, unless stated otherwise.

id

Required

The ID of the course list.

Type: String

Please note

If this attribute is not supplied, the widget becomes non-interactive via JavaScript or other widgets in the page.

type

Required

This attribute changes the course list type.

Type: String

type attribute values:

  • static

  • dynamic

courseids

The IDs list of courses separated by commas that will be displayed in the player.

Type: String

Tip:

This attribute is valid and required if the value of type is static.

widgettitle

The title of the widget.

Type: String
Default value: false

trainingmaterials

If this value is set to true or omitted, enables the drop-down of the courses contained in the Course Content search tab.

Type: Boolean
Default value: true

Tip:

This attribute is valid only if the value of the attribute type is dynamic.

mycoursesandlps

If this value is set to true or omitted, it will enable the drop-down of the courses contained in MyCourses and LPs search tab.

Type: Boolean
Default value: true

Tip:

This attribute is valid only if type is dynamic.

fromcatalogs

If this value is set to true or omitted, it will enable the drop-down of the courses contained in the Course Catalog search tab.

Type: Boolean
Default value: true

Tip:

This attribute is valid only if type is dynamic.

maxresults

Defines the number of courses shown in the list. If this value is empty or omitted, the course list will return all the results.

Type: Number
Default value: empty

Tip:

This attribute is valid only if type is dynamic.

noresulttitle

A custom title shown in the slate when the search result is empty.

Type: String
Default value: Whoops, there's nothing here

noresultdescription

A custom description shown in the slate when the search result is empty.

Type: String
Default value: Looks like there is nothing for you in this area right now

includeplayer

If this value is set to true or omitted, the player will be included on the same widget.

Type: Boolean
Default value: true

autoplay

If set to true, the video in the widget will start playing the content as soon as the Start Learning button is pressed. Otherwise it will wait for user-interaction.

This value will be sent to the included player in the same widget. For more information, please see Embedded learning building blocks: Course player widget.

Type: Boolean
Default value: false

Tip:

This attribute is considered only if the attribute includeplayer is set to true

showfullscreen

If this value is set to true or omitted, this widget will be playable in full screen, which can be activated by pressing the full-screen button in the player. If this attribute is set to false, this option will not be displayed.

This value will be sent to the included player in the same widget. For more information, please see Embedded learning building blocks: Course player widget.

Type: Boolean
Default value: true

Tip:

This attribute is considered only if the attribute includeplayer is set to true

showpip

If this value is set to true, a button allowing this widget to be played in "picture-in-picture" mode is displayed. When pressed, the output of the player is overlaid on screen. If set to false the button is hidden and the functionality is removed.

This value will be sent to the included player in the same widget. For more information please see Embedded learning building blocks: Course player widget.

Type: Boolean
Default value: true

Tip:

This attribute is considered only if the attribute includeplayer is set to true.

showtoc

If this value is set to false then the table of contents button will not be displayed.

This value will be sent to the included player in the same widget. For more information please see Embedded learning building blocks: Course player widget.

Type: Boolean
Default value: true

Tip:

This attribute is considered only if the attribute includeplayer is set to true.

forcefullscreen

If this value is set to true, this widget will be started in full-screen mode, otherwise it will remain within the constraints of the widget’s dimensions in the page.

This value will be sent to the included player in the same widget. For more information, please see Embedded learning building blocks: Course player widget.

Type: Boolean
Default value: false

Tip:

This attribute is only considered if the attribute includeplayer is set to true.

showthumbsintoc

If this value is set to true then a thumbnail preview of this content to be displayed in the table of contents.

This value will be sent to the included player in the same widget. For more information, please see Embedded learning building blocks: Course player widget.

Type: Boolean
Default value: false

Tip:

This attribute is only considered if the attribute includeplayer is set to true.

showpreview

If this value is set to false then the preview will not be displayed.

This value will be sent to the included player in the same widget. For more information, please see Embedded learning building blocks: Course player widget.

Type: Boolean
Default value: true

Tip:

This attribute is only considered if the attribute includeplayer is set to true.

tmdownloadmode

A string value of either blob or link. This attribute changes the training material download mode.

This value will be sent to the included player in the same widget. For more information, please see Embedded learning building blocks: Course player widget.

Type: String
Possible values:

  • blob

  • link

Default value: blob

Tip:

This attribute is only considered if the attribute includeplayer is set to true.

showcoursedeadline

If set to true, shows the deadline of the course in the course details tile. If set to false, the deadline of the course will not be displayed.

Please note:

The expiration date is not visible if the attribute type is set to dynamic.

Type: String
Default value: true

Tip:

This attribute shows the course deadline, not the user’s enrollment deadline for the course.

HTML tag examples

Basic course list

To display a basic course list in your page, add the following tag in the position you wish to place the widget:

<dcbo-course-list 
  id="courselist1" 
  type="dynamic"
  widgettitle="Course List DYNAMIC"
  maxresults="20">
</dcbo-course-list>

Please note that you can place this tag inside a <div> </div> tag in order to manipulate the position, size and behavior of the widget itself.

Course list used with external player

To display a course list that uses a player in a separate widget, add the following tag in the position you wish to place the widget:

<dcbo-course-list 
  id="courselist1" 
  type="dynamic"
  widgettitle="Course List DYNAMIC"
  maxresults="20"
  includeplayer="false">
</dcbo-course-list>

<dcbo-course-player 
  id="player1"
  courseid="insert valid course id"
  autoplay="true"
  forcefullscreen="false" 
  showfullscreen="true" 
  showpip="true"
  showthumbsintoc="false"
  sources="courselist1"
>
</dcbo-course-player>

Please note that you can place this tag inside a <div>⁠</div> tag in order to manipulate the position, size and behavior of the widget itself.

Static course list

To display a static course list with the course player included, add the following tag in the position you wish to place the widget:

<dcbo-course-list 
  id="courselist1" 
  includeplayer="true" 
  type="static" 
  widgettitle="Course List" 
  coursesids="181,189,190,191"
>
</dcbo-course-list>

This example will include four courses in the list, as specified by the coursesids attribute.

Please note that you can place this tag inside a <div> </div> tag in order to manipulate the position, size and behavior of the widget itself.

Widget views

The Course List Widget has different views:

The dynamic-list view in the course list widget is available only when type is dynamic. This view allows you to search courses, learning plans and training material via global search using a command. The results of the global search are split into 3 tabs (Course catalog, Training Material, My Courses and Learning Plans)

The static-list view in the course list widget is available only when type is static. This view allows you to load a maximum of 20 courses.

The myclp-courses-list is a view reachable from the My Courses and Lp tab in the dynamic-list view. This view shows the user a list of courses in the selected learning plan.

The player view integrates the Building Blocks course player widget without the preview. For more information about this view, please see Embedded learning building blocks: Course player widget.

The first visible view depends on the type tag attribute. If type is static, the first view will be the static-list otherwise dynamic-list will be the first view. The player view can be reached from all the views. In every view, if a previous view was shown, a navigation back button is also shown.

Every time the user changes their view, the data will be refreshed to keep them always up-to-date.

Commands accepted by the course list widget

Overview

The following JavaScript commands can be issued to interact with the widget embedded in your page. The commands are dependent on the ID of the widget being stated as an attribute when embedding the widget. In the following list, replace the term ID OF WIDGET with the actual ID of your widget.

To send commands to the internal player follow the single course player documentation using an internal ID with this format style:

"course list widget id"-internal-course-player

List of commands

load_courses

Load the list of courses sent via payload showing only those viewable by the user

Tip:

This command is available only when the type attribute value is static.

DSDK.getCommandBus().send(
  'load_courses', 
  'ID OF WIDGET', 
  {
    ids: "LIST OF IDS"
  }
)

Example payload:

{
  ids: "182,187,179"
}

The promise does not get resolved at this time.

search

Search via global search in the course catalog, My courses and learning plans and training material sections. The filters applied to this search depend on these attributes:

  • maxresults

  • fromcatalogs

  • trainingmaterials

  • mycoursesandlps

Tip:

This command is available only when the type attribute value is dynamic.

DSDK.getCommandBus().send(
  'search',
  'ID OF WIDGET',
  {
    text: "KEYWORD TO SEARCH"
  }
)

Example payload:

{
  text: 'Course with video'
}

The promise does not get resolved at this time.

select_item

Select the item ID of type passed. The possible item types are:

  • course
    Can be used in static and dynamic views. When the widget type is dynamic this command can be used only when course catalogs or my courses and learning plans tabs are selected.

  • learning_plan
    Can be used only in dynamic view and only when the my courses and learning plans tab is selected.

  • training_material
    Can be used only in dynamic view and only when the course content tab is selected.

DSDK.getCommandBus().send(
  'select_item', 
  'ID OF WIDGET', 
  {
    type: "ITEM TYPE",
    id:"ITEM ID"
  }
);

Example payload:

{
  type: 'course',
  id: '181'
}

When the item is selected, the promise is resolved:

{
  select: true
}

Events generated by the course list widget

Overview

The following events are generated by the course list widget usage, allowing you to listen and monitor the behavior of the user during the navigation of the widget and the consumption of the courses and training material with JavaScript to add extra functionality to your page.

To listen to the events, embedded learning provides the proper listener, which is used as follows:

DSDK.getEventManager().on('event_name', (e,p) => {console.log('Event Name => ',p);});

Tip:

In the event listener, the following variables are used:

  • event_name is the name of the event

  • e is a string representing the emitter ID

  • p is the payload which is an object that depends on the events

List of events

widget_created

The widget has been created

Payload type:

{
  id: 'string';
  type: 'WidgetType';
  view: 'FlowView';
}

widget_destroyed

The widget has been destroyed

Payload type:

{
  id: 'string';
  type: 'WidgetType';
  view: 'FlowView';
}

search_started

A search has started

Payload type:

{
  search: 'string',
  emitter: 'string'
}

Example payload:

{
  search:'course name',
  emitter: 'courseListId'
}

search_ended

A search has ended

Payload type:

{
  search: string,
  emitter: string
}

Example payload:

{
  search:'course name',
  emitter: 'courseListId'
}

item_list_loaded

A list of items has been loaded

Please note:

When the widget type, set in the tag attributes, is dynamic this event will be sent:

  • after a search ends with a result

  • when there is a tab switch in dynamic-list view (for example, if you are on the Course Catalogs tab you will receive this event when you switch to the Course Content tab and the course content items are loaded)

When the widget type, set in the tag attributes, is static this event will be sent:

  • after the widget is loaded with the initial data (the static courses)

Payload type:

{
  [
    {
      id: string,
      name: string,
      type: string
    }
  ]
  emitter: string
}

type parameter values:

  • elearning

  • learning_plan

  • training_material

Example payload:

{
  [
    {
      id: 181,
      name: "Course With Video",
      type: "elearning"
    },
    {
      id: 221,
      name: "Video1",
      type: "training_material"
    }
  ]
  emitter: 'courseListId'
}

course_loaded

A course has been loaded by the player.

This event is dispatched by the internal course player so the emitter id will be formatted as courseListId-internal-course-player.

This event is not generated by course list but by the single course player that is included in the course list.

Payload type:

{
  id: string,
  name: string,
  emitter: string
}

Example payload:

{
  id: 189, 
  name: 'Course Example', 
  emitter: 'courseListId-internal-course-player'
}

lp_course_list_loaded

A learning plan has been loaded. This event is dispatched when a user enters in the learning plan.

type parameter values:

  • elearning

  • classroom

  • webinar

Payload type:

{
  [
    {
      id: string,
      name: string,
      type: string
    }
  ]
  emitter: string
}

Example payload:

{
  [
    {
      id: 181,
      name: "Course With Video",
      type: "elearning"
    },
    {
      id: 221,
      name: "Course C2",
      type: "elearning"
    }
  ]
  emitter: 'courseListId'
}

warning_shown

A blank slate is shown

type parameter values:

  • no_result_search
    The dynamic list has no result. This could occur when a search returns an empty response

  • widget_no_content
    No content to show

  • widget_invalid_configuration
    The attributes are not valid or the course type is not supported

Payload type:

{
  type: string,
  emitter: string
}

Example payload:

{
  type: 'no_result_search', 
  emitter: 'player1'
}

training_material_loaded

Training material has been loaded

emitter parameter values:

  • internal-course-player
    Returned if the widget contains the player

  • external-course-player
    Returned if the widget does not contain the player

Payload type:

{
  emitter: string
}

Example payload:

{
  emitter: external-course-player
}

item_selected_external_player

A course has been selected.

Payload type:

{
  id: string,
  name: string,
  type: string
}

Example payload:

{
  id: '181',
  name: 'Course with video',
  type: 
  {
    title: 'learning plan',
  },
}

Related articles