MoodleDocs - User contributions [en]

Development:XMLDB introduction

2010-07-28T12:40:48Z

Josepuib: Wrong verbal tense

[[Development:XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 year old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS, must be fulfilled by following these non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd party developers to migrate to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning. However, it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes drastically.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with the underlying RDBMS. It will help us understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists of a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independent of the underlying RDBMS being used. And this must be particularly true for the XMLDB part.

Obviously it's possible that in the SQL part we find some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[Development:DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with a high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[Development:DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' is still present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and these will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both of these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chunks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending, while using easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprehensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[Development:XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[Development:XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[Development:XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]

Development:XMLDB introduction

2010-07-28T12:32:20Z

Josepuib: Spelling mistake

[[Development:XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 year old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS, must be fulfilled by following these non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd party developers to migrate to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning. However, it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes drastically.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with the underlying RDBMS. It will help us understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists of a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independent of the underlying RDBMS being used. And this must be particularly true for the XMLDB part.

Obviously it's possible that in the SQL part we found some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[Development:DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with a high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[Development:DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' is still present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and these will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both of these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chunks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending, while using easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprehensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[Development:XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[Development:XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[Development:XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]

Pedagogy

2010-05-10T19:30:19Z

Josepuib: spelling mistake (I think it was) /* Social Constructionism as a Referent */

Let's sit back and really reflect on the pedagogy that is at the core of what we, as online educators, are trying to do.

==Definition of Pedagogy==
One definition of [http://en.wiktionary.org/wiki/Pedagogy pedagogy] in Wiktionary says
#The profession of teaching
#The activities of educating, teaching or instructing

Wikipedia has a much longer page on [http://en.wikipedia.org/wiki/Pedagogy Pedagogy]. At one point it said Pedagogy is the art or science of being a teacher, generally refers to strategies of instruction, or a style of instruction. The word comes from the Ancient Greek παιδαγωγέω (paidagōgeō; from παῖς (child) and ἄγω (lead)): literally, "to lead the child”.

==Moodle in three short paragraphs==

The heart of Moodle is courses that contain activities and resources. There are about 20 different types of activities available (forums, glossaries, wikis, assignments, quizzes, choices (polls), scorm players, databases etc) and each can be customised quite a lot. The main power of this activity-based model comes in combining the activities into sequences and groups, which can help you guide participants through learning paths. Thus, each activity can build on the outcomes of previous ones.

There are a number of other tools that make it easier to build communities of learners, including blogs, messaging, participant lists etc, as well useful tools like grading, reports, integration with other systems and so on.

For more about Moodle, see http://moodle.org, and particularly the main community “course” called [http://moodle.org/course/view.php?id=5 Using Moodle]. It's crowded and busy these days, but jump in and you'll soon find interesting stuff I'm sure. The developers and the users are deliberately forced to mix in the same forums. The other great place to start is our [https://docs.moodle.org/ online documentation] which is a community-developed wiki site.

==Social Constructionism as a Referent==

I have these five points on a slide which I use in every presentation I do. They are useful referents taken from research that apply to education in general, boiled down into a simple list that I carry around under the moniker of "social constructionism".

# '''All of us are potential teachers as well as learners - in a true collaborative environment we are both'''.<br /><br /> It's so important to recognise and remember this.<br /><br /> I think this perspective helps us retain some humility as teachers and fight the (very natural!) tendency to consolidate all your history and assume the revered position of “wise source of knowledge”.<br /><br /> It helps us keep our eyes open for opportunities to allow the other participants in our learning situation to share their ideas with us and to remind us to listen carefully and ask good questions that elicit more from others.<br /><br /> I find I need to constantly remind myself of this point, especially when the culture of a situation pushes me into a central role (like now!)<br /><br />
# '''We learn particularly well from the act of creating or expressing something for others to see.'''<br /><br /> For most of us this is basically “learning by doing”, and is fairly obvious, yet it's worth reminding ourselves of it. <br /><br /> It's surprising how much online learning is still just presenting static information, giving students little opportunity to practice the activities they are learning about. I often see online teachers spending a great deal of time constructing perfect resources for their course, which no doubt is a terrific learning experience for them, but then they deny their students that same learning experience. Even textbooks often do a better job, with exercises after every chapter and so on.<br /><br /> Most importantly, such learning is best when you are expressing and presenting posts, projects, assignments, constructions etc '''for others to see'''. In this situation your personal “stakes” are a lot higher, and a lot of self-checking and reflection takes place that increases learning. Seymour Papert (the inventor of logo) famously described the process of constructing something for others to see as a very powerful learning experience, and really this sort of thinking goes right back to Socrates and beyond.<br /><br />
# '''We learn a lot by just observing the activity of our peers'''.<br /><br /> Basically this is about “classroom culture”, or learning by osmosis. Humans are good at watching each other and learning what to do in a given situation through cues from others. <br /><br /> For example, if you walk into a lecture theatre where everyone is sitting in seats, facing the front, listening quietly to the teacher at the front and taking notes, then that's most likely what you are going to do too, right?<br /><br /> If you are in a less rigid class where people are asking questions all the time, then it's likely you'll feel freer to do so too. By doing so you'll be learning about both the subject itself and the meta-subject of how learning occurs from overhearing the discussions of your peers and the kinds of questions that get asked, leading to a richer multi-dimensional immersion in learning.<br /><br />
# '''By understanding the contexts of others, we can teach in a more transformational way (constructivism)'''<br /><br /> As you probably know from experience, advice from a mentor or friend can provide better, more timely and customised learning experience than with someone who doesn't know you and is speaking to a hundred people.<br /><br /> If we understand the background of the people we are speaking to then we can customise our language and our expression of concepts in ways that are best suited to the audience. You can choose metaphors that you know the audience will relate to. You can use jargon where it helps or avoid jargon when it gets in the way.<br /><br /> Again this is a pretty basic idea - every guide to public speaking talks about knowing your audience - but in online learning we need to be particular mindful of this because we often have not met these people in person and don't have access to many visual and auditory cues.<br /><br />
# '''A learning environment needs to be flexible and adaptable, so that it can quickly respond to the needs of the participants within it'''.<br /><br /> Combining all the above, if you as a learning facilitator want to take advantage of your growing knowledge about your participants, giving them tailored opportunities to share ideas, ask questions and express their knowledge, then you need an environment which is flexible, both in time and space.<br /><br /> If you discover that you need to throw your schedule out the window because your participants know a lot less than you'd expected when you first designed the course, you should be able to readjust the schedule, and easily add new activities to help everyone (or just one group) catch up. Likewise, some great ideas for a simulation or something may have come up during discussions, so you should be able to add those later in the course.<br /><br /> Timewise, your participants may be spread over different timezones, or maybe they live in the same timezone but have differing free time, so you should be able to offer asynchronous activities where people can work together but at different times.<br /><br />

Jason Cole from Open University recently referred to these as “Martin's five laws” (ha!) but really they are referents: guiding concepts that I personally find useful to refer to whenever I need to make a decision in any given educational situation. In particular I find them useful for building '''communities of learners'''.

I guess you probably find a lot of this familiar, even if you use different terms. If not there is a lot of research about constructionism, constructivism and social Constructionism which you can find out more about in some of [http://dougiamas.com/writing/ my more formal papers].

==How Moodle tries to support a Social Constructionist view==

I'm going to go through the earlier list again, this time pointing out existing features in Moodle. Pedagogy and software design are closely intertwined in online learning - the "shape" of the software can help or hinder the teacher in what they are trying to do.

# '''All of us are potential teachers as well as learners - in a true collaborative environment we are both'''<br /><br /> Many of the activities in Moodle are designed to allow students to control common content, such as forums, wikis, glossaries, databases, messaging and so on. This encourages students to add to the total course experience for others.<br /><br /> In Moodle 1.7 we've made a huge step of a whole new Roles implementation which further breaks down the distinction of teachers and students, allowing Moodle system administrators and teachers to create new roles with any mix of capabilities they like. If you want students to be allowed to facilitate forums, create quiz questions or even control the course layout then you can. There is a very fine degree of control – for example you can allow students the ability to delete posts in just one single forum if you like.<br /><br /> I hope that people will take these new features and experiment with control in their courses, allowing students more flexibility to do things that were previously thought of as something teachers should do.<br /><br />
# '''We learn particularly well from the act of creating or expressing something for others to see'''<br /><br /> Moodle has a wide range of ways in which people can create representations of their knowledge and share them.<br /><br />
#* The course structure itself is terrific way to construct a shared and active representation of the learning journey that everyone is going through.
#* Forums of course are the core of this, providing spaces for discussion and sharing of media and documents (using the media plugin filters, attachments or simply links).
#* Wikis are collaboratively-built pages useful for group work and other negotiations.
#* Glossaries are collaboratively-built lists of definitions that can then appear throughout the course.
#* Databases are an extension of this idea allowing participants to enter structured media of any type (for example a collection of digital photos or a library of references). <br /><br /><br />
# '''We learn a lot by just observing the activity of our peers'''<br /><br /> The participants page is the main place where you can see everyone in your course. It shows a lot of information about your participants and how recently they've been there.<br /><br /> An Online Users block is the best way to see everyone else who might be on right now.<br /><br /> The Recent Activity block shows a great deal of information about what has happened recently, and via link you can see reports with more detail. Things that happened not only include changes to the course and forum posts, etc, but also things like assignment submissions and quiz attempts. Students can't see the results that other students got from these activities, but they do get some sense that everyone is submitting Assignment 1 now and this peer pressure hopefully helps those who need it.<br /><br /> Finally, almost all the modules will "tag" an entry or change with the name of the user, so that you can see who did what and when. For example, wiki pages all have a history link with full details on every edit.<br /><br />
# '''By understanding the contexts of others, we can teach in a more transformational way (constructivism)'''<br /><br /> There are many different ways to find out about people. Access to these can be decided on a site basis (different sites have different privacy policies): <br /><br />
#* The user profile contains several fields where people can provide information about their background, etc. In particular there is a user profile photograph, which appears throughout Moodle whenever that person writes something. The photo links back to the profile page.
#* A compendium of forum posts (and discussion starters) by that person in that course (or across the site).
#* Individual blogs allow people to express things in a public but reflective way, often providing access to thinking that might not normally expressed in, say, a forum.
#* Overall activity reports show all the contributions from a user in a course, including assignment submissions, glossary entries, etc.
#* User log reports show detailed logs of every action taken by a person in Moodle, as well as graphs showing overall activity statistics.
#* The survey module provides a variety of proven questionnaire instruments for discovering interesting information about the state of mind of the group.<br /><br />
# '''A learning environment needs to be flexible and adaptable, so that it can quickly respond to the needs of the participants within it'''<br /><br />
#* The course page itself is the main tool for a teacher, allowing them to add/remove and structure activities as necessary. Changing the course is one button click away at any time, so the teacher can change it on a whim. In Moodle 1.7 we have now added AJAX features, so that activities, sections and blocks can all be simply dragged-and-dropped.
#* The roles in Moodle 1.7 can be applied individually in every context across the site, and can be further tweaked with overrides. So if you want to create one single quiz where everyone has access to everybody's results, or allow parents of students to see parts of your course, then you can.
#* Navigation around the course and site is automatically generated.
#* The gradebook is automatically maintained, and reflects the activities in the course at any given time.
#* There are preferences for many aspects of appearance and behaviour, at site, course and activity levels, allowing educators to fine-tune the behaviour of Moodle in many ways.
#* External systems can be integrated easily, to maintain authentication, enrolments and other things, allowing Moodle to react smoothly as data in other systems is modified. <br />

==Finding a balance==

Before I talk about about where we are going, let me talk a little about the balance that a Course Management System (aka VLE) like Moodle needs to achieve. One thing I found out quickly in a community like ours is that people have a wide range of expectations of online learning.

At the fascist extreme there are those who want students to be highly controlled: reading resources that are revealed at set times and later sitting quizzes to prove they read those resources. I call this the rat-in-the-maze approach, or dump-and-pump.

At the techno-hippy end of that spectrum there are those who want to devolve management completely, with every user running their own portfolio site, streaming blogs and files to each other using RSS and trackbacks. It's an interesting dream that really opens up thinking about education but I think the problems to be solved are many (such as security, accountability, the structure of institutions etc).

The vast majority of people that I meet fall somewhere between these two extremes. Many of them are new to online learning, and are looking for the next step beyond what they were being paid to do offline, while being accepting of gentle guidance to improving their online techniques. These people are on a steep learning curve already without facing the aggregation of 100 different blogs.

==Progression==

Moodle needs to be flexible to cater for a wide variety of needs while remaining simple enough for ordinary teachers to start making good use of the power of the internet for community building and collaborative learning. My hope is that Moodle can be seen as a toolbox where they can start simply and naturally, and then progress to more and more advanced community facilitation over time. Ultimately, we'd like to see teachers being involved with and supported by a community of their peers.

Let's look at a typical progression that a teacher might go through as they learn to use the Moodle tools:

# Putting up the handouts (Resources, SCORM)
# Having a passive forum
# Using Quizzes and Assignments (less management)
# Using the Wiki, Glossary and Database tools (interactive content)
# Using the Forum seriously and actively
# Combining activities into sequences, where results feed later activities
# Think deeper about each activity, advanced features, unusual applications
# Using the Survey module to study and reflect on course activity
# Using peer-review modules like Workshop
# Conducting active research on oneself, sharing ideas in a community of peers

==Where Moodle can do better and what we're doing about it==

Keeping in mind the theme of this paper and the conference stream, here are a few of the upcoming plans for things that are more related to pedagogy:

===Repositories and Portfolios===

Currently only teachers can upload and manage '''collections''' of files into Moodle, using the Files tool in each course. There is no easy way to share files between courses, and no way for ordinary users to keep a portfolio, say.

This is changing in Moodle 2.0 with the addition of a [[Development:Repository API|Repository API]] (which allows any external repository to be used as a source of files and data) and a [[Development:Portfolio API|Portfolio API]] (which will allow all users to capture things in Moodle and store them in any external repository of their choice).

Special-purpose repositories are a growing area, and it means institutions can keep their valuable data where they want to, even if they switch front-end systems like VLEs.

Most importantly, this will allow the development of e-Portfolios to explode, and these are something I think a lot of us really want to see as a very positive pedagogical enhancement.

===Community Hubs===

We want to improve the way teachers and users of Moodle communicate with each other, not only about e-learning and Moodle, but also in their subject areas. For example, imagine a Biology 101 teacher finding a "community" button in their course, taking them straight to a place where their peers are all discussing best practice for teaching Biology 101, sharing and browsing repositories of course materials and learning designs.

A major focus for Moodle 2.0 is the creation of networking between Moodles, allowing anyone to turn their Moodle site into a Moodle Community Hub. Login between Moodles will be transparent but secure and fully controlled by site administrators. The peer-to-peer nature of the design will allow all sorts of interesting scenarios to develop.

===Better interaction between tools===

Currently Moodle already sends an email as notification of a lot of different types of events, but it can be difficult to manage. By piping all the messaging from throughout the system via the Messaging module that we already have, users will have a much finer control over exactly what sorts of messages they want to see. We can also allow email to come back into Moodle.

Similarly, we'll be integrating the existing blogging much more tightly with the whole system, by adding "blog this" buttons everywhere that allow users to capture and comment on items of interest.

===Metadata and outcome statements===

Currently Moodle courses need to be manually connected to state learning standards. In many places of the world such reporting is mandatory, so it can take a lot of time.

Moodle 1.9 introduced a mechanism so that:

# admins can import a long list of outcome statements (as tags)
# teachers can relate a subset of these to their course
# teachers can connect each activity to an even smaller subset

This helps course design by providing teachers with a tool to ensure the requirements for the course are being met, while also providing much better reporting for admins and students on what has been achieved.

Moodle 2.0 will build on this with [[Development:Progress_tracking|Progress Tracking]] which allows these things to be guided by individual learning plans for each student.

===Role-playing and scenario simulations===

A popular and effective technique in face-to-face teaching is that of role-playing in scenarios, and this can be difficult to do online. You could imagine an Environmental Science course running a role-playing simulation where some students play the government, some as Greenpeace, some as industry for a particular scenario.

The plans for this have been around for a long time, but I hope it can be developed soon. It would be a module where people can be assigned roles within a simulated situation and appear to others anonymously in those roles, interacting in forums, wikis, and all the other tools in Moodle according to the rules of the simulation.

==What else would you like to see?==

I hope this has stimulated some thoughts about the sorts of things you would like to see in your ideal online learning environment. If so, please join in with the discussions on http://moodle.org and let's brainstorm them a bit. I hope we can come up with some new ideas to put in the [http://tracker.moodle.org Moodle Tracker], or at least some support or modifications for old ones.

[[Category:Pedagogy]]
[[fr:Pédagogie]][[es:Pedagogia]][[ru:Педагогика]]
[[de:Pädagogik]]

Course settings

2010-04-21T09:16:57Z

Josepuib: spelling mistake

{{Course admin}}

[[Image:Settings.gif]]'''Course settings''' control how the things appear to the participants in a course. It is the first page viewed after creating a course. It can be edited through the '''Settings''' link in the [[Course administration block]] menu. This page has links to other pages that may describe a setting in more detail. Different versions of Moodle may not have all the settings listed below.

==General==
[[Image:generalsettings1.gif|thumb|General settings]]
===Category===

The site administrator may have created course categories to help teachers and students find their courses easily.

The capability [[Capabilities/moodle/course:changecategory|moodle/course:changecategory]] controls whether a user can edit the course category.

===Short name===
Many institutions have a shorthand way of referring to a course, such as BP102 or COMMS. Even if you do not already have such a name for your course, make one up here. It will be used in several places where the long name is not appropriate. The most common use is in the navigation bar that is at the top of most pages and this provides an active link to the course home page.

[[Image:Assignment nav trail.jpg|Point to Assignment, part of the Features course, in a site called Moodle]]

The above example has the short course name, "Features", in the navigation links (breadcrumb). The short name also appears in the subject line of email messages that are part of the course.

The capability [[Capabilities/moodle/course:changeshortname|moodle/course:changeshortname]] controls whether a user can edit the short name field.

===ID number===
The ID number is an alphanumeric field. It has several potential uses. Generally, it is not displayed to students. However, it can be used to match this course against an external system's ID, as your course catalog ID or can be used in the certificate module as a printed field.

The capability [[Capabilities/moodle/course:changeidnumber|moodle/course:changeidnumber]] controls whether a user can edit the ID number.

===Summary===

The summary appears on the course listings page.

The capability [[Capabilities/moodle/course:changesummary|moodle/course:changesummary]] controls whether a user can edit the course summary.

===Format===
[[Image:generalsettings3.gif|thumb|Format section in course settings]]
See [[Course formats]]

===Number of weeks/topics===
This setting is only used by the 'weekly' and 'topics' course formats. In the 'weekly' format, it specifies the number of weeks that the course will run for, starting from the course starting date. In the 'topics' format, it specifies the number of topics in the course. Both of these translate to the number of "boxes" down the middle of the course page.

[[#top|Top]]
===Course start date===
This is where you specify the starting time of the course (in your own time zone). The first week will start on the date you set here when you use the "Weekly" course format.

This setting will not affect courses using the 'social' or 'topics' formats.

However, this setting will have an effect on the display of logs, which use this date as the earliest possible date you can display. It can also make your course not visible to students even if when the course is available to students (see below).

:''TIP:'' If your institution runs on a weekly schedule, you may want to consider setting the start date for courses on the first day of the week, like a Monday.

:''TIP:'' In general, if your course does not have a real starting date then set the date to yesterday and use the availability setting to reveal the course to students.

===Hidden sections===
This option allows you to decide how the hidden sections in your course are displayed to students. By default, a small area is shown (in collapsed form, usually gray) to indicate where the hidden section is, though they still cannot actually see the hidden activities and texts. This is particularly useful in the Weekly format, so that non-class weeks are clear, or if you have quizes you don't want your students to see.

:''TIP:'' If you choose, these non-available items can be completely hidden, so that students do not even know that sections or an activity in the course are hidden.

[[#top|Top]]
===Show grades===
Many of the activities allow [[Grades|grades]] to be set. By default, the results of all grades within the course can be seen in the Grades page, available from the main course page for students and teachers.

:''TIP:'' If a teacher is not interested in using grades in a course, or just wants to hide grades from students, then they can disable the display of grades with this option. This does not prevent the teacher using or setting grades for an individual activities, it just disables the results from being displayed to students.

===Show activity reports===
[[Activity_report#Individual_Activity_Report|Activity reports]] are available to each student. These reports or logs show their activity and contributions in the current course. These reports include their detailed access log.

Student access to their own reports is controlled by the teacher via this course setting. For some courses, these reports can be a useful tool for a student to reflect on their involvement and appearance within the online environment, but for some courses, this may not be necessary.

Teachers always have access to these reports. Teachers can use the button or tab visible on each person’s profile page or use the [[Reports]] link in the course administration block.

Your site administrator may ask you to turn this feature off. Showing activity reports can place a load on the server, slowing it down at times. For large or long classes it may be more efficient to keep it off.

[[#top|Top]]
===Maximum upload size===
[[Image:Changeupload.jpg|thumb|Maximum upload size setting]]
This setting defines the largest size of file that can be uploaded by students in this course. The site administrator can determine [[Site_policies#Maximum_uploaded_file_sizefile |sizes available]] for the teacher to select. Teachers should be aware of a course's [[Files|file structure]].

It is possible to further restrict this size through settings within each activity module.

===Force theme===
If the site administrator has allowed the teacher to set a course [[Themes|theme]], this pull down menu will appear with a list of themes on the site.

===Is this a meta course?===
A [[Metacourses|metacourse]] only gets its enrollments from one or more other courses. Many metacourses can get their enrollment from the same course. A metacourse can get its enrollment information from many other courses.
''TIP:'' Turning this on prematurely before the meta courses are properly setup will cause Moodle to return 'This course does not allow public access' when users would ordinarily be able to access through internal enrollment. Verify that the linked course(s) exists. Remember a meta course ONLY gets its enrollment from other courses.

[[#top|Top]]

==Enrolments==
[[Image:generalsetting4.gif|thumb|Enrolment settings]]
===Enrolment plugins===
This setting allows you to choose an interactive [[Enrolment plugins|enrolment plugin]], such as [[Internal enrolment|internal enrolment]] or [[Paypal]]. If you use a non-interactive enrolment plugin, this setting has no effect.

===Default role===

From Moodle 1.7 onwards, a default course role, such as student, may be set.

===Course enrollable===
This setting only affects interactive enrolment plugins, such as [[Internal enrolment|internal enrolment]] and [[Paypal]]. It has no affect at all on non-interactive plugins (e.g. External Database, LDAP). Setting it to "no" or if it is outside the specified date range will result in the student being told the course is "Not enrollable" and being returned to the front page, if they are attempting to enroll using an interactive plugin.

:''TIP:'' If you are using Internal enrolment and you have not set an enrolment key, you should seriously consider setting this to ''No'' otherwise any user can enrol on your course.

[[#top|Top]]
===Enrolment duration===
This setting specifies the number of days a student can be enrolled in this course (starting from the moment they enroll). Set this value with care - setting it when not required is a common origin of the complaint, "my students keep disappearing after n days".

:''TIP:'' This is useful for rolling courses without a specific start or end time. Students are automatically unenrolled after the number of days has expired in this setting.

:''TIP:'' This setting can be used as an alternative to a manually unenrolling students or using a clean-up function to remove defunct students at some future time.
:''TIP:'' If this course is a metacourse, the enrolment period will not be used.

==Enrolment expiry notification==
[[Image:generalsettings5.gif|thumb|Enrolment expiry notification settings]]
These settings determine whether teachers and/or students are notified that their enrolment is about to expire and how much notice they should be given.

[[#top|Top]]
==Groups==
[[Image:generalsettings6.gif|thumb|Groups settings]]
===Group mode===
Here you can define the [[Groups|group mode]] at the course level by a pull down menu. "[[Groups#No_groups|No groups]]", "[[Groups#Separate_groups|Separate groups]]" and "[[Groups#Visible_groups|Visible groups]]" are the choices. The selected setting will be the default group mode for all activities defined within that course. The group setting can affect what users see in the [[Participants]] list.

:''TIP:'' You may leave it set to "No groups" and still have specific activities use groups. In this case the force setting below should be set to "no". For example, the teacher can use a group setting to completely separate cohorts of students such that each group is unaware of the other in the course.

===Force===
If the group mode is "forced" at a course-level, then this particular group mode will be applied to every activity in that course. This will override any activities that may have a special group setting.

:''TIP:''The force setting is useful when the teacher wants to set up a course and not have to change each activities group settings.

[[#top|Top]]
===Default grouping===

{{Moodle 1.9}}If [[Groupings|groupings]] are enabled (in Moodle 1.9 onwards), a default grouping for course activities and resources may be set.

==Availability==

[[Image:generalsettings7.gif|thumb|Availability settings]]
This option allows you to "hide" your course completely. It will not appear on any course listings, except to teachers of the course and administrators. Even if students try to access the course URL directly, they will not be allowed to enter.

:''TIP:'' The [[Course_settings#Course_start_date|Start Date]] of the course can also effect course visibility.

[[#top|Top]]
===Enrolment key===
A course [[Enrolment key|enrolment key]] enables access to courses to be restricted to those who know the key. This feature is typically used on sites which encourage self enrolments or use an external database process to register students in a course. The idea is that Teachers or course administrators will supply the key to authorized people using another means like private email, snail mail, on the phone or even verbally in a face-to-face class.

When the key is left blank and [[Course_settings#Course_enrollable|self enrolment]] is allowed, then anyone who has a Moodle username on the site will be able to enrol in the course.

:''TIP:'' A student can be manually enroled in the course and will not have to supply the required key when they enter the course for the first time.

:''TIP:'' If this password "gets out" and you have unwanted people enrolling, you can unenrol them (see their user profile page or unassign them from the [[Assign roles|student role]] in the course) and change this key. Any legitimate students who have already enrolled will not be affected, but the unwanted people will not be able to get back in.

:''TIP:'' If you are using a non-interactive enrolment, system (e.g., External Database, LDAP) and you do not want students who fail the initial check to be asked for an enrolment key that they will not have, set ''Course Enrolable'' to ''No''.

:''TIP:'' You can control who is displayed as providing the Key when someone is requested to supply the key. See [[Internal enrolment]]

[[#top|Top]]
===Guest access===

Allows any authenticated user (i.e. logged in) to access the course (as a [[Guest role|guest]]), including those who have logged in "as guest". You can choose if they need an enrolment key or may enter without one.

People can log in as guests using the "Login as a guest" button on a login screen, where that feature is enabled for the site. When the user tries to enter a course, they will see the [[Log in|login screen]]. If you only need people authenticated via your normal authentication method to access courses (as Guest or not) it is probably wise to disable "Login as a guest" for a slight improvement in site security. See [[Manage authentication]].

Guests in a course ALWAYS have "read-only" access - meaning they cannot leave any posts or otherwise mess up the course for real students. No use information is stored for a guest.

:''TIP:'' This can be handy when you want to let a colleague in to look around at your work, or to let students see a course before they have decided to enroll.
:''TIP:'' You have a choice between two types of guest access: with the enrolment key or without. If you choose to allow guests who have the key, then the guest will need to provide the current enrolment key EVERY TIME they log in (unlike students who only need to do it once). This lets you restrict your guests. If you choose to allow guests without a key, then anyone can get straight into your course.

For more information see [[Guest role]].

[[#top|Top]]
===Cost===

If [[Paypal]] or [[Authorize.net Payment Gateway]] is set as the [[Enrolment plugins|enrolment plugin]], then the course cost can be set in the cost field.

==Language==
[[Image:generalsettings8.gif|thumb|Language settings]]

If you force a language in a course, the interface of Moodle in this course will be in this particular language, even if a student has selected a different preferred language in his/her personal profile.

[[#top|Top]]
==Role renaming==
[[Image:rolesimages.gif|thumb|Role renaming settings]]
{{Moodle 1.9}}In Moodle 1.9 onwards, you can rename the [[Roles|roles]] used in your course. For example, you may wish to rename the [[Teacher role]] as "Facilitator", "Tutor" or "Guide". These new role names will appear within the course. For example on the [[Participants|participants]] and the override permissions pages.

Please note that the site administrator or a [[Course managers|course manager]] may have changed the names or added new roles. These names will appear and the teacher may rename them.

[[Roles FAQ]] contains information on changing the name for teacher in Moodle 1.7 and 1.8. Prior to Moodle 1.7, the words for teacher and student may be changed in the course settings.

:''Tip'': Do not worry about changing every role name. Only change the site roles which are used in your course. For example, you may want to ignore renaming roles such as the [[Administrator role]] or the [[Authenticated user role]].

:''Tip'': To include new role names in a course backup, users should be included in the backup.

[[#top|Top]]
==Default course settings==

An administrator can set course settings defaults in ''Administration > Courses > [[Course default settings]]'' in Moodle 1.9.5 onwards.
[[#top|Top]]

==See also==

*[http://www.youtube.com/watch?v=zWOp1oq-TvI Video showing how to create a course in Moodle]

[[Category:Course]]

[[de:Kurseinstellungen]]
[[es:Administración del curso]]
[[eu:Ikastaroaren_ezarpenak]]
[[fr:Paramètres]]
[[ja:コース設定]]
[[ru:course/edit]]

Installation FAQ

2010-02-09T18:16:07Z

Josepuib:

{{Template:Installing Moodle}}

== System information needed for Installation problems forum ==
When posting questions to the [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum], try to provide as much background information as possible about your Moodle system. Use this template to copy and paste into your post:
* Server Operating System name (version also if possible):
* Browser name (version also if possible):
* Moodle version:
* Moodle install type? (New/Upgrade):
* Moodle config.php attached?(Y/N):
* Phpinfo attached? (Y/N):

For the last two items, try to include the following in your post as an attachment:
* A copy of your phpinfo output as shown in your browser (see the instructions above for an explanation of how to obtain this, or see [[phpinfo]]).
* A copy of the Moodle configuration file (with secret info like database password deleted, of course). This is located in the main Moodle directory (by default called moodle), and is named config.php

Copy and paste both of these into a single text file (using vi, Notepad, etc) and attach this to your post. If your PC is a Windows box and config.php looks messy (line breaks missing or in the wrong places) in Notepad, try Wordpad.

If you cannot provide your phpinfo, try to copy & paste and complete these in your post:
* Webserver (e.g. Apache/IIS) version:
* Database server (e.g. MySQL, PostgreSQL) version:
* PHP version:

For installation on web hosting accounts: contact your support desk who should be able to tell you this information.

: '''Security Warning''': Make sure you edit any files and delete any passwords before posting onto the forum.

[[#top|Top]]

==PHP - is it installed and what version do I have?==

Make a new file on your web site called ''info.php'', containing the following text, and call it from your browser:

<code php>
<?PHP phpinfo() ?>
</code>

If nothing happens then you don't have PHP installed or your webserver is not configured to handle .php files properly. See the installation docs for some information about where to download it for your computer. See the [[phpinfo]] page for details about the content of this page.

[[#top|Top]]

==What & where are Moodle's configuration settings stored?==
Configuration settings are stored in the config.php file stored in your moodle folder. This file is created during the installation process. If there is a problem and the installation cannot create the file, you can try creating it manually from the [[Configuration file]] docs. Please remember that manually editing the file is not recommended and may lead to blank pages, especially if there are additional spaces and/or lines after the final php closing tag "?>".

[[#top|Top]]
==Downloading previous releases of Moodle==
It is possible to download previous versions of Moodle that are not found on the [http://download.moodle.org Standard Moodle Download page]. There are zip and tgz compressed located at <nowiki>http://download.moodle.org/stable[version_number]</nowiki> (see links below).

{| style="width:75%; height:75px" border="0"
|-
| 2.0 Versions || [http://download.moodle.org/stable19 1.9 Versions] || [http://download.moodle.org/stable18 1.8 Versions]
|-
|[http://download.moodle.org/stable17 1.7 Versions] || [http://download.moodle.org/stable16 1.6 Versions] || [http://download.moodle.org/stable15/ 1.5 Versions]
|-
| [http://download.moodle.org/stable14 1.4 Versions] || [http://download.moodle.org/stable13 1.3 Versions] ||
|}

You can download previous releases by using wget, lynx or curl with this URL:
<nowiki>http://download.moodle.org/stable[version_number]</nowiki>.
:For example: to download Moodle version 1.5, use <nowiki>http://download.moodle.org/stable15</nowiki>. You'll see a directory tree with the files displayed. Click on the one you want and download as normal - if you require the latest update of the version, scroll to the end of the list and download the "moodle-latest" file.
* '''Windows Packages''': To download other releases not found in [http://download.moodle.org/windows/ Moodle packages for Windows], use this URL:
:<nowiki>http://download.moodle.org/windows/MoodleWindowsInstaller-latest-[version_number].zip</nowiki>
* '''Mac Packages''': To download other releases not found in [http://download.moodle.org/macosx/ Mac pacakges], use either of these URLs (depending on whether you need the Intel or PPC package):
:<nowiki>http://download.moodle.org/macosx/Moodle4Mac-Intel-[version_number].dmg</nowiki>
:<nowiki>http://download.moodle.org/macosx/Moodle4Mac-PPC-[version_number}.dmg</nowiki>
* '''Using CVS''': You can also use CVS to download older releases and incremental releases of the Moodle generic packages, e.g. Moodle 1.5.4 - see the [[CVS_for_Administrators | CVS documentation]].

[[#top|Top]]

== How to enable and check PHP error logs==
PHP can be set up to log errors in a variety of different ways: two of these involve the use of the php.ini file and the ini_set command. See [[PHP error logs]].

==Email copies are not being sent from my forums==

You ''must'' set up cron properly if you want Moodle to send out automatic email from forums, assignments etc. This same process also performs a number of clean-up tasks such as deleting old unconfirmed users, unenrolling old students and so on.

Basically, you need to set up a process to regularly call the script <code><nowiki>http://yoursite/admin/cron.php</nowiki></code>. Please refer to the [[Cron|cron instructions]].

Tips:
* Try the default settings in ''Administration > Server > Email''. This generally works.
*Make sure that ''allowuseremailcharset'' in ''Administration > Server > Email'' is set to No. Setting this to Yes can cause a problem in some versions of Moodle.

[[#top|Top]]
==I can't log in - I just stay stuck on the login screen==

This may also apply if you are seeing “Your session has timed out. Please login again” and cannot log in.

The following are possible causes and actions you can take (in no particular order):

* Sessions may not be configured properly on the server. You can test this by calling the script <nowiki>http://yourserver/moodle/lib/session-test.php</nowiki>.
* If your server is on shared hosting check that you have not reached your disk space quota. This will prevent new sessions being created and nobody will be able to log in.
* Carefully check the permissions in your 'moodledata' area. The web server needs to be able to write to the 'sessions' subdirectory.
* Your own computer (not your Moodle server) may have a firewall that is stripping referrer information from the browser. Here are some instructions for fixing [http://service1.symantec.com/SUPPORT/nip.nsf/46f26a2d6dafb0a788256bc7005c3fa3/b9b47ad7eddd343b88256c6b006a85a8?OpenDocument&src=bar_sch_nam Norton firewall products].
* Try deleting the ''sessions'' folder in your moodledata directory (anybody currently logged in will be thrown out)
* Try deleting cookies on your computer and/or try another browser or another client computer
* In Site Administration > Server > Session handling, try setting a value for 'Cookie prefix'. You can also do this by setting <code>$CFG->sessioncookie='something';</code> in config.php. This is especially true if you are using multiple Moodles on the same browser.
* You are using the correct username and password, yes?

If you are still having problems, read the [[Can_not_log_in | Cannot log in]] page.

[[#top|Top]]

==I log in but the login link doesn't change. I am logged in and can navigate freely.==

Make sure the URL in your <code>$CFG->wwwroot</code> setting is exactly the same as the one you are actually using to access the site.

[[#top|Top]]
==Uploaded files give "File not found"==

For example: Not Found: The requested URL /moodle/file.php/2/myfile.jpg was not found on this server.

Your web server needs to be configured to allow the part of the URL after a script name to be passed directly to the script. This is usually enabled in Apache 1, but is usually disabled by default in Apache 2. To turn it on, add this line to your ''httpd.conf'', or to a ''.htaccess'' file in your local directory (see [[Installing Moodle]] for more details):

'''AcceptPathInfo''' on

Note, this will ONLY work for Apache versions 2.x.

For IIS you need to configure URL rewriting. This feature is not available from Microsoft, you need to install a 3rd party IIS extension - see http://msdn.microsoft.com/en-us/library/ms972974.aspx
The recommended rewriting rule is

'''RewriteRule''' ^([^\?]+?\.php)(\/.+)$ $1\?file=$2 [QSA]

In theory you could try to use path info on IIS too, but it is not reliable, especially when using unicode file names.

If you are unable to configure your server properly then you can switch Moodle to use an alternative method. The major disadvantages is that you will not be able to use SCORM packages at all and some Adobe Flash and Java applets will not work either.

To use this alternative method, you should change the ''slasharguments'' variable. For moodle versions < 1.7, this is located in the Operating System section of ''Administration > Configuration > [[admin/config|Variables]]''. In later versions, this option is located in ''Site Administration > Server > HTTP''. You should now be able to access your uploaded files.

[[#top|Top]]
==Why are all my pages blank?==

Check the dirroot variable in ''config.php''. You must use complete, absolute pathnames e.g. (for a Windows installation)

<code php>
$CFG->dirroot = "d:\inetpub\sites\www.yoursite.com\web\moodle";
</code>

Another reason might be that PHP has not been configured to support MySQL. This is common on RedHat and OpenBSD installations. In this case, an error is generated, but since error displays are often disabled by default, all that is seen on the browser is a blank screen. To enable PHP error displays see [[Installation_FAQ#How_to_enable_and_check_PHP_error_logs | How to enable and check PHP error logs]].

To determine if MySQL support is your problem, insert this as the second line in your ''config.php'' file

<code php>
phpinfo();
</code>

then reload the web page. Examine the output closely to see if MySQL is supported. If not, look for a package you are missing.

[[#top|Top]]

== Why is a particular page blank or incomplete? ==

*'''Check your web server log files!!'''
:If a particular page is blank or incomplete (it doesn't display the footer), before you do anything else switch on [[Debugging]] and [[Installation_FAQ#How_to_enable_and_check_PHP_error_logs | check your PHP error logs]]. Having established that PHP error logging is working, reproduce the error. Immediately check the error log file right at the end. Hopefully you will see a PHP error message at or very near the end of the file. This may solve your problem directly or makes it a lot easier to diagnose the problem in the Moodle forums.

*If you are '''upgrading to a new version of Moodle''', check that you do not have an old version of a non-standard block or module installed. Remove any such blocks or modules installed using the admin settings page and start the install process again. However, do also make sure that you have included all optional plugins that were required by your courses. This is particularly common with "editing on".

*If you '''do not see any blocks listed''', turn editing on and remove any blocks that you have added to that page and try reloading.

*You may get this error immediately after '''selecting a language'''. At this stage of the installation process your Moodle computer may need to connect to the Internet and download a language pack, so check that the computer can access the Internet by using a browser. Check also that your PHP settings are as given in the Moodle [[Installing_Moodle#Requirements | Moodle Requirements]] page.

'''See also''':
*Using Moodle [http://moodle.org/mod/forum/discuss.php?d=97734 PHP configuration error] forum discussion

==Installation hangs when setting-up database tables==
Sometimes the installation will hang when setting up tables, where only half the page displayed in the browser and/or other outputs are removed. You may see truncated MySQL statements, or the “Scroll to continue” link is displayed but no “Continue” button is there.

See [[Unexpected installation halts]] for more about solutions that involve:
*Checking for MySQL limits
*Checking the .htaccess files
*Code customizations issues
*Checking memory limit
*Upgrade incrementally
*Fix fopen function

[[#top|Top]]

==Why can't I upload a new image into my profile?==

If you don't see anything on your user profile pages to let you upload user images then it's usually because GD is not enabled on your server. GD is a library that allows image processing.

1. Make sure '''GD has been included in your PHP installation'''. You can check this by going to ''Site Administration > Server > [[PHP info]]'' and looking for the gdversion setting. This setting is chosen automatically every time you visit that page. If it shows GD version 1 or version 2 then everything should be fine. Save that configuration page and go back to your user profile.

2. If Moodle thinks GD is not installed, then you will need to '''install the GD library'''.
*On Unix you may need to re-compile PHP with arguments something like this:

./configure --with-apxs=/usr/local/apache/bin/apxs --with-xml --with-gd
--with-jpeg-dir=/usr/local --with-png-dir=/usr --with-ttf --enable-gd-native-ttf
--enable-magic-quotes --with-mysql --enable-sockets --enable-track-vars
--enable-versioning --with-zlib

* On Windows this is usually a matter of "turning on" the extension in PHP by editing your php.ini file. To do this remove the semicolon for the php_gd2.dll extension - check that this file is actually present in your php extensions folder first (search your php.ini for extension_dir to determine where this points to on your hard disk). You should then have a line that looks like this:
extension=php_gd2.dll

:Windows users should see the [[Installing AMP|installation instructions]] for further help.

3. Remember to '''restart your webserver''' (if possible) and re-visit the Moodle configuration page after making any changes to PHP so it can pick up the correct version of GD.

'''See also''': Using Moodle forum discussion [http://moodle.org/mod/forum/discuss.php?d=44271 Profile pictures] for additional information.

== Why doesn't my Moodle site display the time and date correctly? ==

Each language requires a specific language code (called a '''locale''' code) to allow dates to be displayed correctly. The language packs contain default standard codes, but sometimes these don't work on Windows servers.

You can find the correct locale codes for Windows on these two pages: [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclib/html/_crt_language_strings.asp Language codes] and [http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclib/html/_crt_country_strings.asp Country/region] codes (e.g. "esp_esp" for spanish)

These new locale codes can be entered on the Administration >> Configuration >> [[admin/config|Variables]] page, where they override the ones in the currently chosen language pack.
[[#top|Top]]
== How do I uninstall Moodle?==

'''Webhost/manual installation''': If you have installed Moodle manually or have installed onto a webhost, follow these steps:
*Delete the moodle database using this mysql command (or delete using your mysql client, e.g. PHPMyAdmin):
<pre>sql>DROP DATABASE moodle;</pre>
:In the above example replace 'moodle' with the name of the moodle database you created when installing.
*Delete the moodledata directory. If you, or your users, have uploaded materials into this directory take a copy of these before deleting this directory.
*Delete the moodle directory itself. This will delete all of the moodle PHP script files.

'''XAMPP windows installation''': If you have installed Moodle on windows through the XAMPP package, follow these steps:
*Open cmd.exe and navigate to this directory within your installation directory:
<pre>server/mysql/bin</pre>
*Run this command, replacing USERNAME with your database username (the default is "root") and DATABASE with your database name (the default is "moodle"):
<pre>mysqladmin.exe -u USERNAME -p drop DATABASE</pre>
*Enter your database password at the prompt (the default is "" [blank]).
*Enter "y" to confirm the database drop.
*Delete the moodledata directory. If you, or your users, have uploaded materials into this directory take a copy of these before deleting this directory.
*Delete the moodle directory itself. This will delete all of the moodle PHP script files.

==How do I upgrade Moodle? Do I just overwrite the files?==
Do not overwrite files, it may cause strange errors. You should read the [[Upgrade]] documentation before proceeding.

==I obtain the message "Upgrade already running in this session, please wait!"==

Most likely you refreshed the page before the completion message. If you are absolutely sure that there are no upgrade processes active (php and/or mysql), you can click on "!!!" and restart the upgrade.

:''Note'': If you click on "'!!!" or try to restart the upgrade from another browser, there is a chance that your data in the database could be corrupted. If this happens, you will need to restore the database from sql dump and then restart the upgrade and wait - the process can take several hours on large sites.

==Migrating Moodle to a new site or server==
Migrating Moodle means that you have to move the current installation to a new server, and so may have to change IP addresses or DNS entries. To do this you will need to change the $CFG->wwwroot value in the config.php on the new server. You will also have to change any absolute links stored in the database backup file (before restoring the file on the new server) either using the admin/replace.php script, your text editor or another "search and replace" tool, e.g. sed. For more details see the [[Moodle_migration | Moodle Migration]] page.

[[#top|Top]]
==Why does my new installation display correctly on the server, but when I view it from a different machine, styles and images are missing?==
In the installation instructions, one of the suggested settings for 'webroot' is 'localhost'. This is fine if all you want to do is some local testing of your new Moodle installation. If, however, you want to view your new installation from another machine on the same local area network, or view your site on the internet, you will have to change this setting:
*For local testing, 'localhost' is fine for the webroot ($CFG->wwwroot in config.php).
*If you want to test your site from other machines on the same local area network (LAN), then you will have to use the private ip address of the serving machine, (e.g. 192.168.1.2/moodle) or the network name of the serving computer (e.g. network_name_of_serving_machine/moodle) as the web root. Depending on your LAN setup, it may be better to use the network name of the computer rather than its (private) ip address, because the ip address can and will change from time to time. If you don't want to use the network name, then you will have to speak to your network administrator and have them assign a permanent ip address to the serving machine.
*Finally, if you want to test your new installation across the internet, you will have to use either a domain name or a permanent (public) ip address/moodle as your web root. To handle both types of access, see [https://docs.moodle.org/en/masquerading masquerading].

[[#top|Top]]
==Maximum upload file size - how to change it?==
There are several places to change the maximum file upload size. The first place to check is the Administration block. Security -> Site Policies -> and look for "Maximum Uploaded File Size". This is the "maxbyte" variable found in older versions of Moodle (under Admin > Variables). Teachers may also set the maximum file size by the [[Course_settings#Maximum_upload_size|course administration block]].

The second place to check are the server files. The php.ini file has a limit which will override any other setting. The relevant php variables are upload_max_filesize and post_max_size. (Hint: remember to restart your server for changes to take effect). On Ubuntu, you must also change these variables in the apache.conf file, located in /etc/moodle/ on a standard install. Actually, the file need only be reread, which, if you are using phpCGI, happens when you invoke php. For more help see:
*[[Administration_FAQ#How_do_the_limits_on_uploaded_files_work.3F]]
*[[Installing_Moodle#Recheck_PHP_settings]]
*[[Installing_Moodle#Using_a_.htaccess_file_for_webserver_and_PHP_settings]]
*[[Site_policies#Maximum_uploaded_file_size]]
*These forum posts: http://moodle.org/mod/forum/discuss.php?d=63840#287960 and http://moodle.org/mod/forum/discuss.php?d=93882#p414650

[[#top|Top]]

==How do I install Moodle on Windows Vista?==

See [[Installing Moodle on Windows Vista]].

==Moodle claims PHP float handling is not compatible==

The symptom is that when you try to install or upgrade your Moodle, you get a message "Detected unexpected problem in handling of PHP float numbers".

[http://moodle.org/mod/forum/discuss.php?d=114945 This forum thread] and MDL-18253 have more information. In short, this problem should not happen, you can help us by telling posting information about exactly which version of PHP, and OS you are using. That may let us find a way to work around this problem.

You may be able to solve this issue by installing a more recent PHP versions. If you compile PHP yourself from source, changing the compilation options may help. However, since we don't understand the cause, we don't really know. If you do find a solution that works for you, please do tell us about it.

Update: we have a guess that the problem may be the [http://au2.php.net/manual/en/ini.core.php#ini.precision 'precision' setting in your php.ini file]. In a default PHP install this is set of 14. On at least one server that exhibited this problem it had been changed to a smaller value. So, if you see this problem, please try adding
ini_set('precision', 14);
to your config.php file, and report your success in MDL-18253.

==When upgrading Moodle claims my database is not UTF8 when I'm sure it is==

The symptom is that you are upgrading a post-1.6 Moodle to a newer version. The Environment check tells you that your database is not UTF8 and refuses to upgrade.

The database may not have it's character encoding set quite correctly. You can safely try this command on the database

ALTER DATABASE moodle DEFAULT CHARACTER SET utf8 COLLATE utf8_unicode_ci;

(Change 'moodle' for the name of your database). You need to copy this into your MySQL client program that comes packaged with it. Alternatively, a web client, phpmyadmin, is available as a plugin for Moodle or may be available through your hosting control panel.

If your Moodle site is version 1.5 or older then it's telling the truth.

[[#top|Top]]

== How do I run multiple instances of Moodle without duplicating base code? ==

See [http://moodle.org/mod/forum/discuss.php?d=13211 this thread] for a detailed explanation by [[User:Martin_Langhoff| Martin Langhoff]].

== What is FreeTDS and how can I use it in my installation? ==
[[FreeTDS]] is an open source implementation of the Tabular Data Stream protocol used by Microsoft SQL Server and Sybase for their databases. Unfortunately, Microsoft servers don't usually accept TDS 5.0 connections. FreeTDS allows your Unix/Linux applications to talk to these other database products and import and export data between different systems successfully.

== See also ==

* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]

[[Category:FAQ]]
[[Category:Installation]]

[[es:FAQ Instalación]]
[[fr:FAQ d'installation]]
[[nl:Installatie FAQ]]
[[ja:インストールFAQ]]
[[ru:FAQ по установке]]
[[pl:Instalacja FAQ]]
[[de:Installation FAQ]]

Development:lib/formslib.php Usage

2009-10-23T18:02:58Z

Josepuib: missing word

{{Formslib}}
==Usage of Formslib==

There are many phpdoc style comments in lib/formslib.php

course/edit.php and the included course/edit_form.php provide a good example of usage of this library.

Also see the PEAR docs for [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm docs] I found this [http://pear.php.net/manual/en/package.html.html-quickform.tutorial.php quick tutorial] and this [http://www.midnighthax.com/quickform.php slightly longer one] particularly useful.

We created some special wrapper functions for moodle. $mform->get_data() returns null if no data has been submitted or validation fails or returns an object with the contents of the submitted data.

===Basic Usage in A Normal Page===

Generally the structure of a page with a form on it looks like this :

<code php>
require_once('pathtoformdescription');
//you'll process some page parameters at the top here and get the info about
//what instance of your module and what course you're in etc. Make sure you
//include hidden variable in your forms which have their defaults set in set_data
//which pass these variables from page to page

$mform = new yourmod_formfunction_form();//name of the form you defined in file above.
//default 'action' for form is strip_querystring(qualified_me())
if ($mform->is_cancelled()){
//you need this section if you have a cancel button on your form
//here you tell php what to do if your user presses cancel
//probably a redirect is called for!
} else if ($fromform=$mform->get_data()){
//this branch is where you process validated data.

} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.
//setup strings for heading
print_header_simple($streditinga, '',
"<a href=\"$CFG->wwwroot/mod/$module->name/index.php?id=$course->id\">$strmodulenameplural</a> ->
$strnav $streditinga", $mform->focus(), "", false);
//notice use of $mform->focus() above which puts the cursor
//in the first form field or the first field with an error.

//call to print_heading_with_help or print_heading? then :

//put data you want to fill out in the form into array $toform here then :

$mform->set_data($toform);
$mform->display();
print_footer($course);

}
</code>

===Defining Your Form Class===

The form class tells us about the structure of the form. You are encouraged to put this in a file called {function}_form.php probably in the same folder in which the page that uses it is located. The name of your class should be {modname}_{function}_form eg. forum_post_form or course_edit_form. These classes will extend class moodleform.

Note the name you give the class is used as the id attribute of your form in html (any trailing '_form' is chopped off'). Your form class name should be unique in order for it to be selectable in CSS by theme designers who may want to tweak the css just for that form.

====definition()====

[[Development:lib/formslib.php_Form_Definition|Help is here for defining your form]] by defining a function definition() in your form class that sets up your form structure.

===Use in Activity Modules Add / Update Forms===

Syntax is the same in activity modules to create your update / add page. We are still supporting mod.html but if you want to use the new formslib then you can in Moodle 1.8 just include in your module directory the file mod_form.php instead of mod.html and it will be automatically detected. Inside this file you define a class with class name '{modname}__mod_form' which extends the class 'moodleform_mod'. See many examples of the core modules which have been converted to use formslib already.

====defaults_preprocessing====

For activity modules you use the same syntax to define your form. You may also want to override method defaults_preprocessing this can be used to take the data from the data base and tell the form how to fill out defaults in the form with this data. For example in the forum module in forum/mod_form.php we needed to tick an enable check box if a date had been selected in the date select. Normally data is loaded from the database and directly loaded into form fields with the same name as the database record you only need to use defaults_preprocessing if there isn't this one to one relationship. Another example is the lesson/mod_form.php which takes the data from the database and unserializes it. choice/mod_form.php shows an exampe of loading data from another db table referred to by a foreign key, to include in the form.

====Post Processing Still Done in lib.php Functions====

Post processing of data is done in lib.php functions modname_add_instance and modname_update_instance after the data has been validated. When migrating a form often little changes need to be made in the post processing. An exception is that date and date_time_selector fields automatically have their submitted data turned into timestamps so you don't need to do this in your add and update functions anymore.

====Automatically Including Standard Activity Module Form Elements====

Standard activity module form elements are automatically included using the moodleform_mod method standard_coursemodule_elements(). The default is to include a visibility and groupsmode select box and to include all necessary hidden fields. You can pass a parameter false to tell the method that your module doesn't support groups and so you don't want the groupsmode select button.

[[Category:Formslib]]

Development:Assignment development

2009-10-09T16:47:24Z

Josepuib: spelling mistakes

{{Moodle 2.0}}
This was a proposition of Assignment module development from POAS department of Volgograd State Technical University.
We don't want to fork from core, but was forced to do it by Moodle team. So it will be a separate module, that you can use instead of standard assignment. There may be a convertor some time ago.

New module name will be a poasassignment.
== Assignment 1.9 improvements ==
Just several simple, but useful improvements that can be done in stable version too:
# Usability improvement: on submission.php add a combo box to filter the content of the table: Show all/with submissions/await grading. That speed up grading much. See MDL-14238
# New capability: viewownsubmission. Setting it to Deny makes assignment module useful in exam context - collect student's work without their further access to it. See MDL-15356
# Replace link with the number of submissions (for the teacher) with more informative "The ___ of ___ submissions needs grading". MDL-17613

== Refactoring ==
Some areas of assignment can be reworked for greater flexibility and reducing code duplication. Assignment base is actualy an awful, bloated class where all things are intermixed. And any plugin inherits it fully. Some plugins have similar features too, implemented separately. Overall issue for this is MDL-17329.

Some major improvments:
* 'types' will be no longer considered separate activities, just a option in the mod_form
* 'type' plugins, which defines what can be submitted, will be reduced to just that purpose, all workflow would be controlled from main module (reducing numerous duplicates and inconsistences)
* there will be two basic 'type' plugins (text and files), which can be used in any combination (from no one to both)
** no one is effectively an offline task
** files (reworked upload) can serve for both single and multiple files uploads
* there will be possible to create new activities based on this module, inheriting it's main classes, for major workflow customisations, and they will have full access to 'type' plugins
== New Features ==

=== Teams ===
This feature is on hold and may wait for a second version of module. Right now we are more focused on task distribution

One main assumption in the assignment module is need to be eliminated is "one user=one submission=one grade". The quite common practice is grouped assignments, where students can work in small groups on a task. So we need a teams support there. (Well, quite big work as many functions use this assumption).

'''Team''' is a group of students whose work will results in one submission. Teams features:
* submission is one per team, but a grade can be given on per-team or per-student basis
* teacher can define a minimum and maximum number of students in the team
* self-organization (with possibility of confirmation by teacher) or forced by teacher teams
* maximum date of team membership editing
* teacher can add themselves to teamas a mentor, then he only will be notified of events in this team
* 'roles' (or workroles to avoid confusion with Moodle Roles) of people in team (either teacher or student defined) - this is a way to explain who in group will do what
** teacher-defined roles is a list, from which one or several roles can be selected for students
** if teacher doesn't want do define specific roles, students can enter text, explaining their role in the group

=== Individual tasks ===
Individual tasks is quite common situation in the educational process. The module can handle tasks selection and completion.

Individual tasks features:
* adding/editing/deleting of tasks by the teacher
* standart fields: name, description, grade factor (1 by default), min/max teamnumber (if teams activated)
* custom fields, which can be added in any given assignment, of several types: string, text, number, date, menu, file
* some fields can only be accessible to the student once he is selected a task (and it will be approved by a teacher if necessary)
* student's selection (with optional teacher approval), teacher-forced selection or random selection based on a student's selection of subset of tasks fields (number or menu mainly, i.e. some sort of 'complexity' field for example)
* maximum dates of selection (and approval if necessary)
* column with task name (link to the task) when grading
* random filling of some task fields (number or menu mainly) on selection or approval
** there is some problem of misuse of random generator; they are mainly dealt with fact that student's can change task and select new without teacher

=== User interface - tabs ===
Currently assignment have only two main pages: intro/submit (view.php) and grading (submission.php), so it can go away with the link in upper right corner.

New features will require more pages, so it's better to use tabs for them. Tabs visibility will be based on user's capabilities.

Urgent reminders will be places on top (or bottom?) of every tab with color highlighting;
* for students
** if he is late to select a task/become a member of team
** if he is late to submit work
* for teachers
** if student from his/her group asks to delete him from team (or task change)
** if there are students without task/team after date of last approval

=== Grading semi-plugins ===
Sometimes assignments allow for automatic, or semi-automatic grading. It's nice to have options to have a plugin system for this.

=== ''maybe'' One user can get several tasks ===
That needs further discussion. It's something not very uncommon in real word teaching, but somewhat difficult to cope with "one course module=one grade" thing.

=== Tasks workflow ===
Let's see a task workflow in most complicated case (maximum features will be used). States names are somewhat awkward and is subject to change (can anyone propose better names?)

* initially task is '''free''' (1)
* (1) student or teacher can create a team -> '''creating team''' (2)
* (2) student(s) can add themselves to the team, teacher can add students to the team (in last case student notified that he/she was added)
* (2) students can plead to free them from team/task, teacher can disapprove (if allowed) members or task (students is notified if they are disapproved)
* (2) after the team will have at least minimum number of participants -> '''have enough people''' (3)
* (3) all (2) operations still available
* (3) students can confirm his will to work with team(now that he knows all it's members), teacher can approve a team - approvment automatically cleared if team membership changes (people that have approves is notified)
* (3) after the date of last approval, no more changes in teams available for students, (for teachers it's depends on capabilities), if there is an unapproved team the teacher will be shown (and sent) urgent reminder
* (3) after the students (if allowed) approved a team and task -> '''ready''' (4) (if teacher approvment needed) or '''working''' (5) (students and teacher notified)
* (4) after teacher approval -> '''working''' (5) (students notified)
* (4) in case of teacher disapproval -> '''have enough people''' (3) (students notified)
* (5) any student in the team can submit work with flag 'please check our progress' (if allowed), then teacher is notified and able to give comment but not grade (teacher notified, student's notified of comment)
* (5) any student in team can make a normal submit, but it (optionally) may need an approval from other members for grading -> '''await grading''' (6) (teacher notified)
* (6) the teacher can only grade a team in '''await grading''' status
* (6) teacher grades, but grade isn't final -> '''reworking''' (5) (students notified)
* (6) teacher gives final grade -> '''graded''' (7) (students notified)
* (7) person of higher authority will be able to override grade and add something to comment (but maybe not freely edit it, the name of the first grader and regrader will be saved in comment). (students and teacher notified)

Well it's probably looked worse than is. The actual user will see only part of options, and all forms of approval can be disabled.

=== Files handling ===
There is some confusion about files handling in current version of assignment module. This is need to be corrected. So there should be a several types of files:

# '''assignment''' files - files that is showed and accessible to all, and associated with assignment in general even if individual tasks is used (such as guidelines for it's completion that apply to all regardless of individual task);
# '''task''' files - some file(s) that teacher want to give students before they start to work on particular task;
# '''submission''' files - files that was submitted by a particular student (team);
# '''reply''' (comment) files - files that was uploaded by a teacher when grading submitted work, usually rewised versions of submitted files (thanks to A.T. Wyatt comment there)

== Implementation ==

=== New options ===
Let's see an assignment creation/editing screen. Assignment module will keep all existing options.

New options that will be added:
* use individual tasks
* use teams
* last date of approval - active if tasks or teams used, time to which all considerations about group memebrship and tasks selections must be done
* team options (active only if teams selected)
** min and max count of members of team
** the grade will be individual or one per team
** if students must confirm it will to work with team (first student, who create a team, may not be happy with someone who add yourself to it later)
** if teacher must confirm team membership
** if all team members must confirm a submission before grading
* individual task options (active only if tasks is selected)
** allow using same tasks - can several students do one task or all tasks must be different?
** allow using same tasks in one group
** individual date - allow individual due dates to the task
** individual team members count - if teams used, can particular task override min/max number of students in team
** teacher must confirm task selection
** random task assignment

=== DB structure ===
[[Image:db_shema.jpg]]

The new db structure have such tables:
* '''poasassignment''' - main table which have new options :
*# maxmembersontask - maximum count of members which must to do the task
*# minmembersontask - minimum count of members which must to do the task
*# mintaskonmember - minimum count of tasks for one member(needs discussion)
*# maxtaskonmember - maximum count of tasks for one member(needs discussion)
*# timedistrib - initial time for task distribution
*# timeconfirmation - the date after that a student not may create/come into new working group
*# timereception - start time for tasks reception
*# flags - all binary options
* '''poasassignment_tasks''' - table for task list of instance of activity:
*# name - the name of task
*# descripiton - task "body"
*# deadline - individual date for task reception
*# factor - factor for grade
*# maxmembers - maximum workgroup members on task
*# minmembers - minimum workgroup members on task
* '''poasassignment_fields''' - define list of custom fields:
*# ftype - type of the field
*# name - name of the field
*# showintable - additional column in table of tasks
*# maxvalue - maximum value for the field(only numbers)
*# minvalue - minimum value for the field(only numbers)
*# optional - optional field?
*# rndparam - if this field used to define filter for random selection of task
*# rndshow - if this field will get random value on task selection (number or menu fields only)
* '''poasassignment_field_consts''' - define consts for the fields type of list
* '''poasassignment_values''' - values for particular task/workgroup
* '''poasassignment_workgroups''' - table for teams, also submissions stuff go there
* '''poasassignment_workgroup_members''' - members of teams, grade stuff go there:
*# userid -
*# grade - this is the grade for submission
*# submissioncomment -
*# format,teacher,timemarked,mailed - old fields of assignment_submissions
*# ownrole - role which student want implement during task execution
*# finalgrade - final grade(yes/no)?
*# deletefrom - please kick me from this working group (or task)
*# deletecomment - explanation why student needs to delete from this working group
* '''poasassignment_role''' - roles for the task:
*# one task have many roles
*# one student perform many roles
Rethink tables/columns, define how a type plugin can use db, rename workgroups into teams everywhere --[[User:Oleg Sychev|Oleg Sychev]] 11:12, 11 September 2009 (UTC)
=== Tabs ===

==== Info/submit ====
This is an initial tab, that will work basically the same as before.

New abilities:
* show additional dates (i.e. dates of last approval and so on)
* student: show individual task (?tasks?) when the individual tasks is selected
* student: show task status (see workflow of the task above)
* student: show team members (when teams used)
* student: can approve team and submission, select or type his roles
* teacher: the number of submissions will be shown JFI as there is a tab for grading now (maybe as a link, just as in quiz now - it must be moved to down center area)
* teacher: the number of submissions will be showed as <need grading>/<all submissions>

==== Custom fields ====
This tab is for managing custom fields for the tasks. The author can add/edit/delete fields there.

==== Tasks ====
New tab, accessible when individual task feature activated.

Abilities:
* teacher: adding, editing, deleting a task (editing and deleting assigned tasks may be prohibited)
* student: browsing task list, viewing task details
* student (without teams): selecting a task
* student (in team mode): see current teams(at least incomplete), create team for a task, apply for team membership

==== Grading ====
This is an evolved grading page (submission.php), for teachers use.

New abilities:
* the table will reflect a status of task (maybe with icons)
* individual tasks: the table will additionally reflect task name (as a link to popup with it's description) and a grade factor
* teams: the table (and popup for grading too) will have two modes:
* teams and/or individual tasks: in case any form of teacher approvment is needed, columns for approvment will be showed
* grade columns/popus will be showed only when grading is allowed (or if person has mod/assignment:manageanything capability)
*# team grades - each string represent a team
*# individual grades - each string represents a student, but they are sorted by team and teams is spaced somehow
* make an option for the teachers to make any grade final, forbidding further re-submissions and/or regrading (a person with mod/assignment:manageanything can still regrade); in teams with individual grading mode re-submission will be forbidden only when all team members receive final grade
* dropdown to choose whom to display in the table (and in the popup): all, with submissions only, needs grading only

=== Capabilities ===
Current capabilities
* mod/poasassignment:view - actually quite strange capability that can completely block you from assignment
* mod/poasassignment:submit - ability to submit a work
* mod/poasassignment:grade - ability to grade submissions

New capabilities
* mod/poasassignment:viewownsubmission (can be backported to 1.9) - sometimes we need to not allowing the student to see own submission (exams cases mostly)
* mod/poasassignment:manageanything - person with high authority, for whom don't apply usual restrictions: he can edit/delete tasks on which people worked right now, manage group membership and their tasks after an approval, override final grades and so on
* mod/poasassignment:managetasks - ability to create, edit and delete tasks
* mod/poasassignment:managefields - ability to manage custom fields of tasks
* mod/poasassignment:finalgrades - can make grades final
* mod/poasassignment:manageteams - ability to create, force students to the team, approve students (teacher's ability)
* mod/poasassignment:managetaskselection - ability to manage tasks selection for any student (teacher's ability)
* mod/poasassignment:manageownteam - ability to create new team, apply to existing one, confirm memebership of the others in this team (student's ability, setting it to Deny will create an task where only teachers can manage teams membership)
* mod/poasassignment:selectowntask - student's ability to select task (setting to Deny allows for teachers-only tasks selection)
* mod/poasassignment:seeotherstasks - student's ability - if he/she is able to see what tasks are selected by other people, or he can see only if it free for selection

[[Category:Assignment]]

Development:XHTML

2009-09-24T07:55:34Z

Josepuib: missing words added

==XHTML Strict 1.0==

Moodle output must be compliant with XHTML Strict 1.0. This means it must be:

===Well-formed XML===

In a well-formed XML document, every opening tag has a matching close tag; tags are properly nested, attributes are properly quoted, and the file contains no syntax errors. See [http://www.w3.org/TR/xml/#sec-well-formed the XML specification for a formal definition].

While developing, you should have the option Administration ► Server ► Debugging ► XML strict headers turned on. With this option on, your web browser will refuse to display any page that is not well-formed. This makes such problems easy to find and fix.

===Valid XHTML Strict===

This means that the XML of your page follows the particular rules from the [http://www.w3.org/TR/xhtml1/dtds.html#a_dtd_XHTML-1.0-Strict XHTML-1.0-Strict DTD]. <nowiki>For example, the first tag in the file must be <html>, a <form> tag must have an action="" attribute, an <li> can only appear inside an <ol> or <ul>, you cannot use <frame> tags, and so on.</nowiki> and so on.

You can check whether the HTML you output is valid by using a HTML validator, for example the [https://addons.mozilla.org/en-US/firefox/addon/249 Html Validator] add-on for Firefox.

===Semantic markup===

That is, HTML tags should be used only to mark up the appropriate types of content. For example:
* tables should not be used for page layout, just to display tabular information,
* if something is a heading, it should be marked up using <h''n''> tags, for an appropriate ''n'',
* <nowiki>if something is a list, it should be marked up using <ol>, <ul> or <dl>,</nowiki>
* see [[Semantic HTML]] for further details

==Styling==

How the HTML is laid out should be controlled by CSS in whichever theme is currently selected.

* Ensure that the HTML contains enough id="..." and class="..." attributes so that theme designers can easily control how it is displayed.
* Never embed inline styles in the HTML (that is, do not use the style="..." attribute).
* As you change core Moodle code, you must update the standard theme so that Moodle looks OK out of the box.
* If you need to make basic style definitions for a module (or some other sorts of plugin), put them in a file called styles.php in that module. This will be included into every theme.

== Moodle API ==

* Use the functions in lib/weblib to do as much as possible (print_header(), print_box() etc)
* This API will change a lot in Moodle 2.0. See: [[Development:Navigation_2.0]]

== See also: ==

* [http://developer.apple.com/internet/webcontent/bestwebdev.html Web Page Development: Best Practices] by the Safari development team at Apple.

Development:XHTML

2009-09-24T07:53:26Z

Josepuib: missing word added

==XHTML Strict 1.0==

Moodle output must be compliant with XHTML Strict 1.0. This means it must be:

===Well-formed XML===

In a well-formed XML document, every opening tag has a matching close tag; tags are properly nested, attributes are properly quoted, and the file contains no syntax errors. See [http://www.w3.org/TR/xml/#sec-well-formed the XML specification for a formal definition].

While developing, you should have the option Administration ► Server ► Debugging ► XML strict headers turned on. With this option on, your web browser will refuse to display any page that is not well-formed. This makes such problems easy to find and fix.

===Valid XHTML Strict===

This means that the XML of your page follows the particular rules from the [http://www.w3.org/TR/xhtml1/dtds.html#a_dtd_XHTML-1.0-Strict XHTML-1.0-Strict DTD]. <nowiki>For example, the first tag in the file must be <html>, a <form> tag must have an action="" attribute, an <li> can only appear inside an <ol> or <ul>, you cannot use <frame> tags, and so on.</nowiki> and so on.

You can check whether the HTML you output is valid by using a HTML validator, for example the [https://addons.mozilla.org/en-US/firefox/addon/249 Html Validator] add-on for Firefox.

===Semantic markup===

That is, HTML tags should be used only to mark up the appropriate types of content. For example:
* tables should not be used for page layout, just to display tabular information,
* if something is a heading, it should be marked up using <h''n''> tags, for an appropriate ''n'',
* <nowiki>if something is a list, it should be marked up using <ol>, <ul> or <dl>,</nowiki>
* see [[Semantic HTML]] for further details

==Styling==

How the HTML is laid out should be controlled by CSS in whichever theme is currently selected.

* Ensure that the HTML contains enough id="..." and class="..." attributes so that theme designers can easily control how
* Never embed inline styles in the HTML (that is, do not use the style="..." attribute).
* As you change core Moodle code, you must update the standard theme so that Moodle looks OK out of the box.
* If you need to make basic style definitions for a module (or some other sorts of plugin), put them in a file called styles.php in that module. This will be included into every theme.

== Moodle API ==

* Use the functions in lib/weblib to do as much as possible (print_header(), print_box() etc)
* This API will change a lot in Moodle 2.0. See: [[Development:Navigation_2.0]]

== See also: ==

* [http://developer.apple.com/internet/webcontent/bestwebdev.html Web Page Development: Best Practices] by the Safari development team at Apple.

Development:JavaScript guidelines

2009-09-23T17:33:25Z

Josepuib: spelling mistake

{{Moodle 2.0}}

These guidelines can only be applied fully from Moodle 2.0 onwards, because they rely on our new API to facilitate use of JavaScript.

When writing JavaScript for earlier versions of Moodle, please try to follow these guidelines in spirit and use the '''require_js''' function in place of $PAGE->requires->js/yui_lib.

==General principles==

===Moodle should be usable without JavaScript===

Everything in Moodle should work with JavaScript turned off. This is important for accessibility, and in line with the principles of [[Development:Unobtrusive_Javascript|unobtrusive JavaScript]] and [[Development:Progressive_enhancement|progressive enhancement]].

===Minimise inline JavaScript===

Almost all JavaScript code should be in separate .js files. There should be the smallest possible amount of JavaScript inline in the HTML code of pages.

The only <script> tags in the HTML should be
# <script src=... tags to include the necessary .js files.
# Simple function calls to trigger initialisation. For example <script type="text/javascript">initialise_my_widget('some', 'data', 123);</script>.
# Variable definitions to transfer data from the PHP code to JavaScript. For example <script type="text/javascript">var moodle_cfg = {"modpixpath":"http:\/\/tim.moodle.local\/moodle\/mod","sesskey":"ZVNQiq7pHu","developerdebug":true};</script>.

You should not use old-fashioned onXXX="event_handler" attributes in the HTML. Use Modern DOM events. The YUI events library makes this easy.

=== JavaScript libraries ===

* The official JavaScript library for Moodle is [[Development:YUI|YUI]]. That may not be your favourite, but it's the one that was chosen after careful research, so live with it.

* Moodle also has its own JavaScript library code, principally in lib/javascript-static.js.

* Moodle uses the '''TinyMCE''' HTML editor.

===When to include the JavaScript===

As per [http://developer.yahoo.com/performance/rules.html Yahoo's best practice guidelines], load and execute the JavaScript as late as possible, ideally the script tags should be the last thing before the </body> close tag. (This is the default behaviour with Moodle's JavaScript handling functions.)

Since everything should work without JavaScript, load and initialising your scripts only after everything else on the page has loaded should not be a problem and will increase the perceived page-load performance for users.

===Minimise the number of .js files===

Try not to use too many different .js files. Each separate file that the browser has to load incurs an overhead.

On the other hand, organise the JavaScript logically to ease maintenance, and don't include large amounts of irrelevant JavaScript code. Code that is loaded but never used is a waste of time.

So, if you are writing a new module that needs its own JavaScript, try starting with with a single file mod/mymod/mymod.js. If you find that you are writing a lot of JavaScript that is only needed when the teacher edits your module, but is not needed by students, then consider splitting that code into a separate file like mod/mymod/edit.js, and only including it where needed.

==How to achive these general principles in Moodle==

The rest of this page explains how you can achieve the above goals.

===Getting Moodle to load your JavaScript files===

Everything required by the current page is tracked by the $PAGE->requires object, which is an instance of the [http://phpdocs.moodle.org/HEAD/moodlecore/page_requirements_manager.html page_requirements_manager] class. You use it like this:

<code php>
$PAGE->requires->js('mod/mymod/scripts.js');
</code>

By default, this will put the <script> tag that loads the script at the end of the <body> tag, as recommended. If you really must load the script sooner, use one of the following
<code php>
// Load the js file from head.
// (This will throw an exception if head has already been output.)
$PAGE->requires->js('mod/mymod/scripts.js')->in_head();

// Loads the js file as soon as possible (from head, if that has
// not been output yet, otherwise output the script tag right here.)
echo $PAGE->requires->js('mod/mymod/scripts.js')->asap();
</code>

$PAGE->requires keeps track of which files have been included, so even if two different pieces of code request the same library, it is only loaded once.

===Getting Moodle to load YUI libraries===

Because YUI is the official JavaScript library for Moodle, there is a short cut syntax for loading the YUI libraries.

<code php>
$PAGE->requires->yui_lib('autocomplete');
</code>

This knows about the dependencies between the JavaScript libraries, so the above code will actually load the five libraries yahoo, dom, event, datasource and autocomplete. It will also load the required CSS file autocomplete/assets/skins/sam/autocomplete.css.

Because some YUI libraries rely on associated CSS, and because CSS can only be included in the <head> section of the HTML, you should try to call $PAGE->requires->yui_lib before <head> is output, if at all possible. If your code does try to require a YUI library after the header has been printed, and if that YUI library requires some CSS, and exception will be thrown explaining the problem, so you will know it happened.

===JavaScript coding style===

Moodle JavaScript code should should follow the same [[Development:Coding_style|coding style as Moodle PHP code]], allowing for the differences between PHP and JavaScript.

For example, all the rules on ''function_names'', ''class_names'' and ''variablenames'' apply. You should document your code with [http://jsdoc.sourceforge.net/ JSDoc] comments. Layout your JavaScript expressions and statements like the equivalent PHP ones.

Normally, your .js files should simply define things like functions, classes and variables. When the file is loaded, no JavaScript code should actually be executed that has any effect unless it is the sort of code that can safely be executed once per HTML page. This is so that it plays nicely with the require_once-like behaviour of $PAGE->requires->js.

Try to add as few things as possible to the global JavaScript name-space - use a few objects in the global name-space with properties and methods.

(An extreme example of this practice is the YUI libraries which only add a single YAHOO object to the global scope and put everything inside that. Moodle code does not need to go to that extreme - and do not add Moodle-specific code to the YAHOO namespace!)

===Activating your JavaScript===

Since your .js files should not actually do anything when they are loaded, you need some way to trigger them into action. Normally the best way to do this is to put a simple inline script in the HTML that just calls an initialisation function. Typically, you want the HTML page you generate to look like this:

<code xml>

<script type="text/javascript">
init_my_script('perhaps some data', 'for example', 'mything');
</script>
</code>

The best way to generate this initialisation script is to use another feature of $PAGE->requires:
<code php>
$PAGE->requires->js_function_call('init_my_script',
array('perhaps some data', 'for example', 'mything'));
</code>

Once again, by default the <script> tag will be generated at the end of the HTML, but you can change that with modifiers like ->asap() or ->on_dom_ready() (which uses the YUI onDomReady event). Note that the data passed from PHP to JavaScript is automatically escaped using json_encode, so you can pass arrays, objects, and strings containing special characters without worrying.

===Getting more variables from PHP to JavaScript===

The arguments you pass to the initialisation function are one way to get specific data from your PHP code to your JavaScript. However, when you need to initialise several things on the page and they all need the same data, there is a better way:
<code php>
$data = array(
'value1' => $value1,
'value2' => $value2,
);
$PAGE->requires->data_for_js('mymod_config', $data);
</code>

If you do that, then in JavaScript, mymod_config.value1 will contain the value of the PHP variable $value1.

===Getting language strings from PHP to JavaScript===

One type of value you frequently need to get from PHP to JavaScript is the translation of some language strings into the current language. Because this is a common requirement, there is a special syntax for this:
<code php>
$PAGE->requires->string_for_js('tooltip', 'mymod');
</code>
If you make this call, then the JavaScript variable mstr.mymod.tooltip will hold the value of get_string('tooltip', 'mymod').

===Different in content when JavaScript is on or off===

Remember the overriding principals that everything should work with JavaScript off, and we should adopt a [[Progressive enhancement]] approach. However, there are valid reasons why sometimes you need different content with JavaScript is on or off. We can break it down into three cases:

====Content that should only be visible with JavaScript off====

An example of this is the automatic search when you are looking for a user to assign a role to. With JavaScript on, the search automatically starts after a delay. With JavaScript off, we want an explicit Search button visible.

To handle this case, Moodle automatically add a class 'jsenabled' to the body tag using JavaScript. So you just need to add a rule like
<code css>
body.jsenebled .mywidget .submitbutton {
display: none;
}
</code>
to the stylesheet, and the button will be invisible if JavaScript is enabled.

An alternative strategy is to remove the particular bits of HTML from the page using DOM methods. However, if your JavaScript is only loaded at the end of the page, it may take some time for the extra content to disappear, which leads to a disconcerting flicker in the page.

Yet another approach is the old-fashioned <noscript> tag.

====Content that needs to be visible right away when JavaScript is on====

An example is the <nowiki>[+] or [-]</nowiki> icon that can be used to expand/collapse each block if JavaScript is on.

We can divide this into two subcases:

=====Content generated by PHP code=====

Where the HTML for the JavaScript only widget is generated by PHP, we can make it invisible when JavaScript is off using just CSS:
<code css>
.mywidget {
display: none;
}
body.jsenabled .mywidget {
display: block;
}
</code>
However, it could be argued that this approach is not really progressive enhancement.

=====Content generated by JavaScript code=====

This is more in keeping with progressive enhancement, and this is the way that the expand/collapse block icon is handled.

We build the icon using DOM methods. The only problem is that as the JavaScript is loaded in the footer, there is a small delay before the icons appear. Since when the icons appear, they do not cause other content on the page to move around, that is OK. Also, this delayed appearance is becoming more common on the web. For example, on http://twitter.com/, some things only appear a moment after the main part of the page has finished loading.

However, it the delayed appearance is really a problem, then the only solution is to embed the JavaScript that generates the extra content in the middle of the HTML, using $PAGE->requires->js_function_call(...)->now();.

====Content that only appears when the user does something, when JavaScript is on====

An example of this is something like file picker dialog that appears when you add an image to some content in the HTML editor, or the one that pops up when you click 'Add new question' in the quiz editing interface.

We have the same two sub-cases:

=====Content generated by PHP code=====

In this case, you need to make sure the content is always covered by a display: none; rule in the CSS, but then when the user takes an action like clicking a button to reveal the extra content, you need to override that class name some how, perhaps my adding or removing a className using JavaScript.

=====Content generated by JavaScript code=====

In this case, there is no problem. When the use triggers the extra content to appear, it is constructed using DOM methods. There may be a tiny delay, but the chances are that it will hardly be noticeable to the human eye.

In the content generation may be slow (perhaps because it is waiting for an Ajax request) then you should display a progress icon. See, for example, the loading of the tooltip for help icons.

===Don't break XHTML strict!===

Remember that all Moodle output must be [[Development:XHTML|XHTML strict]], and that means that the HTML output must be well-formed XML. Inline JavaScript is a great way to break that. (JavaScript uses the < and & symbols that must be escaped in XML.) Therefore any JavaScript inline in the HTML should be escaped in a CDATA section:

<code xml>
<script type="text/javascript">
//<![CDATA[

// Your JavaScript code goes here.

//]]>
</script>
</code>

Of course, if you are following the above guidelines and putting most of your JavaScript in separate .js files, and using $PAGE->requiers->js_function_call/string_for_js/data_for_js for the rest, then you do not need to worry about this section.

==Testing==

JavaScript support varies a lot between browsers. JavaScript needs to be tested in IE, Firefox and Safari. Ideally, Moodle will support [http://developer.yahoo.com/yui/articles/gbs/ all the browsers that YUI does].

==See also==

* [[Development:Coding|The rest of Moodle coding guidelines]]
* [http://developer.yahoo.com/yui/ YUI documentation]
* [[Javascript FAQ]]
* [[Development:Unobtrusive Javascript]]
* [[Development:JavaScript functions]]
* [http://developer.yahoo.com/performance/rules.html Yahoo's Best Practices for Speeding Up Your Web Site]
* [http://moodle.org/mod/forum/discuss.php?d=106312 Forum thread for discussing this proposal]

{{CategoryDeveloper}}

[[Category:Javascript|JavaScript guidelines]]
[[Category:AJAX|JavaScript guidelines]]

Development:lib/formslib.php Usage

2009-09-23T07:22:34Z

Josepuib: spelling mistake

{{Formslib}}
==Usage of Formslib==

There are many phpdoc style comments in lib/formslib.php

course/edit.php and the included course/edit_form.php provide a good example of usage of this library.

Also see the PEAR docs for [http://pear.php.net/package/HTML_QuickForm/ HTML_QuickForm docs] I found this [http://pear.php.net/manual/en/package.html.html-quickform.tutorial.php quick tutorial] and this [http://www.midnighthax.com/quickform.php slightly longer one] particularly useful.

We created some special wrapper functions for moodle. $mform->get_data() returns null if no data has been submitted or validation fails or returns an object with the contents of the submitted data.

===Basic Usage in A Normal Page===

Generally the structure of a page with a form on it looks like this :

<code php>
require_once('pathtoformdescription');
//you'll process some page parameters at the top here and get the info about
//what instance of your module and what course you're in etc. Make sure you
//include hidden variable in your forms which have their defaults set in set_data
//which pass these variables from page to page

$mform = new yourmod_formfunction_form();//name of the form you defined in file above.
//default 'action' for form is strip_querystring(qualified_me())
if ($mform->is_cancelled()){
//you need this section if you have a cancel button on your form
//here you tell php what to do if your user presses cancel
//probably a redirect is called for!
} else if ($fromform=$mform->get_data()){
//this branch is where you process validated data.

} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.
//setup strings for heading
print_header_simple($streditinga, '',
"<a href=\"$CFG->wwwroot/mod/$module->name/index.php?id=$course->id\">$strmodulenameplural</a> ->
$strnav $streditinga", $mform->focus(), "", false);
//notice use of $mform->focus() above which puts the cursor
//in the first form field or the first field with an error.

//call to print_heading_with_help or print_heading? then :

//put data you want to fill out in the form into array $toform here then :

$mform->set_data($toform);
$mform->display();
print_footer($course);

}
</code>

===Defining Your Form Class===

The form class tells us about the structure of the form. You are encouraged to put this in a file called {function}_form.php probably in the same folder in which the page that uses it is located. The name of your class should be {modname}_{function}_form eg. forum_post_form or course_edit_form. These classes will extend class moodleform.

Note the name you give the class is used as the id attribute of your form in html (any trailing '_form' is chopped off'). Your form class name should be unique in order for it to selectable in CSS by theme designers who may want to tweak the css just for that form.

====definition()====

[[Development:lib/formslib.php_Form_Definition|Help is here for defining your form]] by defining a function definition() in your form class that sets up your form structure.

===Use in Activity Modules Add / Update Forms===

Syntax is the same in activity modules to create your update / add page. We are still supporting mod.html but if you want to use the new formslib then you can in Moodle 1.8 just include in your module directory the file mod_form.php instead of mod.html and it will be automatically detected. Inside this file you define a class with class name '{modname}__mod_form' which extends the class 'moodleform_mod'. See many examples of the core modules which have been converted to use formslib already.

====defaults_preprocessing====

For activity modules you use the same syntax to define your form. You may also want to override method defaults_preprocessing this can be used to take the data from the data base and tell the form how to fill out defaults in the form with this data. For example in the forum module in forum/mod_form.php we needed to tick an enable check box if a date had been selected in the date select. Normally data is loaded from the database and directly loaded into form fields with the same name as the database record you only need to use defaults_preprocessing if there isn't this one to one relationship. Another example is the lesson/mod_form.php which takes the data from the database and unserializes it. choice/mod_form.php shows an exampe of loading data from another db table referred to by a foreign key, to include in the form.

====Post Processing Still Done in lib.php Functions====

Post processing of data is done in lib.php functions modname_add_instance and modname_update_instance after the data has been validated. When migrating a form often little changes need to be made in the post processing. An exception is that date and date_time_selector fields automatically have their submitted data turned into timestamps so you don't need to do this in your add and update functions anymore.

====Automatically Including Standard Activity Module Form Elements====

Standard activity module form elements are automatically included using the moodleform_mod method standard_coursemodule_elements(). The default is to include a visibility and groupsmode select box and to include all necessary hidden fields. You can pass a parameter false to tell the method that your module doesn't support groups and so you don't want the groupsmode select button.

[[Category:Formslib]]

Development:Blocks

2009-09-19T17:31:54Z

Josepuib: blank space deleted

''' A Step-by-step Guide To Creating Blocks '''

Original Author: Jon Papaioannou (pj@moodle.org)

The present document serves as a guide to developers who want to create their own blocks for use in Moodle. It applies to the 1.5 development version of Moodle (and any newer) '''only''', as the blocks subsystem was rewritten and expanded for the 1.5 release. However, you can also find it useful if you want to modify blocks written for Moodle 1.3 and 1.4 to work with the latest versions (look at [[Development:Blocks/Appendix_B| Appendix B]]).

The guide is written as an interactive course which aims to develop a configurable, multi-purpose block that displays arbitrary HTML. It's targeted mainly at people with little experience with Moodle or programming in general and aims to show how easy it is to create new blocks for Moodle. A certain small amount of PHP programming knowledge is still required, though.

Experienced developers and those who just want a '''reference''' text should refer to [[Development:Blocks/Appendix_A| Appendix A]] because the main guide has a rather low concentration of pure information in the text.

== Basic Concepts ==

Through this guide, we will be following the creation of an "HTML" block from scratch in order to demonstrate most of the block features at our disposal. Our block will be named "SimpleHTML". This does not constrain us regarding the name of the actual directory on the server where the files for our block will be stored, but for consistency we will follow the practice of using the lowercased form "simplehtml" in any case where such a name is required.

Whenever we refer to a file or directory name which contains "simplehtml", it's important to remember that ''only'' the "simplehtml" part is up to us to change; the rest is standardized and essential for Moodle to work correctly.

Whenever a file's path is mentioned in this guide, it will always start with a slash. This refers to the Moodle home directory; all files and directories will be referred to with respect to that directory.

== Ready, Set, Go! ==

To define a "block" in Moodle, in the most basic case we need to provide just one source code file. We start by creating the directory ''/blocks/simplehtml/'' and creating a file named ''/blocks/simplehtml/'''''block_simplehtml.php''' which will hold our code. We then begin coding the block:

<code php>
<?php
class block_simplehtml extends block_base {
function init() {
$this->title = get_string('simplehtml', 'block_simplehtml');
$this->version = 2004111200;
}
// The PHP tag and the curly bracket for the class definition
// will only be closed after there is another function added in the next section.
</code>

The first line is our block class definition; it must be named exactly in the manner shown. Again, only the "simplehtml" part can (and indeed must) change; everything else is standardized.

Our class is then given a small method: [[Development:Blocks/Appendix_A#init.28.29| init()]]. This is essential for all blocks, and its purpose is to set the two class member variables listed inside it. But what do these values actually mean? Here's a more detailed description.

[[Development:Blocks/Appendix_A#.24this-.3Etitle| $this->title]] is the title displayed in the header of our block. We can set it to whatever we like; in this case it's set to read the actual title from a language file we are presumably distributing together with the block. I 'll skip ahead a bit here and say that if you want your block to display '''no''' title at all, then you should set this to any descriptive value you want (but '''not''' make it an empty string). We will later see [[Development:Blocks#Eye_Candy| how to disable the title's display]].

[[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] is the version of our block. This actually would only make a difference if your block wanted to keep its own data in special tables in the database (i.e. for very complex blocks). In that case the version number is used exactly as it's used in activities; an upgrade script uses it to incrementally upgrade an "old" version of the block's data to the latest. We will outline this process further ahead, since blocks tend to be relatively simple and not hold their own private data.

In our example, this is certainly the case so we just set [[Development:Blocks/Appendix_A#.24this-.3Eversion| $this->version]] to '''YYYYMMDD00''' and forget about it.

'''UPDATING:'''<br />
Prior to version 1.5, the basic structure of each block class was slightly different. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== I Just Hear Static ==
In order to get our block to actually display something on screen, we need to add one more method to our class (before the final closing brace in our file). The new code is:

<code php>
function get_content() {
if ($this->content !== NULL) {
return $this->content;
}

$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';

return $this->content;
}
} // Here's the closing curly bracket for the class definition
// and here's the closing PHP tag from the section above.
?> </code>

It can't get any simpler than that, can it? Let's dissect this method to see what's going on...

First of all, there is a check that returns the current value of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] if it's not NULL; otherwise we proceed with "computing" it. Since the computation is potentially a time-consuming operation and it '''will''' be called several times for each block (Moodle works that way internally), we take a precaution and include this time-saver.
Supposing the content had not been computed before (it was NULL), we then define it from scratch. The code speaks for itself there, so there isn't much to say. Just keep in mind that we can use HTML both in the text '''and''' in the footer, if we want to.

At this point our block should be capable of being automatically installed in Moodle and added to courses; visit your administration page to install it (Click "Notifications" under the Site Administration Block) and after seeing it in action come back to continue our tutorial.

== Configure That Out ==

The current version of our block doesn't really do much; it just displays a fixed message, which is not very useful. What we 'd really like to do is allow the teachers to customize what goes into the block. This, in block-speak, is called "instance configuration". So let's give our block some instance configuration...
First of all, we need to tell Moodle that we want it to provide instance-specific configuration amenities to our block. That's as simple as adding one more method to our block class:

<code php>
function instance_allow_config() {
return true;
}
</code>

This small change is enough to make Moodle display an "Edit..." icon in our block's header when we turn editing mode on in any course. However, if you try to click on that icon you will be presented with a notice that complains about the block's configuration not being implemented correctly. Try it, it's harmless.
Moodle's complaints do make sense. We told it that we want to have configuration, but we didn't say ''what'' kind of configuration we want, or how it should be displayed. To do that, we need to create one more file: <span class="filename">/blocks/simplehtml/'''config_instance.html'''</span> (which has to be named exactly like that). For the moment, copy paste the following into it and save:

<code php>
<table cellpadding="9" cellspacing="0">
<tr valign="top">
<td align="right">
<?php print_string('configcontent', 'block_simplehtml'); ?>:
</td>
<td>
<?php print_textarea(true, 10, 50, 0, 0, 'text', $this->config->text); ?>
</td>
</tr>
<tr>
<td colspan="2" align="center">
<input type="submit" value="<?php print_string('savechanges') ?>" />
</td>
</tr>
</table>

<?php use_html_editor(); ?>
</code>

It isn't difficult to see that the above code just provides us with a wysiwyg-editor-enabled textarea to write our block's desired content in and a submit button to save. But... what's $this->config->text? Well...
Moodle goes a long way to make things easier for block developers. Did you notice that the textarea is actually named "text"? When the submit button is pressed, Moodle saves each and every field it can find in our '''config_instance.html''' file as instance configuration data.

We can then access that data as '''$this->config->''variablename''''', where ''variablename'' is the actual name we used for our field; in this case, "text". So in essence, the above form just pre-populates the textarea with the current content of the block (as indeed it should) and then allows us to change it.

You also might be surprised by the presence of a submit button and the absence of any <form> element at the same time. But the truth is, we don't need to worry about that at all; Moodle goes a really long way to make things easier for developers! We just print the configuration options we want, in any format we want; include a submit button, and Moodle will handle all the rest itself. The instance configuration variables are automatically at our disposal to access from any of the class methods ''except'' [[Development:Blocks/Appendix_A#init.28.29| init()]].

In the event where the default behavior is not satisfactory, we can still override it. However, this requires advanced modifications to our block class and will not be covered here; refer to [[Development:Blocks/Appendix_A| Appendix A]] for more details.
Having now the ability to refer to this instance configuration data through [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]], the final twist is to tell our block to actually ''display'' what is saved in its configuration data. To do that, find this snippet in ''/blocks/simplehtml/block_simplehtml.php'':

<code php>
$this->content = new stdClass;
$this->content->text = 'The content of our SimpleHTML block!';
$this->content->footer = 'Footer here...';
</code>

and change it to:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = 'Footer here...';
</code>

Oh, and since the footer isn't really exciting at this point, we remove it from our block because it doesn't contribute anything. We could just as easily have decided to make the footer configurable in the above way, too. So for our latest code, the snippet becomes:

<code php>
$this->content = new stdClass;
$this->content->text = $this->config->text;
$this->content->footer = '';
</code>

After this discussion, our block is ready for prime time! Indeed, if you now visit any course with a SimpleHTML block, you will see that modifying its contents is now a snap.

[[#top|Back to top of page]]

== The Specialists ==

Implementing instance configuration for the block's contents was good enough to whet our appetite, but who wants to stop there? Why not customize the block's title, too?

Why not, indeed. Well, our first attempt to achieve this is natural enough: let's add another field to <span class="filename">/blocks/simplehtml/config_instance.html</span>. Here goes:

<code php>
<tr valign="top">
<td align="right"><p>
<?php print_string('configtitle', 'block_simplehtml'); ?>:</p>
</td>
<td>
<input type="text" name="title" size="30" value="<?php echo $this->config->title; ?>" />
</td>
</tr>
</code>

We save the edited file, go to a course, edit the title of the block and... nothing happens! The instance configuration is saved correctly, all right (editing it once more proves that) but it's not being displayed. All we get is just the simple "SimpleHTML" title.

That's not too weird, if we think back a bit. Do you remember that [[Development:Blocks/Appendix_A#init.28.29|init()]] method, where we set [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]]? We didn't actually change its value from then, and [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] is definitely not the same as '''$this->config->title''' (to Moodle, at least). What we need is a way to update [[Development:Blocks/Appendix_A#.24this-.3Etitle|$this->title]] with the value in the instance configuration. But as we said a bit earlier, we can use [[Development:Blocks/Appendix_A#.24this-.3Econfig| $this->config]] in all methods ''except'' [[Development:Blocks/Appendix_A#init.28.29|init()]]! So what can we do?

Let's pull out another ace from our sleeve, and add this small method to our block class:

<code php>
function specialization() {
if(!empty($this->config->title)){
$this->title = $this->config->title;
}else{
$this->config->title = 'Some title ...';
}
if(empty($this->config->text)){
$this->config->text = 'Some text ...';
}
}
</code>

Aha, here's what we wanted to do all along! But what's going on with the [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method?

This "magic" method has actually a very nice property: it's ''guaranteed'' to be automatically called by Moodle as soon as our instance configuration is loaded and available (that is, immediately after [[Development:Blocks/Appendix_A#init.28.29|init()]] is called). That means before the block's content is computed for the first time, and indeed before ''anything'' else is done with the block. Thus, providing a [[Development:Blocks/Appendix_A#specialization.28.29| specialization()]] method is the natural choice for any configuration data that needs to be acted upon "as soon as possible", as in this case.

== Now You See Me, Now You Don't ==

Now would be a good time to mention another nifty technique that can be used in blocks, and which comes in handy quite often. Specifically, it may be the case that our block will have something interesting to display some of the time; but in some other cases, it won't have anything useful to say. (An example here would be the "Recent Activity" block, in the case where no recent activity in fact exists.

However in that case the block chooses to explicitly inform you of the lack of said activity, which is arguably useful). It would be nice, then, to be able to have our block "disappear" if it's not needed to display it.

This is indeed possible, and the way to do it is to make sure that after the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called, the block is completely void of content. Specifically, "void of content" means that both $this->content->text and $this->content->footer are each equal to the empty string (<nowiki>''</nowiki>). Moodle performs this check by calling the block's [[Development:Blocks/Appendix_A#is_empty.28.29| is_empty()]] method, and if the block is indeed empty then it is not displayed at all.

Note that the exact value of the block's title and the presence or absence of a [[Development:Blocks/Appendix_A#hide_header.28.29| hide_header()]] method do ''not'' affect this behavior. A block is considered empty if it has no content, irrespective of anything else.

== We Are Legion ==

Right now our block is fully configurable, both in title and content. It's so versatile, in fact, that we could make pretty much anything out of it. It would be really nice to be able to add multiple blocks of this type to a single course. And, as you might have guessed, doing that is as simple as adding another small method to our block class:

<code php>
function instance_allow_multiple() {
return true;
}
</code>

This tells Moodle that it should allow any number of instances of the SimpleHTML block in any course. After saving the changes to our file, Moodle immediately allows us to add multiple copies of the block without further ado!

There are a couple more of interesting points to note here. First of all, even if a block itself allows multiple instances in the same page, the administrator still has the option of disallowing such behavior. This setting can be set separately for each block from the Administration / Configuration / Blocks page.

And finally, a nice detail is that as soon as we defined an [[Development:Blocks/Appendix_A#instance_allow_multiple.28.29| instance_allow_multiple()]] method, the method [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] that was already defined became obsolete.

Moodle assumes that if a block allows multiple instances of itself, those instances will want to be configured (what is the point of same multiple instances in the same page if they are identical?) and thus automatically provides an "Edit" icon. So, we can also remove the whole [[Development:Blocks/Appendix_A#instance_allow_config.28.29| instance_allow_config()]] method now without harm. We had only needed it when multiple instances of the block were not allowed.

[[#top|Back to top of page]]

== The Effects of Globalization ==

Configuring each block instance with its own personal data is cool enough, but sometimes administrators need some way to "touch" all instances of a specific block at the same time. In the case of our SimpleHTML block, a few settings that would make sense to apply to all instances aren't that hard to come up with.

For example, we might want to limit the contents of each block to only so many characters, or we might have a setting that filters HTML out of the block's contents, only allowing pure text in. Granted, such a feature wouldn't win us any awards for naming our block "SimpleHTML" but some tormented administrator somewhere might actually find it useful.

This kind of configuration is called "global configuration" and applies only to a specific block type (all instances of that block type are affected, however). Implementing such configuration for our block is quite similar to implementing the instance configuration. We will now see how to implement the second example, having a setting that only allows text and not HTML in the block's contents.
First of all, we need to tell Moodle that we want our block to provide global configuration by, what a surprise, adding a small method to our block class:

<code php>
function has_config() {
return true;
}
</code>

Then, we need to create a HTML file that actually prints out the configuration screen. In our case, we 'll just print out a checkbox saying "Do not allow HTML in the content" and a "submit" button. Let's create the file <span class="filename">/blocks/simplehtml/config_global.html</span> which again must be named just so, and copy paste the following into it:

[[Development_talk:Blocks|TODO: New settings.php method]]
: Just to note that general documentation about admin settings is at [[Development:Admin_settings#Individual_settings]]. In the absence of documentation, you can look at blocks/course_list, blocks/online_users and blocks/rss_client. They all use a settings.php file.--[[User:Tim Hunt|Tim Hunt]] 19:38, 28 January 2009 (CST)

<code php>
<div style="text-align: center;">
<input type="hidden" name="block_simplehtml_strict" value="0" />
<input type="checkbox" name="block_simplehtml_strict" value="1"
<?php if(!empty($CFG->block_simplehtml_strict))
echo 'checked="checked"'; ?> />
<?php print_string('donotallowhtml', 'block_simplehtml'); ?>
<p>
<input type="submit" value="<?php print_string('savechanges'); ?>" />
</p>
</div>
</code>

True to our block's name, this looks simple enough. What it does is that it displays a checkbox named "block_simplehtml_strict" and if the Moodle configuration variable with the same name (i.e., $CFG->block_simplehtml_strict) is set and not empty (that means it's not equal to an empty string, to zero, or to boolean FALSE) it displays the box as pre-checked (reflecting the current status).

Why does it check the configuration setting with the same name? Because the default implementation of the global configuration saving code takes all the variables we have in our form and saves them as Moodle configuration options with the same name. Thus, it's good practice to use a descriptive name and also one that won't possibly conflict with the name of another setting.

"block_simplehtml_strict" clearly satisfies both requirements.

The astute reader may have noticed that we actually have ''two'' input fields named "block_simplehtml_strict" in our configuration file. One is hidden and its value is always 0; the other is the checkbox and its value is 1. What gives? Why have them both there?

Actually, this is a small trick we use to make our job as simple as possible. HTML forms work this way: if a checkbox in a form is not checked, its name does not appear at all in the variables passed to PHP when the form is submitted. That effectively means that, when we uncheck the box and click submit, the variable is not passed to PHP at all. Thus, PHP does not know to update its value to "0", and our "strict" setting cannot be turned off at all once we turn it on for the first time. Not the behavior we want, surely.

However, when PHP handles received variables from a form, the variables are processed in the order in which they appear in the form. If a variable comes up having the same name with an already-processed variable, the new value overwrites the old one. Taking advantage of this, our logic runs as follows: the variable "block_simplehtml_strict" is first unconditionally set to "0". Then, ''if'' the box is checked, it is set to "1", overwriting the previous value as discussed. The net result is that our configuration setting behaves as it should.

To round our bag of tricks up, notice that the use of ''if(!empty($CFG->block_simplehtml_strict))'' in the test for "should the box be checked by default?" is quite deliberate. The first time this script runs, the variable '''$CFG->block_simplehtml_strict''' will not exist at all. After it's set for the first time, its value can be either "0" or "1". Given that both "not set" and the string "0" evaluate as empty while the sting "1" does not, we manage to avoid any warnings from PHP regarding the variable not being set at all, ''and'' have a nice human-readable representation for its two possible values ("0" and "1").

=== config_save() ===

Now that we have managed to cram a respectable amount of tricks into a few lines of HTML, we might as well discuss the alternative in case that tricks are not enough for a specific configuration setup we have in mind. Saving the data is done in the method [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], the default implementation of which is as follows:

<code php>
function config_save($data) {
// Default behavior: save all variables as $CFG properties
foreach ($data as $name => $value) {
set_config($name, $value);
}
return true;
}
</code>

As can be clearly seen, Moodle passes this method an associative array $data which contains all the variables coming in from our configuration screen. If we wanted to do the job without the "hidden variable with the same name" trick we used above, one way to do it would be by overriding this method with the following:

<code php>
function config_save($data) {
if(isset($data['block_simplehtml_strict'])) {
set_config('block_simplehtml_strict', '1');
}else {
set_config('block_simplehtml_strict', '0');
}
return true;
}
</code>

Quite straightfoward: if the variable "block_simplehtml_strict" is passed to us, then it can only mean that the user has checked it, so set the configuration variable with the same name to "1". Otherwise, set it to "0". Of course, this version would need to be updated if we add more configuration options because it doesn't respond to them as the default implementation does. Still, it's useful to know how we can override the default implementation if it does not fit our needs (for example, we might not want to save the variable as part of the Moodle configuration but do something else with it).

So, we are now at the point where we know if the block should allow HTML tags in its content or not. How do we get the block to actually respect that setting?

We could decide to do one of two things: either have the block "clean" HTML out from the input before saving it in the instance configuration and then display it as-is (the "eager" approach); or have it save the data "as is" and then clean it up each time just before displaying it (the "lazy" approach). The eager approach involves doing work once when saving the configuration; the lazy approach means doing work each time the block is displayed and thus it promises to be worse performance-wise. We shall hence go with the eager approach.

[[#top|Back to top of page]]

=== instance_config_save() ===

Much as we did just before with overriding [[Development:Blocks/Appendix_A#config_save.28.29| config_save()]], what is needed here is overriding the method [[Development:Blocks/Appendix_A#instance_config_save.28.29| instance_config_save()]] which handles the instance configuration. The default implementation is as follows:

<code php>
function instance_config_save($data) {
$data = stripslashes_recursive($data);
$this->config = $data;
return set_field('block_instance',
'configdata',
base64_encode(serialize($data)),
'id',
$this->instance->id);
}
</code>

This may look intimidating at first (what's all this stripslashes_recursive() and base64_encode() and serialize() stuff?) but do not despair; we won't have to touch any of it. We will only add some extra validation code in the beginning and then instruct Moodle to additionally call this default implementation to do the actual storing of the data. Specifically, we will add a method to our class which goes like this:

<code php>
function instance_config_save($data) {
// Clean the data if we have to
global $CFG;
if(!empty($CFG->block_simplehtml_strict)) {
$data->text = strip_tags($data->text);
}

// And now forward to the default implementation defined in the parent class
return parent::instance_config_save($data);
}
</code>

At last! Now the administrator has absolute power of life and death over what type of content is allowed in our "SimpleHTML" block! Absolute? Well... not exactly. In fact, if we think about it for a while, it will become apparent that if at some point in time HTML is allowed and some blocks have saved their content with HTML included, and afterwards the administrator changes the setting to "off", this will only prevent subsequent content changes from including HTML. Blocks which already had HTML in their content would continue to display it!

Following that train of thought, the next stop is realizing that we wouldn't have this problem if we had chosen the lazy approach a while back, because in that case we would "sanitize" each block's content just before it was displayed.

The only thing we can do with the eager approach is strip all the tags from the content of all SimpleHTML instances as soon as the admin setting is changed to "HTML off"; but even then, turning the setting back to "HTML on" won't bring back the tags we stripped away. On the other hand, the lazy approach might be slower, but it's more versatile; we can choose whether to strip or keep the HTML before displaying the content, and we won't lose it at all if the admin toggles the setting off and on again. Isn't the life of a developer simple and wonderful?

=== Exercise ===
We will let this part of the tutorial come to a close with the obligatory exercise for the reader:
In order to have the SimpleHTML block work "correctly", find out how to strengthen the eager approach to strip out all tags from the existing configuration of all instances of our block, '''or''' go back and implement the lazy approach instead.
(Hint: Do that in the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method.)

=== UPDATING: ===
Prior to version 1.5, the file ''config_global.html'' was named simply ''config.html''. Also, the methods [[Blocks_Howto#method_config_save| config_save]] and [[Blocks_Howto#method_config_print| config_print]] were named '''handle_config''' and '''print_config''' respectively. Upgrading a block to work with Moodle 1.5 involves updating these aspects; refer to [[Blocks_Howto#appendix_b| Appendix B]] for more information.

== Eye Candy ==

Our block is just about complete functionally, so now let's take a look at some of the tricks we can use to make its behavior customized in a few more useful ways.

First of all, there are a couple of ways we can adjust the visual aspects of our block. For starters, it might be useful to create a block that doesn't display a header (title) at all. You can see this effect in action in the Course Description block that comes with Moodle. This behavior is achieved by, you guessed it, adding one more method to our block class:

<code php>
function hide_header() {
return true;
}
</code>

One more note here: we cannot just set an empty title inside the block's [[Development:Blocks/Appendix_A#init.28.29| init()]] method; it's necessary for each block to have a unique, non-empty title after [[Development:Blocks/Appendix_A#init.28.29| init()]] is called so that Moodle can use those titles to differentiate between all of the installed blocks.

Another adjustment we might want to do is instruct our block to take up a certain amount of width on screen. Moodle handles this as a two-part process: first, it queries each block about its preferred width and takes the maximum number as the desired value. Then, the page that's being displayed can choose to use this value or, more probably, bring it within some specific range of values if it isn't already. That means that the width setting is a best-effort settlement; your block can ''request'' a certain width and Moodle will ''try'' to provide it, but there's no guarantee whatsoever about the end result. As a concrete example, all standard Moodle course formats will deliver any requested width between 180 and 210 pixels, inclusive.

To instruct Moodle about our block's preferred width, we add one more method to the block class:

<code php>
function preferred_width() {
// The preferred value is in pixels
return 200;
}
</code>

This will make our block (and all the other blocks displayed at the same side of the page) a bit wider than standard.

Finally, we can also affect some properties of the actual HTML that will be used to print our block. Each block is fully contained within a <table> element, inside which all the HTML for that block is printed. We can instruct Moodle to add HTML attributes with specific values to that container. This would be done to either a) directly affect the end result (if we say, assign bgcolor="black"), or b) give us freedom to customize the end result using CSS (this is in fact done by default as we'll see below).

The default behavior of this feature in our case will assign to our block's container the class HTML attribute with the value "sideblock block_simplehtml" (the prefix "block_" followed by the name of our block, lowercased). We can then use that class to make CSS selectors in our theme to alter this block's visual style (for example, ".sideblock.block_simplehtml { border: 1px black solid}").

To change the default behavior, we will need to define a method which returns an associative array of attribute names and values. For example, the version

<code php>
function html_attributes() {
return array(
'class' => 'sideblock block_'. $this->name(),
'onmouseover' => "alert('Mouseover on our block!');"
);
}
</code>

will result in a mouseover event being added to our block using JavaScript, just as if we had written the onmouseover="alert(...)" part ourselves in HTML. Note that we actually duplicate the part which sets the class attribute (we want to keep that, and since we override the default behavior it's our responsibility to emulate it if required).

And the final elegant touch is that we don't set the class to the hard-coded value "block_simplehtml" but instead use the [[Development:Blocks/Appendix_A#name.28.29| name()]] method to make it dynamically match our block's name.

===and some other useful examples too:===
<code php>
function html_attributes() {
// Default case: an id with the instance and a class with our name in it
return array('id' => 'inst'.$this->instance->id, 'class' => 'block_'. $this->name());
}
</code>

This method should return an associative array of HTML attributes that will be given to your block's container element when Moodle constructs the output HTML. No sanitization will be performed in these elements at all.

If you intend to override this method, you should return the default attributes as well as those you add yourself. The recommended way to do this is:

<code php>
function html_attributes() {
$attrs = parent::html_attributes();
// Add your own attributes here, e.g.
// $attrs['width'] = '50%';
return $attrs;
}
</code>

== Authorized Personnel Only ==

It's not difficult to imagine a block which is very useful in some circumstances but it simply cannot be made meaningful in others. An example of this would be the "Social Activities" block which is indeed useful in a course with the social format, but doesn't do anything useful in a course with the weeks format. There should be some way of allowing the use of such blocks only where they are indeed meaningful, and not letting them confuse users if they are not.

Moodle allows us to declare which course formats each block is allowed to be displayed in, and enforces these restrictions as set by the block developers at all times. The information is given to Moodle as a standard associative array, with each key corresponding to a page format and defining a boolean value (true/false) that declares whether the block should be allowed to appear in that page format.

Notice the deliberate use of the term ''page'' instead of ''course'' in the above paragraph. This is because in Moodle 1.5 and onwards, blocks can be displayed in any page that supports them. The best example of such pages are the course pages, but we are not restricted to them. For instance, the quiz view page (the first one we see when we click on the name of the quiz) also supports blocks.

The format names we can use for the pages derive from the name of the script which is actually used to display that page. For example, when we are looking at a course, the script is <span class="filename">/course/view.php</span> (this is evident from the browser's address line). Thus, the format name of that page is '''course-view'''. It follows easily that the format name for a quiz view page is '''mod-quiz-view'''. This rule of thumb does have a few exceptions, however:

# The format name for the front page of Moodle is '''site-index'''.
# The format name for courses is actually not just '''course-view'''<nowiki>; it is </nowiki>'''course-view-weeks''', '''course-view-topics''', etc.
# Even though there is no such page, the format name '''all''' can be used as a catch-all option.

We can include as many format names as we want in our definition of the applicable formats. Each format can be allowed or disallowed, and there are also three more rules that help resolve the question "is this block allowed into this page or not?":

# Prefixes of a format name will match that format name; for example, '''mod''' will match all the activity modules. '''course-view''' will match any course, regardless of the course format. And finally, '''site''' will also match the front page (remember that its full format name is '''site-index''').
# The more specialized a format name that matches our page is, the higher precedence it has when deciding if the block will be allowed. For example, '''mod''', '''mod-quiz''' and '''mod-quiz-view''' all match the quiz view page. But if all three are present, '''mod-quiz-view''' will take precedence over the other two because it is a better match.
# The character '''<nowiki>*</nowiki>''' can be used in place of any word. For example, '''mod''' and '''mod-*''' are equivalent. At the time of this document's writing, there is no actual reason to utilize this "wildcard matching" feature, but it exists for future usage.
# The order that the format names appear does not make any difference.
All of the above are enough to make the situation sound complex, so let's look at some specific examples. First of all, to have our block appear '''only''' in the site front page, we would use:

<code php>
function applicable_formats() {
return array('site' => true);
}
</code>

Since '''all''' is missing, the block is disallowed from appearing in ''any'' course format; but then '''site''' is set to TRUE, so it's explicitly allowed to appear in the site front page (remember that '''site''' matches '''site-index''' because it's a prefix).

For another example, if we wanted to allow the block to appear in all course formats ''except'' social, and also to ''not'' be allowed anywhere but in courses, we would use:

<code php>
function applicable_formats() {
return array(
'course-view' => true,
'course-view-social' => false);
}
</code>

This time, we first allow the block to appear in all courses and then we explicitly disallow the social format.
For our final, most complicated example, suppose that a block can be displayed in the site front page, in courses (but not social courses) and also when we are viewing any activity module, ''except'' quiz. This would be:

<code php>
function applicable_formats() {
return array(
'site-index' => true,
'course-view' => true,
'course-view-social' => false,
'mod' => true,
'mod-quiz' => false
);
}
</code>

It is not difficult to realize that the above accomplishes the objective if we remember that there is a "best match" policy to determine the end result.

'''UPDATING:''' <br />
Prior to version 1.5, blocks were only allowed in courses (and in Moodle 1.4, in the site front page). Also, the keywords used to describe the valid course formats at the time were slightly different and had to be changed in order to allow for a more open architecture. Refer to [[Development:Blocks/Appendix_B| Appendix B]] for more information on the changes that old blocks have to make to conform to the new standard.

== Lists and Icons ==

In this final part of the guide we will briefly discuss an additional capability of Moodle's block system, namely the ability to very easily create blocks that display a list of choices to the user. This list is displayed with one item per line, and an optional image (icon) next to the item. An example of such a ''list block'' is the standard Moodle "admin" block, which illustrates all the points discussed in this section.

As we have seen so far, blocks use two properties of [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]]: "text" and "footer". The text is displayed as-is as the block content, and the footer is displayed below the content in a smaller font size. List blocks use $this->content->footer in the exact same way, but they ignore $this->content->text.

Instead, Moodle expects such blocks to set two other properties when the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method is called: $this->content->items and $this->content->icons. $this->content->items should be a numerically indexed array containing elements that represent the HTML for each item in the list that is going to be displayed. Usually these items will be HTML anchor tags which provide links to some page. $this->content->icons should also be a numerically indexed array, with exactly as many items as $this->content->items has. Each of these items should be a fully qualified HTML <img> tag, with "src", "height", "width" and "alt" attributes. Obviously, it makes sense to keep the images small and of a uniform size.

In order to tell Moodle that we want to have a list block instead of the standard text block, we need to make a small change to our block class declaration. Instead of extending class '''block_base''', our block will extend class '''block_list'''. For example:

<code php>
class block_my_menu extends block_list {
// The init() method does not need to change at all
}
</code>

In addition to making this change, we must of course also modify the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method to construct the [[Development:Blocks/Appendix_A#.24this-.3Econtent| $this->content]] variable as discussed above:

<code php>
function get_content() {
if ($this->content !== null) {
return $this->content;
}

$this->content = new stdClass;
$this->content->items = array();
$this->content->icons = array();
$this->content->footer = 'Footer here...';

$this->content->items[] = '<a href="some_file.php">Menu Option 1</a>';
$this->content->icons[] = '<img src="images/icons/1.gif" class="icon" alt="" />';

// Add more list items here

return $this->content;
}
</code>

To summarize, if we want to create a list block instead of a text block, we just need to change the block class declaration and the [[Development:Blocks/Appendix_A#get_content.28.29| get_content()]] method. Adding the mandatory [[Development:Blocks/Appendix_A#init.28.29| init()]] method as discussed earlier will then give us our first list block in no time!

[[#top|Back to top of page]]

== See also ==
[http://dev.moodle.org/mod/resource/view.php?id=48 Unit 7 of the Introduction to Moodle Programming course] is a follow up to this course. (But you should follow the forum discussions of that course closely as there are still some bugs and inconsistencies.)

== Appendices ==

The appendices have been moved to separate pages:

* Appendix A: [[Development:Blocks/Appendix A|''block_base'' Reference]]
* Appendix B: [[Development:Blocks/Appendix B|Differences in the Blocks API for Moodle Versions prior to 1.5]]
* Appendix C: [[Development:Blocks/Appendix C|Creating Database Tables for Blocks (prior to 1.7)]]

[[Category:Developer|Blocks]]
[[Category:Tutorial]]

[[es:Desarrollo de bloques]]

Development:XMLDB introduction

2009-09-16T12:19:51Z

Josepuib: spelling mistake

[[Development:XMLDB Documentation|XMLDB Documentation]] > Introduction
----
__NOTOC__
One of the main upcoming features in Moodle 1.7 will be its ability to work with some more [[wikipedia:RDBMS|RDBMS]] ([[wikipedia:MSSQL|MSSQL]] and [[wikipedia:Oracle database|Oracle]]) while maintaining everything working properly with both [[MySQL]] and [[PostgreSQL]]. As Moodle core uses [http://adodb.sourceforge.net/ ADOdb] internally, this possibility has been present since the beginning and, with the current maturity of the project (5 years old baby!), this can be a good moment to sort all this out.

Initially, all our tests and preliminary work was to inspect how [http://adodb.sourceforge.net/ ADOdb] was doing its work, and how we could mix together all those 4 RDBMS, whose SQL dialects, although pretty similar, have some differences and idiosyncrasies that force us to do some important changes to our current database code (formerly '''datalib.php''') and how it's used by the rest of Moodle.

All the changes to be performed, which primary objective is to enable Moodle to work with more RDBMS, must be fulfilled by following these non-functional requirements:

* '''Provide one layer (new) for DB creation/upgrade''' ([[wikipedia:Data_Definition_Language|DDL]]): With this, developers will create their structures in one neutral form, independent of the exact implementation to be used by each RDBMS.

* '''Provide one layer (existing) for DB handling''' ([[wikipedia:Data_Manipulation_Language|DML]]): With this, developers will request/store information also in one neutral form, independent of the RDBMS being used.

* '''Easy migration path from previous versions''': The current installation/upgrade system will work until, at least, Moodle 2.0, allowing 3rd party developers to migrate to the new system.

* '''Simple, usable and effective''': Until now, the way to upgrade Moodle has been really cool and it has worked pretty fine since the beginning. However, it has forced developers to maintain at least two installation and two upgrade scripts for each module/plugin. The new alternative will have only one file to install and one file to upgrade (per module/plugin too), reducing the possibility of mistakes drastically.

* '''Conditional code usage must be minimised''': Database libraries must accept 99% of potential SQL sentences, building/transforming them as necessary to work properly under any RDBMS. The number of places using custom (per DB) code should be minimum.

* '''Well documented''': All the functions defined, both at DML and DDL level must be well documented, helping the developer to find and use the correct one in each situation.

== The Stack ==

The next stack shows how Moodle 1.7 code will interact with the underlying RDBMS. It will help us understand a bit more what we are trying to do and will explain some of the points related in the Roadmap (below in this page).

[[Image:MoodleDBStack.png|center]]

Moodle code will use two ''languages'' to perform its DB actions:

* '''XMLDB neutral description files''': To create, modify and delete database objects (DDL: create/alter/drop tables, fields, indexes, constraints...). It consists of a collection of validated, standard, XML files. They will be used to define all the DB objects. New for 1.7.
* '''Moodle SQL neutral statements''': To add, modify, delete and select database information (DML: insert/update/delete/select records). To modify for 1.7.

Please note the '''neutral''' keyword used in the expressions above. It means that both '''languages''' will be 100% the same, independent of the underlying RDBMS being used. And this must be particularly true for the XMLDB part.

Obviously it's possible that in the SQL part we found some specialised queries (using complex joins, regular expressions...) that will force us to do some '''Exceptions'''. Well, they can exist (in fact, they exist), but we always must try to provide an alternate path to minimise them using neutral statements and standard libraries.

Each one of the '''languages''' above will use its own library to do the work:

* '''Moodle DDL Library''' ([[Development:DDL functions|ddllib.php]]): Where all the functions needed to handle DB objects will exist. This library is new for 1.7 and will provide developers with a high level of abstraction. As input it will accept some well defined objects and actions and it will execute the proper commands for the RDBMS being used.
* '''Moodle DML Library''' ([[Development:DML functions|dmllib.php]]): Where all the functions needed to handle DB contents will exist. This library is new for 1.7, although its contents are, basically, functions currently present in '''datalib.php''' (moved from there). All those DML functions will offer cross-db support for insert/update/delete/select statements using a common behaviour.

Also note that '''datalib.php''' is still present in the schema above. It will contain all the functions that haven't been moved to the new '''ddllib.php''' and '''dmllib.php''' libraries. Only some common functions will remain there, and these will disappear (it's considered a legacy library) in upcoming '''Moodle''' releases (after 1.7) by moving all those functions to their proper library (course/lib.php, user/lib.php....).

Both of these libraries (plus the small '''Exceptions''' bar) will perform all their actions using the '''ADOdb Database Abstraction Library for PHP''' that will receive all the requests from them, communicate with the DB ('''MySQL''', '''PostgreSQL''', '''Oracle''' or '''SQL*Server'''), retrieve results and forward them back to originator library.

== The process ==

This section points to the main areas of information about the '''process of design and implementation''' of the new XMLDB layer:

* [[XMLDB Roadmap|Roadmap]]: Where the whole process is defined. It has been split into small chunks to be performed and tested easily. Also, such documents should be used to track what's done and what's pending, while using easy nomenclature.

* [[XMLDB Problems|Problems]]: A comprehensive list of issues that need to be determined/solved prior to incorporating them into the [[XMLDB Roadmap|roadmap]].

== The documentation ==

This section points to the '''main documentation index''' about the implemented XMLDB:

* [[Development:XMLDB Documentation|Documentation]]: Where you'll find quick links to different parts of the XMLDB documentation.

==See also==

=== XMLDB related ===

* [[Development:XMLDB preliminary links|XMLDB preliminary links]] - A collection of links about general info, searched and analysed at the initial stages of the project
* [[Development:XMLDB preliminary notes|XMLDB preliminary notes]] - A collection of notes collected in the early stages of this project, pointing both to some changes required and some problems to solve.

=== Database related ===

* [[Development:DDL functions|DDL functions]] - Documentation for all the Data Definition Language (DDL) functions available inside Moodle.
* [[Development:DML functions|DML functions]] - Documentation for all the Data Manipulation Language (DML) functions available inside Moodle.

[[Category:XMLDB]]

[[zh:开发:XML数据库计划]]

Development:SSH key

2009-08-27T12:41:05Z

Josepuib:

==What is a SSH key?==

SSH keys are used for secure connections across a network. They come in pairs, so you have a public key and a private key.

The standard ssh2 file format (see
http://www.openssh.org/txt/draft-ietf-secsh-publickeyfile-02.txt)
looks like this:

---- BEGIN SSH2 PUBLIC KEY ----
Comment: "jtbell@Jon-Bells-Computer"
AAAAB3NzaC1kc3MAAACBAPNgmidbM2rhYjUXunpnlXjHWfV+vc8/5YKrn8Y5P0Y6KwmG2G
GMgNBon3LX3iJlBhtuU3FCBj3G1Kdt5vUhQHhUmHVrOasi47vawTrv7ZJCfiaSGwRsiBHt
Jta5CAp7t0EnzX2q6BvPbFBBHNLyy6uNVpL2jOR06Pkx/vaqyScvAAAAFQDHvwmjWYwK9g
K6Sp+pSvI7bwEUtwAAAIANMJDotMpfj89N+7+FJylSS+uFEQSS61PxENl/Mcj1jUREjJg2
eNsJdAB9Ev99hWYS+7lFRtTJ2eh4Y9gpGe7BX3e2YGHOqp8cWCVCIKaMzwk9To+xnfThWq
IfHT8I6CJxp/5ez02m6F2k/5iukvOwbGms6EAZK1DTBhDOHjEQwQAAAIAlz2/qBWkaMP+s
W8FLmGKM+cCw5+asOaJGTwrFVuwJkDMvdEWxmG92A2dxuUske0d/AkN6zJp7HD0wlfesRM
3+c+Res5qun9lFcdM4i03VoV5mXd+T7laS8yku6vZgvZZFnPvr2LOUnc7XThGFwMaQpFEW
U8cvQbttO6QrT2CD2w==
---- END SSH2 PUBLIC KEY ----

However, Moodle uses OpenSSH on its server and this key will not work with the OpenSSH server in this format; OpenSSH requires the key to be in OpenSSH format. Here is an example of a DSA public key in OpenSSH format (usually they are all in one line):

ssh-dss AAAAB3NzaC1kc3MAAACBAJ3hB5SAF6mBXPlZlRoJEZi0KSIN+NU2iGiaXZXi9CDrgVxTp6/
sc56UcYCp4qjfrZ2G3+6PWbxYso4P4YyUC+61RU5KPy4EcTJske3O+aNvec/20cW7PT3TvH1+sxwGry
mD50kTiXDgo5nXdqFvibgM61WW2DGTKlEUsZys0njRAAAAFQDs7ukaTGJlZdeznwFUAttTH9LrwwAAA
IAMm4sLCdvvBx9WPkvWDX0OIXSteCYckiQxesOfPvz26FfYxuTG/2dljDlalC+kYG05C1NEcmZWSNES
GBGfccSYSfI3Y5ahSVUhOC2LMO3JNjVyYUnOM/iyhzrnRfQoWO9GFMaugq0jBMlhZA4UO26yJqJ+BtX
IyItaEEJdc/ghIwAAAIBFeCZynstlbBjP648+mDKIvzNSS+JYr5klGxS3q8A56NPcYhDMxGn7h1DKbb
2AV4pO6y+6hDrWo3UT4dLVuzK01trwp PYp6JXTSZZ12ZaXNPz7sX9/z6pzMqhX4UEfjVsLcuF+ZS6a
QCPO0ZZEa1z+EEIZSD/ykLQsDwPxGjPBqw== someone@somewhere.com

In addition to OpenSSH and Standard SSH formats there are a variety of proprietary formats as well as SSH1 and SSH2 differences to account for, which can make this confusing.

In the example above you will note that the key starts with "ssh-dss". This is because this key was generated using DSA as opposed to RSA. A number of vendors in the SSH arena have argued, as per the PuTTY documentation that can be found at http://the.earth.li/~sgtatham/putty/0.55/htmldoc/Chapter8.html#S8.2.10 that users should employ RSA encryption because

DSA has an intrinsic weakness which makes it very easy to create a signature
which contains enough information to give away the private key! This would
allow an attacker to pretend to be you for any number of future sessions.

An SSH2 public key in OpenSSH format will start with "ssh-rsa".

The idea behind all of this is that once you have keys on the remote server and your local host, access will be simpler since the server will only grant access to someone who has the matching private key.

==Why do I need a SSH key?==

Our CVS server uses OpenSSH, so if you are a Moodle developer and you want to make your logins easier (by avoiding typing in your password all the time) then you will need to submit public key in Openssh format via the "Update my developer information" tab at http://moodle.org/cvs.

==How do I create a SSH key pair?==

===Platform Independent===

Visit http://www.sshkeygen.com and simply follow the directions there.

===Eclipse===

If you plan to use Eclipse for development, please refer to the Eclipse document https://docs.moodle.org/en/Eclipse as Eclipse now has a plugin that allows you to manage all ssh key matters from within Eclipse.

===Unix/Linux===

You can use ssh-keygen at your system prompt. Please consult the man page on your system for the options available to you.

# Run: '''ssh-keygen -t (rsa or dsa)'''. This will not include a passphrase. *
# Use of rsa or dsa above will result in rsa or dsa replacing each XXX below.
# Look in your ~/.ssh directory (or wherever you saved the output). You'll find '''id_XXX''' (private) and '''id_XXX.pub''' (public).
# Cut and paste the contents of '''id_XXX.pub''' into your developer profile on http://moodle.org/cvs
# Put the private key wherever you will be calling CVS from (in your .ssh directory, for example). Make sure it's secure!

* This section initially recommended using ''ssh-keygen -d'' but it is unclear what the source of this -d option might be.

===Windows===
Use puttygen and follow the instructions [http://the.earth.li/~sgtatham/putty/0.58/htmldoc/Chapter8.html here]. Make sure you choose the RSA2 key format and that when you copy the key data into the textbox on the site, that you have all of the characters on one line. If you have opened the key with word pad, it will have line breaks in it which will stop it from working.

The box should look like this:

ssh-rsa
AAAAWfg&jkf4D34H5@4svf..... (single very long line continues beyond edge of textbox)

===Mac OS X===

Development:XHTML

2009-08-26T10:19:54Z

Josepuib:

==XHTML Strict 1.0==

Moodle output must be compliant with XHTML Strict 1.0. This means it must be:

===Well-formed XML===

In a well-formed XML document, every opening tag has a matching close tag; tags are properly nested, attributes are properly quoted, and the file contains no syntax errors. See [http://www.w3.org/TR/xml/#sec-well-formed the XML specification for a formal definition].

While developing, you should have the option Administration ► Server ► Debugging ► XML strict headers turned on. With this option on, your web browser will refuse to display any page that is not well-formed. This makes such problems easy to find and fix.

===Valid XHTML Strict===

This means that the XML of your page follows the particular rules from the [http://www.w3.org/TR/xhtml1/dtds.html#a_dtd_XHTML-1.0-Strict XHTML-1.0-Strict DTD]. <nowiki>For example, the first tag in the file must be <html>, a <form> tag must have an action="" attribute, an <li> can only appear inside an <ol> or <ul>, you cannot use <frame> tags, and so on.</nowiki> and so on.

You can check whether the HTML you output is valid by using a HTML validator, for example the [https://addons.mozilla.org/en-US/firefox/addon/249 Html Validator] add-on for Firefox.

===Semantic markup===

That is, HTML tags should be used only to mark up the appropriate types of content. For example:
* tables should not be used for page layout, just to display tabular information,
* if something is a heading, it should be marked up using <h''n''> tags, for an appropriate ''n'',
* <nowiki>if something is a list, it should marked up using <ol>, <ul> or <dl>,</nowiki>
* see [[Semantic HTML]] for further details

==Styling==

How the HTML is laid out should be controlled by CSS in whichever theme is currently selected.

* Ensure that the HTML contains enough id="..." and class="..." attributes so that theme designers can easily control how
* Never embed inline styles in the HTML (that is, do not use the style="..." attribute).
* As you change core Moodle code, you must update the standard theme so that Moodle looks OK out of the box.
* If you need to make basic style definitions for a module (or some other sorts of plugin), put them in a file called styles.php in that module. This will be included into every theme.

== Moodle API ==

* Use the functions in lib/weblib to do as much as possible (print_header(), print_box() etc)
* This API will change a lot in Moodle 2.0. See: [[Development:Navigation_2.0]]

== See also: ==

* [http://developer.apple.com/internet/webcontent/bestwebdev.html Web Page Development: Best Practices] by the Safari development team at Apple.

Development:Coding

2009-08-25T21:50:49Z

Josepuib:

This page is the top-level page describing Moodle's coding guidelines. It's the place to start if you want to know how to write code for Moodle.

<p class="note">WARNING: Under construction RIGHT NOW!</p>

==Moodle architecture==

Moodle tries to run on the widest possible range of platforms, for the widest possible number of people, while remaining easy to install, use, upgrade and integrate with other systems.

For more about this, see: [[Moodle architecture]].

==Plugins==

Moodle has a general philosophy of modularity. There are over 25 different types of plugins, however many of these plugin types work the same way.

For more about the structure of plugins, see [[Development:Plugins|Moodle plugins]].

==Coding style==

Consistent coding style is important in any development project, and particularly so when many developers are involved. A standard style helps to ensure that the code is easier to read and understand, which helps overall quality.

Writing your code in this way is an important step to having your code accepted by the Moodle community.

Our [[Development:Coding_style|Moodle coding style]] document explains this standard.

==Security==

Security is about protecting the interests and data of all our users. Moodle may not be banking software, but it is still protecting a lot of sensitive and important data such as private discussions and grades from outside eyes (or student hackers!) as well as protecting our users from spammers and other internet predators.

It's also a script running on people's servers, so Moodle needs to be a responsible Internet citizen and not introduce vulnerabilities that could allow crackers to gain unlawful access to the server it runs on.

Any single script (in Moodle core or a third party module) can introduce a vulnerability to thousands of sites, so it's important that all developers strictly follow our [[Development:Security|Moodle security guidelines]].

==XHTML==

It's important that Moodle produces strict, well-formed XHTML code, compliant with all common accessibility guidelines (such as W3C WAG).

This helps consistency across browsers in a nicely-degrading way (especially those using non-visual or mobile browsers), as well as improving life for theme designers.

Full information is here: [[Development:XHTML|Moodle XHTML]]

==JavaScript==

In general, everything in Moodle should work with JavaScript turned off in your browser. If you do have JavaScript enabled it should only improve usability (not add features).

This is important for accessibility, and in line with the principles of unobtrusive JavaScript and progressive enhancement.

See the [[Development:JavaScript guidelines|Moodle JavaScript guidelines]] for more information.

==Internationalisation==

Moodle works in over 81 languages because we pay great attention to keeping the language strings and locale information separate from the code, in language packs.

The default language for all code and documentation, however, is English (AU).

Full details: [[Development:Internationalisation|Moodle Internationalisation]]

==Accessibility==

Moodle should work well for the widest possible range of people.

See: [[Development:Accessibility|Moodle Accessibility]]

==Usability==

See: [[Development:Moodle_User_Interface_Guidelines|Moodle User Interface Guidelines]] (being produced summer 2009)
* Implementing user interfaces: [[Development:Interface_guidelines| Interface Guidelines]]

==Database==

Moodle has a powerful database abstraction layer that we wrote ourselves, called [[Development:XMLDB_Documentation|XMLDB]]. This lets the same Moodle code work on MySQL, PostgreSQL, Oracle and MSSQL.

We have tools and API for [[Development:DDL functions|defining and modifying tables]] as well as [[Development:DML functions|methods for getting data in and out]] of the database.

Overview: [[Development:Database|Moodle Database]] guidelines

==Events==

Moodle allows inter-module communication via '''events'''. Modules can '''trigger''' specific events and other modules can choose to '''handle''' those events.

Full information: [[Development:Events_API|Moodle Events API]]

==Unit tests==

[http://en.wikipedia.org/wiki/Unit_testing Unit testing] is not simply a technique but a philosophy of software development.

The idea is to create automatable tests for each bit of functionality that you are developing (at the same time you are developing it). This not only helps everyone later test that the software works, but helps the development itself, because it forces you to work in a modular way with very clearly defined structures and goals.

Moodle uses a library called simpletest (not very extensively yet though!) that makes writing unit tests fairly simple. Our unit testing is currently not deep but we want to improve this.

Full information here: [[Development:Unit_tests|Moodle Unit Tests]]

== See also ==
* [http://doku.clausvb.de/php_coding_standard.htm General PHP coding standards]
* [http://pear.php.net/manual/en/standards.php PEAR coding standards]

[[Category:Developer|Coding]]

[[es:Manual de Estilo de Código]]
[[ja:コーディング]]
[[zh:代码指南]]
[[pl:Kodowanie]]
[[pt:manual_de_codigo]]
[[fr:Développement:Directives_de_codage]]