MoodleDocs - Wkład użytkownika [pl]

Ajax marking block

2012-04-20T11:40:38Z

Mattgibson: Updated docs for 2.2

The [http://moodle.org/plugins/view.php?plugin=block_ajax_marking AJAX marking block] allows you to view and grade all of your marking without leaving the page you are on. It displays all the ungraded work you need to mark in a tree structure of all of the courses you teach in, along with a count of how many items there are for each course & assessment item. Clicking an item gives you a grading popup, and once you're done, the tree updates itself so you can keep track of what's left.
[[Image:Ajax_marking.png|right]]

==Prioritise your marking whatever way suits you==
===Mark all work for a particular class===
The block has been built with workflow in mind. If you have a class coming up and need to get their marking done, whatever it is, use the cohorts tab to see all their work across courses. If you are not using cohorts, set the course or activity you are interested in to 'show groups nodes' by either using the config tab, or right-clicking the item where you see it. This will break down the work into separate nodes for each group and you can mark just those.

===Mark the most urgent work first===
Each course, activity, group, etc has a count of the unmarked work attached. This is broken down into three numbers: recent (within the last 4 days), medium (4-10 days) and overdue (> 10 days). You can quickly see where the oldest pieces of work are and attend to those first. Marking should never take longer than 2 weeks in order to maintain it's relevance, so now you can make sure you never miss any at all.

=== Mark quizzes faster by doing all answers to one question in rapid succession ===
The block breaks down quizzes into separate questions before showing you all the students' answers, so you can run through all answers to a particular question quickly, keeping your mind focused on the same thing.

==Mark only the things you need to, and hide the rest==
The block provides setting via the config tab and a right-click context menu. The trees update immediately when any changes are made, so you can see what's going on.

===Only show work for activities you actually have to mark===
Sometimes there is work waiting to be graded on an activity that you are not supposed to do anything about e.g. work submitted to practice courses, courses with different topic taught by different people, etc. You can hide these activities by either finding them in the config tab and clicking the show/hide icon, or right-clicking the item in the main courses tree. If you do this for course, it will set all the items in that course to inherit that setting. You can then optionally override the course default for individual activities, but hanging the course level setting will wipe all those overrides out again.

===Only show work for your own teaching groups===
Sometimes, several groups are doing an activity, but you only teach some of them e.g. if the same Moodle course activities and resources are shared across multiple teachers and classes. In this case, you can set individual groups to be either visible or hidden for that activity, either by using the config tab, or by right-clicking in the courses tree as for the show/hide settings. Defaults are set at course level with activity level overrides in the same way as for show/hide. If you have your groups set to 'separate groups', then you will automatically only see work from student in groups you are a member of, as mentioned above.

==Installation==
Get the files into the blocks/jax_marking diretory, then go to the notifications screen (Front page -> administration block -> notifications) where you should see a message about the tables having been set up correctly.

How to get the files:

=== Zip file ===
Download the right zip file [http://moodle.org/plugins/pluginversions.php?plugin=block_ajax_marking here]. Copy it to your /blocks/ folder and unzip it there.

=== Git ===
The gihub repository is [https://github.com/mattgibson/moodle-block_ajax_marking here]. Use the following command to get the latest version onto your system:
cd /path/to/your/moodle/blocks
git clone https://github.com/mattgibson/moodle-block_ajax_marking.git ajax_marking
cd ajax_marking
git checkout MOODLE_22_STABLE

== Troubleshooting ==
If you can't see the work you think you ought to, there are a few reasons for this. Try the following:
* You are an admin and the courses you are looking at have work, but you are not enrolled as a teacher in them. This is to prevent site admins from seeing thousands upon thousands of items unnecessarily. Adding yourself as a teacher in a category will work for the courses within it, but not at site level.
* You have your course or activity set to 'separate groups' and you are not in the same groups as the students whose work you can't see. Many people use this technique to hide classes from teachers who don't teach them, so I've set the block up to respect this. Join all the groups in the course and you should be fine.
* You have used the AJAX Marking Block's configuration tab to set some items to 'hide' or set some groups to 'hide'. To reset the settings, you can either run an SQL query like this: DELETE FROM mdl_block_ajax_marking where userid = <youruserid> or, you can check the config tab and set all the course level things to hide and back again. This will work because changing the course level settings destroys all the overrides at activity level. Don't forget to do the same with any groups.
* The work you are looking for is from a module that is not supported (yet). The list is below: I am aiming to support any and all modules once I have finished the core block features that I have in mind. Hopefully, by the start of June 2012, this will be done and all modules that can be marked will appear.

==Supported types==
* Assignment
* Forum (only if ratings are on)
* Workshop
* Quiz (essay questions only)

==See also==
[[Development:AJAX marking block]]

[[Category:Contributed code]]
[[Category:Teacher]]
[[Category:Administrator]]

Ajax marking block

2011-11-03T16:52:46Z

Mattgibson: /* Supported types */

The [http://moodle.org/mod/data/view.php?d=13&rid=1459 AJAX marking block] allows you to view and complete all of your marking without leaving the page you are on. It displays all the ungraded work you need to mark in a tree structure of all of the courses you teach in, along with a count of how many items there are for each course & assessment item.
[[Image:Ajax_marking.png|right]]

=== 2.0 status:===
The block currently works in a basic way for Moodle 2.0 and 2.1, but lacks the configuration interface. I'm working on this pretty much flat out, and it's involved a significant refactor of almost all of the code in order to make more scalable and to allow for future expansion etc. [[User:Matt Gibson|Matt Gibson]] 00:52, 4 November 2011 (WST)

====Keep track of what you have graded so far====
When the tree nodes are expanded and a student's name is clicked, a pop-up opens with the work to be graded. Once 'Submit' has been clicked in that window, the pop-up closes and tree updates itself by removing the student's node and altering its total count.

====Instantly update without leaving the page====
The [[AJAX]] bit means that every time you click on the nodes to expand them, the data for the child nodes is fetched in the background without refreshing the whole page. This saves on loading the whole lot at the start, which could be time consuming. Clicking 'Collapse and refresh' will re-load the whole tree, with an updated count of your marking including anything that was submitted a second or two ago, and excluding any that were marked by someone else and now don't need your attention.

====Only show grading for your own teaching groups====
Some sites run training courses that don't need grading, or a single course with many teachers and teaching groups following the same programme of study. You can easily choose to hide the work that is not your using the '''configure''' link, which will open a pop up allowing you to show or hide each item individually, or choose to show only the work of some groups, so you only ever see the work that you actually need to mark.

==Installation==
Download the zip file [http://moodle.org/mod/data/view.php?d=13&rid=1459&filter=1 here]. Copy it to your /blocks/ folder and unzip it there. Then, go to the notifications screen (Front page -> administration block -> notifications) where you should see a message about the tables having been set up correctly.

==Roles and permissions==
Note that you will not get anything displayed at all unless you have a teacher role in a course. This course will also need to be one that has gradable items like assignments or forums with ratings, or you will get an error saying that you have no graded assessments yet.

If you want to see all of the items in all of the courses across the site, add yourself as a teacher under Front page Admin block -> users -> permissions -> assign site wide roles

A fix so that admins see everything without doing this is on the way (CONTRIB-1017)

===Configuring the display of each individual assessment item===
The block can be set to show or hide each individual assessment item, or show only the assessments by students in certain groups. Clicking on '''configure''' will bring up an additional tree, which shows all of your courses and names of all the assessment items. When you click on one of the assessments, you will be faced with a number of options on the right:
* Show - the default state, where you will see all students' work
* Show by group - a set of checkboxes will appear with the names of the current groups for that course. You choose which you want to see and group nodes will then be shown between the assessment and student nodes in the main block. The nodes for that assessment will then look like this: '''Course -> Assessment -> Group -> Submission'''
* Hide - do not display any submissions for this assessment item.

The counting of unmarked submissions respects these choices and they are specific to the user who created them. If you are an admin and wish to set the preferences for others, use the 'login as' function to do so.

==Supported types==
* Assignment
* Forum (only if ratings are on)
* Workshop
* Journal (1.9 only)
* Quiz (essay questions only)

==See also==
[[Development:AJAX marking block]]

[[Category:Contributed code]]
[[Category:Teacher]]
[[Category:Administrator]]

Ajax marking block

2011-11-03T16:52:23Z

Mattgibson: /* 2.0 status: */

The [http://moodle.org/mod/data/view.php?d=13&rid=1459 AJAX marking block] allows you to view and complete all of your marking without leaving the page you are on. It displays all the ungraded work you need to mark in a tree structure of all of the courses you teach in, along with a count of how many items there are for each course & assessment item.
[[Image:Ajax_marking.png|right]]

=== 2.0 status:===
The block currently works in a basic way for Moodle 2.0 and 2.1, but lacks the configuration interface. I'm working on this pretty much flat out, and it's involved a significant refactor of almost all of the code in order to make more scalable and to allow for future expansion etc. [[User:Matt Gibson|Matt Gibson]] 00:52, 4 November 2011 (WST)

====Keep track of what you have graded so far====
When the tree nodes are expanded and a student's name is clicked, a pop-up opens with the work to be graded. Once 'Submit' has been clicked in that window, the pop-up closes and tree updates itself by removing the student's node and altering its total count.

====Instantly update without leaving the page====
The [[AJAX]] bit means that every time you click on the nodes to expand them, the data for the child nodes is fetched in the background without refreshing the whole page. This saves on loading the whole lot at the start, which could be time consuming. Clicking 'Collapse and refresh' will re-load the whole tree, with an updated count of your marking including anything that was submitted a second or two ago, and excluding any that were marked by someone else and now don't need your attention.

====Only show grading for your own teaching groups====
Some sites run training courses that don't need grading, or a single course with many teachers and teaching groups following the same programme of study. You can easily choose to hide the work that is not your using the '''configure''' link, which will open a pop up allowing you to show or hide each item individually, or choose to show only the work of some groups, so you only ever see the work that you actually need to mark.

==Installation==
Download the zip file [http://moodle.org/mod/data/view.php?d=13&rid=1459&filter=1 here]. Copy it to your /blocks/ folder and unzip it there. Then, go to the notifications screen (Front page -> administration block -> notifications) where you should see a message about the tables having been set up correctly.

==Roles and permissions==
Note that you will not get anything displayed at all unless you have a teacher role in a course. This course will also need to be one that has gradable items like assignments or forums with ratings, or you will get an error saying that you have no graded assessments yet.

If you want to see all of the items in all of the courses across the site, add yourself as a teacher under Front page Admin block -> users -> permissions -> assign site wide roles

A fix so that admins see everything without doing this is on the way (CONTRIB-1017)

===Configuring the display of each individual assessment item===
The block can be set to show or hide each individual assessment item, or show only the assessments by students in certain groups. Clicking on '''configure''' will bring up an additional tree, which shows all of your courses and names of all the assessment items. When you click on one of the assessments, you will be faced with a number of options on the right:
* Show - the default state, where you will see all students' work
* Show by group - a set of checkboxes will appear with the names of the current groups for that course. You choose which you want to see and group nodes will then be shown between the assessment and student nodes in the main block. The nodes for that assessment will then look like this: '''Course -> Assessment -> Group -> Submission'''
* Hide - do not display any submissions for this assessment item.

The counting of unmarked submissions respects these choices and they are specific to the user who created them. If you are an admin and wish to set the preferences for others, use the 'login as' function to do so.

==Supported types==
* Assignment
* Forum (only if ratings are on)
* Workshop
* Journal
* Quiz (essay questions only)

==See also==
[[Development:AJAX marking block]]

[[Category:Contributed code]]
[[Category:Teacher]]
[[Category:Administrator]]

Ajax marking block

2011-08-05T14:13:33Z

Mattgibson: /* 2.0 status: */

The [http://moodle.org/mod/data/view.php?d=13&rid=1459 AJAX marking block] allows you to view and complete all of your marking without leaving the page you are on. It displays all the ungraded work you need to mark in a tree structure of all of the courses you teach in, along with a count of how many items there are for each course & assessment item.
[[Image:Ajax_marking.png|right]]

=== 2.0 status:===
The block currently works in a basic way for Moodle 2.0, but not yet for 2.1 (question bank code changes need adjusting for). I'm working on this pretty much flat out, and it's involved a significant refactor of almost all of the code in order to make more scalable and to allow for future expansion etc. I am currently sorting out Oracle compatibility and once I've done that, I'm revamping the settings that show or hide individual assessment items. [[User:Matt Gibson|Matt Gibson]] 22:13, 5 August 2011 (WST)

====Keep track of what you have graded so far====
When the tree nodes are expanded and a student's name is clicked, a pop-up opens with the work to be graded. Once 'Submit' has been clicked in that window, the pop-up closes and tree updates itself by removing the student's node and altering its total count.

====Instantly update without leaving the page====
The [[AJAX]] bit means that every time you click on the nodes to expand them, the data for the child nodes is fetched in the background without refreshing the whole page. This saves on loading the whole lot at the start, which could be time consuming. Clicking 'Collapse and refresh' will re-load the whole tree, with an updated count of your marking including anything that was submitted a second or two ago, and excluding any that were marked by someone else and now don't need your attention.

====Only show grading for your own teaching groups====
Some sites run training courses that don't need grading, or a single course with many teachers and teaching groups following the same programme of study. You can easily choose to hide the work that is not your using the '''configure''' link, which will open a pop up allowing you to show or hide each item individually, or choose to show only the work of some groups, so you only ever see the work that you actually need to mark.

==Installation==
Download the zip file [http://moodle.org/mod/data/view.php?d=13&rid=1459&filter=1 here]. Copy it to your /blocks/ folder and unzip it there. Then, go to the notifications screen (Front page -> administration block -> notifications) where you should see a message about the tables having been set up correctly.

==Roles and permissions==
Note that you will not get anything displayed at all unless you have a teacher role in a course. This course will also need to be one that has gradable items like assignments or forums with ratings, or you will get an error saying that you have no graded assessments yet.

If you want to see all of the items in all of the courses across the site, add yourself as a teacher under Front page Admin block -> users -> permissions -> assign site wide roles

A fix so that admins see everything without doing this is on the way (CONTRIB-1017)

===Configuring the display of each individual assessment item===
The block can be set to show or hide each individual assessment item, or show only the assessments by students in certain groups. Clicking on '''configure''' will bring up an additional tree, which shows all of your courses and names of all the assessment items. When you click on one of the assessments, you will be faced with a number of options on the right:
* Show - the default state, where you will see all students' work
* Show by group - a set of checkboxes will appear with the names of the current groups for that course. You choose which you want to see and group nodes will then be shown between the assessment and student nodes in the main block. The nodes for that assessment will then look like this: '''Course -> Assessment -> Group -> Submission'''
* Hide - do not display any submissions for this assessment item.

The counting of unmarked submissions respects these choices and they are specific to the user who created them. If you are an admin and wish to set the preferences for others, use the 'login as' function to do so.

==Supported types==
* Assignment
* Forum (only if ratings are on)
* Workshop
* Journal
* Quiz (essay questions only)

==See also==
[[Development:AJAX marking block]]

[[Category:Contributed code]]
[[Category:Teacher]]
[[Category:Administrator]]

Ajax marking block

2011-08-05T14:13:19Z

Mattgibson: 2.0 status added

The [http://moodle.org/mod/data/view.php?d=13&rid=1459 AJAX marking block] allows you to view and complete all of your marking without leaving the page you are on. It displays all the ungraded work you need to mark in a tree structure of all of the courses you teach in, along with a count of how many items there are for each course & assessment item.
[[Image:Ajax_marking.png|right]]

=== 2.0 status:===
The block currently works in a basic way for Moodle 2.0, but not yet for 2.1 (question bank code changes need adjusting for). I'm working on this pretty much flat out, and it's involved a significant refactor of almost all of the code in order to make more scalable and to allow for future expansion etc. I am currently sorting out Oracle compatibility and once I've done that, I'm revamping the settings that show or hide individual assessment items.

====Keep track of what you have graded so far====
When the tree nodes are expanded and a student's name is clicked, a pop-up opens with the work to be graded. Once 'Submit' has been clicked in that window, the pop-up closes and tree updates itself by removing the student's node and altering its total count.

====Instantly update without leaving the page====
The [[AJAX]] bit means that every time you click on the nodes to expand them, the data for the child nodes is fetched in the background without refreshing the whole page. This saves on loading the whole lot at the start, which could be time consuming. Clicking 'Collapse and refresh' will re-load the whole tree, with an updated count of your marking including anything that was submitted a second or two ago, and excluding any that were marked by someone else and now don't need your attention.

====Only show grading for your own teaching groups====
Some sites run training courses that don't need grading, or a single course with many teachers and teaching groups following the same programme of study. You can easily choose to hide the work that is not your using the '''configure''' link, which will open a pop up allowing you to show or hide each item individually, or choose to show only the work of some groups, so you only ever see the work that you actually need to mark.

==Installation==
Download the zip file [http://moodle.org/mod/data/view.php?d=13&rid=1459&filter=1 here]. Copy it to your /blocks/ folder and unzip it there. Then, go to the notifications screen (Front page -> administration block -> notifications) where you should see a message about the tables having been set up correctly.

==Roles and permissions==
Note that you will not get anything displayed at all unless you have a teacher role in a course. This course will also need to be one that has gradable items like assignments or forums with ratings, or you will get an error saying that you have no graded assessments yet.

If you want to see all of the items in all of the courses across the site, add yourself as a teacher under Front page Admin block -> users -> permissions -> assign site wide roles

A fix so that admins see everything without doing this is on the way (CONTRIB-1017)

===Configuring the display of each individual assessment item===
The block can be set to show or hide each individual assessment item, or show only the assessments by students in certain groups. Clicking on '''configure''' will bring up an additional tree, which shows all of your courses and names of all the assessment items. When you click on one of the assessments, you will be faced with a number of options on the right:
* Show - the default state, where you will see all students' work
* Show by group - a set of checkboxes will appear with the names of the current groups for that course. You choose which you want to see and group nodes will then be shown between the assessment and student nodes in the main block. The nodes for that assessment will then look like this: '''Course -> Assessment -> Group -> Submission'''
* Hide - do not display any submissions for this assessment item.

The counting of unmarked submissions respects these choices and they are specific to the user who created them. If you are an admin and wish to set the preferences for others, use the 'login as' function to do so.

==Supported types==
* Assignment
* Forum (only if ratings are on)
* Workshop
* Journal
* Quiz (essay questions only)

==See also==
[[Development:AJAX marking block]]

[[Category:Contributed code]]
[[Category:Teacher]]
[[Category:Administrator]]

error/moodle/textconditionsnotallowed

2011-06-16T12:07:10Z

Mattgibson: Created page with "http://moodle.org/mod/forum/discuss.php?d=176081"

http://moodle.org/mod/forum/discuss.php?d=176081

XMLDB defining an XML structure

2011-05-06T15:51:47Z

Mattgibson: /* Conventions */ Fixed link

[[Development:XMLDB Documentation|XMLDB Documentation]] > [[Development:XMLDB roadmap|Roadmap]] > Defining one XML structure
----

== Justification ==

Before Moodle 1.7, all the DB install and upgrade was developed twice (once to handle MySQL installations and another to handle PostgreSQL installations). This approach, although working, has caused some headaches in the past, mainly because it was really difficult to keep both lines of development 100% on sync. Some developers do they work against one RDBMS and it was complex to develop to the other one (two test environments, skills on both databases, slower development cycle...). And all this was happening with ''only'' two supported RDBMS!

One of the main objectives of Moodle 1.7 is to extend the the number of supported RDBMS to other flavours (more exactly, to Oracle and MSSQL). And the old approach (one line of development for each DB) could become an absolute nightmare.

Because of this we have planned to build one structure to define all the DB objects used by Moodle. This structure will provide the necessary level of abstraction to be shared by all the RDBMS systems, so the "multiple lines of development" explained in the previous paragraph will be out forever, giving us one robust and well defined way to handle DB objects independently of the underlying RDBMS being used.

== Implementation ==

Initially all our best wishes were to use the [http://phplens.com/lens/adodb/docs-datadict.htm#xmlschema AdoDB XML Schema]. As Moodle is using ADOdb libraries to communicate with databases it sounded like the natural approach to solve the problem. But, finally, two reasons prevented us to use it:

# Although working, it seems to be one feature in progress, with important changes/evolutions arriving at the time of write this document.
# Its lack of support for "prefixes" (one Moodle key feature, to allow multiple instances to run in the same server), would force us to create some awful tricks to generate the objects.

So, finally, we decided to build our own XML files, with everything we need to define every object present in the DB.

== The XMLDB editor ==
[[XMLDB_editor | Main article]]

Although the XML is pretty simple to read (and to write), one of the major drawbacks was its easy and error-prone adoption by the developers. Also some problems with versioning systems getting crazy with XML files (thanks ML!) pointed us to the requirement to use one high-density format (it means, physically '''long lines''') in our XML files.

After some intense thoughts we decided to build one specialised editor for our XML format. This editor should be easy to use and provide support for all the objects present one Moodle DB. And it's done (and will support future enhancements easily, we hope).

The XMLDB Editor makes the addition of tables/fields/keys/indexes practically a trivial task, allowing the developer to spend the time coding and improving things instead of fighting against XML files and the errors caused by manual editing (of course, the developer is free to use such extra-time as desired, beers, dance, books, music...) ;-)

All the new '''install.xml''' files, present under each '''db''' directory in Moodle can be edited (and we recommend it) with just some clicks and keystrokes. Those '''install.xml''' will contain all the info needed to generate the specific objects needed for each RDBMS supported. Obviously, such files, are the neutral replacement for all the *.sql files used until now.

=== Launching ===

Just login to your server as an administrator and, under the Miscellaneous tab of the Administration Block, you'll see a new link pointing to the "XMLDB Editor".

One '''important note''' is that, to be able to handle files properly, the web server needs write access to all those "db" directories where the "install.xml" files reside (and to the files themselves, of course). ;-)

That's all!

=== Use===

We really think the XMLDB Editor is pretty easy to use, so here you won't see a complete guide to use it. We highly recommend you to play with it for a while, viewing how it works and how it modifies the '''install.xml''' files.

It's organised in a top-botton structure, where you start '''loading''' (or '''creating''') a new XMLDB file. Then, you can '''edit''' such file and its '''general structure''' will be showed. This structure have two type of elements, '''tables''' and '''statements''' and the XMLDB Editor allows you to '''add''', '''edit''', '''delete''', and '''move''' them easily. Also, for initial creation of tables, one small but effective '''reverse-enginery''' tool has been developed (only under MySQL) allowing you to retrofit any table from the DB to the XMLDB Editor.

'''Note: If you can't click on the create links....''' you must first create the /db folder (as shown in the list, but it may not really exist) and then make sure it is writeable by the webserver

While editing tables you will see their '''fields''', '''keys''' and '''indexes''' and you'll be able to handle all them easily. Note that some fields can be no-editable. It uses to be because they are being used in some way (part of one key or index) and the idea is to warn you about that.

Fields can be edited and you can specify their '''name''', '''type''', '''length''', '''decimals''', '''null-ability''', '''defaults''' and so one. Exactly the same for both '''keys''' and '''indexes'''.

While editing statements, you must think about them like "collections of sentences". Once you select the '''type''' (only inserts are allowed for now) and '''table''' you are interested you'll be able to introduce the exact values easily, being able to '''duplicate''' them easily to gain some speed if you have a lot of sentences in your development. Sentences can be '''edited''' and '''deleted''' easily too.

One interesting feature is that all the XMLDB Editor pages allow you to enter one '''comment''' about the item being modified (table, index, key, field, statement...). Use it at your entire needs, sure it helps other developers to understand a bit more the DB model.

Please, don't forget to read and understand the next section, where we talk about '''some important guidelines''' to create and handle XMLDB files.

== Conventions ==

Apart of the [[Development:Database| Database Structures guidelines]], some more conventions should be followed:

# About names:
## All lowercase names (tables, indexes, keys and fields).
## Table names and field names must use only a-z, 0-9 and _ chars. Table names can be at most 28 characters long; column names at most 30 characters.
## Key and index names under the XMLDB Files must be formed by concatenating the name of the fields present in the key/index with the '"-" (minus) character.
## Primary key always must be named "primary" (this is one exception to the previous convention).
## It's highly recommended to avoid [[XMLDB_reserved_words|reserved words]] completely. We know we have some of them now but they should be completely out for next releases.
# About NULLS
## Avoid to create all the fields as NOT NULL with the ''silly'' default value <nowiki>''</nowiki> (empty string). The underlying code used to create tables will handle it properly but the XMLDB structure must be REAL. Read more in the [[XMLDB_Problems#NOT_NULL_fields_using_a_DEFAULT_.27.27_clause|Problems Page]].
# About FOREIGN KEYS
## Under the tables of every XMLDB file, you must define the existing '''Foreign Keys''' (FK) properly. This will allow everybody to know a bit better the structure, allow to evolve to a better constrained system in the future and will provide the underlying code with the needed info to create the proper indexes.
## Note that, if you define any field combination as FK you won't have to create any index on that fields, the code will do it automatically!
## This convention is only applicable for relations INSIDE one file. Don't generate FK constraints against other files (courseid, userid), use indexes there.
## Respect Convention 1.3
# About UNIQUE KEYS
## Declare any fields as UNIQUE KEY (UK) only if they are going to be used as target for one FK. Create unique indexes instead.
## Respect Convention 1.3

== One example: the assignment module ==

Here we are going to examine the [http://cvs.moodle.org/moodle/mod/assignment/db/install.xml?view=markup current implementation of the XMLDB Schema for the assignment module] (a simple one). It has been completely generated with the XMLDB Editor but it's nice to know a bit more about the XML internals.

As you can see the structure is pretty simple:

* XMLDB
** TABLES, one or more, each one with
*** FIELDS
*** KEYS
*** INDEXES
** STATEMENTS, none or more, each one with
*** SENTENCES

First of all you should note that all the elements contain the '''PREVIOUS''' and '''NEXT''' attributes. They allow us to keep everything ordered although it isn't meaningful at all from the RDBMS perspective. Also the '''COMMENT''' field is present everywhere to be used as desired.

=== The TABLE element ===

We can ignore the TABLE element, as it's simply one container for the internals (FIELDS, KEYS and INDEXES). Let's go to examine them a bit more:

==== The FIELD element ====

It maps with one field in the DB (obviously). For each field you can define its '''name''', '''type''' (from a list of [[XMLDB column types|neutral types]]), '''length''', '''decimals''' (for some types), '''notnull''' (true/false), '''unsigned''' (true/false), '''sequence''' (if it's autonumeric or serial, true/false), '''enum''' (true/false), '''enumvalues''' (the list of values if the field has been declared as enum, for example <tt>'frog','toad','newt'</tt>) and '''default''' (to assign a default value).

So, in our example, we have two tables, assignment and assignment_submissions, each one with its own fields, defining all the information related above. Please note that naming conventions are followed.

==== The KEY element ====

Here is where all the PRIMARY KEYS (PK), UNIQUE KEYS (UK) and FOREIGN KEYS (FK) will be defined. For each key we define its '''name''', '''type''', '''fields''' (that belongs to it) and optionally (if the key is one FK) the target '''reftable''' and '''reffields'''.

In our example, the assignment table has one (mandatory!) PK (called, "primary", rules are rules) built with the "id" field.

The other table, the "assignment_submissions" one, also has its PK (called "primary" once more) and one FK, with the field "assignment" pointing to the field "id" of the table "assignment". Note that the FK follows the name conventions and its name is, simply, the name of the fields being part of it ("assignment"). Also, the FK has as target to one PK of the same module.

Finally, note that there isn't any index created for all these keys. Moodle will generate them automatically when the table is created. All the keys will have their corresponding index. Point. ;-)

==== The INDEX element ====

Where all the indexes will be defined. For each index you can define its '''name''', '''unique''' (true/false) and the '''fields''' that conform it. Please note that naming conventions are followed.

Also, some "obvious index", like the one based in the "assignment" field of the "assignment_submissions" table doesn't exist. Yes, you know why: Because such column has been defined as a FK and the index will be automatically created (see previous section).

=== The STATEMENT element ===

This is the other '''big container''' in the XMLDB Schema (at the same level as the '''TABLES''' one) and we can define its '''name''', '''type''' (only insert allowed for now) and '''table''' (against the sentences will be executed).

Every statement is a collection of '''sentences'''

==== The SENTENCE element ====

Each sentence implies one simple action to be performed against the DB and it can be defined as the "missing part of the SQL statement". In our example, we have one statement, of type "insert" on table "log_display". With this Moodle knows the initial part of the sentence, i.e:

INSERT INTO log_display

and then the text will be added to create this:

INSERT INTO log_display
(module, action, mtable, field)
VALUES
('assignment', 'view', 'assignment', 'name')

There is one important trick when handling sentences, although they aren't in the assignment example. Take a look to the [http://cvs.moodle.org/moodle/lib/db/install.xml?view=co Core Tables XML Schema] (it's a huge one!). If you go near the end, to the statements section, you will see some sentences like this:

<SENTENCE TEXT="....VALUES ('user', 'view', 'user', 'CONCAT(firstname," ",lastname)')"/>

Such "CONCAT" function isn't standard at all (only MySQL supports it), but don't worry, we'll transform it to the correct concatenation operators for other RDBMS. Just be sure to use the syntax showed above.

== DTD and XML schema ==

Not sure if this will be usable for somebody but here you can find one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.dtd?view=co automatically generated DTD] for the XMLDB files. Also one [http://cvs.moodle.org/moodle/lib/xmldb/xmldb.xsd?view=co automatically generated XML Schema] is available. Any improvement/fix to them will be welcome!

== See also ==

* [[XMLB List of files to create|List of files to create]]: The list of files to be created from scratch. Used to follow the progress.
* http://www.hitsw.com/xml_utilites/: One online XML-DTD-Schema converter.

[[Category:XMLDB]]
[[Category:DB]]

Themes 2.0 adding a settings page

2011-05-03T22:56:58Z

Mattgibson: /* How settings pages work in Moodle */ typo

{{Template:Themes}}{{Moodle 2.0}}This document looks at how to create a settings page for your theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Development:Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Development:Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
 

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Development:Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<code php>
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
// Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible
'embedded' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
// Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible
'embedded' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]] 

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/

$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created as ''$temp'' lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$temp->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
The above line of code is the final line for the page. It is adding the page that we have created '''$temp''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php

/**
* Settings for the demystified theme
*/

// Create our admin page
$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));

// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);

// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);

// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150, 170, 200, 240, 290, 350, 420);
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);

// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);

// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);

// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
</div>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
 

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''#FFA800''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]] 

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>

<?php echo page_doc_link(get_string('moodledocslink')) ?>

</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]] 

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
 

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 overriding a renderer]]
* [[Development:Themes_2.0 adding upgrade code]]
* [[Development:Styling and customising the dock]]
* http://moodle.org/mod/forum/discuss.php?d=152053

Firebug

2011-04-07T10:21:09Z

Mattgibson: /* Tutorials */ Added bit about AJAX debugging

== What is Firebug? ==

Firebug is an add-on for the [[Firefox]] web browser. Firebug integrates with Firefox to put a wealth of development tools at your fingertips while you browse. You can edit, debug, and monitor CSS, HTML, and JavaScript live in any web page...

== Is Firebug only for Firefox? ==

The add-on will only work in Firefox, but there is also a JavaScript based [http://getfirebug.com/lite.html Firebug Lite] version for use with Internet Explorer (IE), Opera, and Safari.

=== Alternatives with similar functionality for other Web browsers: ===

* The [http://www.microsoft.com/downloadS/details.aspx?familyid=E59C3964-672D-4511-BB3E-2D5E1DB91038&displaylang=en Internet Explorer Developer Toolbar] for '''Microsoft IE'''.
* '''IE 8''' comes with its [http://blogs.msdn.com/brunoterkaly/archive/2009/08/03/internet-explorer-8-developer-tools-debugging-html-and-css.aspx own development tools].
* [http://www.opera.com/dragonfly/ Dragonfly] for '''Opera'''. - [http://www.sitepoint.com/blogs/2010/02/28/opera-dragonfly-open-source/ A short introduction from SitePoint]
* The commonly named "JavaScript console" menu item in '''Google Chrome'''.
* The [http://webkit.org/blog/197/web-inspector-redesign/ Web Inspector] menu item in '''Safari'''.

== Where can I get Firebug? ==

* http://getfirebug.com
* https://addons.mozilla.org/en-US/firefox/addon/1843

== Tutorials ==
* [http://www.webmonkey.com/tutorial/Build_Better_Pages_With_Firebug Build Better Pages With Firebug]

* [http://michaelsync.net/2007/09/09/firebug-tutorial-logging-profiling-and-commandline-part-i Firebug Tutorial - Logging, Profiling and CommandLine (Part 1)]

* And for those of us who prefer viewing to reading, there's a bunch of tutorial videos on [http://www.youtube.com/results?search_query=Firebug+firefox&aq=f YouTube].

===Debugging AJAX with Firebug===
Once installed, Firebug can show you the XMLHTTPrequests that happen in the background as AJAXy things occur and also what data is returned. This is pretty handy if you find that the requests are failing for no reason you can discern.

To make the most of this, it's important to make sure that the data being sent by the server is properly encoded and has the right headers. The most efficient way to do this is to use JSON for the response, rather than XML (fewer characters used to represent stuff, so faster to download) and to do so using PHP's native json_encode() function. This will make firebug show you the response in a lot more detail than if you just echoed the data as XML fragments.

To watch the XMLHTTPrequests, enable firebug, click on the '''Net''' tab and enable that too, then click on the '''XHR''' button. Now, anything that happens will show up in firebug. To see the response data from the server, expand the line for that request using the '''+''' icon on the left, then click on the '''response''' tab. This shows the raw data but you should also have a JSON and/or HTML tab which will allow you to see it properly formatted.

== Further enhancements ==
There are some enhancements to make Firebug even more powerful.
* See the [https://addons.mozilla.org/en-US/firefox/search?q=firebug&cat=all complete list of Firebug related add-ons on the Mozilla website].
* [http://www.drweb.de/magazin/mehr-power-fur-firebug/ Mehr Power für Firebug] is an article written in German, but you can just follow the links to the Firefox add-on page.

Here are some of those enhancements.


'''Note''': Some of these enhancements are experimental. Caution should be used when installing experimental add-ons, as they have not been tested by an editor and may harm your computer configuration.


=== FirePHP ===
[http://www.firephp.org/ FirePHP] enables you to log to your Firebug Console using a simple PHP method call. 
There's a [http://moodle.org/mod/forum/discuss.php?d=119961 FirePHP plugin for Moodle] in the works.

=== FireRainbow ===
[https://addons.mozilla.org/en-US/firefox/addon/9603 FireRainbow] (formerly ''Rainbow for Firebug'') - Provides '''JavaScript syntax highlighting''' for Firebug 1.3.

=== CodeBurner ===
[https://addons.mozilla.org/en-US/firefox/addon/10273 CodeBurner] - A Firefox add-on that integrates with Firebug, to extend it with reference material for CSS, HTML, and JavaScript from [http://reference.sitepoint.com SitePoint].

There's also [http://tools.sitepoint.com/codeburner/firefox/ CodeBurner for Firefox], a standalone version of the original CodeBurner for Firebug, but with an independent interface, and more dedicated search tools.

=== YSlow ===
[https://addons.mozilla.org/en-US/firefox/addon/5369 YSlow] - YSlow analyzes web pages and tells you why they're slow based on Yahoo's rules for high performance web sites.

=== Firefinder ===
[https://addons.mozilla.org/en-US/firefox/addon/11905 Firefinder] - Finds HTML elements matching chosen CSS selector(s) or XPath expression.

=== FireQuery ===
[https://addons.mozilla.org/en-US/firefox/addon/12632?from=%2Fde%2Ffirefox%2Faddon%2F12632 FireQuery] is a collection of Firebug enhancements for jQuery. Requires Firebug 1.3 or greater.

Features:
* jQuery expressions are intelligently presented in Firebug Console and DOM inspector
* attached jQuery data are first class citizens
* elements in jQuery collections are highlighted on hover
* jQuerify: enables you to inject jQuery into any page

=== Inline Code Finder for Firebug ===
[https://addons.mozilla.org/en-US/firefox/addon/9641/ Inline Code Finder for Firebug] is an add-on to Firebug, to be able to find HTML elements with any of the below issues:

* Inline JavaScript events
* Inline style
* javascript: links

=== FlashFirebug ===
[https://addons.mozilla.org/en-US/firefox/addon/161670/ FlashFirebug]: Debug your own SWF files inside the browser. Edit properties and inspect elements like you do to HTML. Flash files are no longer the closed components they used to be. This extension requires Firebug and the O-Minds Flash package.

=== FireFile ===
[https://addons.mozilla.org/en-US/firefox/addon/52365/ FireFile]: Firebug extension to save the CSS files edited with firebug live to your web server. That makes Firebug become the first remote-save live-preview CSS editor and allows ultra-fast webdesign.

=== Firebug Autocompleter ===
[https://addons.mozilla.org/en-us/firefox/addon/firebug-autocompleter/ Firebug Autocompleter] - Firebug command line autocomplete.

== See also: ==
* [[Themes FAQ]]
* [[CSS FAQ]]

{{CategoryDeveloper}}
[[Category:Developer tools|Firebug]]
[[Category:Firefox extensions|Firebug]]

Broken/Database

2011-02-14T14:11:35Z

Mattgibson: Added bit about pluralised table names

==Database structures==

To help you create tables that meet these guidelines, we recommend you use the built in [[Development:XMLDB_defining_an_XML_structure#The_XMLDB_editor|database definition (XMLDB) editor]].

# Every table must have an auto-incrementing id field (INT10) as primary key. (see [[IdColumnReasons]])
# The main table containing instances of each module must have the same name as the module (eg widget) and contain the following minimum fields:
#* id - as described above
#* course - the id of the course that each instance belongs to
#* name - the full name of each instance of the module
# Other tables associated with a module that contain information about 'things' should be named widget_things (note the plural).
# Core tables in general should have single word names non-pluralised, and double word names pluralised only for the last letter e.g. 'course', 'course_categories'. The only exceptions should be for reserved words e.g. 'files'. Some tables don't fit this pattern right now for historical reasons, but this will eventually be changed.
# Table and column names should avoid using [[Database reserved words|reserved words in any database]]. Please check them before creation. Table names may be up to 28 characters long, and Column names up to 30 characters.
# Column names should be always lowercase, simple and short, following the same rules as for variable names.
# Where possible, columns that contain a reference to the id field of another table (eg widget) should be called widgetid. (Note that this convention is newish and not followed in some older tables)
# Boolean fields should be implemented as small integer fields (eg INT4) containing 0 or 1, to allow for later expansion of values if necessary.
# Most tables should have a timemodified field (INT10) which is updated with a current timestamp obtained with the PHP time() function.
# Always define a default value for each field (and make it sensible)
# Each table name should start with the database prefix ($CFG->prefix). In a lot of cases, this is taken care of for you automatically. Also, under Postgres, the name of every index must start with the prefix too.
# In order to guarantee [[Development:XMLDB problems#Table and column aliases - the AS keyword|cross-db compatibility]] follow these simple rules about the use of the '''AS''' keyword (only if you need table/column aliases, of course):
#* '''Don't use''' the '''AS''' keyword for '''table aliases'''.
#* '''Do use''' the '''AS''' keyword for '''column aliases'''.
# '''Never''' create UNIQUE KEYs (constraints) at all. Instead use UNIQUE INDEXes. In the future, if we decide to add referential integrity to Moodle and we need UNIQUE KEYs they will be used, but not now. Please note that the XMLDB editor allows you to specify both XMLDB-only UNIQUE and FOREIGN constraints (and that's good, in order to have the XML well defined) but only underlying INDEXes will be generated.
# Those XMLDB-only UNIQUE KEYs (read previous point) only must be defined if such field/fields '''are going to be the target''' for some (XMLDB-only too) FOREIGN KEY. Else, create them as simple UNIQUE INDEXes.
# Tables associated '''with one block''' must follow this convention with their names: '''$CFG->prefix + "block_" + name_of_the_block + anything_else'''. For example, assuming that $CFG->prefix is 'mdl_', all the tables for the block "rss_client" must start by 'mdl_block_rss_client' (being possible to add more words at the end, i.e. 'mdl_block_rss_client_anothertable'...). This rule will be 100% enforced with Moodle 2.0, giving time to developers until then. See [http://tracker.moodle.org/browse/MDL-6786 Task 6786] for more info about this.
# '''Never''' make database changes in the STABLE branches. If we did, then users upgrading from one stable version to the next would have duplicate changes occurring, which may cause serious errors.
# When refering to integer variable in SQL queries, do not surround the value in quotes. For example, get_records_select('question', "category=$catid") is right. get_records_select('question', "category='$catid'") is wrong. It hides bugs where $catid is undefined. ([http://moodle.org/mod/forum/discuss.php?d=80629 This thread explains].)

[[Category:Coding guidelines|Database]]
[[Category:DB|Database]]
[[Category:XMLDB|Database]]

DB layer 2.0 migration docs

2011-02-08T16:23:22Z

Mattgibson: /* The golden changes */

{{Template:Development:dmllib 2.0}}{{Moodle_2.0}}
== Introduction ==
Much of the following documentation will not make much sense unless you first read [[Development:XMLDB_Documentation|the XMLDB documentation]]. Please read it first if you would like to join the effort to convert Moodle's code to the new dmllib.

Also, it's recommended to read the whole [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation before starting with the migration. That will allow you to have some initial knowledge about the new architecture.

This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under the new Moodle 2.0 DB layer. The changes below are grouped into 2 main blocks, [[Development:XMLDB_Documentation|XMLDB]] and [[wikipedia:Data_Manipulation_Language|DML]], to keep them organised. Additional minor changes may be required in the [[wikipedia:Data_Definition_Language|DDL]] code, but won't be documented here.

Although the order of changes shown on this page isn't mandatory at all, it can be interesting to follow the migration progress to be able to understand and learn a bit more about all them. That way, you'll end up knowing not only what to change but how and why those changes are required.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything becomes too complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find a bug in the process, please report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], so that developers will be able to fix it ASAP.

The Glossary module was used as the basis for many of the examples below.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration; that will certainly help many developers. Thanks!

__TOC__

== check_db_syntax: One helper script ==

Before you start migrating your code to Moodle 2.0, it's recommended you install and run the [http://cvs.moodle.org/contrib/tools/check_db_syntax/ check_db_syntax.php] script. Simply copy it to the main folder of your plugin and execute it (from command line or via web). It will show you a list of old DB usages that need to be transformed following the information below in this article.

If you think that something is missing in the script or have any ideas to improve it, feel free to do that yourself, commenting about it in MDL-15237. Thanks!

Also, this (perl-compatible - works in Eclipse, hopefully elsewhere) regex:

(?<!->)(?<!function )(?<!\$)\b(?:(?:count|delete|get|insert|update)_record(?!s_csv)|[gs]et_field|record_exists|execute_sql)|\$CFG->prefix|rs_(?:fetch|close)|(add|strip)slashes(?!_js)

will find most of the things in your code that need attention, with few false positives.

== XMLDB/DDL changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the [[XMLDB editor|XMLDB Editor]] (Admin->Development->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look at some code in core modules, blocks... whatever you need. They are a good reference.
* The most noticeable change (from a migration perspective) in the DDL stuff is that, starting with Moodle 2.0, we have decided to '''drop support for enum (check constraint) fields completely'''. See MDL-18577 and [http://moodle.org/mod/forum/discuss.php?d=118852 this discussion]. That implies changes in different parts of the DB stuff (XML files, function parameters, dropping existing enums...) and are commented with more detail below.

=== The changes ===
* STATEMENTS section was replaced by db/install.php code and db/log.php
* Few other changes are required in install.xml files (that's good news!). Although you must know these:
** The '''ENUM''' and '''ENUMVALUES''' attributes present in your install.xml files will be completely ignored both by the DLL generation stuff and by the XMLDB Editor.
** In Moodle 2.1, those attributes ('''ENUM''' and '''ENUMVALUES''') will be 100% forbidden, so it's highly recommended to erase them beginning now (Moodle 2.0).
** The XMLDB Editor will detect them when loading any install.xml file and will suggest you to fix that easily with one 1-click® option.
** No matter if you have fixed that with the 1-click® option when loading the files... the [[XMLDB editor|XMLDB Editor]] will save any edited install.xml files without those attributes.
** If your Moodle 1.9.x code '''has some enum defined in the database''', you will need to create one upgrade block (in db/upgrade.php) to drop it (the enum, not the field! ;-) as part of the migration from Moodle 1.9 to 2.0 by using the new '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' method.
** Of course, if you don't use/like the XMLDB Editor, you can erase them manually with something like this:
perl -p -e 's/ENUM(VALUES)?=".*?" //g' < install.xml > install.xml.new

* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from the Glossary module):
<code php>
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
</code>
* All upgrade.php scripts must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
<code php>
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
</code>
* All '''XMLDBTable''' instances in your upgrade code must be replaced by '''xmldb_table''' (no change in parameters)
* All '''XMLDBField''' instances in your upgrade code must be replaced by '''xmldb_field''' (with change in params, both $enum and $enumvalues are out from function declaration!)
* All '''XMLDBIndex''' instances in your upgrade code must be replaced by '''xmldb_index''' (no change in parameters)
* All '''XMLDBKey''' instances in your upgrade code must be replaced by '''xmldb_key''' (no change in parameters)
* All the '''addFieldInfo()''' methods must be replaced by '''add_field()''' (with change in params, both $enum and $enumvalues (the 7th and 8th parameters) are out from function declaration!)
* All the '''addIndexInfo()''' methods must be replaced by '''add_index()''' (no change in parameters)
* All the '''addKeyInfo()''' methods must be replaced by '''add_key()''' (no change in parameters)
* All the '''setAttributes()''' methods must be replaced by '''set_attributes()''' (with change in params, both $enum and $enumvalues (the 6th and 7th parameters) are out from function declaration!)
* All the DDL functions used in your upgrade code must be transformed as detailed below (it's simply about adding '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
** table_exists ==> $dbman->table_exists
** field_exists ==> $dbman->field_exists
** index_exists ==> $dbman->index_exists
** find_index_name ==> $dbman->find_index_name
** find_check_constraint_name ==> $dbman->find_check_constraint_name ('''DEPRECATED in 2.0. OUT in 2.1''')
** check_constraint_exists ==> $dbman->check_constraint_exists ('''DEPRECATED in 2.0. OUT in 2.1''')
** find_sequence_name ==> '''OUT in 2.0''', see MDL-20349
** create_table ==> $dbman->create_table
** drop_table ==> $dbman->drop_table
** rename_table ==> $dbman->rename_table
** add_field ==> $dbman->add_field
** drop_field ==> $dbman->drop field
** rename_field ==> $dbman->rename_field
** change_field_type ==> $dbman->change_field_type
** change_field_precision => $dbman->change_field_precision
** change_field_unsigned ==> $dbman->change_field_unsigned
** change_field_notnull ==> $dbman->change_field_notnull
** change_field_enum ==> $dbman->change_field_enum ('''OUT in 2.0''', see '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' to get rid of remaining ENUMs in code).
** change_field_default ==> $dbman->change_field_default
** add_key ==> $dbman->add_key
** drop_key ==> $dbman->drop_key
** add_index ==> $dbman->add_index
** drop_index ==> $dbman->drop_index
* The DDL functions that change things (create/drop/rename/add)_(table/field/index) no longer return boolean. Instead, they throw an exception if they fail. So your upgrade.php no longer needs to use a '''$result''' variable, and instead should use the '''upgrade_mod_savepoint()''' function:
<code php>/** old way **/
if ($result && $oldversion < 2008061000) {
$table = new xmldb_table('facetoface_submissions');
$field = new xmldb_field('notificationtype');
$field->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'timemodified');

$result = $result && $dbman->add_field($table, $field);
}

/** new way **/
if ($oldversion < 2008061000) {
$table = new xmldb_table('facetoface_submissions');
$field = new xmldb_field('notificationtype');
$field->set_attributes(XMLDB_TYPE_INTEGER, '10', XMLDB_UNSIGNED, XMLDB_NOTNULL, null, '0', 'timemodified');

$dbman->add_field($table, $field);
upgrade_mod_savepoint(true, 2008061000, 'facetoface');
}</code>

* Finally, and not less important, your code (module, block... plugin) must guarantee that it can be upgraded '''ONLY''' from Moodle 1.9, so any previous upgrade code can be safely deleted. '''Moodle 2.0 requires Moodle 1.9''' to be upgraded, so everybody will run the 1.9 => 2.0 upgrade (with other paths like 1.8 => 2.0 not being possible). This is a good time to clean-up your upgrade code a bit ;-). Don't forget to take a look at the [[XMLDB editor|XMLDB Editor]] and the core modules to see how [http://cvs.moodle.org/moodle/lib/db/upgrade.php?view=markup upgrade.php] files should look in Moodle 2.0.

== DML changes ==

=== Some comments ===
* The ENTIRE CODEBASE requires an update of ALL database query function calls. Expect most moodle files to be affected by this change.

* This is the more complex part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into three sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere). Finally other changes details can be found in the '''"The tin changes"''' section.

=== The golden changes ===
''PLEASE read the API before going crazy with search & replace''! You can find all the new methods in lib/dml/moodle_database.php. This is essential because some method signatures have changed (params are different), and some method names have even changed (execute_sql() is now execute()).

Each of the golden changes below is given one short name (G1, G2, G3...) for further reference in the rest of the documentation. Let's go:

* G1: Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record, count_records*, delete_records, record_exists), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
<code php>
Example:

// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);
</code>
::Note: for some functions, the $params array is not the second function parameter. For example, set_field:'''
<code php>
// Old syntax
set_field('user', 'firstname', 'Peter', 'id', 1);

// New syntax
global $DB;
$DB->set_field('user', 'firstname', 'Peter', array('id' => 1));
</code>

* G2: All uses of addslashes() '''must be removed'''. They are no longer needed

* G3: All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
<code php>
Example:

// Old syntax:
$user = get_record("user", "firstname", "Peter", "lastname", "Cantrophus");

// New syntax:
global $DB;
$conditions = array("firstname" => "Peter", "lastname" => "Cantrophus");
$user = $DB->get_record("user", $conditions);
</code>
::Note: The example above has been written out in full for clarity. You can use the array() directly within the function call, without using a temporary variable, if you prefer:''
<code php>
global $DB;
$user = $DB->get_record("user", array("firstname" => "Peter", "lastname" => "Cantrophus") );
</code>

* G4: rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
<code php>
Example:

// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
...
}
$rs->close();
</code>

* G5: Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

<code php>
Example:

// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";
</code>

* G6: When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
** Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
** Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array. Note that named params '''must be unique''', no matter if the value passed is the same.

<code php>
Examples:

// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Peter' AND lastname = 'Cantrophus'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Peter', 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('firstname' => 'Peter', 'lastname' => 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :firstname AND lastname = :lastname";
$user = $DB->get_record_sql($sql, $params);
</code>

To obtain a value for the LIKE operator, include any % signs into the parameter string. For example, code that was previously <tt>"LIKE '$value%'"</tt> becomes <tt>"LIKE ?"</tt> with the parameter <tt>$value.'%'</tt>.

* G7: Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

<code php>
Example:

// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);
</code>

'''Note:''' to combine the last two, do the G7 IN SQL stuff first to generate the params array, then do something like
$params['firstname'] = 'peter';
to add the stuff for G6

=== The iron changes ===

*I1: Originally the '''sql_substr()''' function was used without parameters and it returned only the name of the "substring" function to be used under each DB. In Moodle 2.0 and upwards, it has 3 parameters (2 being mandatory) and it returns the complete SQL text to be used when handling substrings. Note that positions in this function are 1-based (first char has index 1).

<code php>
Example:

// Old syntax
$records = get_records_sql("SELECT " . sql_substr() . "(firstname, 1, 20)" . " FROM ... ..."

// New syntax
$records = $DB->get_records_sql("SELECT " . $DB->sql_substr('firstname', 1, 20) . " FROM ... ..."
</code>

=== The tin changes ===
List of minor changes

* T1: Originally get_records() and similar functions were returning false if no records found. All these methods are now always returning arrays, empty array in case of no records found. Please note that get_record() still returns false if specified record not found.
<code php>
Example:

// Old syntax
if (!$posts = get_records('forum_posts', 'parent', 666)) {
$posts = array()
}

// New syntax
global $DB;
$posts = $DB->get_records('forum_posts', array('parent'=>666));
</code>

* T2: Originally DML functions were returning ''false'' if error occurred - ''dml_exception'' is thrown now instead.
<code php>
Example:

// Old syntax
$record = new object();
$record->course = 5;
if (!$id = insert_record('sometable', $record)) {
error('can not insert new record');
}

// New syntax
global $DB;
$record = new object();
$record->course = 5;
$id = $DB->insert_record('sometable', $record);
</code>

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[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.
* [[Development:DDL exceptions|DDL exceptions]] - DDL exceptions information.
* [[Development:DML exceptions|DML exceptions]] - DML exceptions information.

Broken/Enrolment plugins

2010-11-09T13:44:26Z

Mattgibson: /* How to write an Enrolment plugin in Moodle 1.9 */ Added warning over PARAM_ALPHA for plugin names

==How to write an Enrolment plugin in Moodle 1.9==

Create a new directory called <code>/enrol/</code>'''<code>PLUGINNAME</code>'''. Within this directory, create a file <code>/enrol/</code>'''<code>PLUGINNAME</code>'''<code>/enrol.php</code> which contains the declaration for a class called <code>enrolment_plugin_</code>'''<code>PLUGINNAME</code>'''. Note that PLUGINNAME must be letters only as it is passed through PARAM_ALPHA.

<code php>
class enrolment_plugin_PLUGINNAME {
// Functions go here
// ...
}
</code>

=== Mandatory functions ===

Your enrolment plugin class is required to define these two functions, which print and process a configuration form.

<code php>
/**
* Prints out the configuration form for this plugin. All we need
* to provide is the form fields. The <form> tags and submit button will
* be provided for us by Moodle.
*
* @param object $formdata Equal to the global $CFG variable, or if
* process_config() returned false, the form contents
* @return void
*/
public function config_form( $formdata ){
return;
}

/**
* Process the data from the configuration form.
*
* @param object $formdata
* @return boolean True if configuration was successful, False if the user
* should be kicked back to config_form() again.
*/
public function process_config( $formdata ){
return true;
}
</code>

=== Optional functions ===

==== Automated enrolment ====

To handle automated enrolment, your function may contain a <code>setup_enrolments($user)</code> function. This will be called each time a user logs in, to allow the plugin to make any changes to their enrolments.

<code php>
/**
* OPTIONAL: Set up non-interactive enrolments for user. This is the most
* important function for non-interactive enrolment plugins (such as LDAP
* and external database). It is called each time a user logs in.
*
* @param object $user
* @return void
*/
public function setup_enrolments( $user ){
// Note that when you're setting up role assignments, you should use the
// mdl_role_assignment.enrol column to indicate which role assignments
// are from this plugin.
role_assign($someroleid, $user->id, null, $somecontextid, 0, 0, 0, 'PLUGINNAME');
role_unassign($someroleid, $user->id, null, $somecontextid, 'PLUGINNAME');

return;
}
</code>

==== Interactive enrolment ====

Your plugin can handle interactive enrolment (i.e. self-enrolment) by implementing these four functions. (See the manual enrolment plugin <code>enrol/manual/enrol.php</code> for an example that uses all of these.)

<code php>
/**
* OPTIONAL: Prints the entry form/page for interactive enrolment into a course.
*
* This is only called from course/enrol.php. Most plugins will probably
* override this to print payment forms, etc, or even just a notice to say
* that manual enrollment is disabled.
*
* @param object $course
* @return void
*/
public function print_entry(){
}

/**
* OPTIONAL: The other half to print_entry(), this checks the form data.
*
* This function checks that the user has completed the task on the enrollment
* entry page and enrolls them.
*
* @param object $form
* @param object $course
* @return void
*/
public function check_entry( $form, $course ){
// some logic
// some role_assign();
}

/**
* OPTIONAL: Check if the given enrolment key matches a group enrolment key for
* the given course.
*
* @param int $courseid
* @param string $enrolmentkey
* @return mixed The group id of the group which the key matches, or false
* if it matches none
*/
public function check_group_entry( $courseid, $password ){
// some logic
if ( $itlooksgood ){
return $groupid;
} else {
return false;
}
}

/**
* OPTIONAL: Return a string with icons that give enrolment information
* for this course.
*
* @param object $course
* @return string
*/
public function get_access_icons( $course ){
return 'put icons here';
}
</code>

==== Cron ====

Your plugin can perform cron tasks if it contains a <code>cron()</code> function:

<code php>
/**
* OPTIONAL: If this function exists, it will be called each time
* admin/cron.php runs. It takes no arguments and returns no values,
* but anything written to $this->log will be printed to the cron output.
*
* @return void
*/
public function cron(){
$this->log = 'Print this in the cron log!';
}
</code>

=== Language Strings ===

Create a lang directory and file under your plugin's directory, like this '''<code>enrol/PLUGINNAME/lang/en_utf8/enrol_PLUGINNAME.php</code>'''. Plugins are expected to provide at least these two strings:

<code php><?php

// The name of your plugin. Displayed on admin menus.
$string['enrolname'] = 'My plugin';

// Description of your plugin. Shown on the plugin's configuration screen.
$string['description'] = 'This is what my plugin does.';

?></code>

Those two strings will be accessed automatically by Moodle in various situations. You can (and should) of course include other [[Development:Places to search for lang strings|language strings]] in your plugin's lang file(s). These can be accessed like normal language strings, using "enrol_PLUGINNAME" as the module name, e.g. <code>get_string('anotherstring', 'enrol_PLUGINNAME')</code>.

=== Database ===

If your plugin needs to have its own Moodle database tables, create a file called <code>enrol/PLUGINNAME/version.php</code> like this:

<code php><?php
$plugin->version = 2010091600; // Version of your plugin
$plugin->requires = 2007101000; // Required Moodle version (from /version.php)
?></code>

Then create a directory <code>enrol/PLUGINNAME/db</code>, and use the [[XMLDB editor]] to set up your tables.

==Testing paypal using the paypal developer sandbox==

=== For moodle 1.4 - 1.8 ===

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* change the address being used to send data to paypal to use the sandbox. in enrol/paypal/enrol.html:
** change the form post action to be https://www.sandbox.paypal.com/cgi-bin/webscr instead of https://www.paypal.com/cgi-bin/webscr
* change the address that is used to check the acknowledgment from paypal. in enrol/paypal/ipn.php, change:
** $fp = fsockopen ('www.paypal.com', 80, $errno, $errstr, 30);
* to
** $fp = fsockopen ('www.sandbox.paypal.com', 80, $errno, $errstr, 30);
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.

=== For moodle 1.8.2 - 1.9.x ===

The above changes to the code were made part of the release starting with version 1.8.2

If you follow these steps, you can test paypal payments using the paypal developer sandbox instead of the real paypal site. No money is actually charged to any account. All other actions are the same as if you were using the real paypal site.
* create a paypal developer account at https://developer.paypal.com/cgi-bin/devscr?cmd=_home
* create a couple of user accounts in the paypal sandbox and test enrolling in a course that requires payment (note that you need to be logged into the paypal sandbox while doing this testing)
* under the "business" sandbox account you created, log in, go to "Profile", "Instant Payment Notification", and enter the full web-visible HTTPS URL to ../enrol/paypal/ipn.php. Failing to do this is a common mistake, and the cause of most headaches with this plugin.
* add the following line to config.php located in the root directory of your installation (where you installed Moodle).
** $CFG->usepaypalsandbox = 'TRUE';
* Add the business account email address from "business" account you created to the paypal module settings (in 1.9.x - Site Administration>Courses>Enrolments>Paypal>Edit)
* You should be ready to test
* When finished be sure to remove the line that was added to config.php in your root directory.

=== Note about Paypal Sandbox ===

Only implement these changes if the above is not working and Moodle is returning the "...Unfortunately your payment..." message after returning from Paypal Sandbox.

At the time of this writing (14 June 2008) some changes are necessary to test successfully in the Paypal Sandbox. Details can be found [http://www.pdncommunity.com/pdn/board/message?board.id=sandbox&view=by_date_ascending&message.id=9802#M9802 here]. This could change at any time at which point this may become unnecessary. For now do the following (only tested in 1.9.x so far):

* Locate ipn.php in your installation on your server by migrating to to ../enrol/paypal/ipn.php
* Create a backup copy of ipn.php and give it a name something like ipn.php-backup
* Return to ipn.php and locate the following code : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 80, $errno, $errstr, 30);
* Change that code to : 
$header = ''; 
$header .= "POST /cgi-bin/webscr HTTP/1.0\r\n"; 
$header .= "Content-Type: application/x-www-form-urlencoded\r\n"; 
$header .= "Content-Length: " . strlen($req) . "\r\n\r\n"; 
$paypaladdr = empty($CFG->usepaypalsandbox) ? 'www.paypal.com' : 'ssl://www.sandbox.paypal.com'; 
$fp = fsockopen ($paypaladdr, 443, $errno, $errstr, 30); 
* Try the course purchase again.

If the above still is not working you will need to seek help in the [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] Forum.

==Enrolment plugins 1.7==

===Background===
# isteacher(), isstudent(), isadmin(), iscoursecreator() are all deprecated and should be replaced with checks on has_capability instead.
# enrol_student() and add_teacher() are obsolete, so use the generic role_assign() or the convenience function for "students" called enrol_into_course() instead.
# unenrol_student() and remove_teacher() are obsolete, so use the generic role_unassign() instead.
# All the roles have a "shortname", so by default we can refer to them using "teacher", "student", "editingteacher" etc. Note that new roles may have different names. Enrolment plugins can use these to map outside data onto the inside roles without needing to know internal role id numbers. For example, it would be really handy for the flatfile plugin to refer to roles directly like this.
# Each plugin used to implement get_student_courses() and get_teacher_courses() for use at login time. These now need to be converted to one new function called $enrol->setup_enrolments($user) which looks up sets all enrolments for a given user (using role_assign and role_unassign).
# All the session arrays like $USER->student[] and $USER->teacher[] are gone and should not be relied on. You can check what roles a user already has by calling get_user_roles() on that course context.

===What's been done===

#enrol/manual has been converted to use the new functions
#enrol/imsenterprise has been converted - testing needed though

===What still needs to be done===

#enrol/authorize
#enrol/database
#enrol/flatfile
#enrol/ldap
#enrol/paypal

==See also==
*[[Enrolment plugins|Enrolment plugins (administrator)]]
*Using Moodle [http://moodle.org/mod/forum/view.php?id=2981 Enrolment Plugins] forum

[[Category:Developer|Enrolment plugins]]
[[Category:Enrolment]]

Installing Oracle for PHP

2010-06-11T17:23:53Z

Mattgibson: /* Install Oracle */

* http://www.oracle.com/technology/pub/notes/technote_php_instant.html
* http://moodle.org/mod/forum/discuss.php?d=65488#p308002 (with attached html document)
* http://es.php.net/oci8

----

'''Important Note:''' Don't forget to enable this variable in your php.ini (or .htaccess) file:

(else, all your data will be escaped following MySQL rules, that are incorrect for Oracle)

magic_quotes_sybase = On

== Broken versions of OCI8 driver ==

PHP v5.2.4 (and perhaps v5.2.3 as well) have shipped with a bug in the OCI8 driver that leaks statement handles. The version of the OCI8 driver with the bug is v1.2.4. Possible workarounds:

* Upgrade to PHP v5.2.5 or later
* Downgrade to PHP v5.2.1 (reported to work)
* Downgrade only the oci8 driver to the one included in PHP 5.2.1 (it worked for us -- iarenaza)
* If you are on linux and/or can compile PECL extensions, install an older OCI8 driver (v1.2.3 seems to work) from the PECL repository http://pecl.php.net/package/oci8

More information at
* http://bugs.php.net/bug.php?id=42496 -- tracking the PHP OCI8 bug
* http://tracker.moodle.org/browse/MDL-11429 -- diagnostics on the Moodle side

== Installing Moodle on Windows with Oracle Express Edition ==

=== Introduction ===
This section explains how to install Moodle with Oracle Express Edition on Windows. I'm using it for '''debugging''' purpose. It's definitively not a production environment. The goal is to setup easily and quickly a Moodle/Windows/Oracle environment.

=== Install Oracle ===
Download Oracle Express Edition on [http://www.oracle.com/technology/products/database/xe/index.html Oracle web site]. 
You will also need the Instant client [http://www.oracle.com/technology/software/tech/oci/instantclient/htdocs/winsoft.html from here] (free account sign up needed). Copy everything from the unzipped folder into apache/bin. 
Install both. 
Access to the oracle console (http://127.0.0.1:8080/apex). Login: SYS Password: the_one_you_entered_during_the_installation 
Create a new user and give it all rights (including DBA). 
Note: Oracle Express Edition 10g is limited at one database called 'XE'.

=== Set up your oracle extension ===
This document does not explain how to setup apache/php for Oracle. You can have more information on [http://www.oracle.com/technology/tech/php/htdocs/php-oracle-tutorial.html Oracle Documentation]. On my own machine I used my WAMP installation ([http://www.en.wampserver.com/ Wampserver 2.0]) which allowed me to activate all oracle extensions in few clicks (php_oci8, php_oracle, php_pdo_oci, php_pdo_oci8).

=== Install Moodle ===
On the database setup page: 
Driver: Oracle oci8 
Host: empty the field 
Database: //localhost:1521/XE 
User: the user that you created 
Password: the password you gave to the user 

== Related links ==
* [http://lewiscarr.co.uk/node/4 Installing ORACLE drivers with PHP]
*[[Installing MSSQL for PHP]]
*[[PHP]]
*[http://moodle.org/mod/forum/discuss.php?d=134729#p588963 Can i install Moodle with Oracle database]
*[http://moodle.org/mod/forum/discuss.php?d=65488 Who uses Oracle]
*[https://docs.moodle.org/en/Step-by-step_Install_Guide_for_Solaris_10_with_Oracle_10 Step by step Install Guide for Solaris 10 with Oracle 10]
*[http://learningischange.com/2009/05/29/install-moodle-on-an-oracle-database-in-25-minutes-or-less/ Install Moodle on an Oracle Database (in 25 minutes or less)]

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Installing Oracle for PHP

2010-06-11T16:48:30Z

Mattgibson: /* Install Oracle */

* http://www.oracle.com/technology/pub/notes/technote_php_instant.html
* http://moodle.org/mod/forum/discuss.php?d=65488#p308002 (with attached html document)
* http://es.php.net/oci8

----

'''Important Note:''' Don't forget to enable this variable in your php.ini (or .htaccess) file:

(else, all your data will be escaped following MySQL rules, that are incorrect for Oracle)

magic_quotes_sybase = On

== Broken versions of OCI8 driver ==

PHP v5.2.4 (and perhaps v5.2.3 as well) have shipped with a bug in the OCI8 driver that leaks statement handles. The version of the OCI8 driver with the bug is v1.2.4. Possible workarounds:

* Upgrade to PHP v5.2.5 or later
* Downgrade to PHP v5.2.1 (reported to work)
* Downgrade only the oci8 driver to the one included in PHP 5.2.1 (it worked for us -- iarenaza)
* If you are on linux and/or can compile PECL extensions, install an older OCI8 driver (v1.2.3 seems to work) from the PECL repository http://pecl.php.net/package/oci8

More information at
* http://bugs.php.net/bug.php?id=42496 -- tracking the PHP OCI8 bug
* http://tracker.moodle.org/browse/MDL-11429 -- diagnostics on the Moodle side

== Installing Moodle on Windows with Oracle Express Edition ==

=== Introduction ===
This section explains how to install Moodle with Oracle Express Edition on Windows. I'm using it for '''debugging''' purpose. It's definitively not a production environment. The goal is to setup easily and quickly a Moodle/Windows/Oracle environment.

=== Install Oracle ===
Download Oracle Express Edition on [http://www.oracle.com/technology/products/database/xe/index.html Oracle web site]. 
If on windows, you will also need the Instant client [http://www.oracle.com/technology/software/tech/oci/instantclient/htdocs/winsoft.html from here] (free account sign up needed) 
Install both. 
Access to the oracle console (http://127.0.0.1:8080/apex). Login: SYS Password: the_one_you_entered_during_the_installation 
Create a new user and give it all rights (including DBA). 
Note: Oracle Express Edition 10g is limited at one database called 'XE'.

=== Set up your oracle extension ===
This document does not explain how to setup apache/php for Oracle. You can have more information on [http://www.oracle.com/technology/tech/php/htdocs/php-oracle-tutorial.html Oracle Documentation]. On my own machine I used my WAMP installation ([http://www.en.wampserver.com/ Wampserver 2.0]) which allowed me to activate all oracle extensions in few clicks (php_oci8, php_oracle, php_pdo_oci, php_pdo_oci8).

=== Install Moodle ===
On the database setup page: 
Driver: Oracle oci8 
Host: empty the field 
Database: //localhost:1521/XE 
User: the user that you created 
Password: the password you gave to the user 

== Related links ==
* [http://lewiscarr.co.uk/node/4 Installing ORACLE drivers with PHP]
*[[Installing MSSQL for PHP]]
*[[PHP]]
*[http://moodle.org/mod/forum/discuss.php?d=134729#p588963 Can i install Moodle with Oracle database]
*[http://moodle.org/mod/forum/discuss.php?d=65488 Who uses Oracle]
*[https://docs.moodle.org/en/Step-by-step_Install_Guide_for_Solaris_10_with_Oracle_10 Step by step Install Guide for Solaris 10 with Oracle 10]
*[http://learningischange.com/2009/05/29/install-moodle-on-an-oracle-database-in-25-minutes-or-less/ Install Moodle on an Oracle Database (in 25 minutes or less)]

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Installing Oracle for PHP

2010-06-11T16:47:33Z

Mattgibson: /* Install Oracle */

* http://www.oracle.com/technology/pub/notes/technote_php_instant.html
* http://moodle.org/mod/forum/discuss.php?d=65488#p308002 (with attached html document)
* http://es.php.net/oci8

----

'''Important Note:''' Don't forget to enable this variable in your php.ini (or .htaccess) file:

(else, all your data will be escaped following MySQL rules, that are incorrect for Oracle)

magic_quotes_sybase = On

== Broken versions of OCI8 driver ==

PHP v5.2.4 (and perhaps v5.2.3 as well) have shipped with a bug in the OCI8 driver that leaks statement handles. The version of the OCI8 driver with the bug is v1.2.4. Possible workarounds:

* Upgrade to PHP v5.2.5 or later
* Downgrade to PHP v5.2.1 (reported to work)
* Downgrade only the oci8 driver to the one included in PHP 5.2.1 (it worked for us -- iarenaza)
* If you are on linux and/or can compile PECL extensions, install an older OCI8 driver (v1.2.3 seems to work) from the PECL repository http://pecl.php.net/package/oci8

More information at
* http://bugs.php.net/bug.php?id=42496 -- tracking the PHP OCI8 bug
* http://tracker.moodle.org/browse/MDL-11429 -- diagnostics on the Moodle side

== Installing Moodle on Windows with Oracle Express Edition ==

=== Introduction ===
This section explains how to install Moodle with Oracle Express Edition on Windows. I'm using it for '''debugging''' purpose. It's definitively not a production environment. The goal is to setup easily and quickly a Moodle/Windows/Oracle environment.

=== Install Oracle ===
Download Oracle Express Edition on [http://www.oracle.com/technology/products/database/xe/index.html Oracle web site]. 
Install it. 
If on windows, you will also need the Instant client [http://www.oracle.com/technology/software/tech/oci/instantclient/htdocs/winsoft.html from here] (free account sign up needed)
Access to the oracle console (http://127.0.0.1:8080/apex). Login: SYS Password: the_one_you_entered_during_the_installation 
Create a new user and give it all rights (including DBA). 
Note: Oracle Express Edition 10g is limited at one database called 'XE'.

=== Set up your oracle extension ===
This document does not explain how to setup apache/php for Oracle. You can have more information on [http://www.oracle.com/technology/tech/php/htdocs/php-oracle-tutorial.html Oracle Documentation]. On my own machine I used my WAMP installation ([http://www.en.wampserver.com/ Wampserver 2.0]) which allowed me to activate all oracle extensions in few clicks (php_oci8, php_oracle, php_pdo_oci, php_pdo_oci8).

=== Install Moodle ===
On the database setup page: 
Driver: Oracle oci8 
Host: empty the field 
Database: //localhost:1521/XE 
User: the user that you created 
Password: the password you gave to the user 

== Related links ==
* [http://lewiscarr.co.uk/node/4 Installing ORACLE drivers with PHP]
*[[Installing MSSQL for PHP]]
*[[PHP]]
*[http://moodle.org/mod/forum/discuss.php?d=134729#p588963 Can i install Moodle with Oracle database]
*[http://moodle.org/mod/forum/discuss.php?d=65488 Who uses Oracle]
*[https://docs.moodle.org/en/Step-by-step_Install_Guide_for_Solaris_10_with_Oracle_10 Step by step Install Guide for Solaris 10 with Oracle 10]
*[http://learningischange.com/2009/05/29/install-moodle-on-an-oracle-database-in-25-minutes-or-less/ Install Moodle on an Oracle Database (in 25 minutes or less)]

[[Category:Installation]]
[[Category:Developer]]
[[Category:XMLDB]]
[[Category:DB]]

Setting up Netbeans

2010-06-06T19:53:04Z

Mattgibson: /* Checkout of contrib code */ Added symlink tip

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[Development:CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will ned to use the internal SSH and your password (which you can choose to save).

If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

Note that the last three points may cause you some grief when attempting to commit changes. CVS doesn't seem to like having subfolders with different origins. A workaround that operates well for me is to check out the contrib code manually into a folder using the command line as specified in the CVS for developers instructions, then import that code as a new project with existing sources. This allows easy commits and updates, whilst keeping it separate. You can then make a symlink from you main Moodle project to your contrib directory, restart NetBeans (the CVS info and symlink stuff is only refreshed on restart) and then right click the linked directory and choose 'Ignore', then do the same and choose 'Exclude from commit'. You can now use the code as if it were part of Moodle, still getting all the code completion stuff, and also do clean updates and commits from the secondary project. [[User:Matt Gibson|Matt Gibson]] 19:53, 6 June 2010 (UTC)

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)


Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)


== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer|NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2010-06-05T13:21:25Z

Mattgibson: /* Checkout for developers with write access */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[Development:CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

As far as I can tell, there is no way to get NetBeans to work with CVS keys on Mac/Linux via the system SSH binary, so you will ned to use the internal SSH and your password (which you can choose to save).

If you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)


Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)


== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer|NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2010-06-05T13:17:31Z

Mattgibson: /* Checkout for developers with write access */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[Development:CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

====Checkout of main Moodle codebase====

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

====Checkout of contrib code====

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'. Note that you should not try to specify the full contrib repository path yet.
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)


Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)


== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer|NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2010-06-05T13:14:30Z

Mattgibson: /* Checkout for developers with write access */

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[Development:CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org:/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)


Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)


== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer|NetBeans]]
[[Category:Developer tools|NetBeans]]

Ajax marking block

2010-05-29T13:06:55Z

Mattgibson: fixed download link so it doesn't point to head anymore

The [http://moodle.org/mod/data/view.php?d=13&rid=1459 AJAX marking block] allows you to view and complete all of your marking without leaving the page you are on. It displays all the ungraded work you need to mark in a tree structure of all of the courses you teach in, along with a count of how many items there are for each course & assessment item.
[[Image:Ajax_marking.png|right]]
====Keep track of what you have graded so far====
When the tree nodes are expanded and a student's name is clicked, a pop-up opens with the work to be graded. Once 'Submit' has been clicked in that window, the pop-up closes and tree updates itself by removing the student's node and altering its total count.

====Instantly update without leaving the page====
The [[AJAX]] bit means that every time you click on the nodes to expand them, the data for the child nodes is fetched in the background without refreshing the whole page. This saves on loading the whole lot at the start, which could be time consuming. Clicking 'Collapse and refresh' will re-load the whole tree, with an updated count of your marking including anything that was submitted a second or two ago, and excluding any that were marked by someone else and now don't need your attention.

====Only show grading for your own teaching groups====
Some sites run training courses that don't need grading, or a single course with many teachers and teaching groups following the same programme of study. You can easily choose to hide the work that is not your using the '''configure''' link, which will open a pop up allowing you to show or hide each item individually, or choose to show only the work of some groups, so you only ever see the work that you actually need to mark.

==Installation==
Download the zip file [http://moodle.org/mod/data/view.php?d=13&rid=1459&filter=1 here]. Copy it to your /blocks/ folder and unzip it there. Then, go to the notifications screen (Front page -> administration block -> notifications) where you should see a message about the tables having been set up correctly.

==Roles and permissions==
Note that you will not get anything displayed at all unless you have a teacher role in a course. This course will also need to be one that has gradable items like assignments or forums with ratings, or you will get an error saying that you have no graded assessments yet.

If you want to see all of the items in all of the courses across the site, add yourself as a teacher under Front page Admin block -> users -> permissions -> assign site wide roles

A fix so that admins see everything without doing this is on the way (CONTRIB-1017)

===Configuring the display of each individual assessment item===
The block can be set to show or hide each individual assessment item, or show only the assessments by students in certain groups. Clicking on '''configure''' will bring up an additional tree, which shows all of your courses and names of all the assessment items. When you click on one of the assessments, you will be faced with a number of options on the right:
* Show - the default state, where you will see all students' work
* Show by group - a set of checkboxes will appear with the names of the current groups for that course. You choose which you want to see and group nodes will then be shown between the assessment and student nodes in the main block. The nodes for that assessment will then look like this: '''Course -> Assessment -> Group -> Submission'''
* Hide - do not display any submissions for this assessment item.

The counting of unmarked submissions respects these choices and they are specific to the user who created them. If you are an admin and wish to set the preferences for others, use the 'login as' function to do so.

==Supported types==
* Assignment
* Forum (only if ratings are on)
* Workshop
* Journal
* Quiz (essay questions only)

==See also==
[[Development:AJAX marking block]]

[[Category:Contributed code]]
[[Category:Teacher]]
[[Category:Administrator]]

Migrating contrib code to 2.0

2010-05-18T16:25:02Z

Mattgibson:

{{Moodle 2.0}}

WARNING: Under construction RIGHT NOW!

The goal of this page is to provide a checklist of tasks to be considered to upgrade CONTRIB code to Moodle 2.0. Several significant changes have taken place including the File API, DB Layer, Navigation, Output renderer, etc. It would be good if we had a list that contributors could follow to help move them toward being able to migrate the code. Any help in building up this list is greatly appreciated.

''Please add useful links...''

* [[Development:DB_layer_2.0_migration_docs]]
* [[Development:Using the File API in Moodle forms]]
* [[Development:Output_renderers]]
* [[Development:Migrating_your_code_to_the_2.0_rendering_API]] (n.b., some info outdated and may need updating)
* [[Development:Themes_2.0]]

Some details of how to re-design image CSS for plugin code ar in the main themes documentation: [[Development:Themes_2.0_creating_your_first_theme#Using_images_within_CSS]]

Be aware that themes are now cached on the server and so emptying your browser cache will not refresh the CSS. This can only be done by going to the site administration->appearance->themes->theme selector page and clicking the 'invalidate theme caches' button.

Javascript is included in different ways now and will need to be migrated, see the PHPDoc comments in /lib/outputrequirements.lib and some (slightly outdated) advice here: [[Development:JavaScript_guidelines]]

==See also==

* CONTRIB-1988
* http://cvs.moodle.org/moodle/blocks/upgrade.txt?view=markup
* http://cvs.moodle.org/moodle/mod/upgrade.txt?view=markup

[[Category:Developer]]

Migrating contrib code to 2.0

2010-05-18T16:22:11Z

Mattgibson:

{{Moodle 2.0}}

WARNING: Under construction RIGHT NOW!

The goal of this page is to provide a checklist of tasks to be considered to upgrade CONTRIB code to Moodle 2.0. Several significant changes have taken place including the File API, DB Layer, Navigation, Output renderer, etc. It would be good if we had a list that contributors could follow to help move them toward being able to migrate the code. Any help in building up this list is greatly appreciated.

''Please add useful links...''

* [[Development:DB_layer_2.0_migration_docs]]
* [[Development:Using the File API in Moodle forms]]
* [[Development:Output_renderers]]
* [[Development:Migrating_your_code_to_the_2.0_rendering_API]] (n.b., some info outdated and may need updating)
* [[Development:Themes_2.0]]

Some details of how to re-design image CSS for plugin code ar in the main themes documentation: [[Development:Themes_2.0_creating_your_first_theme#Using_images_within_CSS]]

Javascript is included in different ways now and will need to be migrated, see the PHPDoc comments in /lib/outputrequirements.lib and some (slightly outdated) advice here: [[Development:JavaScript_guidelines]]

==See also==

* CONTRIB-1988
* http://cvs.moodle.org/moodle/blocks/upgrade.txt?view=markup
* http://cvs.moodle.org/moodle/mod/upgrade.txt?view=markup

[[Category:Developer]]

DB layer 2.0 migration docs

2010-05-03T21:21:49Z

Mattgibson: /* The golden changes */ Added note on how to combine G6 and G7

{{Template:Development:dmllib 2.0}}{{Moodle_2.0}}
== Introduction ==
Much of the following documentation will not make much sense unless you first read [[Development:XMLDB_Documentation|the XMLDB documentation]]. Please read it first if you would like to join the effort to convert Moodle's code to the new dmllib.

Also, it's recommended to read the whole [[wikipedia:Data_Definition_Language|DDL]] and [[wikipedia:Data_Manipulation_Language|DML]] documentation before start with the migration. That will allow you to have some initial knowledge about the new architecture.

This article defines all the changes that need to be performed in Moodle 1.9 code in order to make it run properly under new Moodle 2.0 DB layer. Changes below are grouped into 2 main blocks ([[Development:XMLDB_Documentation|xmldb]] and [[wikipedia:Data_Manipulation_Language|dml]]) to have them organised. Additional minor changes may be required in the [[wikipedia:Data_Definition_Language|ddl]] code, but won't be documented here.

Although the order of changes showed in this page isn't mandatory at all, it can be interesting to follow it in the migration progress to be able to understand and learn a bit more about all them. That way, you'll end up knowing not only what to change but how and why those changes are required.

Each change will be as simple as possible, representing one easy rule to follow to adapt the code. When anything become too complex to be explained as one simple rule, it will contain one link to the [[Development:dmllib_2.0_examples|examples page]].

For any problem in the migration of code, it's recommended to use the [http://moodle.org/mod/forum/view.php?id=45 Databases forum] at [http://moodle.org moodle.org]. Also if you find any bug in the process, please report it in the [http://tracker.moodle.org/browse/MDL-14679 Moodle Tracker], that way developers will be able to fix it ASAP.

The Glossary module was used as the basis for many of the examples below.

And finally, feel free to complete/fix the list below with the changes you find in the progress of migration, that will certainly help many developers. Thanks!

__TOC__

== check_db_syntax: One helper script ==

Before start migrating your code to Moodle 2.0, it's recommended to install and run the [http://cvs.moodle.org/contrib/tools/check_db_syntax/ check_db_syntax.php] script. Simply copy it to the main folder of your plugin and execute it (from command line or via web). I'll show you the list of old DB usages that need to be transformed following the information below in this article.

If you think that something is missing in the script or have any idea to improve it, feel free to do that yourself, commenting about it in MDL-15237. Thanks!

Also, this (perl-compatible - works in Eclipse, hopefully elsewhere) regex:

(?<!->)(?<!function )(?<!\$)\b(?:(?:count|delete|get|insert|udpate)_record(?!s_csv)|[gs]et_field|record_exists|execute_sql)|\$CFG->prefix|rs_(?:fetch|close)|addslashes(?!_js)

Will find most of the things in your code that need attention, with few false positives.

== XMLDB/DDL changes ==

=== Some comments ===

* When changing DB structures it's highly recommended to use the [[XMLDB editor|XMLDB Editor]] (Admin->Development->XMLDB Editor). It is a safe way to edit install.xml files and to get correct PHP code to be used in upgrade.php scripts.
* If you have some doubts about the list of changes below, it's highly recommended to take a look at some code in core modules, blocks... whatever you need. They are a good reference.
* The most noticeable change (from a migration perspective) in the DDL stuff is that, starting with Moodle 2.0, we have decided to '''drop support for enum (check constraint) fields completely'''. See MDL-18577 and [http://moodle.org/mod/forum/discuss.php?d=118852 this discussion]. That implies changes in different parts of the DB stuff (xml files, function parameters, dropping existing enums...) and are commented with more detail below.

=== The changes ===

* No changes are required in install.xml files at all (that's good news!). Although you must know these:
** The '''ENUM''' and '''ENUMVALUES''' attributes present in your install.xml files will be completely ignored both by the DLL generation stuff and by the XMLDB Editor.
** In Moodle 2.1, those attributes ('''ENUM''' and '''ENUMVALUES''') will be 100% forbidden, so it's highly recommended to erase them since now (Moodle 2.0).
** The XMLDB Editor will detect them when loading any install.xml file and will suggest you to fix that easily with one 1-click® option.
** No matter if you have fixed that with the 1-click® option when loading the files... the [[XMLDB editor|XMLDB Editor]] will save any edited install.xml files without those attributes.
** If your Moodle 1.9.x code '''has some enum defined in the database''', you will need to create one upgrade block (in db/upgrade.php) to drop it (the enum, not the field! ;-) as part of the migration from Moodle 1.9 to 2.0 by using the new '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' method.
** Of course, if you don't use/like the XMLDB Editor, you can erase them manually with something like this:
perl -p -e 's/ENUM(VALUES)?=".*?" //g' < install.xml > install.xml.new

* All upgrade.php scripts, within the main xxxx_upgrade function must have '''$DB''' (uppercase) in the globals declaration (along with others if needed). Example (from glossary module):
<code php>
function xmldb_glossary_upgrade($oldversion=0) {

global $CFG, $THEME, $DB;
</code>
* All upgrade.php scripts, must NOT have '''$db''' (lowercase) in the globals declaration. Delete it if present.
* After the global declaration in the points above, this line must be present (we'll need it later):
<code php>
$dbman = $DB->get_manager(); /// loads ddl manager and xmldb classes
</code>
* All '''XMLDBTable''' instances in your upgrade code must be replaced by '''xmldb_table''' (no change in parameters)
* All '''XMLDBField''' instances in your upgrade code must be replaced by '''xmldb_field''' (with change in params, both enum and enumvalues are out from function declaration!)
* All '''XMLDBIndex''' instances in your upgrade code must be replaced by '''xmldb_index''' (no change in parameters)
* All '''XMLDBKey''' instances in your upgrade code must be replaced by '''xmldb_key''' (no change in parameters)
* All the '''addFieldInfo()''' methods must be replaced by '''add_field()''' (with change in params, both enum and enumvalues are out from function declaration!)
* All the '''addIndexInfo()''' methods must be replaced by '''add_index()''' (no change in parameters)
* All the '''addKeyInfo()''' methods must be replaced by '''add_key()''' (no change in parameters)
* All the '''setAttributes()''' methods must be replaced by '''set_attributes()''' (with change in params, both enum and enumvalues are out from function declaration!)
* All the DDL functions used in upgrade code, must be transformed as detailed below (it's only about to add '''"$dbman->"''' - without the quotes - before each function call). No changes in parameters are required:
** table_exists ==> $dbman->table_exists
** field_exists ==> $dbman->field_exists
** index_exists ==> $dbman->index_exists
** find_index_name ==> $dbman->find_index_name
** find_check_constraint_name ==> $dbman->find_check_constraint_name ('''DEPRECATED in 2.0. OUT in 2.1''')
** check_constraint_exists ==> $dbman->check_constraint_exists ('''DEPRECATED in 2.0. OUT in 2.1''')
** find_sequence_name ==> '''OUT in 2.0''', see MDL-20349
** create_table ==> $dbman->create_table
** drop_table ==> $dbman->drop_table
** rename_table ==> $dbman->rename_table
** add_field ==> $dbman->add_field
** drop_field ==> $dbman->drop field
** rename_field ==> $dbman->rename_field
** change_field_type ==> $dbman->change_field_type
** change_field_precision => $dbman->change_field_precision
** change_field_unsigned ==> $dbman->change_field_unsigned
** change_field_notnull ==> $dbman->change_field_notnull
** change_field_enum ==> $dbman->change_field_enum ('''OUT in 2.0''', see '''[[Development:DB layer 2.0 examples#Dropping one enum from one field|drop_enum_from_field()]]''' to get rid of remaining ENUMs in code).
** change_field_default ==> $dbman->change_field_default
** add_key ==> $dbman->add_key
** drop_key ==> $dbman->drop_key
** add_index ==> $dbman->add_index
** drop_index ==> $dbman->drop_index
* Finally, and not less important, your code (module, block... plugin) must guarantee that it can be upgraded '''ONLY''' from Moodle 1.9, so any previous upgrade code can be safely deleted. '''Moodle 2.0 requires Moodle 1.9''' to be upgraded, so everybody will run the 1.9 => 2.0 upgrade (with other paths like 1.8 => 2.0 not being possible). One good time to clean-up a bit your upgrade code ;-). Don't forget to take a look to the [[XMLDB editor|XMLDB Editor]] and to core modules to see how [http://cvs.moodle.org/moodle/lib/db/upgrade.php?view=markup upgrade.php] files look like in Moodle 2.0.

== DML changes ==

=== Some comments ===
* The ENTIRE CODEBASE requires an update of ALL database query function calls. Expect most moodle files to be affected by this change.

* This is the more complex part to migrate to have the code working under Moodle 2.0, not because of the complexity of the changes themselves (90% of them will be really easy), but because you'll need to triple-check everything works as expected after changes.

* Along the changes below, you'll find links to some examples that will try to make things easier. Anyway, if you are blocked at any point, please ask in forums or tracker (see links at the beginning of the page). Sure it has a good enough solution.

* Once more it's highly recommended to take a look to Moodle core code, searching for similar examples. Of course, new meaningful examples are welcome, and also any clarification in the list of changes below. Feel free to do it, this is a wiki!

* Finally, one more explanation: The changes below have been split into three sections. First one, (called '''"The golden changes"''') are modifications that must be applied to ALL the transformations defined in the second section ('''"The iron changes"'''). Sure you'll understand that after reading them (it's basically a matter of not repeating the golden ones within each iron one, just imagine they are everywhere). Finally other changes details can be found in the '''"The tin changes"''' section.

=== The golden changes ===
''PLEASE read the API before going crazy with search & replace''! You can find all the new methods in lib/dml/moodle_database.php. This is essential because some method signatures have changed (params are different), and some method names have even changed (execute_sql() is now execute()).

Each of the golden changes below is given one short name (G1, G2, G3...) for further reference in the rest of the documentation. Let's go:

* G1: Wherever old functions are used (get_record*, get_field*, set_field, insert_record, update_record, count_records*, delete_records, record_exists), the global $DB must be used as the object on which these functions are called (e.g. get_record_select() becomes $DB->get_record_select()).
<code php>
Example:

// Old syntax
$sql = "WHERE id = 1";
get_record_select($sql);

// New syntax
global $DB;
$sql = "WHERE id = 1";
$DB->get_record_select($sql);
</code>
::Note: for some functions, the $params array is not the second function parameter. For example, set_field:'''
<code php>
// Old syntax
set_field('user', 'firstname', 'Peter', 'id', 1);

// New syntax
global $DB;
$DB->set_field('user', 'firstname', 'Peter', array('id' => 1));
</code>

* G2: All uses of addslashes() '''must be removed'''. They are no longer needed

* G3: All the functions that used to accept a list of string params in the form "param1, value1, param2, value2" now need to be given an array of key=>value pairs as a replacement for these params. Other params remain as before. Check the new API for any exceptions.
<code php>
Example:

// Old syntax:
$user = get_record("user", "firstname", "Peter", "lastname", "Cantrophus");

// New syntax:
global $DB;
$conditions = array("firstname" => "Peter", "lastname" => "Cantrophus");
$user = $DB->get_record("user", $conditions);
</code>
::Note: The example above has been written out in full for clarity. You can use the array() directly within the function call, without using a temporary variable, if you prefer:''
<code php>
global $DB;
$user = $DB->get_record("user", array("firstname" => "Peter", "lastname" => "Cantrophus") );
</code>

* G4: rs_fetch_next_record($rs) is deprecated, in favour of the simple foreach($rs as $var). Calls to rs_close() must be replaced by $rs->close();
<code php>
Example:

// Old syntax
while($result = rs_fetch_next_record($rs)) {
...
}
rs_close();

// New syntax
foreach ($rs as $result) {
...
}
$rs->close();
</code>

* G5: Placeholders must be used for table names. Instead of {$CFG->prefix}tablename, use {tablename}.

<code php>
Example:

// Old syntax
$sql = "SELECT * FROM {$CFG->prefix}user";

// New syntax
$sql = "SELECT * FROM {user}";
</code>

* G6: When PHP variables are used in SQL queries, they must be replaced by parameters. You have the choice between two approaches: ordered parameters, or named parameters.
** Ordered parameters use a simple array of values, which are given to the DML function as $params. The values in the SQL code are simply question marks (?) replacing the values. They are replaced by the DML code one by one, substituting each question mark (?) with the next value in the $params array.
** Named parameters use an associative array of name => value pairs as the $params array. The values in the SQL code are replaced with a colon (:) followed by the key associated with the value, in the $params array.

<code php>
Examples:

// Old syntax
$sql = "SELECT id, firstname FROM {$CFG->prefix}user WHERE firstname = 'Peter' AND lastname = 'Cantrophus'";
$user = get_record_sql($sql);

// New syntax: ordered params
global $DB;
$params = array('Peter', 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = ? AND lastname = ?";
$user = $DB->get_record_sql($sql, $params);

// New syntax: named params
global $DB;
$params = array('firstname' => 'Peter', 'lastname' => 'Cantrophus');
$sql = "SELECT id, firstname FROM {user} WHERE firstname = :firstname AND lastname = :lastname";
$user = $DB->get_record_sql($sql, $params);
</code>

* G7: Replacement of the IN(...) syntax: We no longer hard-code this in our SQL queries, we use a function which determines whether the IN() syntax is needed, or, if there is only one value to compare, the equal (=) sign can be used.

<code php>
Example:

// Old syntax:
$depends_on = array(1, 43, 553);
$gis = implode(',', $depends_on);
$sql = "SELECT *
FROM {$CFG->prefix}grade_items
WHERE id IN ($gis)";
$items = $DB->get_records_sql($sql);

// new syntax
global $DB;
$depends_on = array(1, 43, 553);
list($usql, $params) = $DB->get_in_or_equal($depends_on);
$sql = "SELECT *
FROM {grade_items}
WHERE id $usql";
$items = $DB->get_records_sql($sql, $params);
</code>

'''Note:''' to combine the last two, do the G7 IN SQL stuff first to generate the params array, then do something like
$param['firstname'] = 'peter';
to add the stuff for G6

=== The iron changes ===

*I1: Originally the '''sql_substr()''' function was used without parameters and it returned only the name of the "substring" function to be used under each DB. In Moodle 2.0 and upwards, it has 3 parameters (2 being mandatory) and it returns the complete SQL text to be used when handling substrings. Note that positions in this function are 1-based (first char has index 1).

<code php>
Example:

// Old syntax
$records = get_records_sql("SELECT " . sql_substr() . "(firstname, 1, 20)" . " FROM ... ..."

// New syntax
$records = $DB->get_records_sql("SELECT " . $DB->sql_substr('firstname', 1, 20) . " FROM ... ..."
</code>

=== The tin changes ===
List of minor changes

* T1: Originally get_records() and similar functions were returning false if no records found. All these methods are now always returning arrays, empty array in case of no records found. Please note that get_record() still returns false if specified record not found.
<code php>
Example:

// Old syntax
if (!$posts = get_records('forum_posts', 'parent', 666)) {
$posts = array()
}

// New syntax
global $DB;
$posts = $DB->get_records('forum_posts', array('parent'=>666));
</code>

* T2: Originally DML functions were returning ''false'' if error occurred - ''dml_exception'' is thrown now instead.
<code php>
Example:

// Old syntax
$record = new object();
$record->course = 5;
if (!$id = insert_record('sometable', $record)) {
error('can not insert new record');
}

// New syntax
global $DB;
$record = new object();
$record->course = 5;
$id = $DB->insert_record('sometable', $record);
</code>

== See also ==

* [[Development:XMLDB Documentation|XMLDB Documentation]]: where both xmldb and ddl stuff is explained.
* [[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.
* [[Development:DDL exceptions|DDL exceptions]] - DDL exceptions information.
* [[Development:DML exceptions|DML exceptions]] - DML exceptions information.

SSH key

2010-04-25T21:13:24Z

Mattgibson: /* Mac OS X */

==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===
If you have an existing key in Putty format, open it in puttygen on windows and then choose conversions and export as openssh format. You can then import the key into OS X using
ssh-add -K filename
The -K flag is optional and stores your passphrase in the keychain [http://developer.apple.com/mac/library/documentation/Darwin/Reference/ManPages/man1/ssh-add.1.html ssh-add documentation]

SSH key

2010-04-25T21:10:48Z

Mattgibson: /* Mac OS X */

==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===
If you have an existing key in Putty format, open it in puttygen on windows and then choose conversions and export as openssh format. You can then import the key into OS X using
ssh_add -K filename
The -K flag is optional and stores your passphrase in the keychain.

Broken/Gradebook improvements

2010-03-12T21:27:24Z

Mattgibson: /* Common frustrations */ Gradebook lateness

==Aggregation of hidden grades==

Overlook problem partially solve after the database freeze - workaround was to recalculate the grades on the fly so that users that can the hidden grades are ignored. This approach is expensive and can not be used in conditional activities, grade exports, etc.

Solution is to add new flag into grade categories - aggregate hidden grades. Having two values for each grade would be too complex, selective agrragation should solve most of the problems and should be reasonably backwards compatible.

--[[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]] 11:56, 8 December 2008

==Exports: more flexibility==

Two aspects of the 1.9 export plugin have been criticised by some of Catalyst's clients:

* the fact that grade exports are tied to a course
* the default user profile columns are not all needed and some custom ones would be necessary

Therefore I propose the following changes:

* removing the export plugin dependency on a single course by converting to an array of courses (see MDL-17420)
* making the user-related columns customisable (see MDL-17346)

--[[User:Francois Marier|Francois Marier]] 06:42, 9 December 2008

==Gradebook does not consider groupings functionality==

Student in gradebook view all grade items, but must view only grade items thats belong to his groiping (see MDL-13868).

--[[User:Artem Andreev|Artem Andreev]] 11:07, 9 December 2008

==Common frustrations==
Below are some of the most often reported usability issues in the 1.9 gradebook, which we are trying to address. Several of these are grouped as sub-tasks under MDL-16913.

===Assigning weights to categories and grade items===
This is the most common frustration. Weights are used extensively in many institutions, and were used in 1.8. However, they are difficult to understand in 1.9, and difficult to set up. This issue is discussed extensively in MDL-15680.

===Moving items to categories===
Currently, the [[Edit categories and items]] page lets you move only one grade item or category at a time. It takes two page refreshes and two mouse clicks per move. This is very tedious and time-consuming when many items have to be moved around. MDL-13775 and MDL-12502 address this problem.

===Removing the ''overridden'' attribute of individual grades===
When grades are imported into an existing gradebook, or when grades are manually edited in the grader report, these grades become [[Grade_editing#Overridden|overridden]], which prevents linked activity modules from updating this grade. Removing this attribute is very time-consuming, since one must enter the edit page of each individual grade, untick the checkbox and submit the form. This issue is discussed in [http://moodle.org/mod/forum/discuss.php?d=109636 this forum thread].

===Viewing the overall contribution of each category and item to the course aggregation===
The tracker issue MDL-13777 reports the difficulty in seeing the contribution of each grade item and category to the course total. Calculations and weights may apply, which are not visible in any of the current reports except in each individual category or item's edit page.

--[[User:Nicolas Connault|Nicolas Connault]] 12:41, 4 November 2008

Some more that it would be great to see fixed:
===Setting grade to pass===
Takes a lot of clicks and the edit icon looks like it's part of the main mass of editing icons for the grades table itself, so it's hard to find. This is a very useful feature (at least once MDL-13830 is fixed) as it shows at a glance how many items a student has failed to pass. Seeing a row of red entries is a great way of quickly knowing who to target for extra attention in class. Quite obscure at the moment though, especially seeing as it cannot be done from the module itself. -[[User:Matt Gibson|Matt Gibson]] 07:36, 22 January 2009 (CST)

===Its not possible to see whether or not a student has submitted work which has not been marked===
If the modules could send a special grade e.g. -1 to the gradebook as a placeholder that could be used to add either a css class to a cell, or display a special character to show that work is waiting. Then it would be possible to use the gradebook like a normal one, in order to evaluate students' deadline-meeting for writing reports. At the moment, this is probably the biggest problem in our institution's use of the gradebook. - [[User:Matt Gibson|Matt Gibson]] 07:36, 22 January 2009 (CST)

===Impossible to tell whether work was submitted on time or late===
This is vital for K-12 teachers who are writing reports on students and really needs to be added somehow. Gradebook database changes are needed, so it must be planned as part of a major release. MDL-12111

==Patch for Edit Categories and Items page==
Following is a proposed patch to the '''Edit categories and items''' page in the 1.9 gradebook. It addresses many usability issues while remaining simple. The following features are currently implemented:

===Simple features===
[[Image:gradebook_categories_simple.png|600px]]
*Items and categories are displayed in a table instead of a list. This improves readability and will make drag and drop easier to implement.
*All advanced features are hidden by default, so that the interface by default is almost identical to the original
*An additional column has checkboxes for grade items. All selected items can then be moved to one of the existing grade categories for the current course. Javascript "Select all/Select None" links replace these checkboxes for categories, to make it faster to select or de-select items.

===Advanced features===
[[Image:gradebook_categories_advanced.png|600px]]

*[[Category aggregation|Grade category aggregation type]]: changing this reloads the page, because the grade item weights/extra credits only apply to some of these aggregation types.
*Weight or extra credit: depending on the parent category's aggregation type, each category and grade item may have an input field or a checkbox for weight or extra credit. All these can be edited, then submitted with one click.
*Grade range is displayed for information purposes, but cannot be edited through this interface (it is most often controlled by the linked activity)
*[[Grade_categories#Aggregate_only_non-empty_grades|Aggregate only non-empty grades]]
*[[Grade_categories#Aggregate_including_sub-categories|Aggregate including sub-categories]]
*[[Grade_categories#Include_outcomes_in_aggregation|Include outcomes in aggregation]]
*[[Grade_categories#Drop_the_lowest|Drop the lowest]]
*[[Grade_categories#Keep_the_highest|Keep the highest]]
*[[Grade items|Multiplicator]]
*[[Grade_items|Offset]]

All these settings can be changed then submitted with only one page reload. Just be mindful that changing a category's aggregation type will reload the page and you will lose any non-submitted changes you made to the other settings.

--[[User:Nicolas Connault|Nicolas Connault]] 12:41, 4 November 2008

==Further ideas for 2.0==

The following list is from a gradebook planning meeting on 4 September 2009 between Martin, Nicolas, Petr and Helen:
* Replace hiding as an activity setting with automatic/manual/dated transfer of grades to gradebook
* Duplicate most of the grade item settings into the mod_edit form for each activity (controlled directly by gradebook)
* Implement grading interface centrally for wiki as a test in 2.0, not other modules yet
* Workflow of raw grades in activity -> proposed/hidden grades in gradebook -> final grades released to students
What is the behaviour of hidden grades in calculated grades, exports, teacher view, student view, activity completion ...
* User overviews:
*# Overview of one user (have it now but need to review the capabilities, perhaps one overall is enough but really should check each course
*# Combine multiple gradebooks from one global group into one table of users vs courses, showing final grades for courses
* AJAX-based report to edit rows and columns at once, without reloads
* Adding more switches to turn off things (eg calculations)
* Improving documentation to make it clearer
* Gradebook tracker issues need some rationalisation, update all fix versions (perhaps move all 1.9.6 and 2.0 ones into subtasks like MDL-19131)

--[[User:Helen Foster|Helen Foster]] 11:50, 10 September 2009 (UTC)

==See also==

* [[Development:Tim's_Gradebook_thoughts|Tim's Gradebook thoughts]]

Setting up Netbeans

2010-02-26T14:56:25Z

Mattgibson: Added JIRA module bit

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* Download the latest [http://netbeans.org/community/releases/68/ 6.8 version] with PHP support, only 25 MB.
* Install and run it.

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[Development:CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Git with NetBeans ==

=== NBGit | Git Support for NetBeans ===

"NBGit is a module for the NetBeans IDE that adds support for working with the Git version control system. It uses the JGit library created as part of EGit to interact with Git repositories. Because the module is Java code all the way, it should work better cross-platform modulo platform specific differences, such as file system behavior. It is based on the NetBeans Mercurial module."
(http://nbgit.org)


Unfortunately, the key word in that quote is '''should'''. In reality, because JGit is a rewrite from scratch of the tried-and-tested git core C code, it is still buggy, incomplete and unreliable. Therefore, the NetBeans and Eclipse git plugins are still only beta quality, and pretty sucky. Well, they mostly work for browsing the contents of the repository, but there is a small chance that if you use them for update operations, they will corrupt your repository. Hence, I am still doing git from the command-line.--[[User:Tim Hunt|Tim Hunt]] 11:11, 19 January 2010 (UTC)


== Optimization ==

1. You may want to run NetBeans with the Sun JDK. NetBeans seems to work a bit better with the [http://java.sun.com/javase/downloads/index.jsp Sun JDK]. You'll have to edit NetBeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the NetBeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If NetBeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See FAQ for more [http://wiki.netbeans.org/FaqSettingHeapSize details on memory optimisation].

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

===JIRA support===
You can install the optional JIRA module in order to be able to interact with the Moodle Tracker from within netbeans. This has the advantage of avoiding constantly switching back and forth from the browser and works quite well. Go to Tools->plugins->available plugins and search for JIRA. Once installed, right click 'issue trackers' in the 'services' pane to make a new tracker instance, then enter your details.

== See also: ==
Moodle forums
* [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]

Online resources
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

Book
* [http://www.packtpub.com/netbeans-platform-6-8-developers-guide/book NetBeans Platform 6.8 Developer's Guide] by Jürgen Petri (March 2010), focus on Java and Swing

[[Category:Developer|NetBeans]]
[[Category:Developer tools|NetBeans]]

AJAX marking block

2010-02-25T14:04:44Z

Mattgibson: /* Constructor */

This page outlines the internal architecture of the AJAX marking block and how to extend it for new types of assignment.

=Architecture=

The block has a server side section of code written in PHP and a client side in javascript. The client is based on the YUI treeview widget and sends asynchronous messages to the server to retrieve the data which becomes the nodes of the tree. Each time a node is clicked to expand it, a new message is sent, with the response data parsed and made into the new sub-nodes.

==HTML fallback==
To aid accessibility, the block starts by loading a very basic HTML version so that if javascript is turned off either in the browser or the user's preferences, the block is still usable. This HTML version is normally not visible as the javascript acts to hide it immediately if possible.

==File structure==
The main lib.php file provides a base class which holds most of the useful functions. This is extended through inheritance when either ajax.php is accessed (each time an asynchronous request is sent) or html_list.php is included when the page is initially set up, providing an object which automatically collects submitted POST data and outputs the desired code once instantiated. This file also has a base class, module_base which is extended by each of the modules with a modulename_functions classin the modulename_grading.php file. All of these files are included as needed at the start and the instantiated objects are added to the main library class object as e.g. $AMB_AJAX_response->quiz so that their functions are available. The module objects will need to use many of the library functions, so a reference to the parent library object is passed in via the constructor and is used as $this->mainobject->useful_function().

The javascript.js file contains a collection of functions which are placed within the YAHOO.ajax_marking_block namespace. Some are part of YAHOO.ajax_marking_block.tree_base which is an extended version of the YAHOO.widget.TreeView widget that gets instantiated once for the main tree and once for the configuration tree via a factory function.

=Plugins=
The block is designed to allow new assessment types to be added dynamically. Rach new type will need to provide two files: modulename_grading.php and modulename_grading.js, whic can be placed either in the /block/ajax_marking folder or in the /mod/modulename folder.

To see how these work, take the assignment_grading files as examples.

==PHP==
The php file will need the following:

The usual login check
require_login(0, false);

A class declaration for modulename_function which extends module_base
class assignment_functions extends module_base {

===Constructor===
A constructor which lays out the basic information about this module
function assignment_functions(&$reference) {

The library object (which this object will be attached to) passed in as a reference so that functions can be accessed
$this->mainobject = $reference;

The type must be identical to the modulename stored in the database
$this->type = 'assignment';

This is the capability that will need to be checked to see if the person has grading permission i.e. teachers should be able to do this whilst students should not.
$this->capability = 'mod/assignment:grade';

This is the location of the icon to be displayed for this assessment type. It varies according to which theme setup you have. Smartpix was difficult to integrate, so there is a home-grown solution using this property, at least for 1.9.
$this->icon = 'mod/assignment/icon.gif';

This array is used to match the types which are returned from the nodes being clicked in the ajax tree to the functions which return the next level of the tree. The initial course->assessment node one is built in, so you just need to add the second and possibly third level connections. In this case, when a node of type 'assignment is clicked, the name of the function that will return the next layer of nodes (the individual student submissions) is 'submissions()'. Groups nodes are dealt with automatically, so there is no need to put them here.
$this->functions = array(
'assignment' => 'submissions'
);

It is possible that your assessment may have only two levels e.g. the journal module. This would be because there is no screen that allows you to grade individual students' work and you must have a pop up for the entire journal with all students. Alternatively, it may be that you can only grade a student's work for a subdivision of an assessment e.g. one question at a time in the quiz. In this case, you will have four levels: course, quiz, quiz question, student. Specify the number of levels here so that the nodes are constructed properly. 3 is the norm.
$this->levels = 3;

==Javascript==
Using the assignment module as an example, the javascript file will need to use the YAHOO.ajax_marking_block.modulename namespace and will have to add the following features:

Make a new namespace for the module:
YAHOO.ajax_marking_block.assignment = {};
The following functions (in no particular order) all use this namespace and must be included even if empty unless otherwise stated.

Provide arguments for the pop up window that the grading will happen in. The main thing to change here is the height and width so that the grading interface is visible.
YAHOO.ajax_marking_block.assignment.pop_up_arguments = function(clicked_node) {
return 'menubar=0,location=0,scrollbars,resizable,width=780,height=630';
};

Provide the URL for the pop up window. This will usually involve some combination of the student's userid and the assessement id or coursemodule id. This data is saved in the data attribute of the clicked node and is passed through to this function. You will need to make sure it is passed through by the PHP code on the server.
YAHOO.ajax_marking_block.assignment.pop_up_opening_url = function (clicked_node) {
return '/mod/assignment/submissions.php?id='+clicked_node.data.aid+'&userid='+clicked_node.data.sid+'&mode=single&offset=0';
};

The pop up window needs to be closed after grading has finished, which a small piece of javascript carries out. It does this by checking to see if the URL has changed to the one signifying that your grades have been saved, so grade some work, press 'save' and look to see the URL, which you put in this function.
YAHOO.ajax_marking_block.assignment.pop_up_closing_url = function (clicked_node) {
return '/mod/assignment/submissions.php';
};

There may be a need to send more than just the standard user id and assessment item id with the AJAX request in order to specify what's needed. See the quiz module for an example, where the quiz id and question id are needed as well as the user id. Leave it as below if not required.

YAHOO.ajax_marking_block.assignment.extra_ajax_request_arguments = function (clicked_node) {
return true;
};

You then need to provide code that will alter the pop up's contents so that when the submit button is clicked, the tree nodes are updated. The function below will be run every second from the point at which the pop up is opened until it completes successfully. It aims to test the loaded portion of the DOM to see whether the buttons that need altering are present, then adds an onclick function which will update the tree.

YAHOO.ajax_marking_block.assignment.alter_popup = function(node_id) {

var els = '';

if (YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName) {

els = YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName('submit');
// the above line will not return anything until the pop up is fully loaded

if (els.length > 0) {
var functionText = "return YAHOO.ajax_marking_block.main_instance.remove_node_from_tree(-1, '";
functionText += node_id+"', false); ";

els[0]["onclick"] = new Function(functionText);

// cancel the timer loop for this function
window.clearInterval(YAHOO.ajax_marking_block.timerVar);
}
}
}

AJAX marking block

2010-02-25T14:04:27Z

Mattgibson: /* Constructor */

AJAX marking block

2010-02-25T13:55:41Z

Mattgibson: /* Javascript */

AJAX marking block

2010-02-25T13:40:58Z

Mattgibson: /* PHP */

AJAX marking block

2010-02-25T13:00:18Z

Mattgibson:

This page outlines the internal architecture of the AJAX marking block and how to extend it for new types of assignment.

=Architecture=

The block has a server side section of code written in PHP and a client side in javascript. The client is based on the YUI treeview widget and sends asynchronous messages to the server to retrieve the data which becomes the nodes of the tree. Each time a node is clicked to expand it, a new message is sent, with the response data parsed and made into the new sub-nodes.

==HTML fallback==
To aid accessibility, the block starts by loading a very basic HTML version so that if javascript is turned off either in the browser or the user's preferences, the block is still usable. This HTML version is normally not visible as the javascript acts to hide it immediately if possible.

==File structure==
The main lib.php file provides a base class which holds most of the useful functions. This is extended through inheritance when either ajax.php is accessed (each time an asynchronous request is sent) or html_list.php is included when the page is initially set up, providing an object which automatically collects submitted POST data and outputs the desired code once instantiated. This file also has a base class, module_base which is extended by each of the modules with a modulename_functions classin the modulename_grading.php file. All of these files are included as needed at the start and the instantiated objects are added to the main library class object as e.g. $AMB_AJAX_response->quiz so that their functions are available. The module objects will need to use many of the library functions, so a reference to the parent library object is passed in via the constructor and is used as $this->mainobject->useful_function().

The javascript.js file contains a collection of functions which are placed within the YAHOO.ajax_marking_block namespace. Some are part of YAHOO.ajax_marking_block.tree_base which is an extended version of the YAHOO.widget.TreeView widget that gets instantiated once for the main tree and once for the configuration tree via a factory function.

=Plugins=
The block is designed to allow new assessment types to be added dynamically. Rach new type will need to provide two files: modulename_grading.php and modulename_grading.js, whic can be placed either in the /block/ajax_marking folder or in the /mod/modulename folder.

To see how these work, take the assignment_grading files as examples.

==PHP==
The php file will need the following functions as a minimum:

==Javascript==
Using the assignment module as an example, the javascript file will need to use the YAHOO.ajax_marking_block.modulename namespace and will have to add the following features:

Make a new namespace for the module:
YAHOO.ajax_marking_block.assignment = {};
The following functions (in no particular order) all use this namespace and must be included even if empty unless otherwise stated.

Provide arguments for the pop up window that the grading will happen in. The main thing to change here is the height and width so that the grading interface is visible.
YAHOO.ajax_marking_block.assignment.pop_up_arguments = function(clicked_node) {
return 'menubar=0,location=0,scrollbars,resizable,width=780,height=630';
};

Provide the URL for the pop up window. This will usually involve some combination of the student's userid and the assessement id or coursemodule id. This data is saved in the data attribute of the clicked node and is passed through to this function. You will need to make sure it is passed through by the PHP code on the server.
YAHOO.ajax_marking_block.assignment.pop_up_opening_url = function (clicked_node) {
return '/mod/assignment/submissions.php?id='+clicked_node.data.aid+'&userid='+clicked_node.data.sid+'&mode=single&offset=0';
};

The pop up window needs to be closed after grading has finished, which a small piece of javascript carries out. It does this by checking to see if the URL has changed to the one signifying that your grades have been saved, so grade some work, press 'save' and look to see the URL, which you put in this function.
YAHOO.ajax_marking_block.assignment.pop_up_closing_url = function (clicked_node) {
return '/mod/assignment/submissions.php';
};

There may be a need to send more than just the standard user id and assessment item id with the AJAX request in order to specify what's needed. See the quiz module for an example, where the quiz id and question id are needed as well as the user id. Leave it as below if not required.

YAHOO.ajax_marking_block.assignment.extra_ajax_request_arguments = function (clicked_node) {
return true;
};

You then need to provide code that will alter the pop up's contents so that when the submit button is clicked, the tree nodes are updated. The function below will be run every second from the point at which the pop up is opened until it completes successfully. It aims to test the loaded portion of the DOM to see whether the buttons that need altering are present, then adds an onclick function which will update the tree.

YAHOO.ajax_marking_block.assignment.alter_popup = function(node_id) {

var els = '';

if (YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName) {

els = YAHOO.ajax_marking_block.pop_up_holder.document.getElementsByName('submit');
// the above line will not return anything until the pop up is fully loaded

if (els.length > 0) {
var functionText = "return YAHOO.ajax_marking_block.main_instance.remove_node_from_tree(-1, '";
functionText += node_id+"', false); ";

els[0]["onclick"] = new Function(functionText);

// cancel the timer loop for this function
window.clearInterval(YAHOO.ajax_marking_block.timerVar);
}
}
}

AJAX marking block

2010-02-25T09:14:36Z

Mattgibson:

AJAX marking block

2010-02-25T00:24:15Z

Mattgibson: Began page

Ajax marking block

2010-02-25T00:11:45Z

Mattgibson:

The [http://moodle.org/mod/data/view.php?d=13&rid=1459 AJAX marking block] allows you to view and complete all of your marking without leaving the page you are on. It displays all the ungraded work you need to mark in a tree structure of all of the courses you teach in, along with a count of how many items there are for each course & assessment item.
[[Image:Ajax_marking.png|right]]
====Keep track of what you have graded so far====
When the tree nodes are expanded and a student's name is clicked, a pop-up opens with the work to be graded. Once 'Submit' has been clicked in that window, the pop-up closes and tree updates itself by removing the student's node and altering its total count.

====Instantly update without leaving the page====
The [[AJAX]] bit means that every time you click on the nodes to expand them, the data for the child nodes is fetched in the background without refreshing the whole page. This saves on loading the whole lot at the start, which could be time consuming. Clicking 'Collapse and refresh' will re-load the whole tree, with an updated count of your marking including anything that was submitted a second or two ago, and excluding any that were marked by someone else and now don't need your attention.

====Only show grading for your own teaching groups====
Some sites run training courses that don't need grading, or a single course with many teachers and teaching groups following the same programme of study. You can easily choose to hide the work that is not your using the '''configure''' link, which will open a pop up allowing you to show or hide each item individually, or choose to show only the work of some groups, so you only ever see the work that you actually need to mark.

==Installation==
Download the zip file [http://download.moodle.org/download.php/plugins/blocks/ajax_marking.zip here]. Copy it to your /blocks/ folder and unzip it there. Then, go to the notifications screen (Front page -> administration block -> notifications) where you should see a message about the tables having been set up correctly.

==Roles and permissions==
Note that you will not get anything displayed at all unless you have a teacher role in a course. This course will also need to be one that has gradable items like assignments or forums with ratings, or you will get an error saying that you have no graded assessments yet.

If you want to see all of the items in all of the courses across the site, add yourself as a teacher under Front page Admin block -> users -> permissions -> assign site wide roles

A fix so that admins see everything without doing this is on the way (CONTRIB-1017)

===Configuring the display of each individual assessment item===
The block can be set to show or hide each individual assessment item, or show only the assessments by students in certain groups. Clicking on '''configure''' will bring up an additional tree, which shows all of your courses and names of all the assessment items. When you click on one of the assessments, you will be faced with a number of options on the right:
* Show - the default state, where you will see all students' work
* Show by group - a set of checkboxes will appear with the names of the current groups for that course. You choose which you want to see and group nodes will then be shown between the assessment and student nodes in the main block. The nodes for that assessment will then look like this: '''Course -> Assessment -> Group -> Submission'''
* Hide - do not display any submissions for this assessment item.

The counting of unmarked submissions respects these choices and they are specific to the user who created them. If you are an admin and wish to set the preferences for others, use the 'login as' function to do so.

==Supported types==
* Assignment
* Forum (only if ratings are on)
* Workshop
* Journal
* Quiz (essay questions only)

==See also==
[[Development:AJAX marking block]]

[[Category:Contributed code]]
[[Category:Teacher]]
[[Category:Administrator]]

Setting up Netbeans

2010-01-19T09:36:42Z

Mattgibson: added memory optimisation link

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* I recommend downloading the latest [http://www.netbeans.org/downloads/indexB.html 6.7.1 version with PHP support ]. It's only a 26 MB download.
* Install and run it.

* There's also the brand new [http://netbeans.org/community/releases/68/ NetBeans 6.8 Beta release].

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[Development:CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Optimization ==

1. You may want to run Netbeans with the Sun JDK. Netbeans seems to work a bit better with the Sun JDK. Download it from [http://java.sun.com/javase/downloads/index.jsp]. You'll have to edit Netbeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the Netbeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If Netbeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m
See [http://wiki.netbeans.org/FaqSettingHeapSize here] for more details on memory optimisation.

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

== See also: ==
* Moodle forum: [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

[[Category:Developer|NetBeans]]
[[Category:Developer tools|NetBeans]]

Cron

2009-11-19T20:15:21Z

Mattgibson: Added definition at the start

Cron is the name of a Unix program that runs predefined tasks on a computer at at regular intervals. It assists some of Moodle's modules to perform tasks on a scheduled basis. For example, the cron process might tell Moodle to check all discussion forums so it can mail out copies of new posts to people who have subscribed to that forum.

The primary Moodle script that does all this is located in the admin directory, and is called cron.php. However, it can not tell itself to run, so you need to set up a mechanism where this script is run regularly (eg every five or ten minutes). This provides a "heartbeat" so that the script can perform functions at periods defined by each module. This kind of regular mechanism is known as a '''cron service'''. The service can be part of a webhost or can be something run from a different server or computer.

==Overview of cron==
===Script overview===

The cron.php script looks through the mdl_modules table (assuming the default table prefix is mdl_) in the Moodle database for modules scheduled to have their cron functions run; it then looks in each such module directory for a function called module-name_cron in the lib.php file and runs it. It also looks through the mdl_block table for blocks scheduled for their cron methods (object functions) to be run; it then, for each such block, runs the cron method for a new object associated with that block (I'm omitting details for the benefit of non-programmers; programmers can read admin/cron.php for themselves). These files (the lib.php files and the files where the block classes are defined) can contain cleanup functions, email functions or anything that needs to be run on a regular basis. For example, cron will trigger the system to create the backups of courses at the time specified in the administration settings. It also triggers any messaging module or forum email notifications, but not all functions are called each time the cron runs. Some functions, such as unenrolling students who have not logged in or deleting old copies of log files, are only run occasionally. The cron.php file has a section which will randomly call these core tasks approximately 1 in 5 times the cron runs.

===Invocation===
There are now (1.9) a number of options with respect to how one can invoke cron.php. First off, one can password the invocation of cron.php via its URL. This means whether one calls the script via a browser through an application like wget or curl, or via your own code to the web daemon, the script will not run unless the password is provided, and this would be transmitted in clear text.

You can also now bar invocation by URL be selecting cronclionly. This sets Moodle so that cron.php cannot be invoked by the Moodle URL. See the illustration below. (Menu: Security/Site policies)

[[Image:Moodelcronadmin.png]]

While this is identified as CLI (command line interface) this is a bit misleading in that it does not mean that you have to be sitting at a shell account entering the command. If you enable this switch you can invoke cron.php through any set of batch or script files you wish, but it must be invoked via its correct location in the operating systems file structure. This can be especially frustrating for those not used to scripting in that environment is not typically provided.

===Cron service location and timing===
Note that the machine performing the cron '''does not need to be the same machine that is running Moodle'''. For example, if you have a limited web hosting service that does not have a cron service, then you might choose to run cron on another server or on your home computer. All that matters is that the cron.php file is called regularly.

The load of this script is not very high, so 5 minutes is usually reasonable, but if you're worried about it you can reduce the time period to something like 15 minutes or even 30 minutes. It's best not to make the time period too long, as delaying mail-outs can slow down activity within the course. Remember that mail-outs also wait for the editing time to expire before being queued for sending.

===Testing cron and manual trigger===

First, test that the script works by running it directly from your browser: ''<nowiki>http://example.com/moodle/admin/cron.php</nowiki>''

If cron is called from the command line by any user logged in to your Moodle it will create a temporary admin environment in order to run and then log the user out. You can disable command line running of cron by disabling the appropriate section in the cron.php file.

Now, you need to set up some of way of running the script automatically and regularly.

==Managing Cron on Windows systems==

There are two different ways for setting-up Moodle cron.php on Windows systems:

*Use the '''Moodle Cron package'''. The simplest way is to use this little package [http://download.moodle.org/download.php/windows/MoodleCron-Setup.exe MoodleCron-Setup.exe], which makes this whole thing very easy by installing a small Windows service. Run it and forget about it! :-)
*Use a '''Scheduled Task'''. If you prefer to use the built-in Windows Scheduler or are having trouble with moodle-cron-for-windows package, you can use wget for windows or php from the command line and setup a scheduled task. Just follow these steps:
** Choose either the '''php.exe/php-win.exe (command line binary)''' or '''wget'''
::The php.exe or php-win.exe binary (for PHP version 5 or later) is installed in your php folder (e.g. c:\php) will give you better performance when running the cron script.
::If you want to use wget, download a compiled version of wget for windows from the native GNU Win32 ports (http://unxutils.sourceforge.net/), from Heiko Herold's wget for windows page (http://xoomer.virgilio.it/hherold/) or Bart Puype's wget for windows page (http://users.ugent.be/~bpuype/wget/). If you use Heiko Herold's package, copy all of the .DLL files to your C:\Windows\system32 directory. Copy the wget.exe file to c:\windows (this makes sure wget is always in the search path).
:* Setup a '''Scheduled Task'''.
:: - Go to Start >> Control Panel >> Scheduled Tasks >> Add Scheduled Task.
:: - Click "Next" to start the wizard:
:: - Click in the "Browse..." button and browse to c:\php\php.exe or c:\windows\wget.exe and click "Open"
:: - Type "Moodle Cron" as the name of the task and select "Daily" as the schedule. Click "Next".
:: - Select "12:00 AM" as the start time, perform the task "Every Day" and choose today's date as the starting date. Click "Next".
:: - Enter the username and password of the user the task will run under (it doesn't have to be a priviledged account at all). Make sure you type the password correctly. Click "Next".
:: - Mark the checkbox titled "Open advanced properties for this task when I click Finish" and click "Finish".
:: - In the new dialog box, type the following in the "Run:" text box: <pre>c:\windows\wget.exe -q -O NUL http://my.moodle.site/moodle/admin/cron.php</pre> or <pre>c:\php\php-win.exe -f c:\moodle\admin\cron.php</pre> Replace "c:\moodle" with the path to your moodle directory or "my.moode.site" with the name of your site. 
:: - Click on the "Schedule" tab and there in the "Advanced..." button.
:: - Mark the "Repeat task" checkbox and set "Every:" to 5 minutes, and set "Until:" to "Duration" and type "23" hours and "59" minutes.
:: - Click "OK" and you are done.
* '''Test your scheduled task'''. You can test that your scheduled task can run successfully by clicking it with the right button and chosing "Run". If everything is correctly setup, you will briefly see a DOS command window while wget/php executes and fetches the cron page and then it disappears. If you refresh the scheduled tasks folder, you will see the ''Last Run Time column'' (in detailed folder view) reflects the current time, and that the Last Result column displays "0x0" (everything went OK). If either of these is different, then you should recheck your setup.
* '''Logging cron output'''. You may want to log the output of the cron script as it executes, in case you see the job is producing errors, backups are not being completed or users are experiencing delays in receiving forum emails. To do this, adjust the command so that it uses the php.exe and stores the output in a file called (for example c:\moodle\admin\cron.log). Here is an example of the php.exe command:
<pre>c:\php\php.exe -f c:\moodle\admin\cron.php > c:\moodle\admin\cron.log</pre>

==Managing the cron job on Mac OS X with launchd==

It's really important to start the cron job every 5 minutes. The cron job assists most of Moodle's modules to perform tasks on a scheduled basis. For example, the discussion forums can only mail out copies of new posts to all subscribers if the cron job tells Moodle to do this.

In Mac OS X 10.5 you will find the system daemon ''launchd'' for this service. This daemon offers a standardized interface to any user and all programs started automatically by the system. Please look at http://developer.apple.com/macosx/launchd.html for more informations about the configurations and all parameters.

In our case the service should get the web page http://your-server-address/moodle19/admin/cron.php every 5 minutes. The configuration will be done by the file named ''moodle4mac.cron.plist'' which must be placed in the system folder ''/Library/LaunchDaemons/'' ... surely you can use any other file name but it should say something about the function of the service. The extension must be ''.plist''. After any reboot of your Mac server the cron service will start automaticly because the file is placed in the correct system folder.

===Use the graphical way===
You can use Lingon to add a new daemon plist or to edit one. It produces the same text as you can write in your text editor. http://sourceforge.net/projects/lingon/files/

[[Image:macosx-lingon.png]]

===Use a text editor===
Please use a text editor to write the needed file. You can open the Terminal and use the system editors vi or pico. But you can also write the text file with any GUI text editor ... I mostly use TextWrangler ... but do NOT take an editor for formatted texts like Microsoft Word or OpenOffice Writer. You must get pure text!

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>KeepAlive</key><false/>
<key>Label</key><string>moodle4mac.cron</string>
<key>ProgramArguments</key>
<array>
<string>curl</string>
<string>-s</string>
<string>http://your-server-address/moodle19/admin/cron.php</string>
</array>
<key>RunAtLoad</key><true />
<key>StartInterval</key><integer>300</integer>
<key>StandardErrorPath</key><string>/dev/null</string>
<key>StandardOutPath</key><string>/dev/null</string>
</dict>
</plist>

The label string must be the same as the file name is but without the extension ''.plist''. Save the text file ''/Library/LaunchDaemons/moodle4mac.cron.plist''. The owner of the file must be set to the system user ''root''. That's all, really!

===How to start and stop the cron service===
You can start the new cron service in the Terminal.

sudo launchctl load /Library/LaunchDaemons/moodle4mac.cron.plist

The following command would stop the service. If you want to activate changes in the cron service you need to ''unload'' and then to ''load'' the daemon again.

sudo launchctl unload /Library/LaunchDaemons/moodle4mac.cron.plist

===Only one service for two servers?===
For my server I needed to have a cron service for to instances ''moodle19'' and ''moodle20'' ... no problem ... with the typo ''moodle[19-20]'' I will get a cron service for both.

<nowiki>curl -s http://your-server-address/moodle[19-20]/admin/cron.php</nowiki>

To see if the cron service works correctly you should look at the ''access.log'' of your web server. The cron.php should be accessed every 5 minutes ... on my server for both Moodle instances ''moodle19'' and ''moodle20'' ... oh yes, it works!!

192.168.0.220 - - [30/Jul/2009:22:10:56 +0200] "GET /moodle19/admin/cron.php HTTP/1.1" 200 1136
192.168.0.220 - - [30/Jul/2009:22:10:57 +0200] "GET /moodle20/admin/cron.php HTTP/1.1" 200 1403
192.168.0.220 - - [30/Jul/2009:22:11:18 +0200] "OPTIONS * HTTP/1.0" 200 -
192.168.0.220 - - [30/Jul/2009:22:15:56 +0200] "GET /moodle19/admin/cron.php HTTP/1.1" 200 735
192.168.0.220 - - [30/Jul/2009:22:15:57 +0200] "GET /moodle20/admin/cron.php HTTP/1.1" 200 964
192.168.0.220 - - [30/Jul/2009:22:20:56 +0200] "GET /moodle19/admin/cron.php HTTP/1.1" 200 1136
192.168.0.220 - - [30/Jul/2009:22:20:57 +0200] "GET /moodle20/admin/cron.php HTTP/1.1" 200 1365

==Managing cron on web hosting services==

Your web-based control panel may have a web page that allows you to set up a cron service process.

===CPanel cron service===
If you are using CPanel, login then look for "Advanced" category towards the bottom of the page. Click on Cron Jobs -> Advanced (Unix style). Enter the following for the cron to run every 30 minutes.

Email address for output: emailaddress@mydomain.con
Minute:*/30
Hour:*
Day:*
Month:*
Weekday:*
<nowiki>Command: wget -q -O /dev/null http://www.mydomain.com/moodle/admin/cron.php</nowiki>

Click Commit Changes. Check your email for the output.

[[Image:Cpanel-cron-setup.JPG]]

===Other systems cron service===
For other systems, look for a button called "Cron jobs". In there you can put the same sort of Unix commands as listed below.

If you don't have permissions to run the 'wget' command on the server, you can use this php command:

/usr/local/bin/php -q /real/path/to/script/admin/cron.php

For example:

/usr/local/bin/php -q /home/username/public_html/moodle/admin/cron.php

If you don't know what is the real path of your Moodle folder you can use the PHP command realpath.

Another alternative, if you do not have permission to run the 'wget' command, may be to use a curl command.

For example:

curl --silent --compressed http://mydomain.com/moodle/admin/cron.php

==Using a cron command line in Unix==

There are different command line programs you can use to call the page from the command line. Not all of them may be available on a given server.

'''Note:''' The examples with wget, lynx, and similar are '''not''' the same as the "CLI only" cron checkbox, mentioned above (the configuration variable "cronclionly"). wget, lynx, and other similar utilities are Unix command-line HTTP clients, and thus running cron.php in this way is the same as running it in a browser, from Moodle's point of view.

For example, you can use a Unix utility like 'wget':

wget -q -O /dev/null <nowiki>http://example.com/moodle/admin/cron.php</nowiki>

Note in this example that the output is thrown away (to /dev/null).

A number of users of Moodle have found that 'wget' sometimes fails. Especially if you have trouble with email digests not being sent on a daily basis to all users, an alternative command that solves the problem is:

php <nowiki>http://example.com/moodle/admin/cron.php</nowiki>

The same thing using lynx:

lynx -dump <nowiki>http://example.com/moodle/admin/cron.php</nowiki> > /dev/null

Note in this example that the output is thrown away (to /dev/null).

Alternatively, you can use a standalone version of PHP, compiled to be run on the command line. The disadvantage is that you need to have access to a command-line version of php. The advantage is that your web server logs aren't filled with constant requests to cron.php and you can run at a lower I/O and CPU priority.

/opt/bin/php /web/moodle/admin/cron.php

Example command to run at lower priority:

ionice -c3 -p$$;nice -n 10 /usr/bin/php /moodle/admin/cron.php > /dev/null

===Using the crontab program on Unix===

All that Cpanel does is provide a web interface to a Unix utility known as crontab. If you have a command line, you can set up crontab yourself using the command:

crontab -e

and then adding one of the above commands like:

*/30 * * * * wget -q -O /dev/null <nowiki>http://example.com/moodle/admin/cron.php</nowiki>

The first five entries are the times to run values, followed by the command to run. The asterisk is a wildcard, indicating any time. The above example means run the command ''wget -q -O /dev/null...'' every 30 minutes (*/30), every hour (*), every day of the month (*), every month (*), every day of the week (*).

The "O" of "-O" is the capital letter not zero, and refers the output file destination, in this case "/dev/null" which is a black hole and discards the output. If you want to see the output of your cron.php then enter its url in your browser.

* [http://linuxweblog.com/node/24 A basic crontab tutorial]
* [http://www.freebsd.org/cgi/man.cgi?query=crontab&apropos=0&sektion=5&manpath=FreeBSD+6.0-RELEASE+and+Ports&format=html Online version of the man page]

For '''beginners''', "EDITOR=nano crontab -e" will allow you to edit the crontab using the [http://www.nano-editor.org/dist/v1.2/faq.html nano] editor. Ubuntu defaults to using the nano editor.

Usually, the "crontab -e" command will put you into the 'vi' editor. You enter "insert mode" by pressing "i", then type in the line as above, then exit insert mode by pressing ESC. You save and exit by typing ":wq", or quit without saving using ":q!" (without the quotes). Here is an [http://www.unix-manuals.com/tutorials/vi/vi-in-10-1.html intro] to the 'vi' editor.

==See also==

Using Moodle forum discussions:
*[http://moodle.org/mod/forum/discuss.php?d=41827 Cron - can someone give me a quick confirmation of function?]
*[http://moodle.org/mod/forum/discuss.php?d=97684 Cronjob Question]
*[http://moodle.org/mod/forum/discuss.php?d=97457 Slow cron : avoiding simultaneous cron]
*[http://moodle.org/mod/forum/discuss.php?d=117168 Visibility of cron.php]

[[Category:Installation]]

[[es:Cron]]
[[fr:Cron]]
[[nl:Cron]]
[[sk:Cron]]
[[pl:Cron]]
[[ja:Cron]]

Setting up Netbeans

2009-11-19T14:31:02Z

Mattgibson: Adding a branch to your plugin

[http://www.netbeans.org/features/php/index.html NetBeans] has got a good PHP support. You find a host of information on the website (tutorials, developer blog, screen casts, etc.).

== Features ==
* CVS integration: see all changes, lines deletion, diff in real time, show annotations, diff history...
* Ctrl+Click: Go to declaration
* Export/Import Diff Patch
* Easy navigation
* List of functions
* Code completion
* Instant rename
* HTML, CSS, JavaScript support
* MySQL manager
* Quick Search
* Very few bugs

== Installation ==

* I recommend downloading the latest [http://www.netbeans.org/downloads/indexB.html 6.7.1 version with PHP support ]. It's only a 26 MB download.
* Install and run it.

* There's also the brand new [http://netbeans.org/community/releases/68/ NetBeans 6.8 Beta release].

== Set up for Moodle development ==

* Checkout your Moodle project with a '''CVS client''' - see [[CVS for Administrators]] or [[Development:CVS for developers|CVS for Developers]].

* Open File > New Project > PHP > PHP Application > Next
: You're going to set the project now. ''Name'', ''Location'' and ''Folder'' are used by NetBeans and are not related to the source code. So you can choose whatever you like, except your source folder. ''Sources'' has to be your checked out Moodle branch/head folder. The rest is clear enough. Don't forget to choose UTF-8 for ''Default Encoding''.

: Example:

Project Name: Moodle 1.9 Stable
Project Location: C:\Users\jerome\Documents\NetBeansProjects
Project Folder: C:\Users\jerome\Documents\NetBeansProjects\Moodle 1.9 Stable
Project Sources: C:\Users\jerome\Projects\branch19_STABLE\moodle
Project URL: http://localhost/moodle19/
Index File: index.php
Create: unchecked
Default Encoding: UTF-8
Set as Main Project: unchecked

* Click on Finish.

* Start coding!

== CVS with NetBeans ==

NetBeans comes with '''integrated CVS support''' which might be the easiest way to check out Moodle.

=== Anonymous checkout ===

# In NetBeans, select Window->Versioning->CVS->Checkout
# Select Team->CVS->Checkout
# Enter into CVS Root: '':pserver:anonymous@us.cvs.moodle.org:/cvsroot/moodle''
: (Non-US-residents might use one of the other [https://docs.moodle.org/en/CVS_for_Administrators#CVS_Servers Moodle CVS servers] nearer to them.)
# Click ''Next''
# Browse or enter into ''Module:'' moodle
# Browse or enter into ''Branch:'' MOODLE_19_STABLE
# Browse or enter into ''Local Folder:'' C:\xampp\htdocs
# Click ''Finish'' (and wait a few minutes for Moodle to be checked out)
# When you get the dialog box "Do you want to create an IDE project from the checked-out sources?", Click "Create Project..."
# Select PHP Application with Existing Sources, and click Next
# Browse or enter into ''Sources Folder'' C:\xampp\htdocs\moodle
# Enter into ''Project Name:'' moodle
# Keep the other defaults and click next
# ''Run As:'' should have selected ''Local Web Site (running on local web server)''
# Enter into Project URL http://localhost/moodle/
# Browse or enter into ''Index File:'' index.php
# Click ''Finish''

=== Checkout for developers with write access ===

IF you wish to use NetBeans CVS and have CVS write access, the procedure is as follows:

# Follow the above instructions except for point 3
# At part 3, substitute '':ext:yourusername'' for the part before the @ and remove the country code from after it, leaving it like this ''''':ext:yourusername'''@cvs.moodle.org/cvsroot/moodle''
# Follow the rest of the instructions as above

If you wish to work with a plugin, you will need to check this out separately and add it to the Moodle code project you have just made. This because for some reason, the 'Do you want to create a project' option fails to show any of the files once you open it if you try to check out the plugin on its own (NetBeans 6.7.1 on a Mac).

# Follow the above steps up to point 3, and again substitute '':ext:yourusername'' and click 'next'
# Click 'Browse...' next to the 'Module' dialogue
# Find the plugin you wish to work with in CONTRIB
# Click 'OK'
# Proceed as before up to point 6, then press 'Close' when asked if you want to create a new project.
# Now navigate to the folder you earlier specified in the 'local folder' dialogue and you will find a folder marked 'contrib'.
# navigate to the plugin folder, copy that folder, and then navigate to your main Moodle project folder and paste it where it belongs.

===Adding a branch to your plugin===
Your plugin will likely start with just a HEAD tag and at some point, you will want to branch it so that you can have versions for different Moodles. To add a MOODLE_20_STABLE branch, for example, do the following.

# Checkout as above, but use the MOODLE_20_STABLE branch instead of MOODLE_19_STABLE
# You will end up with an empty folder, which you copy into place as above.
# Find the folder in NetBeans, then right click and choose CVS->Merge changes from branch...
# Choose to merge from whatever branch has all the current code, using the help link if not sure what to do.

There is a small chance that the Merge link will not be there, in which case, you will have to copy the files into the directory by hand outside netbeans and then check them in. If you do this, make sure you don't copy over the 'CVS' folders that will have been made when you checked out the MOODLE_19_STABLE code.

=== A few warnings ===

Some of these warnings could also apply to other IDEs:

* If you want to delete a file from your computer but not from CVS, delete it from Windows Explorer/Nautilus/Finder. Otherwise your next commit could delete the file from CVS. In case you have already deleted a wrong file from NetBeans: with Windows Explorer/Nautilus/Finder, delete all the folder content of this deleted file (including the CVS folder) and update the folder.
* If you rename files and that other people are working on them, NetBeans could end up to mess up your CVS folder (even though that is quite rare). Then NetBeans CVS will refuse to update your code displaying a no explicit error as '''Update Failed'''. In this case, delete the content of the damaged folder with Windows Explorer/Nautilus/Finder. Then update this folder.
* If you create a patch or a new PHP file with NetBeans on Microsoft Windows, please check that it's a Unix format file. You may want to use another software to create Unix format patch/php files.

== Optimization ==

1. You may want to run Netbeans with the Sun JDK. Netbeans seems to work a bit better with the Sun JDK. Download it from [http://java.sun.com/javase/downloads/index.jsp]. You'll have to edit Netbeans config file. Open netbeans/etc/netbeans.conf. Then uncomment and edit:

netbeans_jdkhome="your_JDK_path"

2. To change the Netbeans look and feel run netbeans in the command line with this parameter:
"netbeans" --laf javax.swing.plaf.metal.MetalLookAndFeel

3. If Netbeans starts to slow down, give it more memory
"netbeans" -J-Xmx600m

== Coding faster ==

=== Keyboard shortcuts ===
(Note: Some shortcuts might not work for PHP development.)
* [http://www.phpmag.ru/2009/01/23/extremely-usefull-netbeans-shortcuts/ Extremely Useful NetBeans Shortcuts]
* [http://netbeanside61.blogspot.com/2008/04/top-10-netbeans-ide-keyboard-shortcuts.html Top 10 NetBeans IDE Keyboard Shortcuts I use the most]
* [http://wiki.netbeans.org/KeymapProfileFor60 NetBeans IDE 6.x Keyboard Shortcuts Specification]

=== PHPUnit support ===
See [http://blogs.sun.com/netbeansphp/entry/recent_improvements_in_phpunit_support "Recent improvements in PHPUnit-support"] on how to use PHPUnit with NetBeans.

== See also: ==
* Moodle forum: [http://moodle.org/mod/forum/discuss.php?d=112972 NetBeans 6.5 for moodle/PHP/debugging is a better experience v.s Eclipse]
* [http://www.netbeans.org/kb/trails/php.html NetBeans PHP Learning Trail]
* [http://wiki.netbeans.org/PHP NetBeans PHP Wiki]
* Sun's [http://blogs.sun.com/netbeansphp/ NetBeans PHP Team Blog]

[[Category:Developer|NetBeans]]
[[Category:Developer tools|NetBeans]]

Setting up Netbeans

2009-11-10T23:41:19Z

Mattgibson: /* CVS with NetBeans */ Added instructions for developers with write access

Setting up Netbeans

2009-11-06T12:48:03Z

Mattgibson: small typo

Ajax marking block

2009-07-09T08:52:27Z

Mattgibson:

The [http://moodle.org/mod/data/view.php?d=13&rid=1459 AJAX marking block] allows you to view and complete all of your marking without leaving the page you are on. It displays all the ungraded work you need to mark in a tree structure of all of the courses you teach in, along with a count of how many items there are for each course & assessment item.
[[Image:Ajax_marking.png|right]]
====Keep track of what you have graded so far====
When the tree nodes are expanded and a student's name is clicked, a pop-up opens with the work to be graded. Once 'Submit' has been clicked in that window, the pop-up closes and tree updates itself by removing the student's node and altering its total count.

====Instantly update without leaving the page====
The [[AJAX]] bit means that every time you click on the nodes to expand them, the data for the child nodes is fetched in the background without refreshing the whole page. This saves on loading the whole lot at the start, which could be time consuming. Clicking 'Collapse and refresh' will re-load the whole tree, with an updated count of your marking including anything that was submitted a second or two ago, and excluding any that were marked by someone else and now don't need your attention.

====Only show grading for your own teaching groups====
Some sites run training courses that don't need grading, or a single course with many teachers and teaching groups following the same programme of study. You can easily choose to hide the work that is not your using the '''configure''' link, which will open a pop up allowing you to show or hide each item individually, or choose to show only the work of some groups, so you only ever see the work that you actually need to mark.

==Installation==
Download the zip file [http://download.moodle.org/download.php/plugins/blocks/ajax_marking.zip here]. Copy it to your /blocks/ folder and unzip it there. Then, go to the notifications screen (Front page -> administration block -> notifications) where you should see a message about the tables having been set up correctly.

==Roles and permissions==
Note that you will not get anything displayed at all unless you have a teacher role in a course. This course will also need to be one that has gradable items like assignments or forums with ratings, or you will get an error saying that you have no graded assessments yet.

If you want to see all of the items in all of the courses across the site, add yourself as a teacher under Front page Admin block -> users -> permissions -> assign site wide roles

A fix so that admins see everything without doing this is on the way (CONTRIB-1017)

===Configuring the display of each individual assessment item===
The block can be set to show or hide each individual assessment item, or show only the assessments by students in certain groups. Clicking on '''configure''' will bring up an additional tree, which shows all of your courses and names of all the assessment items. When you click on one of the assessments, you will be faced with a number of options on the right:
* Show - the default state, where you will see all students' work
* Show by group - a set of checkboxes will appear with the names of the current groups for that course. You choose which you want to see and group nodes will then be shown between the assessment and student nodes in the main block. The nodes for that assessment will then look like this: '''Course -> Assessment -> Group -> Submission'''
* Hide - do not display any submissions for this assessment item.

The counting of unmarked submissions respects these choices and they are specific to the user who created them. If you are an admin and wish to set the preferences for others, use the 'login as' function to do so.

==Supported types==
* Assignment
* Forum (only if ratings are on)
* Workshop
* Journal
* Quiz (essay questions only)

[[Category:Contributed code]]
[[Category:Teacher]]
[[Category:Administrator]]

Broken/id:3475

2009-07-06T11:37:01Z

Mattgibson:

Regarding the course import for teachers to start from...
I can envisage a situation whereby the original course author finds new information/ideas and adds stuff to the master course after the teacher has downloaded it, which in the current model would not make it to the teacher as the download is a one off process which they will not repeat. I would prefer a model whereby a course can act as a master template which gets updated regularly so that new questions, resources, activities etc appear dynamically as hidden items within the teacher's downloaded course, ready to be reviewed and revealed if needed. This would be like maintaining your Moodle install using CVS - you get updates all the time as they are created.

It would also be good to be able to track how many people are using a particular course and to have some sort of meta-forum for discussing changes and developemts. Many teachers will end up using the successful/well designed courses, so it would make a lot of sense to have a way of pooling their shared experience and getting that feedback back to the original creator. -- [[User:Matt Gibson|Matt Gibson]] 18:51, 25 June 2009 (UTC)

== Harvesting courses regularly and a few other comments ==

I've put this in the forum, but I'll say it here as well. If a site has a lot of courses to share with a hub, perhaps because they are an OpenCourseWare provider, they might prefer to supply an RSS or OAI list rather than click "publish" on each individual course. OCW Consortium members are already encouraged to offer an RSS feed (with DC metadata) of all their courses that is picked up by a number of OCW search tools. I'm sure Moodle users in that community would love the same approach to mean they could be included in the hubs as well.

To aid course harvesting (but to make publishing easier anyway) I'd like to see the DC metadata editing screen become part of the standard course settings screen, and the data pulled from here as part of the publish to hub functionality (and into any RSS or OAI service).

Using LOM as well as (or instead of) DC would allow more flexible searching at the hub with relatively little extra cost of data inputting.

Finally, there is a great deal of discussion in the OCW community about asset-level re-use. Anecdotal evidence from teachers suggests that the course-level is not fine-grained enough and they'd prefer to pick a single resource/image/activity. See http://opencontent.org/blog/archives/900 and related comments for example. So I'd like to see DC metadata added to resources and modules too, and the searching and import/export/enrol facility in the hub system work at this level also.
-- [[User:Jenny Gray|Jenny Gray]] 14:48, 30 June 2009 (GMT)

I second the points Jenny made above. I can't see much call for importing a whole course, as it will be too much hassle to integrate with current stuff. Ideally, single activities and resources can be copied at once from a remote course. This is already possible within a single site using the contributed sharing cart block, and if this could be brought into core and made to work across sites, it would be a killer app.

If that gets done, it brings up an issue of copyright - some courses will have things that are only licenced for site use and cannot be shared. If there was a switch that would set the item to 'can't copy/view over mnet', then it would be possible to allow access to courses with commercial resources and only share the parts which a teacher has made themselves.

For me, this use case would be an absolute killer app and would make collaboration a breeze across whole countries at a time. -- [[User:Matt Gibson|Matt Gibson]] 11:37, 6 July 2009 (UTC)

Broken/id:3475

2009-06-25T18:55:09Z

Mattgibson:

Broken/id:3475

2009-06-25T18:54:54Z

Mattgibson:

Broken/id:3475

2009-06-25T18:51:26Z

Mattgibson:

Events API

2009-05-26T11:27:26Z

Mattgibson:

{{Moodle 1.9}}

==Overview==

The Events API is a core system in Moodle to allow communication between modules.

An '''event''' is when something "interesting" happens in Moodle that is worth alerting the system about.

Any Moodle modules can '''trigger''' new events (with attached data), and other modules can elect to '''handle''' those events with custom functions that operate on the given data.

==Example==

Let's look at an example of how events are used to implement Messaging in Moodle 2.0. In the messaging system, textual messages are generated for users by different modules, and the user can decide how certain types of messages are displayed.

===Triggering an event===

When a messaging event occurs, the module should trigger a "message_send" event. In this example let's pretend someone just posted to a forum.

The forum module needs to create an object with the data that this event needs. This may vary completely for different types of events, it's just a data object.

$eventdata = new object();
$eventdata->component = 'mod/forum'; // path in Moodle
$eventdata->name = 'posts'; // type of message from that module (as module defines it)
$eventdata->userfrom = $userfrom; // user object
$eventdata->userto = $userto; // user object
$eventdata->subject = "Hi there"; // short one-line subject
$eventdata->fullmessage = "Here is the full message"; // raw text
$eventdata->fullmessageformat = FORMAT_PLAIN; // text format
$eventdata->fullmessagehtml = "Here is the full message"; // html rendered version (optional)
$eventdata->smallmessage = "Here is the truncated message"; // useful for plugins like sms or twitter (optional)

Then we post the object as an event and forget about it:

events_trigger('message_send', $eventdata);

===Handling an event===

Modules or core code can define an events.php in the db directory which defines events they want to be notified about, and describes which of their functions or class methods should be notified. For this case, there is this definition of a handler in lib/db/events.php

$handlers = array (
'message_send' => array (
'handlerfile' => '/lib/messagelib.php',
'handlerfunction' => 'message_send_handler',
'schedule' => 'instant'
)
);

These events.php files are parsed during install / upgrade and stored in a simple database table.

Now, when a '''message_send''' event happens, all the registered handlers functions for that event will be called something like this (but with more error handling):

include_once($CFG->dirroot.$handlers['message_send']['handlerfile']);
call_user_func($handlers['message_send']['handlerfunction'], $eventdata);

Any code can hook into any events this way.

==Database structure==

There are 3 core tables for events. Note that if a handler is queued, and yet to be processed or processing failed, then all subsequent calls on that handler must be queued.

===events_handlers===

This table is for storing which components requests what type of event, and the location of the responsible handler functions.

These entries are created by parsing events.php files in all the modules, and can be rebuilt any time (during an upgrade, say).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventname
|varchar(255)
|name of the event, e.g. 'message_send'
|-
|handlermodule
|varchar(255)
|e.g. moodle, mod/forum, block/rss_client
|-
|handlerfile
|varchar(255)
|path to the file of the function, eg /lib/messagelib.php
|-
|handlerfunction
|text
|serialized string or array describing function, suitable to be passed to '''call_user_func()'''
|-
|schedule
|varchar(255)
|'cron' or 'instant'.
|-
|status
|int(10)
|number of failed attempts to process this handler
|}

===events_queue===

This table is for storing queued events. It stores only one copy of the eventdata here, and entries from this table are being references by the events_queue_handlers table.

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|eventdata
|longtext
|serialized version of the data object passed to the event handler.
|-
|stackdump
|text
|serialized debug_backtrace showing where the event was fired from
|-
|userid
|int(10)
|$USER->id when the event was fired
|-
|timecreated
|int(10)
|time stamp of the first time this was added
|}

===events_queue_handlers===

This is the list of queued handlers for processing. The event object is retrieved from the events_queue table. When no further reference is made to the events_queue table, the corresponding entry in the events_queue table should be deleted. Entry should get deleted (?) after a successful event processing by the specified handler. The status field keeps track of failures, after it gets to a certain number (eg 10?) it should trigger an "event failed" event (that could result in admin being emailed etc, or perhaps even the originating module taking care of it or rolling something back etc).

{| border="1" cellpadding="2" cellspacing="0"
|'''Field'''
|'''Type'''
|'''Info'''
|-
|id
|int(10)
|auto increment identifier
|-
|queuedeventid
|int(10)
|foreign key id corresponding to the id of the event_queues table
|-
|handlerid
|int(10)
|foreign key id corresponding to the id of the event_handlers table
|-
|status
|int(10)
|number of failed attempts to process this handler
|-
|errormessage
|text
|if an error happened last time we tried to process this event, record it here.
|-
|timemodified
|int(10)
|time stamp of the last attempt to run this from the queue
|}

==Standards for naming events==

All event names should follow a consistent naming pattern, such as modulename_noun_verb

==Events which exist==

When we add new events to core we should always add them here too.

Under each event, list the data sent as part of the event.

===Users===
* user_created
** full new record from 'user' table
* user_updated
** full new record from 'user' table

===Courses===
* course_created
** full course record
* course_updated
** full course record
* course_deleted
** full course record
* course_category_deleted
** full category record

===Groups===
* groups_member_added
** groupid
** userid
* groups_member_removed
** groupid
** userid
* groups_group_created
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_updated
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_group_deleted
** id
** courseid
** name
** description
** timecreated
** timemodified
** picture
* groups_grouping_created
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_updated
** id
** courseid
** name
** timecreated
** timemodified
* groups_grouping_deleted
** id
** courseid
** name
** timecreated
** timemodified
* groups_members_removed (user deleted from all groups in a course)
** courseid
** userid
* groups_groupings_groups_removed (remove all groups from all groupings in a course)
** courseid (as plain integer, not object)
* groups_groups_deleted (delete all groups in a course)
** courseid (as plain integer, not object)
* groups_groupings_deleted (delete all groupings in a course)
** courseid (as plain integer, not object)

===Messaging===
* message_send
** component = 'mod/forum': path in Moodle
** name = 'posts': type of message from that module (as module defines it)
** userfrom = $userfrom: a user object to send from
** userto = $userto: a user object to send to
** subject = 'subject line': a short text line
** fullmessage = 'full plain text': raw text as entered by user
** fullmessageformat = FORMAT_PLAIN|FORMAT_HTML|FORMAT_MOODLE|FORMAT_MARKDOWN: the format of this text
** fullmessagehtml = 'long html text'; html rendered version (optional)
** smallmessage = 'short text': useful for plugins like sms or twitter (optional)

===Portfolio===
* portfolio_send
** id : recordid in portfolio_tempdata table, used for itemid in file storage

==Events wishlist==

List of events which it would be nice to have. Please add to this list if what you want is not shown here.

* user_assign_role
* user_unassign_role
* mform_print_form -- this for all types of form e.g. admin settings, user profile, module updating, + some sort of standard way of discriminiating between them e.g. if ($form->name == 'user_profile') {}. This would be better triggered at the end of the form generation process so that new bits can be inserted at any point, or existing bits could be removed.

== See also ==

* [http://moodle.org/mod/forum/discuss.php?d=69103 General Developer Forum thread for discussing this proposal].
* [[Development:Messaging_2.0]]

[[Category:Developer|Events]]
[[Category:Grades]]

Resource module file API migration

2009-05-18T08:53:16Z

Mattgibson: /* Current problems */

{{Moodle_2.0}}

=Current problems=
* text and html resource types separate
* embedded images and files in general are stored in course files without appropriate access control
* local files and Internet links mixed
* is IMS plug-in maintained?
* repository plug-in obsoleted
* embedded images are lost during backup & restore which moves the course to a new site. -- [[User:Matt Gibson|Matt Gibson]] 08:53, 18 May 2009 (UTC)

=Types of resources=
* Directory of files
* Resource page - using new editor element
* External resource link - some file stored elsewhere
* Single uploaded images and files
* Packages and uploaded html files
* Other 3rd party plugins

=Upgrade planning=
Each type requires different upgrade code.

==Directory type==
# Recursively copy directory to resource area, skip backup and moddata contents

==Text and web page==
# Convert to one plug-in using new editor forms element
# Copy directly linked files that may not contain other relative links to resource area
# PROBLEM: deal somehow with html, flash, and java; maybe just warn and manual migration button

==Links to files==
# Links to external sites do not need any upgrade
# If link points to simple file (image, sound, pdf.) copy to resource area
# PROBLEM: links to different courses - already problem now, maybe just warn teachers
# PROBLEM: links to files that may contain other relative links (html, flash, java)

==IMS type==
# copy files to resource area

==hive==
# PROBLEM: remove from core completely?

==3rd party==
# needs docs

=Solution of caching problems=
Teachers often do not understand that files may be cached in browsers, se the same mechanism already implemented in SCORM module.
# Internally store all files as itemid=0
# Add new revision db field into resource table
# When serving files always construct links with itemid==revision
# Ignore itemid for resource files in pluginfile.php

=Internal refactoring and UI changes=
...

=See also=

* [[Development:Using the file API]]
* [[Development:Repository API]]
* [[Development:Portfolio API]]
* [[Development:File API]]
* MDL-14589 - File API Meta issue
* MDL-16089 - Resource module conversion

YUI

2009-05-13T15:27:30Z

Mattgibson:

The Yahoo! User Interface (YUI) Library is a set of utilities and controls, written in JavaScript, for building richly interactive web applications using techniques such as DOM scripting, DHTML and AJAX. All components in the YUI Library have been released as open source under a BSD license and are free for all uses. Details of the YUI can be found at the [http://developer.yahoo.com/yui/index.html Yahoo Developer Website].

==Getting started==

Broadly speaking, you find an example you'd like to implement e.g. from [http://developer.yahoo.com/yui/examples/slider/index.html here], then add it to an existing page, then tweak it to do what you want.

YUI works with a single global object called YAHOO, which all other functions are added to via namespacing. You then use them like this:
YAHOO.util.Event.onDOMready(//do something );

===Dependencies===
In order to make the onDOMready method available to you, you first include a .js file that sets up the global object, then the events library .js file that adds all of the events methods to it. Moodle's way of doing this is with the require_js() function:
<?php require_js(array('yui_yahoo', 'yui_event')); ?>
You can see that you can use shortcuts for many of the libraries. the ajax_get_lib() function in /lib/ajax/ajaxlib.php has details. Otherwise, you use the full path like this:
<?php require_js(array($CFG->dirroot.'/lib/yui/yahoo/yahoo-min.js', $CFG->dirroot.'/lib/yui/event/event-min.js')); ?>
You notice that the files are called xxx-min.js. This is because they have been minified to make them as small as possible for fast page loading. Every file comes in a non-minifed version too called xxx-debug.js, which will give you accurate error messages as well as letting you follow progress in the YUI logger console.

Once you have included the various .js dependency files with require_js() as outlined above, then write your own source .js file and add that to the require_js array '''after''' the other YUI ones. Many of the YUI files have other dependencies, so you'll often need to include more than one and the order matters for them too. Just follow the examples.

You can also inject libraries dynamically if you really want to using [http://developer.yahoo.com/yui/yuiloader/ YUI loader], which adds <script> and <link> tags on the fly and can keep initial page load lighter.

===Skinning===
For CSS, you include the css dependency files in either your theme styles.php or module/block styles.php using the standard PHP include() function. You will often need to apply the yui-skin-sam style to the body tag to get the skins to work right, so add something near the top of your script like:
document.body.className += ' yui-skin-sam';
As a caveat, the paths in the CSS files assume that yui is placed in the site's web root and have no reference to $CFG->wwwroot, so none of the images work. The solution is to go through the CSS files, pulling out any that have
background: url(../../whatever.png);
and paste them into your styles.php below the css include you've added, but looking like this:
background: url(<?php echo $CFG->wwwroot ?>/lib/yui/whatever.png);

==Performance==
Remember to use [http://developer.yahoo.com/yui/examples/event/event-delegation.html event bubbling] wherever possible so that instead of adding a drag-drop listener to every page element, you just add one to the content div which catches all of the events lower down the DOM tree and does what's needed.

==Debugging==
Ideally, you should use Firefox, with the [https://addons.mozilla.org/en-US/firefox/addon/60 webdeveloper], [https://addons.mozilla.org/en-US/firefox/addon/1843 Firebug] and [https://addons.mozilla.org/en-US/firefox/addon/5369 YSlow] extensions loaded. The YUI logger will need to be included as a dependency if you want to use the xxx-debug.js versions of the files, so you need to add it to require_js() before them.

==Documentation for specific libraries==

*[[Yahoo Global Object]] (/lib/yui/yahoo/yahoo.js)
*[[Development:YUI event utility|YUI event utility]] (/lib/yui/event/event.js)
*[[Yahoo DOM Manipulation ]] (/lib/yui/dom/dom.js)
*[[Yahoo Connection Manager]] (/lib/yui/connection/connection.js)
*[[Yahoo Drag and Drop Utility]] (/lib/yui/dragdrop/dragdrop.js)
*[[Yahoo Animation Utility]] (/lib/yui/animation/animation.js)
*[[Development:YUI TreeView|YUI TreeView]] (/lib/yui/treeview/treeview.js)
*[[Yahoo logger]] (/lib/yui/logger/logger-min.js)

[[Category:Javascript|YUI]]
[[Category:AJAX|YUI]]

{{CategoryDeveloper}}

YUI

2009-05-13T15:27:01Z

Mattgibson:

The Yahoo! User Interface (YUI) Library is a set of utilities and controls, written in JavaScript, for building richly interactive web applications using techniques such as DOM scripting, DHTML and AJAX. All components in the YUI Library have been released as open source under a BSD license and are free for all uses. Details of the YUI can be found at the [http://developer.yahoo.com/yui/index.html Yahoo Developer Website].

==Getting started==

Broadly speaking, you find an example you'd like to implement e.g. from [http://developer.yahoo.com/yui/examples/slider/index.html here], then add it to an existing page, then tweak it to do what you want.

YUI works with a single global object called YAHOO, which all other functions are added to via namespacing. You then use them like this:
YAHOO.util.Event.onDOMready(//do something );

===Dependencies===
In order to make the onDOMready method available to you, you first include a .j file that sets up the global object, then the events library .js file that adds all of the events methods to it. Moodle's way of doing this is with the require_js() function:
<?php require_js(array('yui_yahoo', 'yui_event')); ?>
You can see that you can use shortcuts for many of the libraries. the ajax_get_lib() function in /lib/ajax/ajaxlib.php has details. Otherwise, you use the full path like this:
<?php require_js(array($CFG->dirroot.'/lib/yui/yahoo/yahoo-min.js', $CFG->dirroot.'/lib/yui/event/event-min.js')); ?>
You notice that the files are called xxx-min.js. This is because they have been minified to make them as small as possible for fast page loading. Every file comes in a non-minifed version too called xxx-debug.js, which will give you accurate error messages as well as letting you follow progress in the YUI logger console.

Once you have included the various .js dependency files with require_js() as outlined above, then write your own source .js file and add that to the require_js array '''after''' the other YUI ones. Many of the YUI files have other dependencies, so you'll often need to include more than one and the order matters for them too. Just follow the examples.

You can also inject libraries dynamically if you really want to using [http://developer.yahoo.com/yui/yuiloader/ YUI loader], which adds <script> and <link> tags on the fly and can keep initial page load lighter.

===Skinning===
For CSS, you include the css dependency files in either your theme styles.php or module/block styles.php using the standard PHP include() function. You will often need to apply the yui-skin-sam style to the body tag to get the skins to work right, so add something near the top of your script like:
document.body.className += ' yui-skin-sam';
As a caveat, the paths in the CSS files assume that yui is placed in the site's web root and have no reference to $CFG->wwwroot, so none of the images work. The solution is to go through the CSS files, pulling out any that have
background: url(../../whatever.png);
and paste them into your styles.php below the css include you've added, but looking like this:
background: url(<?php echo $CFG->wwwroot ?>/lib/yui/whatever.png);

==Performance==
Remember to use [http://developer.yahoo.com/yui/examples/event/event-delegation.html event bubbling] wherever possible so that instead of adding a drag-drop listener to every page element, you just add one to the content div which catches all of the events lower down the DOM tree and does what's needed.

==Debugging==
Ideally, you should use Firefox, with the [https://addons.mozilla.org/en-US/firefox/addon/60 webdeveloper], [https://addons.mozilla.org/en-US/firefox/addon/1843 Firebug] and [https://addons.mozilla.org/en-US/firefox/addon/5369 YSlow] extensions loaded. The YUI logger will need to be included as a dependency if you want to use the xxx-debug.js versions of the files, so you need to add it to require_js() before them.

==Documentation for specific libraries==

*[[Yahoo Global Object]] (/lib/yui/yahoo/yahoo.js)
*[[Development:YUI event utility|YUI event utility]] (/lib/yui/event/event.js)
*[[Yahoo DOM Manipulation ]] (/lib/yui/dom/dom.js)
*[[Yahoo Connection Manager]] (/lib/yui/connection/connection.js)
*[[Yahoo Drag and Drop Utility]] (/lib/yui/dragdrop/dragdrop.js)
*[[Yahoo Animation Utility]] (/lib/yui/animation/animation.js)
*[[Development:YUI TreeView|YUI TreeView]] (/lib/yui/treeview/treeview.js)
*[[Yahoo logger]] (/lib/yui/logger/logger-min.js)

[[Category:Javascript|YUI]]
[[Category:AJAX|YUI]]

{{CategoryDeveloper}}

SSH key

2009-03-26T12:57:50Z

Mattgibson: /* Windows */

==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 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===