MoodleDocs - User contributions [en]

LESS

2013-10-02T21:28:43Z

Mattc: node is something other than node.js

== Overview ==

LESS ([http://lesscss.org lesscss.org]) extends CSS with dynamic behavior such as variables, mixins, operations and functions. It's an advanced way of writing CSS that we use in some themes within Moodle.

Browsers don't interpret it themselves, however, so LESS files need to be converted into normal CSS before use.

Recess is one tool used to compile and compress LESS into CSS under *nix based systems. There are [https://github.com/cloudhead/less.js/wiki/GUI-compilers-that-use-LESS.js many others tools for LESS].

== The bootstrapbase theme ==

Moodle's [[Bootstrap]] base theme has rules written using LESS.

The main LESS file is '''theme/bootstrapbase/less/moodle.less''', with additional files in '''theme/bootstrapbase/less/moodle/''' imported by the main file.

After compiling the LESS files, CSS ends up in '''theme/bootstrapbase/style/moodle.css'''. This file should not be edited manually.

== Installing Recess ==

=== Ubuntu ===

The following commands should be run to install Recess

<code bash>
sudo apt-get install npm nodejs
# If the above fails due to the error "The following packages have unmet dependencies",
# run the commands separately, ie.
# sudo apt-get install npm
# and then
# sudo apt-get install nodejs
npm install recess -g
# If the above fails with a "..permission denied.." error,
# run npm install with sudo:
# sudo npm install recess -g
</code>

<code>npm</code> stands for Node Package Manager, and is the equivalent of apt-get for node.js packages.

=== Mac OS X ===
1. Install the basic node packages from the web site: [http://nodejs.org http://nodejs.org] (or use your favourite package manager to install <code>node</code> and <code>npm</code>).

2. On the command line, install recess like this:
<code bash>
npm install recess -g
</code>

=== Windows 7 ===

In order to install Recess you need to have Node.js installed first, which is relatively simple to do.

Go to nodejs.org click install.

When installed go to -> Start -> All Programs -> type Node.js into the Search box, then select Node.js Command prompt (black icon) from the list. Now you are ready to install Recess. So at the command line prompt type the following:

<code bash>
npm install recess -g
</code>

<code>npm</code> stands for Node Package Manager, and is the equivalent of apt-get for node.js packages.

== Using Recess ==

After editing the LESS files, compile (minified) your CSS as follows:

<code bash>
cd theme/bootstrapbase/less/
recess --compile --compress moodle.less > ../style/moodle.css
</code>

or if you prefer to run it from the top-level:

<code bash>
recess --compile --compress theme/bootstrapbase/less/moodle.less > theme/bootstrapbase/style/moodle.css
</code>

This will compile and compress the moodle.less file (and all the LESS and CSS files it imports) into a single file, moodle.css, and store it in the style folder of the bootstrapbase theme.

Alternatively if you want to view the normal (un-minified) CSS then use the following method.

<pre>
recess --compile moodle.less > ../style/moodle.css
</pre>

'''NOTE:''' if you are getting an empty moodle.css file, this is being caused by a parsing error in your LESS code. A bug in <code>recess</code> currently prevents it giving you helpful error messages in many cases. You will need to examine what you have altered or written to make sure it is complete and the syntax is correct. The <code>lessc</code> compiler is what is used by <code>recess</code> to do the actual compiling and will have been installed automatically along with it. If you call it directly as <code>lessc moodle.less</code> it should give you a helpful error message that points you to where the problem is.

File API

2012-05-22T22:12:32Z

Mattc: /* Delete file */

{{Moodle 2.0}}
==Overview==

The File API is for managing all the files stored by Moodle. If you are interested in how the file API works internally, see [[File API internals]]. The page is just about what you need to know to use the file API. Related is the [[Repository API]], which lets users get files into Moodle.

If you are looking for an explanation on how to manage moodle files in moodle forms, you most likely need to read [[Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]].

==File areas==

Files are conceptually stored in '''file areas'''. A file area is uniquely identified by:
* A context id.
* full component name (using [[Frankenstyle]]), for example 'course', 'mod_forum', 'mod_glossary', 'block_html'.
* A file area type, for example 'intro' or 'post'.
* A unique itemid. Normally, the itemid relates to something depending on the file area type. For example, for a 'course', 'intro' file area, the itemid is 0. For forum post, it is the post id.

File areas are not listed separately anywhere, they are stored implicitly in the files table. Please note that each subsystem is allowed to access only own file areas, for example only code in /mod/assignment/* may access files with component 'mod_assignment'.

===Naming file areas===

The names of the file areas are not strictly defined, but it is strongly recommended to use singulars and common names of areas if possible (intro, post, attachment, description, ...).

==Serving files to users==

You must refer to the file with a URL that includes a file-serving script, often pluginfile.php. For example

The general form of the URL is something like
<code php>
$url = $CFG->wwwroot/pluginfile.php/$contextid/$component/$filearea/arbitrary/extra/infomation.ext
</code>

A specific example might be
<code php>
$url = $CFG->wwwroot/pluginfile.php/$forumcontextid/mod_forum/post/$postid/image.jpg
</code>

The file serving script then looks at the context id, and component name, and the file area name, and based on that arranges for the file to be served, following appropriate security checks.

In most cases this is done by calling a callback function in the appropriate plugin, these functions are stored in lib.php files and named component_name_pluginfile() . The arbitrary/extra/infomation.ext is passed to the callback. For example, files in the mod_forum+post file area end up being served by the mod_forum_pluginfile function in mod/forum/lib.php.

You normally use an API function to generate these URL automatically, most often the <tt>file_rewrite_pluginfile_urls</tt> function.

==Getting files from the user==

* See [[Using_the_File_API_in_Moodle_forms|Using the File API in Moodle forms]]

==Examples==
Please note that in reality developers outside of core will not deal with file api directly in majority of cases, instead use formslib elements which are doing all this automatically.

===Browsing files===
<code php>
$browser = get_file_browser();
$context = get_system_context();

$filearea = null;
$itemid = null;
$filename = null;
if ($fileinfo = $browser->get_file_info($context, $component, $filearea, $itemid, '/', $filename)) {
// build a Breadcrumb trail
$level = $fileinfo->get_parent();
while ($level) {
$path[] = array('name'=>$level->get_visible_name());
$level = $level->get_parent();
}
$path = array_reverse($path);
$children = $fileinfo->get_children();
foreach ($children as $child) {
if ($child->is_directory()) {
echo $child->get_visible_name();
// display contextid, itemid, component, filepath and filename
var_dump($child->get_params());
}
}
}

</code>

===Moving files around===

For example, if you have just built a file at the path
<code php>
$from_zip_file = $CFG->dataroot . '/temp/backup/' . $preferences->backup_unique_code .
'/' . $preferences->backup_name;
</code>
And you want to move it into the course_backup file area, do
<code php>
$context = get_context_instance(CONTEXT_COURSE, $preferences->backup_course);
$fs = get_file_storage();
$file_record = array('contextid'=>$context->id, 'component'=>'course', 'filearea'=>'backup',
'itemid'=>0, 'filepath'=>'/', 'filename'=>$preferences->backup_name,
'timecreated'=>time(), 'timemodified'=>time());
$fs->create_file_from_pathname($file_record, $from_zip_file);
</code>

=== List area files ===
<code php>
$fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);
foreach ($files as $f) {
// $f is an instance of stored_file
echo $f->get_filename();
}
</code>

Or as links...

<code php>
$out = array();

$fs = get_file_storage();
$files = $fs->get_area_files($contextid, 'mod_assignment', 'submission', $submission->id);

foreach ($files as $file) {
$url = "{$CFG->wwwroot}/pluginfile.php/{$file->get_contextid()}/mod_assignment/submission}";
$filename = $file->get_filename();
$fileurl = $url.$file->get_filepath().$file->get_itemid().'/'.$filename;
$out[] = html_writer::link($fileurl, $filename);
}

$br = html_writer::empty_tag('br');

return implode($br, $out);
</code>

=== Create file ===

Here's how to create a file whose contents will be a text string. This is the equivalent of the PHP function <tt>file_put_contents</tt>.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'contextid' => $context->id, // ID of context
'component' => 'mod_mymodule', // usually = table name
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Create file containing text 'hello world'
$fs->create_file_from_string($fileinfo, 'hello world');
</code>

If you want to create a file in the Moodle file area based on a 'real' file e.g. in a temporary folder, you can use <tt>create_file_from_pathname</tt> instead.

Unlike with ordinary files, this method will not automatically overwrite an existing file. If you wish to overwrite a file, you must first get the file and (if it exists) delete it, and only then create it again.

=== Read file ===

This is a way to read a file, equivalent to <tt>file_get_contents</tt>. '''Please note your are allowed to do this ONLY from mod/mymodule/* code, it is not acceptable to do this anywhere else.''' Other code has to use file_browser interface instead.

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'component' => 'mod_mymodule', // usually = table name
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'contextid' => $context->id, // ID of context
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo['contextid'], $fileinfo['component'], $fileinfo['filearea'],
$fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename']);

// Read contents
if ($file) {
$contents = $file->get_content();
} else {
// file doesn't exist - do something
}
</code>

If you want to access the file directly on disk, this is not permitted. Instead, you need to make a copy of the file in a temporary area and use that. You can do this with <tt>$file->copy_content_to($pathname)</tt>.

=== Delete file ===

<code php>
$fs = get_file_storage();

// Prepare file record object
$fileinfo = array(
'component' => 'mod_mymodule',
'filearea' => 'myarea', // usually = table name
'itemid' => 0, // usually = ID of row in table
'contextid' => $context->id, // ID of context
'filepath' => '/', // any path beginning and ending in /
'filename' => 'myfile.txt'); // any filename

// Get file
$file = $fs->get_file($fileinfo['contextid'], $fileinfo['component'], $fileinfo['filearea'],
$fileinfo['itemid'], $fileinfo['filepath'], $fileinfo['filename']);

// Delete it if it exists
if ($file) {
$file->delete();
}
</code>

==See also==

* [[Core APIs]]
* [[File API internals]] how the File API works internally.
* [[Using the File API in Moodle forms]]

[[Category:Files]]
[[Category:API]]

Filters 1.9 and before

2009-05-07T23:11:41Z

Mattc: /* Adding a settings screen */

'''Please note:''' This page contains information for developers. You may prefer to read the [[Filters| information about filters for teachers and administrators]].

-----

'''Filters''' allow for the for the automatic transformation of entered text into different, often more complex forms. For example the titles of [[Resources]] can automatically become hyperlinks that take you to the relevant resource, URLs pointing to [[mp3]] files can become [[Flash]] controls embedded in the webpage that let you pause and rewind the audio. The possibilities are endless and there are a number of standard filters included with Moodle and many more specialized filters contributed by the community.

==To create a filter==

To create a filter that removes all occurrences of the letter "x" - we'll call it "removex":

# Create a new folder inside Moodle's /filter/ folder, called "removex"
# Create a new PHP script file inside the folder you've just created - name it "filter.php"
# Write a new PHP function in this file, called "removex_filter()" which takes two parameters - a course ID and a piece of text to be filtered - and returns the processed text.

For our example the filter.php file would look like:

<code php>
<?php
function removex_filter($courseid, $text) {
return str_replace('x', '', $text);
}
?>
</code>

When trying this out, remember to make sure that you activate the filter in the [[Filters|filters administration screen]].

Also remember that text filtering functions, when activated, will be used intensively by the server, so you should optimise the filters as far as possible (cut down on database calls etc). Moodle caches the results of filtering to help with processing speed, but it's still worth being careful about your filter design.

Filters are applied to all text that is printed with the [[Output functions|output functions]] format_text() or format_string(). One thing to keep in mind when designing the filter is that the function format_text() first applies other transformations (for example text_to_html() or replace_smilies()) before the strings are passed to your filter. The function format_string() on the other hand passes the string as it is.

==Adding a settings screen==

Moodle 1.6 added the options for filters to have their own settings screen. To do this perform the following steps:
* In the same folder as the filter create a file called '''filtersettings.php'''.
* Add admin_setting objects to the $settings page like this:
<code php>
$settings->add(new admin_setting_configcheckbox('filter_myfilter/mysetting',
get_string('mysetting', 'filter_myfilter'),
get_string('configmysetting', 'filter_myfilter'), 0));
</code>

In standard Moodle, the censor, mediaplugin and tex filters have good examples of what you need to do.

==A note on language strings==

As the sharp-eyed will have noticed in the last section, the language strings for your filter (if any) should go in the file filter/myfilter/lang/en_utf8/filter_myfilter.php, and can be accessed using
<code php>
get_string('mystring', 'filter_myfilter').
</code>

Note that every filter must define the string 'filtername', so you can copy and paste the following to start your filter_myfilter.php file:

<code php>
<?php // $Id$
// Language string for filter/myfilter.

$string['filtername'] = 'My magic filter.';

</code>

==See also==

* [[Filters 2.0]] The new version of these instructions for after Moodle 2.0 is released.
* [[Filters schema]] - a page containing some ideas and thoughts about modifications to the filters system
* [[Filters]]

[[Category:Filters]]
[[Category:Filter]]

lib/formslib.php Validation

2007-12-10T19:38:06Z

Mattc: /* MoodleQuickForm::addRule() */

{{Formslib}}

There are two ways to add validation in the forms lib.

== MoodleQuickForm::addRule() ==

You use this typically inside your moodleform::definition method. For example to set a field as required.

<pre>
$mform->addElement('text','shortname', get_string('shortname'),'maxlength="15" size="10"');
$mform->setHelpButton('shortname', array('courseshortname', get_string('shortname')), true);
$mform->setDefault('shortname', get_string('defaultcourseshortname'));
$mform->addRule('shortname', null, 'required', null, 'client');
$mform->setType('shortname', PARAM_MULTILANG);
</pre>

There is good documentation for this on the [http://pear.php.net/manual/en/package.html.html-quickform.intro-validation.php PEAR web site]

In Moodle formslib you can set certain rules' error message to null and a default error message will automatically be used. The default messages are defined in lang/{language}/form.php. Here are the English definitions :

<pre>
$string['err_alphanumeric']='You must enter only letters or numbers here.';
$string['err_email']='You must enter a valid email address here.';
$string['err_lettersonly']='You must enter only letters here.';
$string['err_maxlength']='You must enter not more than $a->format characters here.';
$string['err_minlength']='You must enter at least $a->format characters here.';
$string['err_nopunctuation']='You must enter no punctuation characters here.';
$string['err_nonzero']='You must enter a number not starting with a 0 here.';
$string['err_numeric']='You must enter a number here.';
$string['err_rangelength']='You must enter between {$a->format[0]} and {$a->format[1]} characters here.';
$string['err_required']='You must supply a value here.';
</pre>

== moodleform::validation() ==

Define a method validation on your moodleform child to make your own custom validation for the form. This is done on the client side. And data_submitted will return null until the function returns no errors. You return an array of errors if there is any error or an empty array if there are no errors.

<pre>
class course_edit_form extends moodleform {

function definition() {
blah blah;
}

/// perform some extra moodle validation
function validation($data) {
$errors= array();
if ($foundcourses = get_records('course', 'shortname', $data['shortname'])) {
if (!empty($data['id'])) {
unset($foundcourses[$data['id']]);
}
if (!empty($foundcourses)) {
foreach ($foundcourses as $foundcourse) {
$foundcoursenames[] = $foundcourse->fullname;
}
$foundcoursenamestring = implode(',', $foundcoursenames);
$errors['shortname']= get_string('shortnametaken', '', $foundcoursenamestring);
}
}

if (empty($data['enrolenddisabled'])){
if ($data['enrolenddate'] <= $data['enrolstartdate']){
$errors['enroldateendgrp'] = get_string('enrolenddaterror');
}
}
return $errors;
}
}
?>
</pre>

{{Moodle 1.9}}There is a new parameter $files in Moodle 1.9, it allows validation of uploaded files too.
<pre>
function validation($data, $files) {
$errors = parrent::validate($data, $files);
if (empty($files['userfile'])) {
if (array_key_exists('url', $data)) {
$errors['url'] = get_string('required');
}
}
return $errors;
}
</pre>