Skip to main content

Docebo Help

How can we help?

Embedded learning building blocks: Course list widget

Last updated
Docebo module
Reading time
User level
  • Administrators

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.

Mode Description
Static 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 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-player 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.
Attribute Type Description
id string

The ID of the course list.

Tip: This attribute is required.

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

This attribute changes the course list type.

type attribute values:

  • static
  • dynamic

Tip: This attribute is required.
coursesids string

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

Tip: This attribute is valid and required if the value of type is static.
widgettitle string

The title of the widget.

Default value:

false
trainingmaterials boolean

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

Default value:

true

Tip: This attribute is valid only if type is dynamic.
mycoursesandlps boolean

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.

Default value:

true

Tip: This attribute is valid only if type is dynamic.
fromcatalogs boolean

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.

Default value:

true

Tip: This attribute is valid only if type is dynamic.
maxresults number

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

Default Value:

empty

Tip: This attribute is valid only if type is dynamic.
noresulttitle string

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

Default Value:

Whoops, there’s nothing here
noresultdescription string

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

Default Value:

Looks like there is nothing for you in this area right now
includeplayer boolean

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

Default Value:

true
autoplay boolean

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.

Default Value:

false

Tip: This attribute is valid only if includeplayer is true.
showfullscreen boolean

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.

Default Value:

true

Tip: This attribute is valid only if includeplayer is true.
showpip boolean

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.

Default Value:

true

Tip: This attribute is valid only if includeplayer is true.
showtoc boolean

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.

Default Value:

true

Tip: This attribute is valid only if includeplayer is true.
forcefullscreen boolean

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.

Default Value:

false

Tip: This attribute is valid only if includeplayer is true.
showthumbsintoc boolean

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.

Default Value:

false

Tip: This attribute is valid only if includeplayer is true.
showpreview boolean

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.

Default Value:

true

Tip: This attribute is valid only if includeplayer is true.
tmdownloadmode string

tmdownloadmode attribute values:

  • blob
  • link

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.

Default Value:

blob

Tip: This attribute is valid only if includeplayer is true.
showcoursedeadline string

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 type is set to dynamic.

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 variable.

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:

View Description
dynamic-list 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)
static-list 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.
myclp-courses-list 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.
player 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

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
Command Description and
response promise payload		 
DSDK.getCommandBus().send(
  'load_courses', 
  'ID OF WIDGET', 
  {
    ids: "LIST OF IDS"
  }
)
 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.

Example payload: 
{
  ids: "182,187,179"
}
The promise does not get resolved for now.		 
DSDK.getCommandBus().send(
  'search',
  'ID OF WIDGET',
  {
    text: "KEYWORD TO 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.

Example payload: 
{
  text: 'Course with video'
}
The promise does not get resolved for now.		 
DSDK.getCommandBus().send(
  'select_item', 
  'ID OF WIDGET', 
  {
    type: "ITEM TYPE",
    id:"ITEM ID"
  }
);
 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.

Example payload:

{
  type: 'course',
  id: '181'
}
When the item is selected the promise is resolved: 
{
  select: true
}

Events generated by the course list widget

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 that indicates the emitter ID
  • p is the payload which is an object that depends on the events
Event name Payload type and description
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
}