MoodleDocs - User contributions [en]

CodeSniffer

2013-11-07T16:26:44Z

Leblangi: /* Linux set up */

{{Moodle 2.0}}

==Overview==

===Scope===
This document describes the CodeSniffing/Code checker tools their purpose and usage.

===Function===
The function of the CodeSniffer tool is to analyse PHP5 (only) code, apply a set of rules that match the [[Coding_style | Moodle Coding Style]], and output a report showing which parts of the code do not conform to this style.

==Usage==

===Using codechecker===

codechecker is a local plugin that creates a web based interface for checking the syntax of a given file. It can be found at
https://github.com/moodlehq/moodle-local_codechecker

Once installed a new codechecker option will appear in site administration\development page.

This page allows for the code in a specified directory to be checked, e.g. if you wanted to check the code for the shortanswer question type you would enter
/question/type/shortanswer

You would then be presented with a list of the count of files processed and any warnings or errors.

===Installing codechecker===

To install using git, type this command in the root of your Moodle install
git clone git://github.com/moodlehq/moodle-local_codechecker.git local/codechecker

Then edit .gitignore in your development folder eg:
gedit /var/www/moodle/.gitignore

And add /local/codechecker/ - including the slash at the end

Alternatively, download the zip from

https://github.com/moodlehq/moodle-local_codechecker/zipball/master

unzip it into the local folder, and then rename the new folder to codechecker.

===Codechecker output===

The output is similar to the following

Files found: 21

question\type\calculated\backup\moodle1\lib.php - 1 error(s) and 10 warning(s)
then a list of all files checked with a count of errors and warnings..followed by a summary
Total: 31 error(s) and 262 warning(s)

Then a list describing the exact issue in each file

<nowiki>question\type\calculated\backup\moodle1\lib.php

2: The opening <?php tag must be followed by exactly one newline.
········//·convert·and·write·the·answers·first
50: Inline comments must start with a capital letter, digit or 3-dots sequence
etc etc

</nowiki>You can then edit the files to attempt to remove each issue.

===IDE plugin alternatives===

Using the web based interface means switching between the browser and the editing environment. You may find it easier to use a plugin that allows you to check your code against the standards as you go along.

For Eclipse users
http://www.phpsrc.org/

For Netbeans users

Make sure you have the PEAR php Codesniffer code installed, you can find instructions at
http://pear.php.net/package/PHP_CodeSniffer/download/All

Then install the netbeans plugin which can be found at

https://github.com/beberlei/netbeans-php-enhancements/downloads

Once installed you can check it within Netbeans by going to
Tools/Options/PHP and click on the codesniffer tab.

====Windows set up====

There is an option for the codesniffer script. On my windows xampp install this needs to point to

C:\xampp\php\phpcs.bat

Underneath this should be a list of some of the coding standards available, but by default this will not include Moodle. To install the moodle standard, copy the"moodle" and "phpcompatibility" folders from local\codechecker into your standards directory which for me was under

php\PEAR\PHP\CodeSniffer\Standards

[[Image:codesniffer.jpg]]

Now when you restart your Netbeans you should see a new moodle coding standard. Right clicking on a file name should present you with a new option of "Show Code Standard Violations".

====Linux set up====

After installing codesniffer and codechecker, copy the moodle and phpcompatibility standard folders from (assuming you have the code in /local/codechecker)

/var/www/moodle/local/codechecker/

to

/usr/share/pear/PHP/CodeSniffer/Standards/

There is an option to set the default standard in a configuration file:

phpcs --config-set default_standard moodle

Then restart Netbeans and it should now work. You can also switch between coding standards.

===Simple example===
The script is located in lib/pear/PHP and is called runsniffer. To check the syntax of a given file (e.g. index.php), run:

<code>
lib/pear/PHP/runsniffer index.php
</code>

You will get a report that looks like this:

<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AND 24 WARNING(S) AFFECTING 130 LINE(S)
--------------------------------------------------------------------------------
1 | WARNING | $Id$ tag is no longer required, please remove.
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | A cast statement must be followed by a single space
55 | ERROR | line indented incorrectly; expected 0 spaces, found 4
....
</code>

The first column shows the line at which the ERROR or WARNING was found. The CodeSniffer uses a set of rules which are still being defined, so that what is currently defined as ERROR or WARNING is likely to change in the near future.

You should fix all ERRORs, but may safely ignore the WARNINGs. Fixing warnings will help your code be even more readable and consistent with other code that follow this standard.

===Advanced Usage===
====Ignoring warnings====
You can run the CodeSniffer with the -n flag to ignore warnings:

<code>
lib/pear/PHP/runsniffer -n index.php
</code>

Resulting output:
<code>
--------------------------------------------------------------------------------
FOUND 139 ERROR(S) AFFECTING 125 LINE(S)
--------------------------------------------------------------------------------
28 | ERROR | line indented incorrectly; expected 0 spaces, found 4
50 | ERROR | line indented incorrectly; expected 0 spaces, found 4
...
</code>

====Recursive analysis====
If you give the name of a folder instead of a file, it will search, analyse and report on all PHP files found in this folder and all its subfolders. This will produce a full report for each PHP file. Since this is likely to be too much information, you may want to print only a summary report, by using the following syntax (search the files/ folder as an example):

<code>
lib/pear/PHP/runsniffer --report=summary files
</code>

Report:
<code>
PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/files/index.php 11 58
/web/htdocs/moodle_blog2/files/draftfiles.php 6 22
--------------------------------------------------------------------------------
A TOTAL OF 17 ERROR(S) AND 80 WARNING(S) WERE FOUND IN 2 FILE(S)
--------------------------------------------------------------------------------
</code>

You can also use the -n flag to ignore warnings.

====Several files in one folder====
If you want to search all files under a folder, but not recurse through the subfolders, you can use the -l flag (local files only):

<code>
lib/pear/PHP/runsniffer --report=summary -l grade

PHP CODE SNIFFER REPORT SUMMARY
--------------------------------------------------------------------------------
FILE ERRORS WARNINGS
--------------------------------------------------------------------------------
/web/htdocs/moodle_blog2/grade/index.php 0 2
/web/htdocs/moodle_blog2/grade/lib.php 6 210
/web/htdocs/moodle_blog2/grade/querylib.php 5 39
--------------------------------------------------------------------------------
A TOTAL OF 11 ERROR(S) AND 251 WARNING(S) WERE FOUND IN 3 FILE(S)
--------------------------------------------------------------------------------
</code>

You can pass as many files and folders to the script as you want, the analysis and flags will apply to all of them.

===Special rules===
When recursing through folders, the CodeSniffer script looks for a file called thirdpartylibs.xml. Currently there is only one, found under lib/. It lists directories and files which are meant to stay 'as-is' in Moodle, in order to ensure minimum hassle when upgrading these libraries. You can use this file as a template to create your own list of exceptions.

===Other report formats===
CodeSniffer can export its reports in the following formats:
#full: default, shown first above
#summary: also shown above
#xml: Simple XML format
#csv: Comma-separated list
#checkstyle: XML format intended for use with CruiseControl

==See also==

#[[Coding]]
#[[Coding style]]

Admin settings

2013-06-11T13:42:58Z

Leblangi: /* See also */

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 activity 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]]

Adding courses and categories to the custom menu

2013-06-11T12:44:05Z

Leblangi: /* How to add "My Courses" to the Custom Menu Bar for Moodle 2.4 */

{{Themes}}
Hello this is going to be a very brief tutorial on how to add a courses and categories tree to the custom menu. 
The reason for writing this tutorial is simply that this seems to be a request that is being made over and over again.

==Before we get started==
Please please please make sure you are familiar with the other Themes 2.0 tutorials before attempting this tutorial.

In particular I would recommend being familiar with the following documents and tutorials as I'm going to move through this tutorial at a fast pace.

* [[Themes overview]]
* [[Creating a theme]]
* [[Overriding a renderer]]
* [[Extending the theme custom menu]]

Providing you are familiar with the above you should manage just fine with this tutorial and if you ever get stuck don't forget to ask in the theme's forums, there is always someone around who can help.

===Two words of warning===
'''First''' Just a quick warning here, this tutorial adds all categories and courses to the navigation, on a site with a large number of categories and/or courses this will be a performance hit. I would strongly suggest that if you are looking to implement something such as this on a large site that you talk to your system admin and/or resident developer about setting up a shared cache and caching the result of the get_course_category_tree method... it is a technical task but doing so will improve the performance of this extension on a large site.

'''Second''' If you have categories nested 2 or more deep then there is a chance that you will run into display problems with the custom menu on some themes... not too much you can do about it but if you encounter it with a core theme and you fix it perhaps you would be kind enough to create an issue in our bug tracker and share the fix. That'd being said this is only a hunch I have all of the theme's may be fine :)

==Laying the ground work==
Alright I don't want this tutorial to drag out so get ready. For this tutorial I am just going to extend the standard theme, I'm going to make absolutely no changes to the design and layout of the theme or the custom menu I am ONLY going to add a list of courses and categories to it.

So to begin with within your Moodle themes directory create a new directory coursecategorymenu in which I want you to create three files, the first config.php which is obviously required, the second renderers.php as we are going to achieve this by overriding a renderer, and the third the English language file for this theme.

You should end up with:

* moodle/theme/coursecategorymenu
* moodle/theme/coursecategorymenu/config.php
* moodle/theme/coursecategorymenu/renderers.php
* moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php

==config.php==
Obviously because all I want to base this theme off the standard theme and only override a renderer the config.php file is going to be VERY basic, so much so that I'm not going to go into details about it, as you've read the recommended tutorials you will already be completely familiar with everything it is doing.

<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>

==renderers.php==
This is of course where the magic is going to happen.

In my case I want to add a branch to the end of the custom menu titled ''Courses'' and then I want to add the category and course structure to that branch.

So like the [[Themes 2.0 extending the custom menu|extending the custom menu]] tutorial I will be overriding the core renderer and I will also be overriding the render_custom_menu_method.

So the code for this:
<code php>
class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
// Our code will go here shortly
}

}
</code>

You'll notice that is identical to the starting code for the extending custom menu tutorial.

The difference comes in the code that we are going to populate it with:

<code php>
require_once($CFG->dirroot.'/course/lib.php');

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
</code>

So lets work through this code line by line:

<code php>
require_once($CFG->dirroot.'/course/lib.php');
</code>

This we need to do because we are going to use part of the course API, in particular a function called ''get_course_category_tree()'' that we'll look at shortly.
The function we want to use exists within the course lib file and in order to be sure its always available we need to include this file.

<code php>
$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);
</code>

This line adds the ''Courses'' branch to the custom menu into which we will add the category and course structure.

<code php>
$categorytree = get_course_category_tree();
</code>

This line is the main one to note, here we are calling a Moodle function that will return us a category and course tree, because all courses need to be within a category the initial return is an array of categories, each category in the array will have the properties of the category as well as two additional properties, the first property '''categories''' is an array containing all of this categories sub categories, and the second property '''courses''' is also an array containing all of the courses within this category.

<code php>
$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}
</code>

Now these lines of code deal with the initial array of categories returned by the ''get_course_category_tree'' function.

In this case we iterate of the initial categories and for each one we call a method of the renderer '''add_category_to_custommenu''' now those of you who are clued in will realise that this method doesn't exist yet... and you are correct - we need to write this method which is what we will look at next. 
As a heads up the reason that we need to write another method is because we need a method that we can call recursivily as there are potentially infinite category branches all contains sub categories and courses.

<code php>
return parent::render_custom_menu($menu);
</code>

The final line of code simply calls the original render_custom_menu method now that we have extended the custom menu as we want.

Now that we have looked at the render_custom_menu lets write the function we just talked about '''add_category_to_custommenu'''. 
This function as discussed above is special in that we intend to call it recursively, that means we want to call it once for EVERY category that exists in the tree. We will need to give it the categories parent menu item as well as the category object we want added.

Lets look at the code for this method:

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}
</code>

Ok so that doesn't look too bad, as you've already read the extending custom menu tutorial you will be able to spot some of the things it is doing, none the less lets walk through the code.

<code php>
protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
.....
}
</code>

First up the function definition, this function is going to be private because only we need it and it is going to take two arguments, the first $parent has to be a custom_menu_item, the second $category has to be the category object.

The objective of this method is to add a category node to the custom menu, in regards to our arguments we want to add $category as a child of $parent.

<code php>
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
</code>

This line looks very familiar, here we are adding a node for the category to the $parent, we are also collecting the newly added node as $branch.

<code php>
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
</code>

Now this code is responsible for add the sub categories of this category to the menu as well, first we need to check that the categories property isn't empty (if it is there is nothing to add).
Assuming there are sub categories we need go through each of them and call this method on them so that they get added to the custom menu as well. 
This is called recursion.

<code php>
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
</code>
This code is very similar to the above code except that we are looking at the courses within this category. 
Also note that this bit of code doesn't call add_category_to_custommenu recursivily, it doesn't need to as courses are the last bit we want to display on the menu within the category.

And that is it, time to tidy up and we're done.

==Finishing up==
All of the code is written now there is only last thing to do in order to tidy up however and that is to add the ''courses'' string that we used earlier... did you spot it?

This is of course very easy, open up '''moodle/theme/coursecategorymenu/lang/en/theme_coursecategorymenu.php''' and add the following:

<code php>
<?php

$string['courses'] = 'Courses';
</code>

And we're done. If you now browse to your site and change to the new theme you should see the Courses branch at the end of your custom menu that contains all of the categories, sub categories and courses for your site.

==Full source==
===config.php===
<code php>
<?php

$THEME->name = 'coursecategorymenu';
$THEME->parents = array('standard', 'base');
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
</code>
===renderers.php===
<code php>
<?php

class theme_coursecategorymenu_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {
global $CFG;

require_once($CFG->dirroot.'/course/lib.php');

$branch = $menu->add(get_string('courses', 'theme_coursecategorymenu'), null, null, 10000);

$categorytree = get_course_category_tree();
foreach ($categorytree as $category) {
$this->add_category_to_custommenu($branch, $category);
}

return parent::render_custom_menu($menu);
}

protected function add_category_to_custommenu(custom_menu_item $parent, stdClass $category) {
$branch = $parent->add($category->name, new moodle_url('/course/category.php', array('id' => $category->id)));
if (!empty($category->categories)) {
foreach ($category->categories as $subcategory) {
$this->add_category_to_custommenu($branch, $subcategory);
}
}
if (!empty($category->courses)) {
foreach ($category->courses as $course) {
$branch->add($course->shortname, new moodle_url('/course/view.php', array('id' => $course->id)), $course->fullname);
}
}
}

}
</code>
===lang/en/theme_coursecategorymenu.php===
<code php>
<?php

$string['courses'] = 'Courses';
</code>

==How to add "My Courses" to the Custom Menu Bar for Moodle 2.4==

This adds a nice drop down for logged in users so they can easily see their relevant courses. Note the code below has not been tested on Moodle 2.0-2.3, but you can find working code and instructions on how to add "My Courses" to the custom menu bar for those versions at: [[Themes_2.0_extending_the_custom_menu]]

Below is the Moodle 2.4 custom menu code to add to theme/themename/renderers.php

<code php>
// Add the code below to Moodle 2.4 /theme/themname/renderers.php
<?php>

class theme_themename_core_renderer extends core_renderer {

protected function render_custom_menu(custom_menu $menu) {

global $CFG;
require_once($CFG->dirroot.'/course/lib.php');

// Moodle 2.4 doesn't appear to support $mycourses = $this->page->navigation->get('mycourses'); so

if (isloggedin() && !isguestuser() && $mycourses = enrol_get_my_courses(NULL, 'visible DESC, fullname ASC')) { //which does work

$branchlabel = get_string('mycourses') ;
$branchurl = new moodle_url('/course/index.php');
$branchtitle = $branchlabel;
$branchsort = 8000 ; // lower numbers = higher priority e.g. move this item to the left on the Custom Menu
$branch = $parent->add($branchlabel, $branchurl, $branchtitle, $branchsort);

foreach ($mycourses as $mycourse) {
$branch->add($mycourse->shortname, new moodle_url('/course/view.php', array('id' => $mycourse->id)), $mycourse->fullname);
}
}
}

//Note to integrate this into the code for adding course and categories at the top of this document page,
//remove this class definition (you only need it once, and change the function name here to:
//
// protected function render_mycourses_custom_menu(custom_menu_item $menu, $position) {
//
//then add a line in the original render_custom_menu function towards the end of it and invoke this function by
//
// $this->render_mycourses_custom_menu($menu, 12000) ;
//
//
//Finally, don't forget to add the language definition for mycourses if that is not already set. Bon chance!!
</code>

Please note, in the comments I did also highlight the bit that doesn't work in Moodle 2.4.

==See also==

* [http://developer.yahoo.com/yui/3/node-menunav/ YUI 3 Menunav component the custom menu uses]