MoodleDocs - User contributions [en]

Local plugins

2019-06-07T11:46:57Z

Monidu: fix to conform ro https://docs.moodle.org/dev/Plugin_contribution_checklist#Settings_storage

{{Infobox Project
|name = Local customisations
|state = Implemented
|tracker = MDL-17376, MDL-16438
|discussion = http://moodle.org/mod/forum/discuss.php?d=126017 http://moodle.org/mod/forum/discuss.php?d=86903
|assignee = [[User:Petr Škoda (škoďák)|Petr Škoda (škoďák)]], some parts were originally proposed and implemented in 1.9 by Penny Leach
}}
{{Moodle 2.0}}

The recommended way to add new functionality to Moodle is to create a new standard plugin (module, block, auth, enrol, etc.).The /local/ plugins are mostly suitable for things that do not fit standard plugins.

== Custom /local/ plugins ==

Local plugins are used in cases when no standard plugin fits, examples are:
* event consumers communicating with external systems
* custom definitions of web services and external functions
* applications that extend moodle at the system level (hub server, amos server, etc.)
* new database tables used in core hacks (discouraged)
* new capability definitions used in core hacks
* custom admin settings
* extending the navigation block with custom menus [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095]

=== Standard plugin features: ===
* /local/xxx/[[version.php]] - version of script (must be incremented after changes)
* /local/xxx/db/install.xml - executed during install (new version.php found)
* /local/xxx/db/install.php - executed right after install.xml
* /local/xxx/db/uninstall.php - executed during uninstallation
* /local/xxx/db/upgrade.php - executed after version.php change
* /local/xxx/db/access.php - definition of capabilities
* /local/xxx/db/events.php - event handlers and subscripts
* /local/xxx/db/messages.php - messaging registration
* /local/xxx/db/external.php - web services and external functions descriptions
* /local/xxx/cron.php - cron job, run at the interval defined in version.php. Alternatively, you can define <tt>local_xxx_cron()</tt> in lib.php. Between those two methods, the lib.php one is preferred. But both of them are considered legacy and have been deprecated for Moodle 3.5 (MDL-52846) and will be deleted for Moodle 3.9 (MDL-61165). [[https://docs.moodle.org/dev/Task_API#Legacy_cron More info here]]. They are being replaced with the [[Task_API]].
* /local/xxx/lang/en/local_pluginname.php - language file
* /local/xxx/lib.php - function library, automatically included with by config.php. Hook functions local_pluginname_extend_navigation() and local_pluginname_extend_settings_navigation() can be used to add items to the navigation and settings blocks
* /local/xxx/settings.php - configuration options. These get added to the admin menu.

The ''xxx'' is used instead of your local plugin name, plugins of the same type are installed/upgraded in alphabetical order.

=== List of differences from normal plugins: ===
* always executed last during install/upgrade - guaranteed by order of plugins in <code>get_plugin_types()</code>
* are expected to use event handlers - events are intended for communication core-->plugins only, local plugins are the best candidates for event handlers
* can add admin settings to any settings page - loaded last when constructing admin tree
* do not need to have any UI - other plugins are usually visible somewhere
* some extra hooks (not implemented yet)

== /local/xxx/db/messages.php ==
Example File Structure:
<code php>
<?php

/**
* Defines message providers (types of messages being sent)
*
* @package mod-forum
* @copyright 1999 onwards Martin Dougiamas http://moodle.com
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

$messageproviders = array (

/// Ordinary single forum posts
'posts' => array (
)

);
</code>

== Other /local/ customisation files==

===Customised site defaults===

Different default site settings can be stored in file /local/defaults.php.
These new defaults are used during installation, upgrade and later are
displayed as default values in admin settings. This means that the content
of the defaults files is usually updated BEFORE installation or upgrade.

These customised defaults are useful especially when using CLI tools
for installation and upgrade.

Sample /local/defaults.php file content:
<code php>
<?php
$defaults['moodle']['forcelogin'] = 1; // new default for $CFG->forcelogin
$defaults['scorm']['maxgrade'] = 20; // default for get_config('scorm', 'maxgrade')
$defaults['moodlecourse']['numsections'] = 11;
$defaults['moodle']['hiddenuserfields'] = array('city', 'country');
</code>
First bracket contains string from column plugin of config_plugins table.
Second bracket is the name of setting. In the admin settings UI the plugin and
name of setting is separated by "|".

The values usually correspond to the raw string in config table, with the exception
of comma separated lists that are usually entered as real arrays.

Please note that not all settings are converted to admin_tree,
they are mostly intended to be set directly in config.php.

=== 2.0 pre-upgrade script===

You can use /local/upgrade_pre20.php script for any code that needs to
be executed before the main upgrade to 2.0. Most probably this will
be used for undoing of old hacks that would otherwise break normal
2.0 upgrade.

This file is just included directly, there does not need to be any
function inside. If the execution stops the script is executed again
during the next upgrade. The first execution of lib/db/upgrade.php
increments the version number and the pre upgrade script is not
executed any more.

== Customisations outside of /local/ directory==

=== Forced settings===

Sometimes it is useful to force some settings and prevent any changes of these settings via the standard admin UI. It is possible to hardcode these settings in config.php.

In case of course settings it is very simply, the values are assigned directly to $CFG properties. In case of plugins the values are specified in a multidimensional array in $CFG->force_plugin_settings.

Sample code in config.php
<code php>
$CFG->allowobjectembed = 0;
$CFG->forced_plugin_settings = array('page'=>array('displayoptions'=>5, 'requiremodintro'=>1), 'folder'=>array('requiremodintro'=>1));
</code>

=== Local language customisations===

Moodle supports other type of local customisation of standard language
packs. If you want to create your own language pack based on another
language create new dataroot directory with "_local" suffix, for example
following file with content changes string "Login" to "Sign in":
moodledata/lang/en_local
<code php>
<?php
$string['login'] = 'Sign in';
</code>
See also https://docs.moodle.org/en/Language_editing

=== Custom script injection===

Very old customisation option that allows you to modify scripts by injecting
code right after the require 'config.php' call.

This setting is enabled by manually setting $CFG->customscripts variable
in config.php script. The value is expected to be full path to directory
with the same structure as dirroot. Please note this hack only affects
files that actually include the config.php!

; Examples:
* disable one specific moodle page without code modification
* alter page parameters on the fly

=== Direct code modifications===
This is usually the last resort, if possible do not do it. And if you still do it use some version control system (preferably git).

=== Direct database modifications===
Very strongly discouraged! Sometimes field lengths may be modified without side effects. Adding or removing of db fields will most probably cause major problems during future upgrades. New database tables should be added only from plugins.

== Examples ==

=== Adding an element to the settings menu ===

In local/*pluginname*/lib.php, define a function named local_*pluginname*_extend_settings_navigation, this will get called when Moodle builds the settings block.
This example adds a link to the bottom of the course administration section of the settings block.
<code php>
function local_myplugin_extend_settings_navigation($settingsnav, $context) {
global $CFG, $PAGE;

// Only add this settings item on non-site course pages.
if (!$PAGE->course or $PAGE->course->id == 1) {
return;
}

// Only let users with the appropriate capability see this settings item.
if (!has_capability('moodle/backup:backupcourse', context_course::instance($PAGE->course->id))) {
return;
}

if ($settingnode = $settingsnav->find('courseadmin', navigation_node::TYPE_COURSE)) {
$strfoo = get_string('foo', 'local_myplugin');
$url = new moodle_url('/local/myplugin/foo.php', array('id' => $PAGE->course->id));
$foonode = navigation_node::create(
$strfoo,
$url,
navigation_node::NODETYPE_LEAF,
'myplugin',
'myplugin',
new pix_icon('t/addcontact', $strfoo)
);
if ($PAGE->url->compare($url, URL_MATCH_BASE)) {
$foonode->make_active();
}
$settingnode->add_node($foonode);
}
}
</code>

=== Removing the "Site Home" link from the navigation menu ===
<code php>
function local_xxx_extend_navigation(global_navigation $navigation) {
if ($home = $navigation->find('home', global_navigation::TYPE_SETTING)) {
$home->remove();
}
}
</code>

=== Adding Site Wide Settings For Your Local Plugin ===

If you need to add site wide settings for your local plugin, perhaps connection details for an API, you will need to do something similar to the below in your settings file (local/yourplugin/settings.php)

<code php>
// Ensure the configurations for this site are set
if ( $hassiteconfig ){

// Create the new settings page
// - in a local plugin this is not defined as standard, so normal $settings->methods will throw an error as
// $settings will be NULL
$settings = new admin_settingpage( 'local_yourplugin', 'Your Settings Page Title' );

// Create
$ADMIN->add( 'localplugins', $settings );

// Add a setting field to the settings for this page
$settings->add( new admin_setting_configtext(

// This is the reference you will use to your configuration
'local_yourplugin/apikey',

// This is the friendly title for the config, which will be displayed
'External API: Key',

// This is helper text for this config field
'This is the key used to access the External API',

// This is the default value
'No Key Defined',

// This is the type of Parameter this config is
PARAM_TEXT

) );

}
</code>

== Local customisations in previous versions ==
Previous versions include only partial support for customisations in /local/ directory.

=== List of local customisations in 1.9.x: ===
* /local/cron.php - custom cron jobs
* /local/settings.php - custom admin settings
* /local/db/upgrade.php - general modifications
* /local/lang/* - custom strings
* /local/lib.php - local_delete_course()

=== Migration from old 1.9.x /local/: ===
* <code>local/*</code> needs to be copied to new directory
* <code>local/xxxx/db/install.php</code> is intended for first installation, originally everything was in upgrade.php
* events are used instead of hooks
* upgrade code needs to migrate old settings, events, etc. directly in core db tables - such as change component strings and capability names from db/install.php or manually before/after upgrade

==See also==

* [http://moodle.org/mod/forum/discuss.php?d=170325&parent=753095 Extending navigation block]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=86903 Local Customisations] forum discussion
* http://cvs.moodle.org/moodle/local/readme.txt?view=markup
* [[Local customisation (Moodle 1.9)]]

[[Category:Plugins]]

jQuery

2017-05-19T11:49:16Z

Monidu:

{{Moodle 2.9}}

Before Moodle 2.9 we used [[YUI]] to write javascript in Moodle. As of Moodle 2.9 we are transitioning to jQuery and [[Javascript Modules]] because Yahoo has ceased all new development on YUI (http://yahooeng.tumblr.com/post/96098168666/important-announcement-regarding-yui).

This page explains the recommended way to use jQuery in core and plugins, although other [[jQuery pre2.9|older]] methods of including jQuery will still work.

== Why do we need JQuery? ==
JQuery is useful for handling browser inconsistencies, and for utility functions that would otherwise be duplicated all over the code. Some particular things that JQuery is good at are:
* DOM Manipulations
* Promises ($.Deferred)
* Ajax

== How to use JQuery ==
As of Moodle 2.9, the recommended way to write javascript is in AMD Modules. For more information on writing AMD modules in Moodle see [[ Javascript Modules ]].

JQuery has been added as an AMD Module and is available to all AMD javascript.

To make use of JQuery, either list it as a dependency of your module, or use a require call to load it.

=== As a dependency of a module ===
<code>
define(['jquery'], function($) {
// Private functions.
var privateFunc = function(a) {
// JQuery is available via $ if I want it
return a + 1;
};

// Public functions.
return {
publicFunc: function(b) {
// JQuery is available via $ if I want it
return privateFunc(b) + 1;
}
}
});
</code>

=== With a require call ===
<code>
require(['jquery'], function($) {
// JQuery is available via $
});
// JQuery is not in scope and cannot be used.
</code>

== What about JQuery UI ? ==
JQuery UI is a separate project containing a library of reusable widgets that relies on JQuery. JQuery UI is available for plugins to use, but it should not be used in core code.

The problems with JQuery UI are:
* It uses an entirely different themeing system for CSS that does not work well with Moodle themes
* It introduces CSS conflicts with bootstrap
* The widgets have some accessibility features - but only if used in a very specific way which is not well documented

Over time we will build up a library of widgets in core either by wrapping a suitable library or implementing from scratch.

If you STILL want to use JQuery UI in your plugin, it is available as an AMD module named 'jqueryui'.

<code>
require(['jquery', 'jqueryui'], function($, jqui) {
// JQuery is available via $
// JQuery UI is available via $.ui
});
// JQuery is not in scope and cannot be used.
// JQuery UI is not in scope and cannot be used.
</code>

{{Moodle 3.2}}
In Moodle 3.2 we upgraded jQuery to 3.1 and removed the jQuery migrate plugin. You should not have to change your code unless you have been ignoring jQuery deprecation notices for many many years (but it's recommended to test it in 3.2).

==See also==
* [[Javascript Modules]]
* [[Useful core Javascript modules]]
* [[jQuery pre2.9]]
* [http://jquery.com jQuery]
* [http://jqueryui.com jQuery User Interface]

[[Category:Javascript]]

Moodle 3.1 release notes

2016-05-19T12:24:30Z

Monidu:

[[Releases]] > {{FULLPAGENAME}}

Release date: 23 May 2016 (Not yet released)

Here is [https://tracker.moodle.org/secure/IssueNavigator!executeAdvanced.jspa?jqlQuery=project+%3D+mdl+AND+resolution+%3D+fixed+AND+fixVersion+in+%28%223.1%22%29+ORDER+BY+priority+DESC&runQuery=true&clear=true the full list of fixed issues in 3.1].

See our [https://docs.moodle.org/31/en/New_features New Features page] for a more user-friendly introduction to Moodle 3.1 with screenshots.

Important:

* PHP extension <tt>xmlreader</tt> is now required (MDL-51603).

==Major features==

===Highlights===

* MDL-53451 - Competencies support in Moodle
* MDL-52954 - Improvements to the Assignment grading user interface
* MDL-31989 - [https://docs.moodle.org/31/en/Global_search Global Search] API allows to search forums, wikis and other content throughout the whole site. [https://docs.moodle.org/31/en/Global_search Installation and setup] of SOLR server is required,
* MDL-52002 - Significant performance improvements in gradebook calculations
* MDL-48012 - [https://docs.moodle.org/31/en/Recycle_bin Recycle bin] plugin is now part of standard Moodle distribution: allow instructors to "undo" deletions of course modules and courses. [https://moodleassociation.org/ Moodle Users Association] project
* MDL-49279 - Add support in moodle plugins for exporting "Mobile app addons"

===Forum===

* MDL-372 - Allow to [https://docs.moodle.org/31/en/Using_Forum#Pinned_posts "pin" discussions] to keep them always on the top of the list
* MDL-34160 - Allow forum email subject to be customised
* MDL-47365 - Add [https://docs.moodle.org/31/en/Using_Forum#Permalinks permalink] option to forum posts
* MDL-51214 - Rename the News forum to [https://docs.moodle.org/31/en/Announcements "Announcements"]
* MDL-44087 - Forum does not observe message notification settings for digest emails
* MDL-53050 - Highlight the selected forum post when deep linking with a #anchor

===Assignment===

* MDL-52397 - Feedback for Assignments is not sent if the assignment grade timemodified setting was set to two days ago
* MDL-52596 - Add a 'maxperpage' site wide setting for grading table size (to mitigate broken grading pages in large courses)
* MDL-52269 - Not obvious to tell if an assignment is in blind marking if user holds the "mod/assign:viewblinddetails" capabilty
* MDL-52270 - Difficult to cross reference users with their blind identities
* MDL-44598 - List student names on 'grant extension' screen
* MDL-52490 - Download selected assign submissions as a zip file
* MDL-52290 - EditPDF - Also show the total page number in the pagination
* MDL-52489 - "Download all submissions as a zip" should maintain the folder structure in students submissions

===LTI===

* MDL-52154 - Rework LTI admin screens
* MDL-45064 - Option to add Preconfigured LTI Tool to Activity Chooser
* MDL-52035 - Integrate LTI Provider support in Moodle as the [https://docs.moodle.org/31/en/Publish_as_LTI_tool Publish as LTI tool]
* MDL-52821 - Compliance: Send tool_consumer_instance_description in LTI launch request

===Feedback===

* MDL-53738 - Feedback activity module will be enabled by default in new 3.1 installations. If you are upgrading to 3.1 we recommend you to enable it manually.
* MDL-52094 - Various improvements to UI and bug fixes, including:
** Performance improvement to download responses as raw data in multiple formats (CSV, Excel, etc.) - now available on "Show responses" page instead of "Analysis"
** Allow any characters in labels, do not display empty labels
** Do not display empty pages
** Map frontpage feedback to multiple courses without leaving the form
** Improved display of automatic question numbers
** Disable "Response time" for anonymous feedbacks
** Use moodleforms to display feedback

===SCORM===

* MDL-45712 - Add Result field to the SCORM Interactions Report
* MDL-48680 - Add score and status submission events to SCORM activity
* MDL-42473 - Add group support to SCORM activity

===Quiz===

* MDL-52738 - Quiz attempt/review page should have a previous button to match next
* MDL-46092 - Add the OU styling of the Quiz navigation into Moodle core as the default
* MDL-46091 - Rationalise confirmations when you start a quiz
* MDL-52806 - Show right answers when manually grading automatically marked questions
* MDL-53304 - Immediate feedback behaviours should not show a disabled check button when you can't use it

===Other activity modules===

* MDL-42190 - Workshop: Possibility to delete a submission
* MDL-51306 - Folder: [https://docs.moodle.org/31/en/Folder_resource Bulk download all files within a folder activity as ZIP file]
* MDL-52414 - Lesson: Allow Default Settings for [https://docs.moodle.org/31/en/Lesson_settings Lesson Module Settings]
* MDL-51267 - URL/File: Make setting up a [https://docs.moodle.org/31/en/URL_resource_settings#General URL]/[https://docs.moodle.org/31/en/File_resource_settings#Uploading_files File] resource more obvious
* MDL-50794 - Workshop: [https://docs.moodle.org/31/en/Workshop_settings Restricting file types as attachments] to a workshop

===Gradebook===

* MDL-48634 - Option to rescale existing grades when changing max points
* MDL-52522 - grade_minmaxtouse should be respected for overridden categories
* MDL-51900 - Tab Down Grade Column in Single View of Gradebook
* MDL-52309 - Make Grade History report require user to submit parameters before the report starts running

===Performance===

* MDL-51374 - Do not purge entire databasemeta cache when there are structure changes (esp temp tables).
* MDL-51603 - Refactor downloading of csv, ods, excel etc files in reports and exports across moodle to stream progressively
* MDL-34925 - Improve bulk user export performance
* MDL-50385 - Performance improvement to the grade history report

===Tagging===

* MDL-50851 - Introduce tag collections - ability to separate independent tag areas
* MDL-52252 - Add tags to modules (Resources and Activities)
* MDL-25742 - Allow to search wiki pages by tags
* MDL-51283 - Rename "official" tags to "standard", allow admin to set for each tag area how to use standard tags
* MDL-16855 - Add tag filtering to "Manage tags" page
* MDL-52707 - Allow tags to be combined

===Usability===

* MDL-27628 - [https://docs.moodle.org/31/en/Course_meta_link Enrol meta:] Possible to add multiple courses without leaving the form
* MDL-51818 - Move the profile 'Message' button to be next to the user picture
* MDL-52258 - Calendar now shows duration in calendar block
* MDL-53043 - Move user search box above the students list in the manual enrolments popup
* MDL-35590 - Navigation block redesign to meet ARIA specification ([https://docs.moodle.org/dev/Tree documentation])
* MDL-49963 - Allow to message all participants when there are more than one page in participants list
* MDL-51354 - Help popup and improved name for events dropdown menu on the course and site logs pages
* MDL-53026 - Use inplace editable for editing cohort names
* MDL-51706 - Move plagiarism links to the top of the summary and full text outputs
* MDL-53382 - "Show all" link on participants page should be moved beneath the page switcher

===Other improvements===

* MDL-53057 - Add [https://docs.moodle.org/31/en/File_system_repository#Using_a_File_System_repository_file search feature to the File system repository]
* MDL-48506 - Improve memcached cache store so that it is multi-site safe
* MDL-50661 - Restyle "Clean" theme to use Logo and Header in Frontpage with smaller logo option in other pages.
* MDL-36652 - When downloading an Excel spreadsheet of student logs, have the course short name included in the file name.
* MDL-53207 - Display stock avatar instead of own user picture from messages from fake users
* MDL-52781 - ??? Improve core_user::fill_properties_cache()
* MDL-51698 - Markup the crumb trail so search engines understand it and leverage it
* MDL-53072 - Option to choose whether we include suspended users when auto-creating groups
* MDL-52869 - Convert inline activity name edit to use the inplace editable element

===For administrators===

* MDL-26935 - New capability to control role renaming
* MDL-28030 - Add config.php settings to allow plugins to rewrite output moodle_urls (eg clean / semantic urls)
* MDL-52752 - Administrators can specify an alternate URL to use for MathJax
* MDL-52219 - Completion tracking & availability should default to on for new installs
* MDL-52990 - Enable all emails to be themed, ie add 4 wrapper mustache templates
* MDL-53260 - Option to display CLI upgrade messages in English
* MDL-52386 - Allow to control field for flagging enabled/disabled users in LDAP authentication (useful for Active Directory)
* MDL-52383 - Calendar "Days to look ahead" should allow intervals up to 1 year
* MDL-49934 - Admins or managers should be able to retrieve assignments info via get_assignments web service

==Security issues==

There are no security issues included in this release, please refer to [https://docs.moodle.org/dev/Moodle_3.0.4_release_notes Moodle 3.0.4 release notes]

==For developers==
* MDL-31989 - [https://docs.moodle.org/dev/Search_API Global Search] API allows to search forums, wikis and other content throughout the whole site.
* MDL-53451 - Competencies support in Moodle ([https://docs.moodle.org/dev/Competency_API documentation])
* MDL-52954 - file_storage class can now convert between office documents ([https://docs.moodle.org/dev/File_API#Convert_between_file_formats_.28office_documents.29 documentation])
* MDL-30811 - Introduce notification stack to moodle sessions ([https://docs.moodle.org/dev/Notifications documentation])
* MDL-49279, MDL-50032 - Allow external functions to add themselves into services
* MDL-51802 - Reusable element for inplace editing ([https://docs.moodle.org/dev/Inplace_editable documentation])
* MDL-50887 - Antivirus: Implement plugins infrastructure for antivirus and create ClamAV plugin.
* MDL-52237 - Add a callback to inject nodes in the user profile navigation
* MDL-50464 - New renderer for RSS Client Block allows themes to customise its look
* MDL-50851 - Significant changes to Tags API, tag areas can now implement callbacks to display tagged items ([https://docs.moodle.org/dev/Tag_API documentation])
* MDL-53274 - Throw exception (in developer mode) if page context is not set, otherwise it is not noticeable in AJAX calls
* MDL-52826, MDL-52715 - Allow to use moodleforms in AJAX requests ([https://docs.moodle.org/dev/Fragment documentation])
* MDL-52013 - Allow mod_assign plugins to add calendar events
* MDL-51718 - Allow to specify scheme in moodle_url
* MDL-51700 - Ajax service should clean the return values of the external functions
* MDL-46891 - Upgrade to behat 3.x ([https://docs.moodle.org/dev/Acceptance_testing/Migrating_from_Behat_2.5_to_3.x_in_Moodle documentation])
* MDL-48362 - Improve the enrol API to prevent logic in the UI ([https://docs.moodle.org/dev/Enrolment_plugins#Standard_Editing_UI documentation])
* MDL-51324 - New course chooser element for moodleforms ([https://docs.moodle.org/dev/lib/formslib.php_Form_Definition#autocomplete documentation])
* MDL-52996 - Allow Atto customisation for special-purpose plugins
* MDL-53311 - Changes to navigation tree structure ([https://docs.moodle.org/dev/Tree documentation])

For full list of deprecations refer to lib/upgrade.txt and upgrade.txt files in the folder where the particular plugin is located. Here are the most major deprecations:

* MDL-53962 - '''Changes to webservices XML-RPC API''' - it is now '''critical''' to specify parameters for XML-RPC calls in the correct order. Previously Zend may have been able to work out the order, our new implementation, at this stage, cannot.
* MDL-49414 - Remove deprecated web services
* MDL-48621 - Deprecate the old events system
* MDL-52207 - Delete Zend framework

==See also==
*[[Moodle 3.0 release notes]]

[[Category:Release notes]]
[[Category:Moodle 3.1]]

[[fr:Notes de mise à jour de Moodle 3.1]]
[[es:Notas de Moodle 3.1]]

Setting up Eclipse

2007-07-20T10:50:40Z

Monidu: /* Installing the necessary plugins */

[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, so the information here should be pretty accurate.

==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 create 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 "Don't ask me this 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==

By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins.

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.

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 >'''.

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://phpeclipse.sourceforge.net/update/releases/; then click '''OK'''.

Back in the wizard, turn on just two things in the box "Sites to include in search":
* Your newly created '''Phpeclipse Update Site'''; and
* the one called '''Europa Discovery Site'''.
Then click '''Finish'''.

It goes off 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. The ones you want (you may have to search the tree structure) are, '''PHPeclipse''' (from your newly created PHPEclipse Update Site) and all the '''Web Standard Tools (WST)''' (usually under 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 build 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 ...'''.

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. With '''*.html''' selected in the top box, 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 '''Internet -> Proxy Settings'''. (Yes, I know you have entered the somewhere else before. Now you have to enter them again here. I don't know why. You just do.)

===PHP Settings===

These are all hidden under the '''PHPeclipse Web Development''' bit of the tree.

Under '''PHPeclipse Web Development -> Browser Preview Defaults''', turn off both checkboxes.

Under '''PHPeclipse Web Development -> PHP''', on the '''Appearance''' tab, set '''Displayed tab width''' to 4.

Under '''PHPeclipse Web Development -> PHP''', on the '''Typing''' tab, turn off all the options except '''Pasting for correct indentation''', '''Insert spaces for tab''' and '''Close PHPdocs and comments''' and '''Remove trailing spaces on editor save'''. It would be nice to turn on more of these options, but most of the rest don't work very well.

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

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

Under '''PHPeclipse Web Development -> PHP -> Templates''', I like to define a new template to help with debugging:
;Name
:dump
;Description
:Dump a PHP variable
;Pattern
<pre>echo '<pre>'; //DONOTCOMMIT
print_r(${cursor});
echo '</pre>';</pre>
You can do other useful things with templates too.

There is a really stupid bug. Under '''PHPeclipse Web Development -> 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.

===CVS Settings===

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

Under '''Team -> CVS -> SSH2 Connection Method''', you can set up a public/private key pair. If you do this, you won't have to keep typing your Sourceforge password when doing CVS operations. See http://sourceforge.net/docs/F02/ for the instructions of what you have to do at the Sourceforge end to make this work. That should make it clear what you have to do in Eclipse.

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 -> 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===

Foreach XXX in CSS, HTML, Javascript, XML:

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

==Checking out the Moodle code==

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

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 [[CVS_for_Administrators#CVS_Servers|these mirrors]]
;Repository path
:/cvsroot/moodle
;User
:anonymous
;Password
:(leave blank)
;Connection type
:pserver
</div>
;Host
:moodle.cvs.sourceforge.net
;Repository path
:/cvsroot/moodle
;User
:(your sourceforge username)
;Password
:(if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your sourceforge 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 the 1.6 stable branch, or another branch, repeat all the other steps with a few changes:
* This time you can choose '''Use and existing repository location''' instead of typing all the sourceforge CVS details again.
* Select the appropriate branch.
* Use a different project name.

==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-hightlighted.

===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 taked 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 fine 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.

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 the really important features. I sure you can learn everything else on your own. An you could always read the built in help!

===Creating a patch===

In the synchronise view, right click on an item (file or folder) and choose '''Create Patch...'''. Or in the navigator, right click on 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.

==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:Setting up Eclipse]]

Setting up Eclipse

2007-07-20T10:49:19Z

Monidu: /* Installing Eclipse */

[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, so the information here should be pretty accurate.

==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 create 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 "Don't ask me this 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==

By default, Eclipse comes with the Java tools. For everything else you will need to install some plugins.

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.

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 >'''.

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://phpeclipse.sourceforge.net/update/releases/; then click '''OK'''.

Back in the wizard, turn on just two things in the box "Sites to include in search":
* Your newly created '''Phpeclipse Update Site'''; and
* the one called '''Callisto Discovery Site'''.
Then click '''Finish'''.

It goes off 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. The ones you want (you may have to search the tree structure) are, '''PHPeclipse''' (from your newly created PHPEclipse Update Site) and all the '''Web Standard Tools (WST)''' (usually under Callisto 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 build 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 ...'''.

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. With '''*.html''' selected in the top box, 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 '''Internet -> Proxy Settings'''. (Yes, I know you have entered the somewhere else before. Now you have to enter them again here. I don't know why. You just do.)

===PHP Settings===

These are all hidden under the '''PHPeclipse Web Development''' bit of the tree.

Under '''PHPeclipse Web Development -> Browser Preview Defaults''', turn off both checkboxes.

Under '''PHPeclipse Web Development -> PHP''', on the '''Appearance''' tab, set '''Displayed tab width''' to 4.

Under '''PHPeclipse Web Development -> PHP''', on the '''Typing''' tab, turn off all the options except '''Pasting for correct indentation''', '''Insert spaces for tab''' and '''Close PHPdocs and comments''' and '''Remove trailing spaces on editor save'''. It would be nice to turn on more of these options, but most of the rest don't work very well.

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

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

Under '''PHPeclipse Web Development -> PHP -> Templates''', I like to define a new template to help with debugging:
;Name
:dump
;Description
:Dump a PHP variable
;Pattern
<pre>echo '<pre>'; //DONOTCOMMIT
print_r(${cursor});
echo '</pre>';</pre>
You can do other useful things with templates too.

There is a really stupid bug. Under '''PHPeclipse Web Development -> 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.

===CVS Settings===

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

Under '''Team -> CVS -> SSH2 Connection Method''', you can set up a public/private key pair. If you do this, you won't have to keep typing your Sourceforge password when doing CVS operations. See http://sourceforge.net/docs/F02/ for the instructions of what you have to do at the Sourceforge end to make this work. That should make it clear what you have to do in Eclipse.

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 -> 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===

Foreach XXX in CSS, HTML, Javascript, XML:

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

==Checking out the Moodle code==

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

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 [[CVS_for_Administrators#CVS_Servers|these mirrors]]
;Repository path
:/cvsroot/moodle
;User
:anonymous
;Password
:(leave blank)
;Connection type
:pserver
</div>
;Host
:moodle.cvs.sourceforge.net
;Repository path
:/cvsroot/moodle
;User
:(your sourceforge username)
;Password
:(if you set up the SSH2 key thing in preferences, leave this blank, otherwise, type in your sourceforge 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 the 1.6 stable branch, or another branch, repeat all the other steps with a few changes:
* This time you can choose '''Use and existing repository location''' instead of typing all the sourceforge CVS details again.
* Select the appropriate branch.
* Use a different project name.

==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-hightlighted.

===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 taked 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 fine 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.

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 the really important features. I sure you can learn everything else on your own. An you could always read the built in help!

===Creating a patch===

In the synchronise view, right click on an item (file or folder) and choose '''Create Patch...'''. Or in the navigator, right click on 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.

==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:Setting up Eclipse]]