MoodleDocs - User contributions [en]

User:Avindra Goolcharan

2013-05-01T00:31:01Z

Avindra: Created page with "I am a software developer working with Moodle and Totara."

I am a software developer working with Moodle and Totara.

testing LDAP on a Mac

2013-05-01T00:29:29Z

Avindra: format page

{{stub}}

It was quite a battle to install a LDAP server on my mac and make it work with Moodle. Here are the steps for OpenDS in Mac OSX Lion:

# I had Moodle installed with Apache LDAP module installed too.
# I downloaded OpenDS for Mac and installed it. I changed the hostname for jerome.moodle.local. Which is translated into dc=jerome,dc=moodle,dc=local. I didn’t change cn= Directory Manager. I set the password to ‘admin’. Finally I selected to generate 5 users (if you missed out this step, you can uninstall and reinstall the server. That’s what I did when I ended up to have some difficulties to create a new user.).
# To test if the LDAP server was correctly installed I run the following command line (in OpenDS/bin folder): <code>./ldapsearch -h 127.0.0.1 -p 1389 -b uid=user2,ou=People,dc=jerome,dc=moodle,dc=local -D “uid=user2,ou=People,dc=jerome,dc=moodle,dc=local” -w admin “(objectClass=*)”</code>
# I opended the control panel, and changed the user.2 username for user2. i also changed his password for ‘admin’.
# In the Moodle LDAP settings, I changed the following:

<pre>
Host URL: 127.0.0.1:1389 (it didn’t work without the port LDAP number)
Distinguished name: uid=user2,ou=People,dc=jerome,dc=moodle,dc=local
Password: admin
Contexts: ou=People,dc=jerome,dc=moodle,dc=local (you need this entire linet, just ‘ou=People’ doesn’t work.)
User attribute: uid
</pre>

Note: disconnect your computer from the network, otherwise the LDAP server could send requests everywhere and you could be banned.

Form API

2013-05-01T00:27:27Z

Avindra: /* add_action_buttons($cancel = true, $submitlabel=null); */ syntax highlighting

==Overview==
Web Forms in moodle are created using forms API. Form API supports all html elements (checkbox, radio, textbox etc), with improved accessibility and security.
==Highlights==
# Tested and optimised for use on major screen-readers Dragon and JAWS.
# Tableless layout.
# Process form data securely, with required_param, optional_param and session key.
# Supports client-side validation
# Facility to add Moodle help buttons to forms.
# Support for file repository using [[File_API]]
# Support for many custom moodle specific and non-specific form elements.
# Addition for repeated elements.
# Addition for form elements in advance group

==Usage==
For creating a form in moodle, you have to create class extending moodleform class and override [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#definition.28.29 definition] for including form elements.
<code php>
//moodleform is defined in formslib.php
require_once("$CFG->libdir/formslib.php");

class simplehtml_form extends moodleform {
//Add elements to form
public function definition() {
global $CFG;

$mform = $this->_form; // Don't forget the underscore!

$mform->addElement('text', 'email', get_string('email')); // Add elements to your form
$mform->setType('email', PARAM_NOTAGS); //Set type of element
$mform->setDefault('email', 'Please enter email'); //Default value
...
}
//Custom validation should be added here
function validation($data, $files) {
return array();
}
}
</code>
Then instantiate form (in this case simplehtml_form) on your page.
<code php>
//include simplehtml_form.php
require_once('PATH_TO/simplehtml_form.php');

//Instantiate simplehtml_form
$mform = new simplehtml_form();

//Form processing and displaying is done here
if ($mform->is_cancelled()) {
//Handle form cancel operation, if cancel button is present on form
} else if ($fromform = $mform->get_data()) {
//In this case you process validated data. $mform->get_data() returns data posted in form.
} else {
// this branch is executed if the form is submitted but the data doesn't validate and the form should be redisplayed
// or on the first display of the form.

//Set default data (if any)
$mform->set_data($toform);
//displays the form
$mform->display();
}
</code>

==Form elements==
===Basic form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#button button]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#checkbox checkbox]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#radio radio]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#select select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#multi-select multi-select]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#password password]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#hidden hidden]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#html html] - div element
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#static static] - Display a static text.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#text text]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#textarea textarea]

===Custom form elements===
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#advcheckbox advcheckbox] - Advance checkbox
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#passwordunmask passwordunmask] - A password element with option to show the password in plaintext.
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#recaptcha recaptcha]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectyesno selectyesno]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#selectwithlink selectwithlink]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_selector date_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#date_time_selector date_time_selector]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#duration duration]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#editor editor]
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filepicker filepicker] - upload single file
# [https://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms#filemanager filemanager] - upload multiple files
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#tags tags]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#addGroup addGroup]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modgrade modgrade]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#modvisible modvisible]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#choosecoursefile choosecoursefile]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#grading grading]
# [https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#questioncategory questioncategory]

==Commonly used functions==

====add_action_buttons($cancel = true, $submitlabel=null);====

You will normally use this helper function which is a method of moodleform to add all the 'action' buttons to the end of your form. A boolean parameter allow you to specify whether to include a cancel button and specify the label for your submit button (pass the result of get_string). Default for the submit button label is get_string('savechanges'). Note the '''$this''' not '''$mform'''

<code php>
$this->add_action_buttons();
</code>

====[[lib/formslib.php_Form_Definition#setDefault_2|setDefault()]]]====
To set the default value for an element.

====[[lib/formslib.php_Form_Definition#disabledIf|disableif()]]====
For any element or groups of element in a form you can conditionally disable the group or individual element depending on conditions.

====[[lib/formslib.php_Form_Definition#addRule|addRule()]]====
Add rule for server/client side validation. Like text field is required element and is of type email.

====[[lib/formslib.php_Form_Definition#setHelpButton|setHelpButton()]]====
Sets pop-up help button to a form element.

====[[lib/formslib.php_Form_Definition#addHelpButton|addHelpButton()]]====
Adds pop-up help button to a form element

====[[lib/formslib.php_Form_Definition#setType|setType()]]====
PARAM_* types are used to specify how a submitted variable should be cleaned.

====[[lib/formslib.php_Form_Definition#disable_form_change_checker|disable_form_change_checker()]]====
By default, any Moodle form will pop-up an "Are you sure?" alert if you make some changes and then try to leave the page without saving. Occasionally, that is undesirable, in which case you can call <tt>$mform->disable_form_change_checker()</tt>.

==FAQ==
[https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#Use_Fieldsets_to_group_Form_Elements How to group elements]
==See also==

* [[Core_APIs]]
* [[lib/formslib.php_Usage]]
* [[lib/formslib.php_Form_Definition]]

[[Category:API]]

Progress Bar

2013-05-01T00:24:44Z

Avindra: syntax highlighting

= Progress Bar Lib =
There are two Progress Bar libs avaiable in Moodle, the old one and a OOP one.

== Old Progress Bar ==
<code php>
function print_progress($done, $total, $updatetime=5, $sleeptime=1, $donetext='')
</code>
== OOP Progress Bar ==

Usage:
<code php>
set_time_limit(0);
$pb = new progressbar('bar', 500);
$pb->create();
$num_tasks = 200; // the number of tasks to be completed.
for($cur_task = 0; $cur_task <= $num_tasks; $cur_task++)
{
for ($i=0; $i<100000; $i++)
{
;;;
}
$pb->update_adv($cur_task, $num_tasks, 'this is'. $cur_task . 'h');
}
?>
<hr/>
<?php
$pt = new progressbar('zbar', 900);
$pt->create();
$num_tasks = 200; // the number of tasks to be completed.
for($cur_task = 0; $cur_task <= $num_tasks; $cur_task++)
{
for ($i=0; $i<100000; $i++)
{
;;;
}
$pt->update_adv($cur_task, $num_tasks, 'this is'. $cur_task . 'h');
}
</code>

Student projects/Admin page cleanup/XML file format

2013-05-01T00:23:31Z

Avindra: /* Sample XML Files */ syntax highlight, reword

Part of the [[Student projects/Admin page cleanup]] project involves coming up with a format for storing the hierarchy of admin settings and general information about the settings. (N.B. the XML file is for storing ''how'' the settings are organized, not the setting themselves -- those are still stored in the database for reasons of efficiency.)

== XML DTD ==
The following XML DTD defines the format for the file that'll store the Moodle Admin structure:

<!DOCTYPE moodleadmin [
<!ELEMENT moodleadmin (category|settinggroup|settingpage)*>
<!ELEMENT category (category|settinggroup|settingpage)*>
<!ATTLIST category name CDATA #REQUIRED
visiblename CDATA #REQUIRED
auth CDATA #REQUIRED>
<!ELEMENT settinggroup (setting*)>
<!ATTLIST settinggroup name CDATA #REQUIRED
visiblename CDATA #REQUIRED
auth CDATA #REQUIRED
icon CDATA #IMPLIED>
<!ELEMENT setting EMPTY>
<!ATTLIST setting name CDATA #REQUIRED
visiblename CDATA #REQUIRED
type (text|select|htmledit|checkbox|multiselect) #REQUIRED
selectoptions CDATA #IMPLIED
description CDATA #REQUIRED
setoninstall (true|false) #IMPLIED
writeproc CDATA #REQUIRED
readproc CDATA #REQUIRED>
<!ELEMENT settingpage EMPTY>
<!ATTLIST settingpage name CDATA #REQUIRED
visiblename CDATA #REQUIRED
auth CDATA #REQUIRED
icon CDATA #IMPLIED
hardcoded CDATA #REQUIRED>
]>

== Sample XML Files ==

The following code represents a short, sample XML file.

<code xml>
<moodleadmin>
<category name="php_code_must_return_string"
auth="php_code_must_return_boolean">
<settinggroup name="php_code_must_return_string"
auth="php_code_that_must_return_boolean">
<setting name="php_code_must_return_string"
type="(text|select|htmledit|checkbox)"
selectoptions="option1,option2,option3"
description="php_code_must_return_string"
setoninstall="(true|false)"
writeproc="php_code_must_return_boolean"
readproc="php_code_must_return_string" />
</settinggroup>
<settingpage name="php_code_must_return_string"
hardcoded="filename.php"
auth="php_code_must_return_boolean" />
</category>
</moodleadmin>
</code>

A more complete sample is available [http://betaserv.vkm.ca:82/moodle/lib/admin_sample_2.xml here]. The files were validated using [http://www.stg.brown.edu/service/xmlvalid/ this service].

== Explanations ==

Categories appear in the hierarchical menu as folders, while settinggroups and settingpages appear as actual clickable items. Thus, categories can be nested, while settinggroups and settingpages must appear either within a category or at the moodleadmin root level. Settings '''must''' appear in a settinggroup.

Next, the attributes. If an attribute has the same name in two different tags (e.g. auth in settingpage and settinggroup), it's because it serves the same purpose in both tags. To that end, I'll only describe what happens to each attribute, not each tag/attribute combination. Also, note that many attributes actually take PHP code and not just plaintext, allowing for much more expandability without having to redo the XML DTD every time we need a new feature.
* name should contain an internal name for the element. This name must be unique within the parent tag (e.g. the same name could exist in two different categories, but all tags one level below a category must have unique names)
* visiblename should contain the actual text to be displayed to the user (e.g. as the name of the folder, of a settingpage, of an actual setting, etc.) It is parsed through PHP and must contain code that returns a string, for example
&quot;User Settings&quot;
get_string('Administration')
* auth should contain PHP code that evaluates to either true or false to determine whether or not the current user should be given access to the settinggroup, settingpage or category. The auth field is also used to detect whether we're on a course page or the main page (since admin links are page-context-sensitive). For example
isadmin()
iscreator()
(($this->instance->pageid == SITEID) &amp;&amp; isadmin())

(in progress...)

== Remarks and Things Remaining To Be Done ==

* Defaults aren't being stored in the XML DTD since the PHP simplexml extension seems unable to process those defaults. Instead, PHP code that deals with the XML must appropriately replace default text when an implied attribute is blank.
* The main XML file will be stored in lib/admin.xml

[[Category:Project]]

Firefox

2013-05-01T00:20:24Z

Avindra: /* What is Firefox? */ cleanup section

== What is Firefox? ==
Firefox is a free internet browser owned by Mozilla. You can download it from http://www.mozilla-europe.org/en/products/firefox/.

There are a number of very useful developer tools available for Firefox, such as [[Firebug]], the [[Web developer toolbar]], [[Stylish]], and DOM Inspector. These are useful for investigating and fixing bugs in Moodle, especially when working on themes.

== Add-ons ==
You can customize Firefox with a host of [https://addons.mozilla.org/en-US/firefox/ add-ons].

=== Search plugins ===
A search plugin allows you to search certain websites directly from the search bar of the browser.

You can find all search plugins for Moodle at http://mycroft.mozdev.org/search-engines.html?name=moodle.

[[Image:Firefox search plugins.png]]

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

[[Category:Developer tools|Firefox]]
[[Category:Firefox extensions|Firefox]]

Setting up Eclipse

2013-05-01T00:17:07Z

Avindra: remove signatures

[http://www.eclipse.org/ Eclipse] is an IDE originally designed for Java, but now with plugins for many languages including PHP. It has lots of very powerful features, and it is the editor that some Moodle developers like to use. Other (more) popular choices are vim and emacs.

However, Eclipse is not the easiest program in the world to get started with, so I'm going to take you through it step by step. These instructions assume Eclipse 3.2, the current version at the time of writing. It should not change much between releases.

This article started off as a brain-dump by [[User:Tim Hunt|Tim Hunt]]. Since then, several other people have worked through it and made corrections and the information should be pretty accurate.

A new PHP plugin called PDT, which is better, but uses more memory. Follow the instructions [[#Installing_the_necessary_plugins,_for_Eclipse_Classic]] PART 1. The following instructions, from the section [[#Setting_the_preferences_for_Moodle_development]] mostly still apply after you have done the install, but some of the details are a bit different.

==Prerequisites==

Eclipse is written in Java, so I recommend getting the latest Java runtime environment from http://java.com/ for maximum speed and reliability.

Eclipse is quite big, so I recommend lots of memory in your computer. I have used it on Windows, MacOS X and Linux, in each case with 1GB of memory, and that is plenty.

==Installing Eclipse==

Go to http://www.eclipse.org/downloads/. Click on the link corresponding to your operating system where it says '''Eclipse Classic'''. Choose a Mirror, and wait for the ~100MB download.

You will notice that what you have got is a zip file (unless your system automatically decompresses it for you).

On Windows, unzip it into '''C:\Program Files''' (all the files go into an '''Eclipse''' folder there). Then look in the Eclipse folder and drag Eclipse.exe to the Start menu/Desktop/Quicklaunch bar to make a shortcut for starting it.

On MacOS, unzip and copy the Eclipse folder into Applications. Go into the Eclipse folder and drag the Eclipse app to the Dock for ease of launching.

On Linux, unzip somewhere suitable, and make an easy way to launch it.

==The first time you run Eclipse==

The first time you launch Eclipse it does a bit of setup stuff, for instance, it creates a '''workspace'''. This is where it stores the things you are working on. The default location is sensible on all platforms, so use that.

For some reason, every time you start Eclipse, it asks you which workspace you want to use. I have never seen the need to have more than one, so I recommend turning on the checkbox that says "Use this as the default and do not ask again".

Another thing that happens the first time you run Eclipse is that you arrive at a welcome screen. This has links to various bits of help, which you can read if you like, but you probably don't need to if you are following these instructions. So find the button on the welcome page that closes it and gets you to the main Eclipse screen.

==Installing the necessary plugins, for Eclipse Classic==

By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins. Before we begin make sure Eclipse is up to date. '''Help > Check for Updates'''. For old versions of Eclipse, Eclipse 3.4 or before go to Part 2.

====PART 1====
PHP Development Tools (PDT) is part of the Eclipse's standard plugins.
#Open up Eclipse and on the menu bar go to '''Help > Install New Software'''
#In the "Work with" box type in <nowiki>http://download.eclipse.org/releases/</nowiki>''<release name>''/
::for example http://download.eclipse.org/releases/juno/
#In the next box "type filter text" type in "'''php'''"
#Select the plugin "'''PHP Development Tools (PDT) SDK Feature'''"
#Make sure "Contact all update sites during install ..." is selected and click "'''Next'''"
# Follow the rest of the installation process.

====PART 2====
The following information of this section about plugins for PHP is for Eclipse 3.4 Ganymede or before.

If you are sitting behind a web proxy, from the '''Window''' menu choose '''Preferences ...'''. Choose '''Install/Update''' from the tree view on the left, and enter the proxy information in the boxes on the right. If you aren't behind a proxy, ignore this step. (On Eclipse 3.4.0 on OSX this is in '''Eclipse > Preferences > General > Network Connections''')

From the '''Help''' menu choose '''Check for Updates'''.

On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.

The next screen is a list of upgrade sites to check. You need to add one to the list, so click the '''New Remote Site ...''' Button.

In the pop-up dialog, give the remote site a name like '''PHPeclipse Update Site'''; set the URL to http://update.phpeclipse.net/update/nightly; then click '''OK'''. Click '''Finish'''. Under '''PHPEclipse Nightly Builds''', check '''PHPeclipse'''. Click '''Finish'''. Wait while it downloads (this may take a few minutes). Click '''Install'''. You will be prompted to restart Eclipse, click '''Restart'''.

''Note, there is now also another PHP editor for Eclipse. The update URL is http://download.eclipse.org/tools/pdt/updates/''

Restart the wizard (from the '''Help''' menu choose '''Software Updates -> Find and Install''').

On the first screen of the wizard, make sure that "Search for new features to install" is selected, then click '''Next >'''.

Select just two things in the box "Sites to include in search":
* Your newly created '''Phpeclipse Update Site'''; and
* the one called '''Europa Discovery Site''' (or possibly '''Callisto Discovery Site''').
Then click '''Finish'''.

It goes off and sees what updates are available at those sites. As it does so, it may occasionally pop up a dialog asking you to choose a mirror. Each time, select a sensible one.

Eventually, you get to a new wizard for selecting and installing the updates you want (Select the features to install). The ones you want (you may have to expand and search the tree structure) are: all the '''PHPEclipse Nightly Builds''' (from your newly created PHPEclipse Update Site) and the '''Web Standard Tools (WST)''' (usually under Callisto or Europa Discovery Site --> Web and J2EE Development).

Next, and very importantly, you must click the '''Select Required''' button which should resolve dependencies and remove the warning message you are probably worrying about. Then you can click the '''Next >''' button.

Read and agree to all the license agreements. Then click '''Next >'''.

Click '''Finish''', and wait for the plugins to download.

Once the downloads have finished, a warning will pop-up telling you that all the plugins you downloaded are not digitally signed. The Eclipse Foundation built digital signing of plugins into their architecture as a security measure, and then did not sign any of their own plugins! Anyway, click the '''Install All''' button.

Finally, a window will pop up asking you to restart Eclipse. Do so.

==Setting the preferences for Moodle development==

Now go to the '''Window''' menu, and choose '''Preferences ...''' ('''Eclipse''' menu on Mac OS X).

The Eclipse preferences are immense, with a tree view on the left, which selects which screen to display on the right. Don't panic, we'll guide you through it.

===General settings===

If you have strong feelings about fonts (I would hate to edit code an anything except Andale Mono), choose '''General -> Appearance -> Colors and Fonts''' from the tree on the left. Then on the right look under '''Basic''' and change '''Text Font'''. All the other editor font settings will inherit from this, so this is probably the only one you have to change.

Under '''General -> Content Types''', select PHP Source File, and add '''*.html''' to the box at the bottom.

Under '''General -> Editors -> File Associations''', if it is not already there, add '''*.php''' to the top box. With '''*.php''' selected in the top box, make sure '''PHP Editor''' is set to default in the bottom box (use the '''Default''' button - the default will appear at the top of the list).

With '''*.html''' selected in the top box, if it is not already there, add '''PHP Editor''' to the bottom box. Then select '''PHP Editor''' in the bottom box and click the '''Default''' button to change it, because in Moodle, most HTML files actually contain PHP code.

If you use a web proxy, enter the details under '''Network Connections'''. (Yes, I know you have entered them somewhere else before. Now you have to enter them again here. I don't know why. You just do.)

===PHP Settings===

Under '''General -> Editors -> Text Editors''', check '''Show line numbers''' to display line numbers in the left margin (optional). Click '''Apply'''. (When you are editing a PHP file, you could left-click in the left margin and tick the '''Show Line Numbers''' line in the contextual menu. However, this toggle only applies to plain text files, ''not'' to HTML or PHP files. The only place where you can toggle line numbers on/off for such files is in the PHP/Appearance menu.)

Under '''PHPeclipse -> Browser Preview Defaults''', turn off all checkboxes (if necessary). Click '''Apply'''.

Under '''PHPeclipse -> PHP''', on the '''Appearance''' tab, set '''Displayed tab width''' to 4 (if necessary). Click '''Apply'''.

Under '''PHPeclipse -> PHP''', on the '''Typing''' tab, turn off all the options except '''Pasting for correct indentation''', '''Insert spaces for tab''' and '''Close PHPdocs and comments'''. Click '''Apply'''.

Under '''PHPeclipse -> PHP -> Editor''', turn on '''Remove trailing spaces on editor save'''. Click '''Apply'''.

Under '''PHPeclipse -> PHP -> Formatter''', on the '''New Lines''' tab, turn on '''Clear all blank lines'''. Click '''Apply'''.

Under '''PHPeclipse -> PHP -> Formatter''', on the '''Style''' tab, turn off '''Indentation is represented by a tab'''. Click '''Apply'''.

Under '''PHPeclipse -> PHP -> Templates''', I like to define a new template to help with debugging:
;Name
:dump
;Description
:Dump a PHP variable
;Pattern
<pre>print_object(${word_selection}${cursor}); // DONOTCOMMIT</pre>
You can do other useful things with templates too. Here are two more I use:
<pre>debugging("'${word_selection}${cursor}'"); // DONOTCOMMIT</pre>
<pre>$$string['${word_selection}${cursor}'] = '.';</pre>
That is, a simple debug message with a stack trace, and a new language string.

There is a really stupid bug. Under '''PHPeclipse -> Project Defaults''', you would like to add "." to the '''Include Paths''', but you can't using the GUI. You will have to edit one of the Eclipse config files by hand. So
# Note down the path to your Eclipse profile. On Windows it will be something like '''C:/Documents and settings/XXXX/workspace''', and on Unixy systems something like '''~/workspace'''.
# Close Eclipse.
# Open the file '''net.sourceforge.phpeclipse.ui.prefs''' that is in the directory '''(your workspace)/.metadata/.plugins/org.eclipse.core.runtime/.settings''' in a text editor.
# Look for a line in the file that starts '''_php_include_paths=''' If it is not there, add it at the end.
# Change this line to say '''_php_include_paths=.'''
# Run Eclipse again.

===SSH2===
Information about generating SSH2 keys for the purpose of connecting to cvs.moodle.org can be found here at https://docs.moodle.org/en/Development:SSH_key , but please finish reading this section before reading that material.

The Eclipse installation has its own SSH client plugin so you do not have to use a separate ssh client in connection with your use of Eclipse (this is one reason you will be using extssh below, instead of just ext, however, if you wish you may alter the configuration to use an external client but please post news of your success and configuration). See, http://www.jcraft.com/eclipse-cvsssh2/ , for additional information on this plugin.

'' Since Eclipse 3.0M6 the CVSSSH plugin is incorporated into Eclipse, [http://www.jroller.com/prane/entry/eclipse_3_0_cvs_support as "extssh" instead of "extssh2"]''

Please note that Eclipse is fully equipped to generate ssh2 rsa and dsa keys as well as import keys. You may encounter issues with passphrases that are too long (a bug reportedly fixed but which may still in fact be present) and some issues with using keypairs generated by other applications have been seen, so it may be best to generate a key pair with Eclipse. Additional details on how to do this will be added.

Sourceforge, at http://sourceforge.net/docs/F02/ , provides instructions on how to create a SSH key for it's CVS (remember, Moodle does not use sourceforge for its CVS now and you will need to generate keys for cvs.moodle.org, not sourceforge). This is mentioned by way of general explanation, not for the purposes of providing instructions on how to generate your keys for Eclipse. To make use of the public key, login to Moodle.org and add it via the Update My Developer Information tab under CVS Developers (http://moodle.org/cvs). Remember, public keys provided to Moodle must be in the Openssh format.

===CVS Settings===

These are almost all hidden under the '''Team''' bit of the tree.

Under '''General -> Network Connections -> SSH2 -> Key Management''', you can set up a public/private key pair. If you do this, you won't have to keep typing your password when doing CVS operations.

The rest of the ones in this section are personal preferences, but I recommend them because the default settings are very irritating.

Under '''Team''', set '''Perspectives''' to '''None'''.

Under '''Team -> CVS''', on the '''Files and Folders''' tab, set '''Default text mode''' to '''ASCII with keyword expansion (-kkv)'''.

Under '''Team -> CVS -> Annotate''' set '''Use Quick Diff annotate mode for local file annotations''' to '''Yes''', and '''Open perspective after a 'Show Annotations' operation''' to '''No'''.

Under '''Team -> CVS -> Label Decorations''', switch to the '''Icon Decorations''' tab and turn on all the settings, and then on the '''Text Decorations''' tab change both '''File Decoration''' and '''Folder Decoration''' to be just '''{name}'''.

===Web and XML settings===

For each XXX in CSS, HTML, Javascript, XML:

Under '''Web and XML -> XML Files -> Source''', choose '''Indent using spaces''' and '''indentation size''' 4.

==Checking out the Moodle code==

From the '''File''' menu, choose '''New -> Project ...'''.

In the wizard that pops up, choose '''CVS -> Projects from CVS''', then click '''Next >'''.

Select '''Create a new repository location''', then click '''Next >'''.

Fill in
<div style="float: right; border: 1px solid orange; padding: 0 1em;">
For anonymous CVS access use
;Host
:XX.cvs.moodle.org
where XX.cvs.moodle.org is one of [[:en:CVS_for_Administrators#CVS_Servers|these mirrors]]
;Repository path
:/cvsroot/moodle
;User
:anonymous
;Password
:(leave blank)
;Connection type
:pserver
</div>
;Host
:cvs.moodle.org
;Repository path
:/cvsroot/moodle
;User
:(your Moodle CVS username)
;Password
:(if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your Moodle CVS password.)
;Connection type
:extssh
(CVS experts, if you are confused by that last one, know it is an Eclipse-specific thing.) Then click '''Next >'''.

On the next screen of the Wizard, choose '''Use an existing module'''. Wait a moment, then select '''moodle''' from the list. Click '''Next >'''.

On the next screen, make sure the option '''Check out as a project configured using the New Project Wizard''' is selected, then click '''Next >'''.

Click '''Refresh Tags''', then choose the branch you want. For now leave it set to '''HEAD'''.

Click '''Finish'''.

Now you will find yourself back at the start of the '''New Project''' Wizard. This is because of the option you chose three paragraphs ago. This time you should select '''PHP -> PHP Project''', then click '''Next >'''.

Make up a project name. '''moodle''' would be sensible.

Click '''Finish''', and wait while all the moodle files are checked out of CVS.

Once it has finished, it will probably ask you if you want to switch to the PHP perspective. Answer '''Yes'''.

If you also need another branch (1.6, 1.7, 1.8, ...) repeat all the other steps with a few changes:
* This time you can choose '''Use an existing repository location''' instead of typing all the sourceforge CVS details again.
* Select the appropriate branch. If you don't see the branch you want, see [https://docs.moodle.org/en/Development:Setting_up_Eclipse#Resetting_the_branch_information this Troubleshooting tip].
* Use a different project name (e.g. moodle16, moodle17, etc.).

==Let your development web server know where your files are==

Either by editing you web server's config files, or using a symbolic link. Make sure your webserver can see your new working set of files at a sensible URL, so you can test the code you are working on.

==Quick tour of some cool features, and remaining configuration changes==

I find the default workbench setup is pretty good. Here is a quick guide to some of the bits.

===Navigator===

To the left is the '''Navigator'''. This is a tree view of all your files. If you double-click on a file, it opens in the editor in the middle. Try opening '''course/lib.php''' now. You will notice that it comes up nicely syntax-highlighted.

===Error highlighting===

In the middle of the file, just type any old text, for example "I like Eclipse". Obviously, this is not valid PHP syntax, and Eclipse will notice this, and put a red underline under it. Also, by the scrollbar is a ruler with a red mark in it to show the error.

You will see some yellow marks lower down the ruler. There are warnings. Click on one, and you will be taken to where that warning is in the file. Hover your mouse over the warning, and you will get a tooltip explaining what the problem might be.

Save the edited file. (Don't worry that it is broken, we'll clean up the mess later.) Notice that a red error marker is added to the file in the navigator, so you can see that there is a problem. Also, error markers are added to the course folder, and the whole project, so you could see there was an error even if the navigator tree was collapsed.

You will probably find lots of warnings that the config.php file can't be found. In the navigator, find the file '''config-dist.php'''. Do '''Copy''' then '''Paste''' and choose to call the new file '''config.php'''. Edit this new config.php as normal. You should find that most of the include file warnings have gone now.

Notice also that there is another marker on each file icon. A little yellow cylinder on most files, but a white-on-brown star on the one you have edited. This is telling you the CVS status of each file. The brown stars are changes you have made but not checked in yet.

===Outline===

Over to the right is the Outline view. This shows a list of functions and classes defined in this file. By default, they are listed in the same order as in the file, but if you click on the '''az''' toolbar button, they are sorted into alphabetical order.

Click on the function name '''add_course_module''' in the Outline. You will see that the editor scrolls to the definition of that function.

===Code navigation===

In that function, hover the mouse pointer over the function name '''insert_record'''. After a while, the documentation for that function will appear in a big tooltip.

Hold down CTRL, move the mouse pointer over the function name '''insert_record''', then click. Eclipse should load '''dmllib.php''', and scroll you to where this function is defined. (You can also do this by clicking on the function name and pressing the F3 key.)

In the main Eclipse toolbar, there are forward and back arrows like in a web browser. Click back now to get back to '''course/lib.php'''.

===Open resource===

From the '''Navigate''' menu, choose '''Open Resource...'''. In the dialog that pops up, start typing a filename for instance type '''moodlel'''. In the box in the middle of the dialog, you will see it list all the files in the project whose names start that way. At the bottom is a box which lists the different folders that contain a file with that name. This can be a very quick way of opening files with fairly unique names like moodlelib.php, without having to click through the levels of the navigator tree. Of course, it is not so useful for an index.php file! Click OK now to open moodlelib.php. (It would actually work if you just did CTRL + Shift + R, moodlel, Enter.)

===Multi-file search===

Scroll down moodlelib a little bit, and double click on the name of the constant '''MOODLE_INTERNAL''' where it is defined, so that the text is selected. Then, from the '''Search''' menu, choose '''Search...'''. Notice that the '''Containing text''' box has already been filled in for you with the text you just selected. Of course you can just type text into this box without selecting it first. Notice that you can do regular expression searches, but leave that turned off for now. In the '''File name patterns''' box type '''*.css, *.html, *.inc, *.js, *.php, *.xml'''. (This is the most useful general setting for working on moodle. Eclipse will remember this setting, so you only have to enter it once.) Click '''Search'''.

The search results will appear in a new view underneath the editor. That view has a toolbar with yellow up and down arrows. Click the down arrow a few times and it will take you to the first few matches in the code, opening the relevant files as necessary.

===Synchronize view===

I think this is my favorite feature. From the '''Window''' menu, select '''Show View -> Other...'''. In the dialog that pops up, select '''Team -> Synchronize''', then click '''OK'''.

This opens the Synchronize view below the editor. The view has a toolbar. Click on the first toolbar button, which pops up the Synchronize wizard.

On the first screen, there will probably only be one option: '''CVS'''. Make sure that is selected, then click '''Next >'''.

Under '''Scope''', choose '''Workspace''', then click '''Finish'''.

Wait while it talks to the CVS server. After a while, you will see that the Synchronize view lists course/lib.php, and something called '''.project...''' That is, it is listing just the files you have edited, but not checked in yet.

'''.project''' is something that belongs to Eclipse that we don't care about. So select it and bring up the context menu, and choose '''Add to .cvsignore...'''. In the dialog that pops up, choose the top option, then click '''OK'''. Then you will find the Synchronize view shows you a '''.cvsignore''' file that you aren't interested in, so add that to .cvsignore too!

If you double-click on '''course/lib.php''' here, you will see that it opens the compare editor, which is a nice graphical display of the changes in this file.

If you select a file or files here, then bring up the context menu, you will see the option to '''Commit...''' the changes. (But don't do that now!). This is the easiest way to commit things in Eclipse.

However, our changes were rubbish, so we want to undo them. So open the context menu again, and choose '''Override and Update'''. This checks a clean copy of the file out of CVS, removing our changes.

Note that the easiest way to do an ordinary CVS Update is to select the top-level project-folder in the Navigator view on the left, open the context menu, and choose '''Team -> Update'''.

That's all of the really important features. I'm sure you can learn everything else on your own. And you can always read the built in help!

===Creating a patch===

In the synchronise view, right-click an item (file or folder) and choose '''Create Patch...'''. Or in the navigator, right-click an item and choose '''Team -> Create Patch...'''.

This brings up a two-page wizard. On the first page you can select where you want the patch made. For small patches it can be useful to create them on the clipboard, but normally you will want to save them in a file.

On the second page, you can set some options, but normally you don't need to change the defaults which are '''Unified''' diff format, and Patch root set to '''Workspace'''. Well, sometimes it is helpful to change the second one to '''Project''' but it is not important.

There is a corresponding apply patch wizard that you can use to apply a patch to a project.

===Switching to another branch or version===

Suppose you have been using a check-out of HEAD from CVS, and then as the 1.9 release approaches, the MOODLE_19_STABLE branch is created, and you want to start following that instead.
# Right click on the moodle project in the navigator view, and select '''Team -> Switch to Another Branch or Version ...'''.
# choose the second radio button: '''Select the tag from the following list'''.
# If the branch you want is not in the '''Matching tags''' box, see [[Setting_up_Eclipse#Resetting the branch information|Resetting the branch information]] below.
# Select the branch you want and click '''Finish'''.

==Troubleshooting==

Some tips on how to solve common problems that may crop up.

===Resetting the branch information===

Every now and then, Eclipse may lose information on the branch tags it knows about. Hitting refresh tags may fix it, but if not, try the following:

#Bring up the tag dialogue (example using "Team / Switch to Another Branch or Version").
#Click on Configure tags... (not Refresh tags).
#Select config-dist.php in the top left box (if this is a Moodle checkout).
#Click Add Checked tags.
#Click OK.
#Then you will have all tags.

(thanks to Tim Hunt)

This info saved my day to find all branches:
1. Window->Show View->Other. Select CVS->CVS Repositories.
2. Context Menu->New->Repository Location...
3. Fill in the location information identifying your repository and click Finish.
4. Expand the newly-created repository location.
5. Add the branch:
1. Right-click it and expand configure branches and versions.
2. Expand HEAD and select the project moodle.
3. Context Menu->Configure Branches and Versions...
4. In the "Browse files for tags" table, select one or more files
that contain tags you would like to see (for example scroll down
to find config.php).
5. On the right the existing tags will appear.
6. Select the tags: for example MOODLE_15_STABLE
7. Click "Add Selected Tags".
8. Click "OK".
6. Locate branches, MOODLE_19_STABLE, moodle MOODLE_19_STABLE.
7. Context Menu->Check Out As Project.
("stolen" from Joan Codina Filba
General developer forum -> Moodle floating "block"/toolbar released -> Re: Moodle floating "block--PATCH FOR GRADES & ASIGNMENT --PROBLEM)

===Error loading php files after Ubuntu 7.04 Install===

A java issue with Ubuntu 7.04 may cause an error when you attempt to load php pages. Refer to:
http://www.plog4u.org/index.php/Using_PHPEclipse_:_Installation_:_Installing_PHPEclipse for details about how to fix this in Ubuntu 7.04.

After upgrading from Ubuntu 7.04 to 7.10, I had to go in and re-edit the /etc/eclipse/java_home file in order to get the CVS functions to work and be able to open PHP files. When I tried to do a CVS update, I initially received an error about org.eclipse.team.internal.ccvs.ui.wizards.CheckoutWizard). Everything seemed to work again after reapplying the fix for the aforementioned 7.04 java issue.

===Strange mouse behavior in Eclipse with Ubuntu 9.10===

After upgrading to Ubuntu 9.10 I began have left mouse clicks that did not appear to be actually firing off the expected events. I stumbled across https://bugs.launchpad.net/ubuntu/+source/gtk+2.0/+bug/452938. Essentially what I did was modify /usr/bin/eclipse and added in the line: export GDK_NATIVE_WINDOWS=true so that it executes before starting Eclipse.

== Related Links ==

There is an excellent series of articles published by IBM on using Eclipse for Drupal developement here : [http://www-128.ibm.com/developerworks/ibm/osource/index.html Using open source software to design, develop, and deploy a collaborative Web site Tools and techniques for getting relatively complicated Web sites up and running quickly].

[[Category:Developer tools|Eclipse]]

Admin reports

2012-11-13T01:59:33Z

Avindra: syntax highlighting, formatting

{{Moodle 2.1}}
This document applies to Moodle versions before 2.2. See [[Reports]] for the new unified reports in Moodle 2.2 and later.

==Overview==

An admin report is a folder of code under admin/report. For example, you might make a folder in there called '''myreport'''.

In there, the only code you are required to have is an index.php file. This will normally display a simple HTML form for controlling the report, and, the code for displaying the report. You will probably also want a language file, which would be called lang/en_utf8/report_myreport.php following the example above.

In addition, you can add any other PHP code you like, and then link people to it from index.php.

So, the minimal code layout is:

admin/
...
report/
backups/
capability/
...
myreport/
lang/
en_utf8/
report_myreport.php
index.php
...
...

==What to do in index.php==

The simplest way to work this out is by example. You should look at some of the reports that ship with Moodle. [http://cvs.moodle.org/moodle/admin/report/capability/index.php?view=markup admin/report/capability], is a good one to start with. Let us go through that example to see what is there (I will put into italics the bits that are more advanced - the things that the capability report does, but which a simple report will not need to do.):
# Require some libraries. Admin reports will always need config.php and adminlib.php.
# Check the user is logged in and has appropriate permissions. ''(Normally admin reports are controlled by the 'moodle/site:viewreports' capability, the capability report is a special case.)''
# Get the parameters from the URL that control the report, and clean them up a bit.
# ''Include some JavaScript code that enhances the report for people with JavaScript turned on in their browser.''
# Log this request.
# Print the page header. Since this is an administration page, we need to do this using the admin_externalpage... functions. You probably just need to copy these two lines exactly, then replace 'capability' with your report name.
# Display a form to control the report.
# If the URL contains all the parameters needed to generate the report, do so, and display the results. ''(You don't need to understand the details of what the capability report is doing, because your report will do something different. However, the general structure will probably be the same: get some data out of the database, then display it.)''
# Print the footer, using the admin_externalpage... function.
# ''Define some functions, if that is the best way to structure the code of your report. You could, of course, create a separate lib.php file inside your report folder.''

==How your report gets included in the admin tree==

By default, your report will be included in the admin tree under the 'Reports' section, and it will only appear to people with the 'moodle/site:viewreports' capability. If the report is in the ''myreport'' folder, then the report name will be get_string("myreport", "report_''myreport''"). The report name, needed for the call to admin_externalpage_setup, will be "report''myreport''".

If you want more control over how your report appears, for example, if you want it to appear somewhere other than under Reports, or if you want it to be controlled by another capability, then you can create a settings.php file. For example, for the capability report, there is a settings.php file that contains:

<code php>
<?php // $Id$
$ADMIN->add('''"roles"''', new admin_externalpage('reportcapability',
get_string('capability', 'report_capability'),
"$CFG->wwwroot/$CFG->admin/report/capability/index.php",
"moodle/role:manage"
));
?>
</code>

(The two non-standard bits there have been put into bold.)

==Strings you must define in you lang/en_utf8/report_''myreport''.php==

You just need to define

<code php>
$string["myreport"] = 'What my report is called';
</code>

to make the report show up properly in the admin tree, but if your report does anything interesting, you will almost certainly need more.

== Creating a new report in admin block ==

I am using Moodle 1.9. I have created a new reporting module in my local moodle server. I tried following the examples on this page but was not able to get the new report folder to show in my menu, the admin_externalpage functions where failing. To accomplish the same thing, I completed these steps:

'''1 -''' Created a new folder under admin\report, called AU_ProfessionalDevelopment

'''2 -''' Copied index.php and settings.php from the admin\report\question folder into the AU_ProfessionalDevelopment folder.

'''3 -''' edited setting.php, updating the string '''question''' with folder name '''AU_ProfessionalDevelopment'''.

'''4 -''' edited index.php, stripping out most of the code, leaving the following:

<code php>
require_once('../../../config.php');
require_once($CFG->libdir.'/adminlib.php');
admin_externalpage_setup('reportAU_ProfessionalDevelopment');
admin_externalpage_print_header();
admin_externalpage_print_footer();
</code>

'''5''' Reloaded the moodle page (i am logged in as the admin - and can see the Admin. Block). I can see '''AU_ProfessionalDevelopment''' in the admin\report block. Clicking on it loads my page with the admin header and footer.

==See also==

* [http://moodle.org/mod/data/view.php?d=13&rid=913 System images report] this is another very simple report, in contrib. Might be a good one to look at.

[[Category:Plugins]]

Admin settings

2012-11-09T21:36:10Z

Avindra: syntax highlighting

Moodle's configuration is stored in a mixture of the config, config_plugins, and a few other tables. These settings are edited through the administration screens, which can be accessed by going to the .../admin/index.php URL on your moodle site, or using the Administration block that appears to administrators of the Moodle front page. This page explains how the code for displaying and editing of these settings works.

==Where to find the code==

This is explained further below, but in summary:
* The library code is all in lib/adminlib.php.
* The definition of the all the parts of the admin tree is in admin/settings/* some of which call out to plugins to see if they have settings they want to add.
* The editing and saving of settings is managed by admin/settings.php, admin/upgradesettings.php, and admin/search.php.
* The administration blocks that appear on the front page and on most of the admin screens is in blocks/admin_tree and blocks/admin_bookmarks.

In my experience most of this code is pretty easy to understand and work with, so here I will focus on giving an overview. For details, see the code.

==The building blocks==

All the settings are arranged into a tree structure. This tree structure is represented in memory as a tree of PHP objects.

At the root of the tree is an '''admin_root''' object.

That has children that are '''admin_category'''s.

Admin categories contain other categories, '''admin_settingpage'''s, and '''admin_externalpage'''s.

Settings pages contain individual '''admin_setting'''s.

admin_setting is a base class with lots of subclasses like '''admin_setting_configtext''', '''admin_setting_configcheckbox''', and so on. If you need to, you can create new subclasses.

External pages are for things that do not fit into the normal settings structure. For example the global assign roles page, or the page for managing activity modules.

==How the tree is built==

When Moodle needs the admin tree, it calls admin_get_root in lib/adminlib.php, which
# creates a global $ADMIN object which is an instance of admin_root.
# does require_once admin/settings/top.php, which adds the top level categories to $ADMIN.
# does require_once on all the other files in admin/settings to add more specific settings pages and the settings themselves. Some of these settings files additionally make calls out to various types of plugins. For example
#* admin/settings/plugins.php gives activity modules, blocks, question types, ... a chance to add admin settings.
# adds the admin reports to the tree.

As an optimisation, before building each bit of the tree, some capability checks are performed, and bits of the tree are skipped if the current user does not have permission to access them.

Exactly how different types of plugin should add their settings to the tree should be documented in the [[Developer_documentation#Make_a_new_plugin|instructions for writing that sort of plugin]].

==Individual settings==

Let us look at a simple example: [http://cvs.moodle.org/moodle/mod/forum/settings.php?view=markup mod/forum/settings.php]. This is included by admin/settings/plugins.php, which has already created $settings, which is an admin_settingpage that we can add to. The file contains lots of lines that look a bit like:

<code php>
$settings->add(new admin_setting_configcheckbox('forum_replytouser', get_string('replytouser', 'forum'),
get_string('replytouser_desc', 'forum'), 1));
</code>

What this means is that to our settings page, we are adding a checkbox setting. To understand this in more detail, we need to know what arguments the constructor for an admin_setting takes. The definition of the constructor is:

<code php>
function admin_setting($name, $visiblename, $description, $defaultsetting) {
</code>

So, $name here is 'forum_replytouser'. This means that this setting is stored in the database in the row of the config table where name='forum_replytouser', and is accessible as $CFG->forum_replytouser.

$visiblename is get_string('replytouser', 'forum'), this is the label that is put in front of setting on the admin screen.

$description is get_string('replytouser_desc', 'forum'), this is a short bit of text displayed underneath the setting to explain it further.

$defaultsetting is the default value for this setting. This value is used when Moodle is installed. For simple settings like checkboxes and text fields, this is a simple value. For some more complicated settings, this is an array.

Let as now look at a more complicated example, from mod/quiz/settingstree.php:

<code php>
$quizsettings->add(new admin_setting_text_with_advanced('quiz/timelimit',
get_string('timelimit', 'quiz'), get_string('timelimit_desc', 'quiz'),
array('value' => '0', 'fix' => false), PARAM_INT));
</code>

This shows two new things:

$name here is 'quiz/timelimit'. This is more complicated than a simple setting name. It means that this setting is stored in the config_plugins table, in the row where plugin='quiz' and name='timelimit'. It is not accessible through $CFG, to get it you can use get_config('quiz', 'timelimit').

And this example shows a $defaultsetting that is an array.

Normally, if you want a particular sort of setting, the easiest way is to look around the admin screens of your Moodle site, and find a setting like the one you want. Then go and copy the code and edit it. Therefore, we do not include a complete list of setting types here.

==External pages==

admin_externalpages represent screens of settings that do not fall into the standard pattern of admin_settings. The admin_externalpage object in the settings tree holds the URL of a PHP page that controls various settings.

In that PHP page, near the start you need to call the function admin_externalpage_setup($pagename), then, instead of the usual print_header and print_footer functions, you use admin_externalpage_print_header() and admin_externalpage_print_footer() functions. This ensures that your page appears with the administration blocks and appropriate navigation.

Note that if your external page relies on additional optional or required params, you may need to use the optional arguments to admin_externalpage_print_header to ensure that the Blocks editing on/off button works.

Note that there are some subclasses of admin_externalpage, for example admin_page_managemods. In a lot of cases, these subclasses only exist to override the search method so this page can be found by appropriate searches.

Once again, to understand this in more depth, your best approach is to look at how some of the external pages in Moodle work.

==See also==

* [[Modules|adding settings for actvitiy modules]]
* [[Admin_reports#How_your_report_gets_included_in_the_admin_tree|adding admin reports to the tree]]
* [[Repository_plugins#APIs_for_Administration|configuration of repository plugins]]
* [[Filters#Adding_a_settings_screen|configuration for filter]]
* [[Developer_documentation|Other developer documentation]]

Reports

2012-11-09T17:48:48Z

Avindra: syntax highlighting

{{Moodle 2.2}}

In Moodle 2.2 the [[Course reports]] and [[Admin reports]] were combined into one Reports directory (/report) that serves both needs.

==Overview==

A report is a folder of code under /report. For example, you might make a folder in there called '''myreport'''.

In there, the only code you are required to have is an index.php file. This will normally display a simple HTML form for controlling the report, and, the code for displaying the report. You will probably also want a language file, which would be called lang/en_utf8/report_myreport.php following the example above.

In addition, you can add any other PHP code you like, and then link people to it from index.php.

So, the minimal code layout is:

report/
backups/
completion/
...
myreport/
lang/
en/
report_myreport.php
index.php
version.php
...

==What to do in index.php==

The simplest way to work this out is by example. You should look at some of the reports that ship with Moodle. [https://github.com/moodle/moodle/blob/master/report/configlog/index.php report/log] is a good one to start with. Let us go through that example to see what is there (I will put into italics the bits that are more advanced):

# Require some libraries.
# Check the user is logged in and has appropriate permissions - all external admin pages use admin_externalpage_setup() which by default requires 'moodle/site:config' capability
# Get the parameters from the URL that control the report, and clean them up a bit.
# Print the page header. Since this is an administration page, we need to do this using the admin_externalpage... functions.
# Display a table with data and paging controls
# Print the footer

==How your report gets included in the navigation ==

Reports can present itself in different contexts:
* system level - controlled by settings.php
* at user level - controlled by *_extend_navigation_user() callbacks
* at course level - controlled by *_extend_navigation_course() callbacks
* at module level - controlled by *_extend_navigation_module() callbacks

In our example the configlog report is usable only at the system level, the admin tree integration is done through settings.php file
<code php>
$ADMIN->add('reports', new admin_externalpage('reportconfiglog', get_string('configlog', 'report_configlog'), "$CFG->wwwroot/report/configlog/index.php"));
$settings = null;
</code>
The <code>$settings = null</code> tells moodle that plugin does not have any settings and only want to display link to external admin page.

If you want to include your report in course navigation for example you need to create lib.php file and add following function:

<code php>
function report_myreport_extend_navigation_course($navigation, $course, $context) {
if (has_capability('report/myreport:view', $context)) {
$url = new moodle_url('/report/myreport/index.php', array('id'=>$course->id));
$navigation->add(get_string('pluginname', 'report_myreport'), $url, navigation_node::TYPE_SETTING, null, null, new pix_icon('i/report', ''));
}
}
</code>

You will also need access.php file with definition of 'report/myreport:view' capability.

==Strings you must define in you lang/en/report_''myreport''.php==

You just need to define
<code php>
$string['pluginname'] = 'What my report is called';
</code>

to make the report show up properly in the admin tree, but if your report does anything interesting, you will almost certainly need more.

==See also==

* [http://moodle.org/mod/data/view.php?d=13&rid=913 System images report] this is another very simple report, in contrib. Might be a good one to look at.
* [[General report plugins]] - new reports in 2.2+

[[Category:Plugins]]

Plugin types

2012-11-09T17:45:45Z

Avindra: syntax highlighting

The M in Moodle stands for modular. The easiest and most maintainable way to add new functionality to Moodle is by writing one of these types of plugin.
If none of the standardized types fits your needs, you can use the "local" type.

You can get the most recent list of types with the following script, or refer to the table below.
<code php>
<?php
define('CLI_SCRIPT', true);
require('path/to/config.php'); // global moodle config file.
print_object(get_plugin_types());
</code>

{| class="nicetable"
|-
! Plugin type
! Component name
! Moodle path
! Description
! Moodle versions
|-
| [[Activity modules]]
| mod
| /mod
| Activity modules are the most important type of plugins. They provide activities in courses. For example: Forum, Quiz and Assignment.
| All
|-
| [[Admin reports]]
| report
| /admin/report
| Provides useful views of data in a Moodle site, for admins only.
| Up to 2.1 (for 2.2+ see [[Reports]])
|-
| [[Admin tools]]
| tool
| /admin/tool
| Provides utility scripts useful for admins to examine and modify a Moodle site
| 2.2+
|-
| [[Assignment types|Assignment 2.2 types]]
| assignment
| /mod/assignment/type
| Different forms of assignments to be graded by teachers
| 1.x - 2.2
|-
| Assignment 2.3 submissions
| assignsubmission
| /mod/assign/submission
| Different forms of assignment submissions
| 2.3+
|-
| Assignment 2.3 feedbacks
| assignfeedback
| /mod/assign/feedback
| Different forms of assignment feedbacks
| 2.3+
|-
| [[Authentication plugins]]
| auth
| /auth
| Allows connection to external sources of authentication
| 2.0
|-
| [[Blocks]]
| block
| /blocks
| Small information-displays or tools that can be moved around pages
| 2.0+
|-
| [[Course formats]]
| format
| /course/format
| Different ways of laying out the activities and blocks in a course
| 1.3+
|-
| [[Course reports]]
| coursereport
| /course/report
| Reports of activity within the course
| Up to 2.1 (for 2.2+ see [[Reports]])
|-
| [[Database fields]]
| datafield
| /mod/data/field
| Different types of data that may be added to the Database activity module
| 1.6+
|-
| [[Database presets]]
| datapreset
| /mod/data/preset
| Pre-defined templates for the Database activity module
| 1.6+
|-
| [[Editors]]
| editor
| /lib/editor
| Alternative text editors for editing content
| 2.0+
|-
| [[Enrolment plugins]]
| enrol
| /enrol
| Ways to control who is enrolled in courses
| 2.0+
|-
| [[Filters]]
| filter
| /filter
| Automatically convert, highlight, and transmogrify text posted into Moodle.
| 1.4+
|-
| [[Gradebook export]]
| gradeexport
| /grade/export
| Export grades in various formats
| 1.9+
|-
| [[Gradebook import]]
| gradeimport
| /grade/import
| Import grades in various formats
| 1.9+
|-
| [[Gradebook reports]]
| gradereport
| /grade/report
| Display/edit grades in various layouts and reports
| 1.9+
|-
| [[Grading methods]]
| gradingform
| /grade/grading/form
| Interfaces for actually performing grading in activity modules (eg Rubrics).
| 2.2+
|-
| [[Local plugins]]
| local
| /local
| Generic plugins for local customisations
| 2.0+
|-
| [[Messaging consumers]]
| message
| /message/output
| Send messages to users via different methods (email, sms, jabber, etc)
| 2.0+
|-
| [[Plagiarism plugins]]
| plagiarism
| /plagiarism
| Define external services to process submitted files and content
| 2.0+
|-
| [[Portfolio plugins]]
| portfolio
| /portfolio
| Connect external portfolio services as destinations for users to store Moodle content
| 1.9+
|-
| [[Question behaviours]]
| qbehaviour
| /question/behaviour
| Control how student interact with questions during an attempt
| 2.1+
|-
| [[Question formats]]
| qformat
| /question/format
| Import and export question definitions to/from the question bank
| 1.6+
|-
| [[Question types]]
| qtype
| /question/type
| Different types of question (e.g. multiple-choice, drag-and-drop) that can be used in quizzes and other activities
| 1.6+
|-
| [[Quiz access rules]]
| quizaccess
| /mod/quiz/accessrule
| Add conditions to when or where quizzes can be attempted, for example only from some IP addresses, or student must enter a password first
| 2.2+
|-
| [[Quiz reports]]
| quiz
| /mod/quiz/report
| Display and analyse the results of quizzes, or just plug miscellaneous behaviour into the quiz module
| 1.1+
|-
| [[Reports]]
| report
| /report
| Provides useful views of data in a Moodle site for admins and teachers
| 2.2+
|-
| [[Repository plugins]]
| repository
| /repository
| Connect to external sources of files to use in Moodle
| 2.0+
|-
| [[SCORM reports]]
| scormreport
| /mod/scorm/report
| Analysis of SCORM attempts
| 2.2+
|-
| [[Themes]]
| theme
| /theme
| Change the look of Moodle by changing the the HTML and the CSS. See also [[Themes 1.9]].
| 2.0+
|-
| [[User profile fields]]
| profilefield
| /user/profile/field
| Add new types of data to user profiles
| 1.9+
|-
| [[Webservice protocols]]
| webservice
| /webservice
| Define new protocols for web service communication (such as SOAP, XML-RPC, JSON, REST ...)
| 2.0+
|-
| [[Workshop allocation methods]]
| workshopallocation
| /mod/workshop/allocation
| Define ways how submissions are assigned for assessment in the [[Workshop]] module
| 2.0+
|-
| [[Workshop evaluation methods]]
| workshopeval
| /mod/workshop/eval
| Implement the calculation of the grade for assessment (grading grade) in the [[Workshop]] module
| 2.0+
|-
| [[Workshop grading strategies]]
| workshopform
| /mod/workshop/form
| Define the type of the grading form and implement the calculation of the grade for submission in the [[Workshop]] module
| 2.0+
|}

==See also==
* [[Guidelines_for_contributed_code|Guidelines for contributing code]]
* [[Core APIs]]
* [[Frankenstyle]]
* [http://moodle.org/plugins Moodle Plugins database] - lists all the modules that people have contributed

[[Category:Coding guidelines|Plugins]]
[[Category:Plugins]]

Finding your way into the Moodle code

2012-11-09T17:44:13Z

Avindra: syntax highlighting

This article is aimed at people totally new to Moodle development and have some PHP experience, if you don't have that experience please visit [[PHP for novices|PHP for novices]]. It is a few tips to help you get started with the mass of Moodle code.

Please feel free to add more tips here, but I think it is also good if we can keep this article quite short.

==Developer documentation==

If you have not already found it, the main source of developer documentation is [[Developer_documentation]].

==Finding a way in==

For finding where to start, you need to know that when you are looking at, for example, http://moodle.org/mod/forum/discuss.php?d=82799, then the code for that is in /mod/forum/discuss.php, and you just need to follow through what it does.

It calls functions in the main Moodle libraries, and the three most important are:

*lib/moodlelib.php - general stuff.
*lib/weblib.php - things to do with output of HTML
*lib/dmllib.php - things to do with getting data in and out of the database.

==Understanding what you find==

As you look at the code, it is often a good idea, to insert statements like
<code php>
debugging('In function require_login');
</code>
which will print the message above if it gets far enough so you know the code has not stalled before there, or
print_object($course);
which will print out a variable, showing you what it contains.

Variable like $course are often objects with lots of fields. Seeing what they contain will help you understand what is going on. The first of these prints out whatever text you give it, and information about the sequence of function calls that the code took to get there. (It only works if you go to ''Administration > Server > [[:en:Debugging|Debugging]]'', and turn the debug level to ALL or DEVELOPER.)

==Tools that can help==

*'''Eclipse''', for instance helps finding function definitions. You can hold down CTRL and click on the name of a function, it immediately jumps you to where that function is defined. ([[Setting_up_Eclipse]])
*'''Emacs'''
*'''Vim'''
*'''TextMate'''

See also [[Developer documentation#Tools]] and [[:Category:Developer tools]].

==See also==
* [http://dev.moodle.org/course/view.php?id=2 Introduction to Moodle Programming] a course at dev.moodle.org
* [[Development FAQ]]
* [[Developer_documentation]]
* [[Overview]]
* [[ctags]]
* [http://blog.danpoltawski.co.uk/archives/2009-05-Secrets-of-Learning-Moodle-Development!.html "Secrets of Learning Moodle Development!"] by Moodle core developer [[User:Dan Poltawski| Dan Poltawski]]
* [http://www.slideshare.net/tjh1000/a-basic-introduciton-to-the-moodle-architecture-5442122 A basic introduction to the Moodle architecture] by Moodle core developer Tim Hunt
* [http://www.aosabook.org/en/moodle.html The Architecture of Open Source Applications: Moodle] by Tim Hunt