- Explore the requirements of a book tool.
- Name and set up an initial book tool.
- Figure out how to integrate github.
A book tool
The Moodle book module is part of core Moodle. Changing core Moodle is (understandably) hard. Recently, I discovered that there is a notion of a Book tool. This appears to be a simple “plugin” architecture for the Book module. People can add functionality to the Book module without it being part of core. The current plan is that the github work here will be implemented as a Book tool.
What does that mean? My very quick search doesn’t reveal any specific information. The book tool page within the list of plugin types in the Developer documentation is missing. Suggesting that perhaps what follows should be added to that page.
The plugin types page describes book tools as
Small information-displays or tools that can be moved around pages
Which is perhaps not the best description given the nature of the available Book tools.
The tool directory
The book tools appear to reside in ~/mod/book/tool. Each tool has it’s own directory. Apparently, with all the fairly common basic requirements in terms of files
The Book module’s lib.php has various calls to get_plugin_list(‘booktool’) in various places
The first two look for matching functions (e.g. book_plugin_get_post_actions) in the book tool’s lib.php which get called and then used to modify operations.
The settings navigation is where the changes to the settings/administration block get made and from there that’s how the author gets access to the booktool’s functionality.
Naming and getting it started
The plan seems to be to
- Create a new github repository for the new book tool
- Copy and edit an existing book tool to get started.
- Figure out how to slowly add github functionality.
Creating the booktool github repository
The repository will need to be called moodle-booktool_pluginname. What should the plugin name be?
I’ll start with github. Existing tools tend to include a verb e.g. print, exportepub, importepub, exportimscp. So this may be breaking a trend, but that can always be fixed later.
And then there was a repository.
Clone a local copy.
Copy the contents from another book tool and start editing
And take a note of work to do on the issues section of the github repository.
Updated the icon. Wonder if that will work as is?
Login to local moodle. It has picked up the new module and asking to install. That appeared to work. Now what happens when I view a book resource? Woohoo that works.
Doesn’t do anything useful beyond display the availability of GitHub (with the nice icon).
Push that code back to the repository.
How to integrate github
Time to actually see if it can start talking to GitHub and how that might be achieved.
Initial plan for this is
- Hard code details of github repository and credentials for a single Book module.
- Implement the code necessary to update the link in the settings block based on whether the book is up-to-date with the repository.
- Implement index.php function to display various status information about current repository and book.
- Implement the fetch and push functions.
From here on a lot more thought will need to be given to the workflow.
- Implement the interface to configure the repository/credentials
Which all beg the question.
How to talk to the GitHub API
The assumption underpinning all of this is that the tool will use GitHub API to access it’s services. Moodle is written in PHP, so I’m looking for a PHP-based method for talking to the GitHub API.
There’s no clear winner, so time to do a comparison
- Scion: Wrapper – initial impressions good. Does use cURL. But requires other “scion” based code
- KnpLabs API – requires another library for the HTTP requests. Not a plus.
- tan-tan-kanarek version – looks ok. No mention of other requirements.
Let’s try the latter. Installation and it’s all working. Now only need to grok the API and how to use it from PHP.
The focus here is on an individual file. The book will be connected to an individual file.
Most of these request seem linked to the Contents part of the API – part of Repositories.
- Does the file exist in the repo?
Getting the content should return a 200 status code and “type: file” if it is a file, but it will also return the content of the file.
- Create a new file
API: PUT /repos/:owner/:repo/contents/:path
- (fetch) Get the content for the file.
API – GET /repos/:owner/:repo/contents/:path
- (push) Update the file with new content.
API: PUT /repos/:owner/:repo/contents/:path
- What is the status of the file in the repo?
- What is the relationship between the content/status of the file in the repo and the content in the book.
Running out of time. Will have to come back to this another day for Step 2.