Well, I've been devoted by my boss to the task of altering the moodle 1.5 assignment module to do a whole bunch of stuff it doesn't currently do, and things that aren't addressed by echo-assignment or review-assignment.
My question is really pretty simple: is there any documentation on how the assignment module actually works? I've been at it one day now, just sifting through code trying to figure it out, and my meager programming ability makes all this seem really, really, really convoluted. Things like functions named "p()" don't help things, but whatever, I'm dealing with it.
Can anyone point me to something (OTHER THAN SOURCE CODE) that gives some kind of information on where to start in altering this module? The developer overview wasn't much help aside from confirming that the assignment module does, indeed, have the required files.
Thanks for any guidance.
brian.
Here's an example of my level of ignorance for anyone who might be able to help.
Right now I'm just trying to figure out how everything is related. Clearly a module must look somewhere in the main library to get to functions like get_record for example. However, I cannot figure out how!!!! The mod/assignment/index.php file calls this function, in fact, and yet the function is not defined anywhere under the mod directory at all, so how the heck does it work? It's not defined in any included file either. I started looking for nested includes, but that turned up dry as well.
I know this is overly simple, but I guess I'm more of a simple code hacker than a designer or developer. It took me 30 minutes just to figure out how values made it (in human-readable form) to the drop-down lists in forms. Turns out there's more than one lang file defining a string for any given language.
Any help appreciated.
Right now I'm just trying to figure out how everything is related. Clearly a module must look somewhere in the main library to get to functions like get_record for example. However, I cannot figure out how!!!! The mod/assignment/index.php file calls this function, in fact, and yet the function is not defined anywhere under the mod directory at all, so how the heck does it work? It's not defined in any included file either. I started looking for nested includes, but that turned up dry as well.
I know this is overly simple, but I guess I'm more of a simple code hacker than a designer or developer. It took me 30 minutes just to figure out how values made it (in human-readable form) to the drop-down lists in forms. Turns out there's more than one lang file defining a string for any given language.
Any help appreciated.
Anyone? How about another specific question about the structure of the assignment module:
When you get to the first form used to create an assignment, that actually seems to be created by a file in the courses module, which I guess makes some sense since you don't really want to create an instance of an assignment without having all the information (like the assignment type).
Once you pick the type and fill out the rest of the information, and click "next", you're then calling the details.php file in the assignment module directory. This file looks pretty simple. It calls the "setup" function of the appropriate class. For example, I figured if you chose to create an assignment of type uploadsingle, it would go to types/uploadsingle, open up the assignment.class.php file, and call the setup function. Not so much. That file doesn't contain a setup function, in spite of it appearing to be the class *definition*.
OK, so grep'ing the assignment module directory, there's a "setup" function in mod/assignment/lib.php. Is this the same function being called by details.php?
This next question is a deeper ignorance: in details.php, when you pass $form to the setup function, what value does that actually have? Is that just an object containing all of the data elements from the earlier courses/mod.html form?
Any clues or pointers would be very much appreciated.
Thanks.
brian.
When you get to the first form used to create an assignment, that actually seems to be created by a file in the courses module, which I guess makes some sense since you don't really want to create an instance of an assignment without having all the information (like the assignment type).
Once you pick the type and fill out the rest of the information, and click "next", you're then calling the details.php file in the assignment module directory. This file looks pretty simple. It calls the "setup" function of the appropriate class. For example, I figured if you chose to create an assignment of type uploadsingle, it would go to types/uploadsingle, open up the assignment.class.php file, and call the setup function. Not so much. That file doesn't contain a setup function, in spite of it appearing to be the class *definition*.
OK, so grep'ing the assignment module directory, there's a "setup" function in mod/assignment/lib.php. Is this the same function being called by details.php?
This next question is a deeper ignorance: in details.php, when you pass $form to the setup function, what value does that actually have? Is that just an object containing all of the data elements from the earlier courses/mod.html form?
Any clues or pointers would be very much appreciated.
Thanks.
brian.
Brian
I share your interest in finding some documentation that more clearly explains the flow of data within Moodle. The Documentation folks may be working on that now, but I would love to see a diagram of some kind for each module. I also am not a programmer and only had an introducation to Algol programming way back in 1963. Do today's programmers make something like the good old flow chart when they design?
Well, programming and scripting are not the same thing. I do TONS of scripting in the course of my work, using PHP, Perl, shell and other stuff. For this type of work (I'm a system administrator), no flow chart is really needed. However, developers working on more complex systems like moodle should have at some point created some form of flow chart, probably using some whiz-bang modeling technology like UML. I personally would settle for a plain text or ascii diagram description of how modules work.
Seems like it would be in the best interest of the project as a whole, since such documentation lowers the barrier to entry for younger developers to help out, and encourages seasoned developers to help out as well. Most seasoned developers I know (and I know many) hate the lack of developer docs in open source projects and they end up rolling their own solution instead as a result, because they figure by the time they figure out how something like moodle actually works, and how to implement a new feature in the proper way, they could've just prototyped something from scratch that does exactly what they want. In the case of moodle, they might be right.
If I get my assignment type implemented, I'll make it available once the project is out of my hair. I'm likely to then deploy it, document it internally, and never touch moodle again.
Usually I look specifically for documentation before I recommend a product for use by the department. I slipped this time, and am paying for it. After 24 hours of doing nothing but sifting through code, I've only just *sorta* figured out how the assignment module works, and what's more I don't think I can implement my changes without creating a completely different module, so it's 24 hours wasted. Now I need to figure out how to create a module from scratch, so I'll be looking at the newassignment module to possibly use as a template.
Seems like it would be in the best interest of the project as a whole, since such documentation lowers the barrier to entry for younger developers to help out, and encourages seasoned developers to help out as well. Most seasoned developers I know (and I know many) hate the lack of developer docs in open source projects and they end up rolling their own solution instead as a result, because they figure by the time they figure out how something like moodle actually works, and how to implement a new feature in the proper way, they could've just prototyped something from scratch that does exactly what they want. In the case of moodle, they might be right.
If I get my assignment type implemented, I'll make it available once the project is out of my hair. I'm likely to then deploy it, document it internally, and never touch moodle again.
Usually I look specifically for documentation before I recommend a product for use by the department. I slipped this time, and am paying for it. After 24 hours of doing nothing but sifting through code, I've only just *sorta* figured out how the assignment module works, and what's more I don't think I can implement my changes without creating a completely different module, so it's 24 hours wasted. Now I need to figure out how to create a module from scratch, so I'll be looking at the newassignment module to possibly use as a template.
Hmm, usually it takes a couple weeks for a new student with decent grades in some programming courses to figure out how to write a simple Moodle module, and then a few more weeks to thouroughly test and debug it. This seems better than other open source software we've worked with, and certainly easier than closed source (or easier than paying $70k to be allowed to build a block
>.
Not to say that flow charts and good comments aren't a great idea (I think Mark did a very nice one for lesson, for instance, and the 'howto' docs for building new blocks are a great model and did allow me to make a --simple--new block in a few hours), however I wonder what software you are talking about that is so well documented one can build a new module in a day or two?
Not to say that flow charts and good comments aren't a great idea (I think Mark did a very nice one for lesson, for instance, and the 'howto' docs for building new blocks are a great model and did allow me to make a --simple--new block in a few hours), however I wonder what software you are talking about that is so well documented one can build a new module in a day or two?
In the past I have worked extensively with numerous content management solutions, and other PHP software, usually involving customization or extension. Some of these solutions were put together very simply. Others were quite complex. Most were nightmarish in one way or another. Many had documentation even in their earliest days on how to extend the application "the right way" available, either from the project itself or on the site of a contributor to the project. It existed, which is the point.
The other point is that saying that other projects don't have documentation like this is not only incorrect, it's also not justification for not having it, and it certainly isn't going to stop developers from expecting it.
The last point is that, as I've said, I'm not a full-time programmer. I didn't take courses in programming complex, OO PHP systems.
For completeness, I'll also point out that I never said my expectation was to get things done in "a day or two". I'm actually here asking for help to make sure I haven't missed some documentation that maybe does exist on another site, because my project is to be completed in two weeks, and this system is, as I've also said, slightly beyond my meager programming abilities. If nobody knows of such documentation, I'd like to officially make a feature request that some documentation be developed along these lines.
The other point is that saying that other projects don't have documentation like this is not only incorrect, it's also not justification for not having it, and it certainly isn't going to stop developers from expecting it.
The last point is that, as I've said, I'm not a full-time programmer. I didn't take courses in programming complex, OO PHP systems.
For completeness, I'll also point out that I never said my expectation was to get things done in "a day or two". I'm actually here asking for help to make sure I haven't missed some documentation that maybe does exist on another site, because my project is to be completed in two weeks, and this system is, as I've also said, slightly beyond my meager programming abilities. If nobody knows of such documentation, I'd like to officially make a feature request that some documentation be developed along these lines.
One thing that would help is if you would tell us what your project is supposed to do.
Unfortuntly, you stepped into the newest, most 'advanced', and most poorly documented Moodle code, the "All New 1.5 Assignment" module. Most of the other modules are much easier to understand and many have decent documentation in the code.
Two weeks is also a very short time to accomplish a secure and stable module (I would say it's too short a time for programming, debugging, and security evaluation for anything but a very simple tool), so you might communicate to your boss that good things that will be easy to maintain and extend in the coming years take a bit longer, esp. for someone not familiar with the codebase.
For a new (to Moodle) programmer, I would recommend planning two weeks to get familiar with the codebase, say by following the block HowTo and making a block, then by reworking the Module template and making a simple module, and then you'll be able to estimate how long a more complex tool should take.
Unfortuntly, you stepped into the newest, most 'advanced', and most poorly documented Moodle code, the "All New 1.5 Assignment" module. Most of the other modules are much easier to understand and many have decent documentation in the code.
Two weeks is also a very short time to accomplish a secure and stable module (I would say it's too short a time for programming, debugging, and security evaluation for anything but a very simple tool), so you might communicate to your boss that good things that will be easy to maintain and extend in the coming years take a bit longer, esp. for someone not familiar with the codebase.
For a new (to Moodle) programmer, I would recommend planning two weeks to get familiar with the codebase, say by following the block HowTo and making a block, then by reworking the Module template and making a simple module, and then you'll be able to estimate how long a more complex tool should take.
Thanks. I agree with you. Actually, the two weeks is technically for a "prototype". At first, I thought it should be an assignment type, called "uploadmulti", which would look and act much like the "uploadsingle" type, but would allow a professor to specify the names of the required files, and then students would upload those files to complete the task. Sounds simple, but this implies quite a number of things.
The odd thing is that some of the things appear to be in place to support this, but then on the database end I'd have to add some things, so this led me to the conclusion that a new module might be in order.
I do have specific questions about specific bits of code, so maybe I can find a developer forum here and ask those questions and get somewhere.
I did notice that another module was documented a bit better in the code than the assignment module. This just made me more bitter though, so I dismissed it as coincidence.
thanks again.
The odd thing is that some of the things appear to be in place to support this, but then on the database end I'd have to add some things, so this led me to the conclusion that a new module might be in order.
I do have specific questions about specific bits of code, so maybe I can find a developer forum here and ask those questions and get somewhere.
I did notice that another module was documented a bit better in the code than the assignment module. This just made me more bitter though, so I dismissed it as coincidence.
thanks again.