kolibri-explore-plugin 6.10.0

Kolibri plugin for Endless custom presentation

Kolibri Explore Plugin

This plugin adds the Endless Key experience on top of Kolibri:

• A content navigation view exposed in the /explore URL. As an alternative to the Kolibri Learn plugin for self-guided learners.

• Branding and layout customizations for several channels.

• Download of content packs with extra metadata.

Usage

This is a plugin for Kolibri, so it must be installed in your Kolibri environment.

Install latest release from PyPi:

pip install kolibri-explore-plugin

Then enable it in Kolibri and run migrations:

kolibri plugin enable kolibri_explore_plugin
kolibri manage migrate

Download the apps-bundle.zip from the GitHub releases page and extract them to the kolibri_explore_plugin/apps folder. Note that this is not ideal, because you should know where has pip installed the plugin.

Download the JSON files from the endless-key-collections repo and place them in kolibri_explore_plugin/static/collections/.

Now start Kolibri. You should be able to navigate to /explore if / doesn't redirect you already.

Setup

Make sure you already have the latest pipenv.

Either if you want to build or develop the plugin, please run:

./scripts/bootstrap.sh

Just like Kolibri, we use a Python virtual environment along with Node to obtain the exact same dependencies.

Building

Creating the .whl file

With all the dependencies installed, it's now possible to build the plugin by running:

yarn build-dist

A .whl file will be created in the dist/ folder. You can then install it:

pip install dist/kolibri_explore_plugin-*.whl

Development

Getting started with development

For developing you could build and install the .whl file over and over for each iteration. But is much easier to install the project in editable mode, which basically creates a symlink:

pip install --editable .

Note: you still need to enable the plugin and run migrations as in Usage above!

Then serve the plugin in watch mode:

yarn dev

Usually you will also be developing Kolibri, as described in the Kolibri developer documentation.

So probably you have the following running in another Terminal tab:

yarn run devserver-hot

And you can edit both the plugin and Kolibri in live-mode. Further, you can also edit a custom channel presentation in another Terminal tab. See "Developing custom channel presentations" section below.

Configuring the precommit hook

To run checks before any commit just run this command:

pre-commit install -f --install-hooks

There is a continuous integration tool in Github that will run the same checks for each pull request.

Bundling custom channel presentations

There is a Github action that does this automatically on each release. To do it locally yourself:

yarn build:apps

All custom presentation app bundles should be added in the kolibri_explore_plugin/apps directory to have this fully working. The zip bundle should be named custom-channel-ui.zip and it should be placed inside the corresponding app folder.

Developing custom channel presentations

Instead of bundling the custom channel presentation inside the apps directory, it's possible to work with a proxy for development. Note that the proxy will be used for all the channels, not only for the channel in question.

1. Run the custom channel presentation development server. For instance to run the template:

$ cd packages/template-ui
$ yarn serve

2. Run Kolibri with the PROXY_CUSTOM_CHANNEL environment variable enabled:

$ cd /PATH/TO/kolibri
$ PROXY_CUSTOM_CHANNEL=1 yarn run devserver-hot

Every request to the custom-channel-ui.zip will be proxied to the devserver. The hot reloading should work here too!

Ingesting highlighted content

Make sure to have a .env file with the spreadsheet key as content:

CONTENT_SPREADSHEET_KEY=123456

Then run the script:

./scripts/ingest_highlighted.py

If everything goes well, the highlighted-content.json file will be updated. You then need to commit the file.

Releasing

To release a new version first please bump the version number to either major or minor. Note that the major version also needs a version name for branding. Eg:

# For a minor release:
yarn bump-version minor

# For a major release:
yarn bump-version major "Komodo Dragon"

That creates a new commit and a git tag. Please push them to the remote:

git push
git push origin NEW_TAG

Then build:

yarn build-dist

And finally upload the built .whl file to PyPi:

yarn release

Note: These release steps can be done by triggering bump2release.yml action.

How to display the build information

To show the build information in the front page, as a tag in top right corner, you can set the environment variable, SHOW_BUILD_INFO to "true", for example, for the development kolibri server:

$ SHOW_BUILD_INFO=true yarn run devserver