Logs for 2013 05 22 - acli/ATutor GitHub Wiki
This is a tidied-up version of my logs for 2013-05-22. A fair amount of code tracing has been done in the past couple of days and I feel that if I don’t write it down now I will forget when I have discovered what; this will be problematic since a number of discoveries have been pretty unexpected.
Documentation on the “sublinks.php” functionality is sparse. In the official documentation we get a brief mention when module.php is briefly discussed, and another equally brief mention when sublinks.php itself is discussed. Because of the bizarre way this project has to go through, sublinks was hard hit and I had to spend hours tracing why it was not working, so here are some discoveries that had never been documented:
In each course’s home page, in the default theme (note that this is handled differently in different themes) you will see a few boxes on the screen, each screen corresponding to an enabled module. Under the module’s title, you can see either “None Found.” (or more accurately term “none_found” in the language_text table) or some stuff; this “stuff” is what sublinks.php controls.
In the absence of sublinks.php, you can hard-code “stuff” in module.php by keying the stuff into the 'text' field of $this->_pages[$_student_tool] (and $this->_page[$_group_tool] if it is different). Obviously, this is not desirable, since the 'text' field cannot produce dynamic content and it will not be translated, so a different way is normally used.
This other way is sublinks.php, which is a script that returns an array of strings: You can almost think of it as a function except that it is actually not one. If it returns a zero-equivalent value, the “stuff” displayed reverts back to what you specified in the 'text' field (or, failing that, whatever is keyed to 'none_found' in language_text).
Interestingly, there is actually no requirement that the so-called “sub-content link” script be called “sublinks.php.” You can call it anything; you just have to key it to the correct title_var within $this->_list.
In the sample code provided in the official documentation, we can see that sublinks.php is not keyed to a path. In the example it has been keyed to 'hello_world', but there is no explanation why or what this key is.
In reality, this key is $this->_pages[$_student_tool]['title_var']. Note that this is whatever title_var you are using for $_student_tool (see include/lib/menu_pages.php), which is not necessarily the same as your module’s ID string. In particular, if your $_group_tool is not the same your $_student_tool, your $_group_tool probably has a different title_var keyed to it; in that case you might also want to key sublinks.php to $this->_pages[$_group_tool]['title_var'].
When sublinks.php is run
- AT_INCLUDE_PATH is defined (as indicated at the top of the file),
- the current directory is the ATutor root, and
- module.php has been run.
module_groups.php (which must be called module_groups.php) defines two functions, a module_id_create_group and a module_id_delete_group function. This module_id is your module’s ID string, which in fact must correspond to the name of your module’s directory because that is how mods/_core/modules/classes/Module.class.php constructs the function names to test and call.
This has implications for modules that are meant to be in extra which ultimately would move to _standard to replace an existing standard module (such as the case in this project). Barring some unsightly eval-based gymnastics, there is absolutely no way to give these functions the correct names without changing them by hand.
Note: During the code tracing I discovered that $this has a field called _directoryName. Obviously, this is supposed to be internal and not used anywhere outside of the Module class itself.
Observations:
- mods/_core/groups/create_automatic.php and mods/_core/groups/create_manual.php call module_id_create_group
- mods/_core/groups/delete_group.php calls module_id_delete_group
- Current directory appearently at mods/_core/groups
- module.php seems to be in effect (AT_INCLUDE_PATH and all other constants are defined)
Several observations:
- We don’t really know where we are. getcwd() shows we are one level down the ATutor root, inside “users” but it is not clear if we can rely on this
- module.php seems to have been run (i.e., constants are available)
During the code tracing I discovered that $this has a field called _type. It is unfortunate that this seems to be meant as private, because there is also AT_MODULE_TYPE_CORE, AT_MODULE_TYPE_STANDARD, and AT_MODULE_TYPE_EXTRA, which should come in handy.
More useful are AT_MODULE_DIR_CORE and AT_MODULE_DIR_STANDARD, which correspond to “_core” and “_standard,” respectively. I have been writing just _core and _standard but apparently I am supposed to use the constants.
Suddenly this came to me: What is sorely needed in ATutor are logs. Not just any old logs, but logs geared towards the system administrator and developer. The fact that the bug in module_news.php’s SQL statement has been checked into HEAD and IDRC has never noticed the problem speaks volumes about how much logs are useful.
ATutors actually has logs. In the admin interface. So what do they do? I don’t know.
- “In reply to” hacking: The relative path to the original post (including mod/_standard and all) is embedded in the actual reply body; this is incredibly bad design and things will certainly break until we move up to _standard space
- Email notifications: Need to verify what’s going on
- Formatting panel: Can we just turn it off, please? It’s very annoying when using a screen reader. I say if you’re depending on Javascript you have deep design issues; I stand by my claim.
- Post button: Why is it so hard to find the Post button when using a screen reader?
- Search does not work. Well, it does, sort of, but it returns paths pointing to mods/_standard/forums, which is wrong.
- Figure out why I could not add user “Bob,” of “Alice and Bob” (A and B) fame.