cordova-plugin-classkit

v1.0.0

Published

4 years ago

Cordova plugin for using Apple's ClassKit framework.

0High
0Medium
0Low

sebastianbaar

ecosystem:cordova cordova-ios classkit schoolwork

Cordova ClassKit Plugin

Plugin to use Apple's ClassKit framework in your Cordova apps. Manage and create Contexts and Activities and add Activity Items to track the student's progress within the Schoolwork App.

Prerequisites

Only works with Xcode 9.4 and iOS 11.4. Your Provisioning Profile must include the ClassKit capability. Read more about how to Request ClassKit Resources in this article. Also note that you can’t test ClassKit behavior in Simulator because Schoolwork isn’t available in that environment.

Supported Platform(s)

Installation

cordova plugin add cordova-plugin-classkit
Turn on ClassKit in Xcode's Capabilities tab

The code is written in Swift and the Swift support plugin is configured as a dependency.

API

.initContextsFromXml(urlPrefix, success, error)

Init contexts defined in XML file CCK-contexts.xml

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | urlPrefix | String | | URL prefix to use for custom URLs to locate activities (deeplink). | | success | Function | | Is called when the api successfully initializes the contexts from XML. | | error | Function | | Is called when the api encounters an error while initializing the contexts from XML. |

Example

CordovaClassKit.initContextsFromXml(
  "myurlprefix://",
  () => {
    console.log('success');
  },
  e => {
    console.log("error:", e);
  }
);

CCK-contexts.xml (read Add Contexts to your App for more infos about the XML file)

<root>
    <context
        title="Parent Title 1"
        type="2"
        displayOrder="1"
        topic="math"
        identifierPath="parent_title_one">
        <context
            title="Child 1 1"
            type="3"
            identifierPath="parent_title_one, child_one"></context>
        <context
            title="Child 1 2"
            type="3"
            identifierPath="parent_title_one, child_two">
            <context
                title="Quiz 1 2 1"
                type="8"
                identifierPath="parent_title_one, child_two, child_two_quiz"></context>
        </context>
    </context>
    <context
        title="Parent Title 2"
        type="2"
        displayOrder="0"
        topic="computerScienceAndEngineering"
        identifierPath="parent_title_two">
        <context
            title="Child 2 1"
            type="3"
            identifierPath="parent_title_two, child_two">
            <context
                title="Quiz 2 1 1"
                type="8"
                identifierPath="parent_title_two, child_two, child_one_quiz"></context>
        </context>
    </context>
</root>

.addContext(urlPrefix, context, success, error)

Init context with identifier path

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | urlPrefix | String | | URL prefix to use for custom URLs to locate activities (deeplink).
| context | Object | | Context to initialize. | | success | Function | | Is called when the api successfully initializes the context. | | error | Function | | Is called when the api encounters an error while initializing the context. |

All available context attributes:

| Attribute | Type | Default | Description | | ------------------------------ | -------- | ------------------------------------------------------------ | -------------------------------------------------- | | identifierPath | String[] | | Full identifier path from root, including the context identifier itself. | | title | String | | Title of the context. | | type | Number | | Optional. Type value for the context. | | topic | String | | Optional. Topic value of the context. | | displayOrder | Number | 0 | Optional. Display order of the context. |

All available type values (CLSContextType):

| Value | Type | |-------------|----------- | 0 | CLSContextType.none | | 1 | CLSContextType.app (Reserved for the main app context) | | 2 | CLSContextType.chapter | | 3 | CLSContextType.section | | 4 | CLSContextType.level | | 5 | CLSContextType.page | | 6 | CLSContextType.task | | 7 | CLSContextType.challenge | | 8 | CLSContextType.quiz | | 10 | CLSContextType.exercise | | 11 | CLSContextType.lesson | | 12 | CLSContextType.book | | 13 | CLSContextType.game | | 14 | CLSContextType.document | | 15 | CLSContextType.audio | | 16 | CLSContextType.video |

All available topic values (CLSContextTopic):

| Value | Type | |-------------|----------- | "math" | CLSContextTopic.math | | "science" | CLSContextTopic.science | | "literacyAndWriting" | CLSContextTopic.literacyAndWriting | | "worldLanguage" | CLSContextTopic.worldLanguage | | "socialScience" | CLSContextTopic.socialScience | | "computerScienceAndEngineering" | CLSContextTopic.computerScienceAndEngineering | | "artsAndMusic" | CLSContextTopic.artsAndMusic | | "healthAndFitness" | CLSContextTopic.healthAndFitness |

Example

var context = {
  identifierPath: ["parent_id", "child_id", "my_context_identifier"],
  title: "My Context Title",
  type: 2,
  topic: "math",
  displayOrder: 1
};

CordovaClassKit.addContext(
  "myurlprefix://", context,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.removeContexts(success, error)

Remove all contexts

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | success | Function | | Is called when the api successfully removes all contexts. | | error | Function | | Is called when the api encounters an error while removing the contexts. |

Example

CordovaClassKit.removeContexts(
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.removeContext(identifierPath, success, error)

Remove context with identifier path

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | identifierPath | String[] | | Full identifier path from root, including the context identifier itself. | | success | Function | | Is called when the api successfully removes the context. | | error | Function | | Is called when the api encounters an error while removing the context. |

Example

CordovaClassKit.removeContext(
  ["parent_id", "child_id", "my_context_identifier"],
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.beginActivity(identifierPath, asNew, success, error)

Begin a new activity or restart an activity for a given context

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | identifierPath | String[] | | Full identifier path from root, including the context identifier itself. | | asNew | Boolean | false | Should a new activity be created (or an old activity be restarted). | | success | Function | | Is called when the api successfully begins or restarts an activtiy. | | error | Function | | Is called when the api encounters an error while beginning or restarting an activity. |

Example

CordovaClassKit.beginActivity(
  ["parent_id", "child_id", "my_context_identifier"], true,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.endActivity(success, error)

End the active activity

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | success | Function | | Is called when the api successfully ends the active activity. | | error | Function | | Is called when the api encounters an error while ending the active activity. |

Example

CordovaClassKit.endActivity(
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setProgressRange(fromStart, toEnd, success, error)

Adds a progress range to the active given activity. developer.apple.com

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | fromStart | Number | | The beginning of the new range to add. This should be fractional value between 0 and 1, inclusive. | | toEnd | Number | | The end of the new range to add. This should be larger than the start value and less than or equal to one. | | success | Function | | Is called when the api successfully adds a progress range. | | error | Function | | Is called when the api encounters an error while adding a progress range. |

Example

CordovaClassKit.setProgressRange(
  0.0, 0.33,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setProgress(progress, success, error)

Adds a progress to the active given activity. developer.apple.com

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | progress | Number | | A measure of progress through the task, given as a fraction in the range [0, 1]. | | success | Function | | Is called when the api successfully adds a progress. | | error | Function | | Is called when the api encounters an error while adding a progress. |

Example

CordovaClassKit.setProgress(
  0.33,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setBinaryItem(binaryItem, success, error)

Adds activity information that is true or false, pass or fail, yes or no.
Use an activity item of this type to indicate a binary condition, such as whether a student passed a test or failed it. Set the valueType property to specify how the binary condition should be reported to a teacher. developer.apple.com

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | binaryItem | Object | | The binary item to add to the activity. | | success | Function | | Is called when the api successfully adds a binary item. | | error | Function | | Is called when the api encounters an error while adding a binary item. |

All available binaryItem attributes:

| Attribute | Type | Default | Description | | ------------------------------ | -------- | ------------------------------------------------------------ | -------------------------------------------------- | | identifier | String | | A unique string identifier for the activity item. | | title | String | | A human readable name for the activity item. | | type | Number | | A type value for the activity item. | | isCorrect | Boolean | | The value that the binary activity item takes. | | isPrimaryActivityItem | Boolean | false | Optional. Should the activity item be added as the primary activity item. |

All available type values (CLSBinaryValueType):

| Value | Type | |-------------|----------- | 0 | CLSBinaryValueType.trueFalse | | 1 | CLSBinaryValueType.passFail | | 2 | CLSBinaryValueType.yesNo |

Example

var binaryItem = {
  identifier: "binary_item_id",
  title: "My Binary Item 1",
  type: 0,
  isCorrect: true,
  isPrimaryActivityItem: false
};

CordovaClassKit.setBinaryItem(
  binaryItem,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setScoreItem(scoreItem, success, error)

Adds activity information that signifies a score out of a possible maximum.
Use an activity item of this type to indicate the relative success in completing a task, like the number of correctly answered questions on a quiz. developer.apple.com

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | scoreItem | Object | | The score item to add to the activity. | | success | Function | | Is called when the api successfully adds a score item. | | error | Function | | Is called when the api encounters an error while adding a score item. |

All available scoreItem attributes:

| Attribute | Type | Default | Description | | ------------------------------ | -------- | ------------------------------------------------------------ | -------------------------------------------------- | | identifier | String | | A unique string identifier for the activity item. | | title | String | | A human readable name for the activity item. | | score | Number | | The score earned during completion of a task. | | maxScore | Number | | The maximum possible score, against which the reported score should be judged. | | isPrimaryActivityItem | Boolean | false | Optional. Should the activity item be added as the primary activity item. |

Example

var scoreItem = {
  identifier: "total_score",
  title: "Total Score",
  score: 0.66,
  maxScore: 1.0,
  isPrimaryActivityItem: true
};

CordovaClassKit.setScoreItem(
  scoreItem,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

.setQuantityItem(quantityItem, success, error)

Activity information that signifies a quantity.
Use an activity item of this type to associate a discrete value with a task. For example, you might use it to indicate how many times the user requested a hint while taking a quiz. developer.apple.com

Parameters

| Parameter | Type | Default | Description | | ---------------- | ---------- | ------- | ------------------------------------------------------------- | | quantityItem | Object | | The quantity item to add to the activity. | | success | Function | | Is called when the api successfully adds a quantity item. | | error | Function | | Is called when the api encounters an error while adding a quantity item. |

All available quantityItem attributes:

| Attribute | Type | Default | Description | | ------------------------------ | -------- | ------------------------------------------------------------ | -------------------------------------------------- | | identifier | String | | A unique string identifier for the activity item. | | title | String | | A human readable name for the activity item. | | quantity | Number | | A quantity associated with the task. | | isPrimaryActivityItem | Boolean | false | Optional. Should the activity item be added as the primary activity item. |

Example

var quantityItem = {
  identifier: "quantity_item_hints",
  title: "Hints",
  quantity: 8,
  isPrimaryActivityItem: false
};

CordovaClassKit.setQuantityItem(
  quantityItem,
  () => {
    console.log("success");
  },
  e => {
    console.log("error:", e);
  }
);

Add Contexts to your App

A context [...] represents an area within your app, such as a book chapter or a game level, that teachers can assign to students as tasks. You create a hierarchy of contexts to enable teachers to browse and assign your app’s content. You provide deep links to the content that the contexts represent to help teachers guide students to your content. developer.apple.com

There are two different types of contexts that you are able to initialize with this plugin: static (you know your contexts beforehand) and dynamic (you add contexts at run time).

Static Contexts in XML File

If you have a lot of static contexts you want to add to your app you could either call addContext(context, success, error) for every context or use a hierarchical XML representation of your contexts to initialize your contexts from calling initContextsFromXml(urlPrefix, success, error). Latter will be more clear and structured (at least for me... that's the reason I added this option... ;-) ). Therefore the plugin adds a CCK-contexts.xml file to your Resources folder in Xcode. The structure is as follows:

<root>
    <context identifierPath="parent_title_one"  title="Parent Title 1" type="2" displayOrder="1" topic="math">
        <context title="Child 1 1" type="3" identifierPath="parent_title_one, child_one"></context>
        <context title="Child 1 2" type="3" identifierPath="parent_title_one, child_two">
            <context title="Quiz 1 2 1" type="8" identifierPath="parent_title_one, child_two, child_two_quiz"></context>
        </context>
    </context>
    <context title="Parent Title 2" type="2" displayOrder="0" topic="computerScienceAndEngineering" identifierPath="parent_title_two">                
    ...
    </context>
    ...
</root>

You have to start with exactly one root node <root></root>. Now, nest all your <context></context> nodes in here building a hierarchical representation of all your static contexts. All available <context>-tag attributes are:

All available type values (CLSContextType):

All available topic values (CLSContextTopic):

Edit the CCK-contexts.xml file directly in the Resources folder in Xcode. Within your application call initContextsFromXml(urlPrefix, success, error) to init your contexts from CCK-contexts.xml.

Dynamic Contexts

To dynamically add contexts to your application use addContext(context, success, error).

Deep Linking

As Apple's documentation states you should/have to "provide deep links to the content that the contexts represent to help teachers guide students to your content". developer.apple.com The deep linking is not part of this plugin! Please use your 3rd party plugin of choice here, e.g. Ionic Deeplinks Plugin or Branch.

Contributing

This plugin needs testing!

Test it
Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

License

This software is released under the [Apache 2.0 License][apache2_license].

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Cordova ClassKit Plugin

Prerequisites

Supported Platform(s)

Installation

API

.initContextsFromXml(urlPrefix, success, error)

Parameters

Example

.addContext(urlPrefix, context, success, error)

Parameters

Example

.removeContexts(success, error)

Parameters

Example

.removeContext(identifierPath, success, error)

Parameters

Example

.beginActivity(identifierPath, asNew, success, error)

Parameters

Example

.endActivity(success, error)

Parameters

Example

.setProgressRange(fromStart, toEnd, success, error)

Parameters

Example

.setProgress(progress, success, error)

Parameters

Example

.setBinaryItem(binaryItem, success, error)

Parameters

Example

.setScoreItem(scoreItem, success, error)

Parameters

Example

.setQuantityItem(quantityItem, success, error)

Parameters

Example

Add Contexts to your App

Static Contexts in XML File

Dynamic Contexts

Deep Linking

Contributing

License