Hi,<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />
I too am developing a standard API for calling Moodle functions, which will then be called from various places including a web service. I am focussing specifically on creating courses and resources rather than users, and am developing functions that will “wrap” the existing functions, in order to make the job of the calling program simpler.
Unfortunately I will not be able to post my code in the public domain in its entirety, as it is interwoven with code that was developed for internal use only, and I do not have sufficient time to write a completely generic API class to post to moodle.org. However, I can advise and assist with the development of a library of generic functions, that could appear in a future Moodle release.
Here is a very rough list of the sort of functions I am developing and their functionality – these will be methods of a library class.
- init_generic_course
Creates a course and fixes sort order.
i. Passed an object representing a course record (with properties representing the required fields).
ii. Validates that the required properties are present, defaults certain values (timecreated, timemodified).
iii. Defaults sortorder field prior to record insertion and calls fix_course_sortorder before and after insert to ensure that sortorder field contains valid values.
iv. Calls addslashes on the database fields and inserts record into the course table.
v. Returns the ID of the new course.
- add_resource_html
Provides a simple method to create an HTML resource, and links it to a specified section in the course page.
i. Passed as arguments: course, section (section number within page rather than unique ID), name, alltext (the HTML to display), summary, windowpopup, windowpage (these last two govern whether new window should be opened or display in same page).
ii. Looks up the section number. Can also create a new section with the next consecutive section number if a dummy section number is passed.
iii. Calls resource_add_instance from mod/resource/lib.php
iv. Calls add_module_to_section (see below).
v. Returns the new resource ID number.
- add_resource_file
Provides a simple method to commit a file to Moodle, and links it to a specified section in the course page.
i. Passed as arguments: course, section (section number within page rather than unique ID), name, sourcefile (the name and path of the resource file), summary, windowpopup, windowpage (these last two govern whether new window should be opened or display in same page)..
ii. Internal operation is similar to add_resource_html except that it also copies the file to the correct location within the moodledata file store.
iii. Returns the new resource ID number.
- add_label
Provides a simple method to add a label to a section in a Moodle course.
i. Passed as arguments: course, section (section number within page), content, headingfont (governs whether label should be in bold font as for a heading or normal text format).
ii. Calls label_add_instance from lib.php.
iii. Calls add_module_to_section.
iv. Returns the label ID number.
- add_module_to_section
This function is called from the add_resource_html, add_resource_file and add_label functions to add a label, file link or html page to the correct section on a page.
i. Passed as arguments: course, module type, module instance no. (unique ID), section (section number within course), summary text, visible (if a new section is to be generated, governs whether or not it will be visible to students).
ii. Ensures that the course exists (otherwise throws exception).
iii. If passed a dummy value for section, (-1) it calls Create_Section to create a new section, after the highest-numbered existing one within the specified course, and add the module link or label to that section (this feature is merely a time-saver).
iv. It calls Moodle library functions add_course_module and add_mod_to_section to create the module record and link it to the correct section.
v. It also sets the module’s visible status, dependant upon that of the overall section. (Note that an option to override this could be added to the parameters).
vi. It calls rebuild_course_cache.
- create_section
i. Passed as arguments: course, section (i.e.section number within course), summary, visible (whether or not visible to students).
ii. Inserts a record into course_sections with the correct details.
iii. Returns the new section’s unique ID number.
- check_section_valid
i. Passed as arguments: course, section (i.e.section number within course), noexception (boolean – whether to throw exception).
ii. If the section exists, it returns the section ID number (the unique ID).
iii. If section does not exist, it either returns -1 or throws an exception dependant upon value of noexception.
Where data is inserted into the database, addslashes() is called as a matter of course, but clean_param() is not used, as it is assumed that these functions will always be called from other code which will determine whether or not the inbound data requires sweeping for scripts etc.
It would also be desirable to develop “update” versions of these functions to allow the courses and objects within them to be updated without deleting them completely, but that is less of a priority for myself at the moment.
Thanks,
Gareth Morgan
