icPlayer

https://icplayer.com/doc
Admin
icPlayer is an interactive content player for embedding educational content with comprehensive...
Tokens:5,693
Snippets:43
Trust Score:7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Start jsTestDriver Server (Java)

Source: https://icplayer.com/doc/addon/build_process

Initiates the jsTestDriver server required for testing addons. This command is executed from the addons/tools directory. Ensure the jsTestDriver.jar is present.

```shell
java -jar addons/tools/JsTestDriver.jar --port 9876
```

--------------------------------

### Run Default Build Target (Ant)

Source: https://icplayer.com/doc/addon/build_process

Executes the default build target using Apache Ant. This process includes testing all Player components. Ensure Ant is installed and configured in your environment.

```shell
ant
```

--------------------------------

### Get Score Object using PlayerUtils Wrapper

Source: https://icplayer.com/doc/embed/player_utils

This example demonstrates how to use the PlayerUtils wrapper to retrieve the score object for the current presentation. It initializes the player, loads content, and then accesses the event bus and utility functions to get presentation details and the associated score.

```javascript
var player;
function icOnAppLoaded(){
	player = icCreatePlayer('_icplayer');
	player.load('content/default.ic.xml');
	
	player.onPageLoaded(function() {
		var eventBus = player.getPlayerServices().getEventBus();
			listener = function() {}
			utils = new PlayerUtils(player);
			presentation = utils.getPresentation();
			scoreObject = utils.getPresentationScore(presentation);
		
		console.log(scoreObject);
	});
}

```

--------------------------------

### Embed icPlayer using Basic HTML

Source: https://icplayer.com/doc/embed/basic

This HTML snippet demonstrates the minimal structure required to embed the icPlayer. It includes loading jQuery, the icPlayer script, and initializing the player instance. Ensure the path to `icplayer.nocache.js` is correct.

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <title>icPlayer Embed Test</title>

    <!-- 1. Load jQuery (Required) -->
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>

    <!-- 2. Load icPlayer -->
    <script type="text/javascript" src="icplayer/icplayer.nocache.js"></script>

    <!-- 3. Initialize Player -->
    <script>
        var player;
        function icOnAppLoaded() {
            // Create player instance attached to the div with id '_icplayer'
            player = icCreatePlayer('_icplayer');
            
            // Load content (XML file)
            player.load('content/default.ic.xml');
        }
    </script>

    <!-- 4. MathJax Configuration (Optional, for Math support) -->
    <script type="text/javascript" 
        src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.7/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
    </script>
  </head>

  <body>
    <!-- Player Container -->
    <div id="_icplayer"></div>
  </body>
</html>
```

--------------------------------

### Initialize IC Player and Save/Load Lesson State with JavaScript

Source: https://icplayer.com/doc/embed/state

This snippet demonstrates how to initialize an IC Player, set its state, and load content using JavaScript. It also shows how to retrieve the player's state. Ensure the player is initialized before attempting to set or get its state.

```javascript
var player;
function icOnAppLoaded(){
    player = icCreatePlayer('_icplayer');
    // Write state to player before loading content
    player.setState(state);
    player.load('content/default.ic.xml');
}

// Read state from player
var state = player.getState();
```

--------------------------------

### Handle 'ShowErrors' Event with PlayerUtils

Source: https://icplayer.com/doc/embed/player_utils

This example shows how to listen for the 'ShowErrors' event using the PlayerUtils wrapper. It tracks the number of times the event is fired on a specific page to differentiate between the first check and subsequent checks, allowing for custom actions like saving to a database or providing feedback.

```javascript
var player;
function icOnAppLoaded(){
	player = icCreatePlayer('_icplayer');
	player.load('content/default.ic.xml');

	var checkCounter = {};
	
	player.onPageLoaded(function() {
		var eventBus = player.getPlayerServices().getEventBus();
			listener = function() {}
			utils = new PlayerUtils(player);
			presentation = utils.getPresentation();
		
		listener.onEventReceived = function(eventName, eventData) {
			var scoreObject = utils.getPresentationScore(presentation);
				maxScore = scoreObject.maxScore;
				score = scoreObject.score;
				pageIndex = player.getPlayerServices().getCurrentPageIndex();
			
			if (!(pageIndex in checkCounter)) {
				checkCounter[pageIndex] = 0;
			}
			
			if (checkCounter[pageIndex] == 0) {
				console.log('First Check. Save to Database.')
				console.log(scoreObject.paginatedResult[pageIndex]);
			} else {
				console.log('Next Checks. Give more coins.')
				console.log(scoreObject.paginatedResult[pageIndex]);
			}
			
			checkCounter[pageIndex]++;
		}
		
		eventBus.addEventListener('ShowErrors', listener);
		
	});
}

```

--------------------------------

### Presentation Type

Source: https://icplayer.com/doc/addon/player_services

Methods for interacting with the presentation object, including getting page count, specific pages, and the table of contents.

```APIDOC
## Presentation Type

### Description
Represents the presentation in the player, providing methods to access its properties and structure.

### Methods

#### `getPageCount()`
* **Description**: Returns the total number of pages in the presentation.
* **Returns**: `number` - The total page count.

#### `getPage(index)`
* **Description**: Returns a specific page object based on its index.
* **Parameters**:
  * **index** (number) - Required - The zero-based index of the page to retrieve.
* **Returns**: `Page` object

#### `getTableOfContents()`
* **Description**: Returns a hierarchical table of contents for the presentation, consisting of chapters and pages.
* **Returns**: `Array` - An array of chapter objects. Each chapter has `type`, `getName()`, `size()`, and `get(index)` methods. Each page within a chapter has `type`, `getName()`, `getBaseURL()`, and `isReportable()` methods.
```

--------------------------------

### Get Lesson Score using Player API - JavaScript

Source: https://icplayer.com/doc/embed/results

This JavaScript code snippet demonstrates how to initialize the player, load content, and then retrieve the lesson score by iterating through pages and using score services. It calculates the average percentage score across all reportable pages.

```javascript
var player;
function icOnAppLoaded(){
	player = icCreatePlayer('_icplayer');
	player.load('content/default.ic.xml');
}
    
function getLessonScore(){
	var ps = player.getPlayerServices();
	var model = ps.getPresentation();
	var scoreService = ps.getScore();
	var sumOfScore = 0.0;
	var count = 0;
	for(var i = 0; i < model.getPageCount(); i++){
		var page = model.getPage(i);
		if(page.isReportable()){
			count += 1;
			var score = scoreService.getPageScore(page.getName());
			var percentageScore = (score['score']*100.0)/score['maxScore']
			sumOfScore += percentageScore; 
		}
	}
	
	var lessonScore = sumOfScore/count;
	return lessonScore;
}
```

--------------------------------

### Create Presenter Instance

Source: https://icplayer.com/doc/addon/presenter

Creates a new Presenter instance. The `run` function is called to initialize the addon when a module is loaded, taking the view DOM reference and model data as arguments.

```javascript
function AddonDemo_create(){

    var presenter = function(){}

    presenter.run = function(view, model){
    }

    return presenter;
}
```

--------------------------------

### Embedding Player with Subset of Pages

Source: https://icplayer.com/doc/embed/pages

This code snippet demonstrates how to initialize the ICPHONE player, set a subset of pages to load, and then load the content. It also includes important remarks regarding the `setPages` method and state compatibility.

```APIDOC
## Embedding Player - Loading Subset of Pages

### Description
This section details the process of embedding the ICPHONE player and specifically loading a subset of pages from the content.

### Method
JavaScript (Client-side)

### Endpoint
N/A (Client-side JavaScript API)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```javascript
var player;
function icOnAppLoaded(){
    player = icCreatePlayer('_icplayer');
    // Set subset of pages before loading content
    player.setPages('2,3,4');
    player.load('content/default.ic.xml');
}
```

### Response
#### Success Response
N/A (This is a client-side script execution)

#### Response Example
N/A

### Remarks
1.  **Page Order**: Pages must be set using `setPages()` *before* loading content with `load()`.
2.  **`setPages()` Argument**: The argument for `setPages()` must be a string containing page indexes separated by commas. Providing an incorrect format will result in an `IllegalArgumentException`.
3.  **State Compatibility**: The state for a presentation with a subset of pages selected is incompatible with a presentation that loads all pages. Ensure consistency in your approach.
```

--------------------------------

### Commands Type

Source: https://icplayer.com/doc/addon/player_services

Interface for executing commands within the player, such as navigating pages, executing code, and managing answer checks.

```APIDOC
## Commands Type

### Description
Provides methods to execute various commands within the player runtime.

### Methods

#### `executeEventCode(code)`
* **Description**: Sends script code to be executed by the player.
* **Parameters**:
  * **code** (string) - Required - The script code to execute.

#### `gotoPage(name)`
* **Description**: Navigates the player to a page with the specified name.
* **Parameters**:
  * **name** (string) - Required - The name of the page to navigate to.

#### `gotoPageIndex(index)`
* **Description**: Navigates the player to a page using its index.
* **Parameters**:
  * **index** (number) - Required - The index of the page to navigate to.

#### `getTimeElapsed()`
* **Description**: Returns the time elapsed in seconds since the start of the lesson session.
* **Returns**: `number` - Time elapsed in seconds.

#### `checkAnswers()`
* **Description**: Sets the presentation to display errors mode, typically after checking user answers.

#### `uncheckAnswers()`
* **Description**: Restores the presentation to its normal work mode, after answers have been checked.
```

--------------------------------

### Basic addon.xml Structure

Source: https://icplayer.com/doc/addon/model

Defines the fundamental structure of an addon.xml file, including the addon ID and the model for custom properties. The model specifies property names, types, and display names for editor integration.

```xml
<?xml version='1.0' encoding='UTF-8' ?>
<addon id='AddonId'>
    <model>
        <property name='HTTPS' type='boolean'/>
        <property name='ID' type='string'/>
        <property name='URL' type='string' displayName='Page URL'/>
        <property name='Items' type='list'>
            <property name='Name' type='string' isLocalized='True'/>
        </property>
    </model>
</addon>
```

--------------------------------

### Page Type

Source: https://icplayer.com/doc/addon/player_services

Methods for retrieving information about a specific page, including its ID, name, URL, reportability, and modules.

```APIDOC
## Page Type

### Description
Represents a single page within the presentation, providing details about the page and its content.

### Methods

#### `getId()`
* **Description**: Returns the unique identifier of the page.
* **Returns**: `string` - The page ID.

#### `getName()`
* **Description**: Returns the name of the page.
* **Returns**: `string` - The page name.

#### `getBaseURL()`
* **Description**: Returns the base URL for the page, ending with a slash.
* **Returns**: `string` - The page base URL.

#### `isReportable()`
* **Description**: Indicates whether the page should be included in lesson reports.
* **Returns**: `boolean` - True if the page is reportable, false otherwise.

#### `getModules()`
* **Description**: Returns a list of module IDs present on this page.
* **Returns**: `Array<string>` - An array of module IDs.
```

--------------------------------

### Player Services API

Source: https://icplayer.com/doc/addon/player_services

The Player Services API enables calling functions on the player runtime. It provides access to the presentation, current page, commands, event bus, score, modules, text parser, and static file paths.

```APIDOC
## Player Services API

### Description
Provides access to various player functionalities including presentation details, page navigation, command execution, event handling, score retrieval, module access, text parsing, and static file paths.

### Functions

#### `getPresentation()`
* **Description**: Returns an object representing the current presentation, which has methods to access presentation and page-related information.
* **Returns**: `Presentation` object

#### `getCurrentPageIndex()`
* **Description**: Returns the index of the currently displayed page.
* **Returns**: `number` - The index of the current page.

#### `getCommands()`
* **Description**: Returns an object that provides methods for executing various player commands.
* **Returns**: `Commands` object

#### `getEventBus()`
* **Description**: Returns an object for interacting with the player's event bus, allowing event listening and sending.
* **Returns**: `EventBus` object

#### `getScore()`
* **Description**: Returns an object for retrieving score-related information for the presentation.
* **Returns**: `Score` object

#### `getModule(moduleID)`
* **Description**: Retrieves a module presenter based on the provided module ID.
* **Parameters**:
  * **moduleID** (string) - Required - The ID of the module to retrieve.
* **Returns**: `ModulePresenter` object

#### `getTextParser()`
* **Description**: Returns an object used for parsing text elements, such as definition links.
* **Returns**: `TextParser` object

#### `getStaticFilesPath()`
* **Description**: Returns the path to static files included with the player.
* **Returns**: `string` - The path to static files.

#### `isBook()`
* **Description**: Checks if the player is in book mode, displaying two pages at a time.
* **Returns**: `boolean` - True if in book mode, false otherwise.

#### `hasCover()`
* **Description**: Checks if the first page is always displayed as a single page (cover).
* **Returns**: `boolean` - True if the first page is a cover, false otherwise.
```

--------------------------------

### TextParser

Source: https://icplayer.com/doc/addon/player_services

Utility for parsing and connecting text elements, particularly definition links, within the player.

```APIDOC
## TextParser

### Description
Provides functionality to parse text and handle definition links.

### Methods

#### `parse(text)`
* **Description**: Parses the given text, replacing definition links (e.g., `\def{word}`) with appropriate elements.
* **Parameters**:
  * **text** (string) - Required - The text to parse.
* **Returns**: `string` - The parsed text.

#### `connectLinks(element)`
* **Description**: Connects all definition links within the specified element to the event bus. Each link will trigger a 'Definition' event upon interaction.
* **Parameters**:
  * **element** (HTMLElement) - Required - The HTML element containing the links to connect.
```

--------------------------------

### EventBus

Source: https://icplayer.com/doc/addon/player_services

Handles event listening and sending within the player. Allows registration of listeners for specific events and sending custom events.

```APIDOC
## EventBus

### Description
Manages event handling within the player, enabling communication through event listeners and event sending.

### Methods

#### `addEventListener(event_name, listener)`
* **Description**: Registers a listener function for a specific event.
* **Parameters**:
  * **event_name** (string) - Required - The name of the event to listen for.
  * **listener** (object) - Required - An object with an `onEventReceived(eventName, eventData)` function.

#### `sendEvent(eventName, eventData)`
* **Description**: Sends an event to the event bus.
* **Parameters**:
  * **eventName** (string) - Required - The name of the event to send.
  * **eventData** (Array) - Optional - An array containing data for the event.
```

--------------------------------

### Embed icplayer with Subset of Pages (JavaScript)

Source: https://icplayer.com/doc/embed/pages

This snippet demonstrates how to initialize the icplayer and load only a specified subset of pages. The `setPages` method must be called before `load` to define which pages are included. Ensure the page indexes are provided as a comma-separated string to avoid exceptions.

```javascript
var player;
function icOnAppLoaded(){
    player = icCreatePlayer('_icplayer');
    // Set subset of pages before loading content
    player.setPages('2,3,4');
    player.load('content/default.ic.xml');
}  
```

--------------------------------

### Embed IC Player and Listen for Status Changes (JavaScript)

Source: https://icplayer.com/doc/embed/status

This snippet demonstrates how to create an IC Player instance, load content, and attach an event listener for status changes. The listener logs the event type, source, and value to the console, which can be used for analytics. It requires the `icCreatePlayer` function to be available in the global scope.

```javascript
var player;
function icOnAppLoaded(){
    player = icCreatePlayer('_icplayer');
    player.load('content/default.ic.xml');
   	player.onStatusChanged(function(type, source, value){
        console.log("type:" + type + ", source: " + source, ", value:" + value);
   	});
}
```

--------------------------------

### Set Player Controller

Source: https://icplayer.com/doc/addon/presenter

Sets the player controller for the Presenter. This allows the addon to interact with player functions by providing a `controller` object of type `PlayerServices`.

```javascript
presenter.setPlayerController = function(controller){
    }
```

--------------------------------

### Register Addon in AddonDescriptorFactory (JavaScript)

Source: https://icplayer.com/doc/addon/create_addon

This JavaScript function registers a new addon within the icplayer's AddonDescriptorFactory. It takes the addon's unique ID, its display name, and the editor menu group it belongs to as arguments. This is a crucial step for the player and editor to recognize and utilize the newly created addon.

```javascript
AddonDescriptorFactory.addDescriptor("MyAddonId", "Addon name", "Editor menu group")
```

--------------------------------

### Score

Source: https://icplayer.com/doc/addon/player_services

Provides methods to retrieve score-related information, including maximum score, total score across pages, and score for individual pages.

```APIDOC
## Score

### Description
Provides access to scoring information within the player.

### Methods

#### `getMaxScore()`
* **Description**: Returns the maximum possible score for the entire presentation.
* **Returns**: `number` - The maximum score.

#### `getTotalScore()`
* **Description**: Returns the calculated score based on all opened pages.
* **Returns**: `number` - The total score.

#### `getPageScore(pageName)` **(Deprecated)**
* **Description**: Returns the score for a given page by its name. (Deprecated, use `getPageScoreById` instead).
* **Parameters**:
  * **pageName** (string) - Required - The name of the page.
* **Returns**: `object` - An object containing `score`, `maxScore`, `checkCount`, and `mistakeCount` for the page.

#### `getPageScoreById(pageId)`
* **Description**: Returns the score for a given page using its ID.
* **Parameters**:
  * **pageId** (string) - Required - The ID of the page.
* **Returns**: `object` - An object containing `score`, `maxScore`, `checkCount`, and `mistakeCount` for the page.
```
Tokens:
Raw