Moodle2 Tools for Teachers Files

                         Moodle2 Tools for Teachers

           Command line tool to push resources on a Moodle server


Here is my small contribution to the Moodle comunity.
I  made these  tools to  help me  to publish  the updates  of contents  and
resources that I propose for courses I teach, without having to click click
and click again.
I have no  problem with rich interactives interfaces (i.e.  clicking on web
2.0 pages),  if I have to  do it only once.  However, if I have  to perform
actions in  a regular and  systematic way (e.g. updating  courses documents
quarter after quarter), I do prefer using a command line tool.

This is the purpose of the following tools.

There are  some difficulties. It's not  as simple as copying  document on a
shared directory. Moodle  is doing its best to avoid  managing files on the
traditional way.  Files are a  concept of  dinosaurs (like me),  now please
think "resources".  No more filesystem.  Instead, several bubbles  of space
(at least one per resource) in which you arrange your materials.
As  a consequence,  the  naming is  complex  since you  have  to guess  the
resource identifier choosed  by the database (retrieve this  numbers in the
url of your resource).
Moreover, the question mark in url of documents breaks the traditional path
scheme  of html  documents.  You can't  publish  a set  of  html pages  and
pictures  and  follow cross  referecences:  relative  links does  not  work
anymore. In certain  circumstances, workarounds are possible  if the server
can rename urls on the fly... sometimes.
Nevertheless, the main problem is that Moodle does not provide ways to push
content from  outside. One  can only  pull content  from inside  Moodle (by
clicking). Moodle supports  ftp, webdav, file system  access, web download,
etc., but only as client, not as server.
And sometimes,  you have nothing at  all: for Page and  Book resources, you
are supposed to type documents by hand using the small embedded html editor
:( This  may be  good enough to  write some  notes on a  blog, but  not for
authoring documents of courses (and even less to create a book).
Moodle 2  offers a promising  REST (web services) API.  Unfortunately, this
seems to be still under development or discontinued, and is not yet usable,
except for some demonstration examples.

I really hope that the Web Services part of Moodle will be improved in next
releases, with consistent API, and  a clear separation between the internal
server settings  and parameters  exposed to external  clients. 
In the  mean time, I do  need to manage  things with a given  Moodle server
right now...  This is why  I developed those tools  that play with  the web
api. (I mimic click.) However, I won't have the energy to do it again...

In fact, those tools are shell scripts. I spent hours to develop them, with
the  try-and-fix strategy.  They are  not really  complex, but  there is  a
plethora of magic settings to adjust.

Be careful, those tools are very fragile, very few errors are detected.
I do my best, however it is not always enough.

Note that I tested these scripts with only two Moodle 2.6 servers.
(Those for whom I have access.) I hope everything goes well with yours...
If not, you can modify those scripts for your needs.



Installation:
  Copy the tools you need somewhere in your PATH. (e.g. /usr/local/bin)

Dependencies:
  bash curl tr sed jshon xmlstarlet tidy xxd
  (check packages for your distribution)

Configuration:
  Edit  the  scripts  with a  text  editor  to  set  up default  values  of
  parameters. (e.g. the URL of the Moodle server you use)

Licence:
  (c) 2014  Christophe Lohr <clohr@users.sourceforge.net>
  GPLv3 or later <http://www.gnu.org/licenses/>
  https://sourceforge.net/projects/m2tt/

Acknowledgements:
  Many thanks to the HttpFox plugin for Firefox.


Descriptions of tools:

* mtt_files-update.sh
  Update contents (files, directories) of a given Files-Resource
  Dependencies: bash curl tr sed jshon xmlstarlet xxd

  Usage:
    mtt_files-update [-h] [-m <moodle url>]
                     [-u <user name>] [-p <password>]
                     [-r <resource id>]
                     [-n]  (do not purge before uploading)
                     [-M <main file name>]
                     <file> ...

  Note:
  -r You  must know  the number  that identifies  the resource,  which must
     already exist.  So, look at  the number in the  url when you  watch or
     modify properties of  your resource. Then, keep  this number carefully
     (e.g. in your  own scripts). You will need it  all the time thereafter
     to make your updates.
  -n By default  mtt_files-update purges the content  of the Files-Resource
     before  uploading your  files. The  '-n' option  avoid this  behavior.
     However your  files may  be renamed as  files(1) files(2)...  if those
     names alrady exists.
  -M In a  Files-Resource, one file should  be designated as the  main file
     within the set of files. By default  this is the first one you upload.
     This option allows you to specify which one is your main file.
  Also note  that subdirectories are preserved.  If you send  foo/bar, your
  ressource will contain a foo directory that will contain the bar file.
  Moreover one can rename <file> using <LocalFileName;RemoteFileName>


* mtt_page-update.sh
  Update contents (text and embedded files) of a given Page-Resource
  Dependencies: bash curl tr sed jshon xmlstarlet tidy xxd

  Usage:
    mtt_page-update [-h] [-m <moodle url>]
                    [-u <user name>] [-p <password>]
                    [-r <resource id>]
                    [-n]  (do not purge before uploading files)
                    [-d <html document to update the page>]
                    [-t body|iframe|redirect]
                    [-f]  (fix relative links within web files)
                    [<file> ...]

  Notes:
    -t Several ways (or tricks) are proposed to publish a Page-Resource.
       'body': First,  tries  to fix  the problem  of  the question mark in
          moodle  urls.  So, relative links  within the  html document  are
          replaced by absolute  links to the moodle  server... This implies
          rewriting the html document, assuming  it is well-formed and utf8
          encoded.
          Then, sends  the html document  as content of  the Page-Resource.
          However,  the  header  will  be  lost,  with  links,  styles  and
          scripts... So, you may have to beforehand modify your document to
          use inline styles...
        'iframe': The  html document is sent  as it, like other  files. The
          Page Resource will be an <iframe> that call it. If your server is
          not so  subject to the  problem of question  mark in urls,  it is
          probably the nicest trick to choice.
        'redirect': The html  document is sent as it, like other files. The
          Page-Resource will just be a link to it.
    -f Do  its best  to fix  relative links  within  web documents uploaded
       (html, xhtml).  If your Moodle server  is subject to the  problem of
       question mark in its urls, this can be an acceptable work-around, or
       not. Do tests to see what's happen with your server.
    [<file> ...] The content of the Page-Resource may depend on other files
      (images, html pages, etc.) You can upload the files in the same time, 
      if any.


* mtt_files-dndupload.sh
  Upload files as Files-Resources into a section of a course
  (Mimics the Moodle2 drag'n drop feature via the web interface)
  Dependencies: bash curl sed jshon

  Usage:
    mtt_files-dndupload [-h] [-m <moodle url>]
                        [-u <user name>] [-p <password>]
                        [-c <course id>] [-s <section>]
                        <file> ...

  Note: 
    I don't know how to send a directory. I don't know if it is possible.


* mtt_file-upload.sh
  Create a Files-Resource and put a file in it.
  Dependencies: bash curl tr sed grep

  Usage:
    mtt_file-upload [-h] [-m <moodle url>]
                    [-u <user name>] [-p <password>]
                    [-c <course id>] [-p <section>]
                    [-f <local file name>] [-t <remote file title>]

  Note: That was one of my first attempt to develop a tool for Moodle2.
    To be honest, this tool is not really useful.


* mtt_delete-resource.sh
  Delete a resource
  Dependencies: bash curl tr sed jshon

  Usage:
    mtt_delete-resource [-h] [-m <moodle url>]
                         [-u <user name>] [-p <password>]
                         [-c <course id>] [-r <resource id>]


* mtt_course-contents.sh
  Retrieves plenty of internal data relating to a given course
  It uses the default ugly REST-JSON API provided by Moodle v2.x
  Dependencies: bash curl jshon

  Usage:
    mtt_course-contents.sh [-h] [-m <moodle url>] [-u <user name>]
                           [-p <password>] [-c <course id>]

  Note:  My first  strategy  was to  play  with the  REST  API proposed  by
  Moodle2. This was a great disappointment, a stalemate.
  Moodle  propose  plenty  of  REST  calls. They  are  gathered  within  so
  called services. The default  service is named 'moodle_mobile_app', which
  contains almost 5% of existing REST  calls, that are almost all tagged as
  deprecated. However  you are free  to define  your own service,  with all
  REST calls you want.  Then, you have to put your  hands into the database
  of moodle to give a shortname for this new service.
  Then you have to  set up roles and permissions for  users with regards of
  the REST calls. Note that you  may define permissions that are completely
  opposite to those defined for actions via web pages...
  This means a lot of configurations from the Moodle administrator side.
  And finally client-tools have access  REST calls  that requires plenty of
  magic parameters  that are  internals to  the server.  (e.g. You  want to
  browse files of a resource and you have to provide a 'context level' !?!)
  As a conclusion: this REST API is not usable yet. Too bad.