MoodleDocs - User contributions [en]

Development talk:Survey 2 brainstorm

2011-04-09T07:04:23Z

Kordan:

Jenny Gray wrote "once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it? "

I do not see the necessity for having the "edit responses" capability for any-one (admin / teacher or student) in a survey-type activity. Once responses have been submitted, they should remain as they are...

--[[User:Joseph Rézeau|Joseph Rézeau]] 08:59, 8 April 2011 (CDT)

Ciao Joseph
I am the author of the text you cited.
You are right until we talk about the questionnaire intended as a "pure" educational tool but in a wider sense the list of permissions I reported may become useful. I add some cases, sadly very common to me, in which reported permissions may become important.
As you know, I am the collector of requests of users asking for web services through moodle at the Italian National Institute of Health.

example 1.
At national level, we need to collect information about a topic.
Infos come from hospitals. In each hospital there is administrative staff (group of few persons). Each people in that group needs: to enter info, to update info with the time, to see the record added by his/her colleagues (AND NOT COMING FROM OTHER HOSPITALS) and, maybe, to edit/delete their own records.

example 2.
At national level, we need to collect information about a topic.
Infos come from hospitals. In each hospital there is administrative staff (group of few persons). At a defined deadline, data entry has to be denied and people from hospitals is no longer allowed to add/edit/delete records BUT people from NIH is supposed to add some NIH specific additional info and maybe, edit/delete ALL entered records.

Even this, it is a long time I believe the first permissions item (ALL/ALL/ALL) has no sense and is completely useless.

As usual, sorry for my English.

--[[User:Daniele Cordella 2|Daniele Cordella 2]] 02:03, 9 April 2011 (CDT)

Development talk:Survey 2 brainstorm

2011-04-09T07:04:03Z

Kordan:

Jenny Gray wrote "once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it? "

I do not see the necessity for having the "edit responses" capability for any-one (admin / teacher or student) in a survey-type activity. Once responses have been submitted, they should remain as they are...

--[[User:Joseph Rézeau|Joseph Rézeau]] 08:59, 8 April 2011 (CDT)

Ciao Joseph
I am the author of the text you cited.
You are right until we talk about the questionnaire intended as a "pure" educational tool but in a wider sense the list of permissions I reported may become useful. I add some cases, sadly very common to me, in which reported permissions may become important.
As you know, I am the collector of requests of users asking for web services through moodle at the Italian National Institute of Health.

example 1.
At national level, we need to collect information about a topic.
Infos come from hospitals. In each hospital there is administrative staff (group of few persons). Each people in that group needs: to enter info, to update info with the time, to see the record added by his/her colleagues (AND NOT COMING FROM OTHER HOSPITALS) and, maybe, to edit/delete their own records.

example 2.
At national level, we need to collect information about a topic.
Infos come from hospitals. In each hospital there is administrative staff (group of few persons). At a defined deadline, data entry has to be denied and people from hospitals is no longer allowed to add/edit/delete records BUT people from NIH is supposed to add some NIH specific additional info and maybe, edit/delete ALL entered records.

Even this, it is a long time I believe the first permissions item (ALL/ALL/ALL) has no sense and is completely useless.

As usual, sorry for my English.
--[[User:Daniele Cordella 2|Daniele Cordella 2]] 02:03, 9 April 2011 (CDT)

Development talk:Survey 2 brainstorm

2011-04-09T07:03:00Z

Kordan:

Jenny Gray wrote "once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it? "

I do not see the necessity for having the "edit responses" capability for any-one (admin / teacher or student) in a survey-type activity. Once responses have been submitted, they should remain as they are...

--[[User:Joseph Rézeau|Joseph Rézeau]] 08:59, 8 April 2011 (CDT)

Ciao Joseph
I am the author of the text you cited.
You are right until we talk about the questionnaire intended as a "pure" educational tool but in a wider sense the list of permissions I reported may become useful. I add some cases, sadly very common to me, in which reportd permissions may become important.
As you know, I am the collector of requests of users asking for web services through moodle at the Italian National Institute of Health.

example 1.
At national level, we need to collect information about a topic.
Infos come from hospitals. In each hospital there is administrative staff (group of few persons). Each people in that group needs: to enter info, to update info with the time, to see the record added by his/her coleegues (AND NOT COMING FROM OTHER HOSPITALS) and, maybe, to edit/delete their own records.

example 2.
At national level, we need to collect information about a topic.
Infos come from hospitals. In each hospital there is administrative staff (group of few persons). At a defined deadline, data entry has to be denied and people from hospitals is no longer allowed to add/edit/delete records BUT people from NIH is supposed to add some NIH specific additional info and maybe, edit/delete ALL entered records.

Even this, it is a long time I believe the first permissions item (ALL/ALL/ALL) has no sense and is completely useless.

As usual, sorry for my English.
--[[User:Daniele Cordella 2|Daniele Cordella 2]] 02:03, 9 April 2011 (CDT)

Development:Themes 2.0 adding upgrade code

2011-03-29T09:15:02Z

Kordan: /* Step 2: upgrade.php */

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: upgrade.php==
This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

defined('MOODLE_INTERNAL') || die();

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Themes 2.0 adding upgrade code

2011-03-29T07:58:01Z

Kordan: /* Step 2: upgrade.php */

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: upgrade.php==
This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

function xmldb_theme_mythemename_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Themes 2.0 adding upgrade code

2011-03-29T07:56:28Z

Kordan: /* Step 2: upgrade.php */

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: upgrade.php==
This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

function xmldb_mythemename_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Themes 2.0 adding upgrade code

2011-03-29T07:52:11Z

Kordan: /* Step 1: version.php */

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put them in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: upgrade.php==
This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

function xmldb_mythemename_anomaly_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Themes 2.0 adding upgrade code

2011-03-29T07:51:22Z

Kordan: /* Step 1: version.php */

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
defined('MOODLE_INTERNAL') || die;

$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put the in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: upgrade.php==
This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

function xmldb_mythemename_anomaly_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Themes 2.0 adding upgrade code

2011-03-29T07:49:18Z

Kordan: /* Step 1: version.php */

As theme's have got considerably more advanced in Moodle 2 there is now on occasion a need to write upgrade code for a theme. This quick tutorial looks at just how to do that.

==Why?==
As part of the Moodle 2 revamp theme's have been given the same abilities as many of the other plugin types within Moodle. They are now able to have settings pages, database tables, they can override renderers, and they can do all sorts of great things.

Unfortunately this change has its positives and negatives, on the positive you can now really get some cool stuff happening within a theme, the downside is just like any other plugin you need to think about those who are already using your theme when you make changes.

If you are changing the name of a setting, or if you are changing the database schema for the theme you will need to add upgrade code to your theme so that those who are already using your theme are moved along nicely and don't lose the effort they've put into customising and setting up your theme.

==Step 1: version.php==
For those of you who are already familiar with writing Moodle plugins you will be familiar with the version.php, however for many themer's the reality is that they've never gone beyond adding a settings page so this will be new.

The version.php file is a requirement for many plugin types, however for theme's it is optional. The idea is that it contains just two or three lines of code that tell Moodle what version the plugin is and a little bit about where it is meant to be, or what version of Moodle it requires. The version.php file for a theme should be created within the theme's base directory e.g. ''moodle/theme/mythemename/version.php''.

The following is an example of what a version.php file for a theme looks like.

<code php>
<?php

/**
* This is the version.php file for my theme.
*/
$plugin->version = 2011032900;
$plugin->component = 'theme_mythemename';
$plugin->requires = 2010122500;
$plugin->maturity = MATURITY_STABLE;
</code>

The first thing to notice here is that we are setting properties of an object called $plugin, this object will be used to describe our theme.
We are setting four properties here, version, component, requires, and maturity. The version property is required and the rest are optional however it is best practice to put the in as well.
===The version property===
The version property is the version number of our theme and needs to be an integer, although you can set it to any integer value you want it is '''HIGHLY''' recommended to use the date format shown above as it is used everywhere else throughout Moodle.

The format is YYYYMMDDXX :
# YYYY is the four digit year, e.g. 2011
# MM is the month with preceding 0 if required, e.g. 03
# DD is the day with preceding 0 is required, e.g. 28
# XX is an incrementing value starting at 00, you can increment this if you add several upgrade code blocks on the same day.

As a hint its easiest just to set the version property to today's date when adding upgrade code, or releasing a version of your theme that introduces something new such as a database table, or config setting.

===The component property===
The component is used to describe the plugin and its type. In our case we are working with themes and the theme name I have used in my example is mythemename, therefore the component is theme_mythemename.

When installing or upgrading a plugin Moodle checks the component and uses it to make sure that the plugin has been installed in the correct location. This is particularly helpful for the end user as it prevents nasty accidents where they accidentally put a plugin in the wrong place.

If you are working on other types of plugins the component of course will differ, its best to refer to the docs for those plugin types to find out what you would have to use there.

===The requires property===
The requires property sets the version of Moodle that is required by this plugin. This is particularly handy if your plugin makes use of a feature that was introduced in a specific version of Moodle, or if your plugin relies on a bug fix that was introduced in a specific version.

You can find the current Moodle version by looking at main Moodle version.php file. In the example above I have set my theme to require Moodle 2.0.1 by setting the requires property to Moodle's version number when that was released. If you are trying to find out a specific version number you can do so by heading to https://github.com/moodle/moodle, changing the tag drop down to the version you desire, then inspecting the version.php file at the bottom of the files list. You should see $version = XXXXXXXXXX;.

===The maturity property===
This is a property that is expected to be fully supported in Moodle 2.1. It informs Moodle about the state of the code and can be one of the following values:
; MATURITY_STABLE : Use this when the theme is stable and works well.
; MATURITY_RC : This marks the theme as a release candidate, users can expect the theme to contain one or two bugs but be largely stable and usable.
; MATURITY_BETA : This marks the theme as a beta release, users can expect the theme to contain several bugs and for it to be likely to change still.
; MATURITY_ALPHA : This marks the theme as an alpha release, this is the first release of a new theme and users will expect to find a lot still needs to be done.

==Step 2: upgrade.php==
This is the main upgrade file. It should be located in a directory called ''db'' located within your theme's directory, for example '''moodle/theme/mythemename/db/upgrade.php'''.

The upgrade.php file should contain just a single function that needs to be named following a strict naming scheme. In the case of my theme that for this example I've called mythemename that function will be as follows:
<code php>
<?php

function xmldb_mythemename_anomaly_upgrade($oldversion) {
// We'll look at what is in here shortly.

return true;
}
</code>

This special function gets called when ever the admin is upgrading the site and gives our theme the opportunity to run any upgrade code it requires.

Upgrade code within this function should be written in a special style where each operation is written as a block and the theme version is upgraded incrementally after each operation.

For the following example lets assume I have two settings for my theme, ''mythemename_settingone'', and ''mythemename_settingtwo''. As part of my upgrade I want to rename the settings to mythemename_settinga, and mythemename_settingb.

<code php>
<?php

function xmldb_theme_mythemename_upgrade($oldversion) {

if ($oldversion < 2011032900) {
$currentsetting = get_config('theme_mythemename');

// Create a new config called settinga and give it settingone's value.
set_config('settinga', $currentsetting->settingone, 'theme_mythemename');
// Remove settingone
unset_config('settingone', 'theme_mythemename');

// Create a new config called settingb and give it settingtwo's value.
set_config('settingb', $currentsetting->settingtwo, 'theme_mythemename');
// Remove settingtwo
unset_config('settingtwo', 'theme_mythemename');

// Upgrade the version that Moodle knows is installed so that this upgrade
// isn't run again.
upgrade_plugin_savepoint(true, 2011032900, 'theme', 'mythemename');
}

return true;
}
</code>

Looking at this code it does the following things:
# It compares and the '''$oldversion''' to the version we set (2011032900) and our version is newer it runs the upgrade code.
# The upgrade code gets the current settings so that we can change them.
# It creates a new setting called settinga and we give it settingb's value.
# It deletes settingone as we no longer want it.
# It repeats the last two steps for settingb/settingtwo.
# It updates the version Moodle knows is installed by calling ''upgrade_plugin_savepoint''
# Finally the function returns true so that the rest of the upgrade continues.

==Done==
Just like that we have added upgrade code to our theme that renames two settings. To do that we had to add a version.php file and a upgrade.php file.

==More information==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 creating your first theme]]
* [[Development:Themes 2.0 adding a settings page]]

Development:Survey 2 brainstorm

2011-03-26T07:15:49Z

Kordan: /* Uncategorised requested features */

Development:Survey 2 brainstorm

2011-03-26T07:12:35Z

Kordan: /* Question management */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (custom html and css, as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none

==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission
* option whether to show results immediately after submission, or a thank you message with link to results.

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons (horizontal & vertical display)
* short text entry
* long text entry
* checkbox
* drop down menu
* customisable likert scale for rating
* date (Example: When were you born?)

===New question types===
* short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
* time
(Example:
When do you usually take breakfast?
)
* "static text"/"read only" fields (auto filled by the software) like, current_date, user_name, record_ID, counter...
* allocation (Drag and drop)
* ranking

==Result display==

* report per survey, per user and per question
* report about non-respondent users
* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use [maybe later]
* question sets can be used across multiple courses [maybe later]
* questions can be re-ordered within an activity
* question sets can be combined to create a template

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:58:12Z

Kordan: /* Result display */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (custom html and css, as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none

==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission
* option whether to show results immediately after submission, or a thank you message with link to results.

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons (horizontal & vertical display)
* short text entry
* long text entry
* checkbox
* drop down menu
* customisable likert scale for rating
* date (Example: When were you born?)

===New question types===
* short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
* time
(Example:
When do you usually take breakfast?
)
* "static text"/"read only" fields (auto filled by the software) like, current_date, user_name, record_ID, counter...
* allocation (Drag and drop)
* ranking

==Result display==

* report per survey, per user and per question
* report about non-respondent users
* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:57:32Z

Kordan: /* Instance settings page */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (custom html and css, as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none

==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission
* option whether to show results immediately after submission, or a thank you message with link to results.

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons (horizontal & vertical display)
* short text entry
* long text entry
* checkbox
* drop down menu
* customisable likert scale for rating
* date (Example: When were you born?)

===New question types===
* short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
* time
(Example:
When do you usually take breakfast?
)
* "static text"/"read only" fields (auto filled by the software) like, current_date, user_name, record_ID, counter...
* allocation (Drag and drop)
* ranking

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:55:56Z

Kordan: /* General features of the Module */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (custom html and css, as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none

==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons (horizontal & vertical display)
* short text entry
* long text entry
* checkbox
* drop down menu
* customisable likert scale for rating
* date (Example: When were you born?)

===New question types===
* short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
* time
(Example:
When do you usually take breakfast?
)
* "static text"/"read only" fields (auto filled by the software) like, current_date, user_name, record_ID, counter...
* allocation (Drag and drop)
* ranking

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:55:07Z

Kordan: /* General features of the Module */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none

==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons (horizontal & vertical display)
* short text entry
* long text entry
* checkbox
* drop down menu
* customisable likert scale for rating
* date (Example: When were you born?)

===New question types===
* short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
* time
(Example:
When do you usually take breakfast?
)
* "static text"/"read only" fields (auto filled by the software) like, current_date, user_name, record_ID, counter...
* allocation (Drag and drop)
* ranking

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:53:09Z

Kordan: /* Instance settings page */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none
==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons (horizontal & vertical display)
* short text entry
* long text entry
* checkbox
* drop down menu
* customisable likert scale for rating
* date (Example: When were you born?)

===New question types===
* short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
* time
(Example:
When do you usually take breakfast?
)
* "static text"/"read only" fields (auto filled by the software) like, current_date, user_name, record_ID, counter...
* allocation (Drag and drop)
* ranking

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:51:54Z

Kordan: /* Question types */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none
==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

*option: allow/deny save without submission
*option: anonymous survey or named responses
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons (horizontal & vertical display)
* short text entry
* long text entry
* checkbox
* drop down menu
* customisable likert scale for rating
* date (Example: When were you born?)

===New question types===
* short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
* time
(Example:
When do you usually take breakfast?
)
* "static text"/"read only" fields (auto filled by the software) like, current_date, user_name, record_ID, counter...
* allocation (Drag and drop)
* ranking

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:48:52Z

Kordan: /* Instance settings page */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none
==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

*option: allow/deny save without submission
*option: anonymous survey or named responses
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons
** horizontal & vertical
* short text entry
* long text entry
* allocation
* checkbox
* customisable likert scale for rating
* ranking

===New question types===
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time (see next example)

(Example:
When do you usually take breakfast?
)

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:48:22Z

Kordan: /* Field level settings */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none
==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

*option: allow/deny save without submission
*option: anonymous survey or named responses
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons
** horizontal & vertical
* short text entry
* long text entry
* allocation
* checkbox
* customisable likert scale for rating
* ranking

===New question types===
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time (see next example)

(Example:
When do you usually take breakfast?
)

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:47:37Z

Kordan: /* Field level settings */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none
==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

*option: allow/deny save without submission
*option: anonymous survey or named responses
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission
===Field level settings===
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
* define a range of valid answers for fields allowing this

(Example 1: Please, enter your seniority. (limited between 0 and 50 years)
Example 2: Date of birth: (limited between 18 and 100 years ago))
* define fields default to be loaded at "new record" display time
* optional "other" text field for drop down menu/radio button/check box.

(Example for drop down: Where were you born? If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.)
* custom question numbers
* question name to name columns header in the downloaded document

==Field level settings==
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
* custom question numbers
* question name to name columns header in the downloaded document

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons
** horizontal & vertical
* short text entry
* long text entry
* allocation
* checkbox
* customisable likert scale for rating
* ranking

===New question types===
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time (see next example)

(Example:
When do you usually take breakfast?
)

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:44:11Z

Kordan: /* Instance settings page */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none
==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

*option: allow/deny save without submission
*option: anonymous survey or named responses
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
* option: allow/deny save without submission (save and restart)
* option: anonymous survey or named responses
* option: allow access to records any time/after you've submitted/after close date/never
* opening and closing submission dates
* number of maximun allowed submission
===Field level settings===
* type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields). This information may not be used at field definition time but is useful for data verification/check.

(Example: Please, enter your card ID: _______ This field should be defined, for instance, as char(7))
* option: mandatory/non mandatory field
* free text description field for further description and advices to the completer
* define a range of valid answers for fields allowing this

(Example 1: Please, enter your seniority. (limited between 0 and 50 years)
Example 2: Date of birth: (limited between 18 and 100 years ago))
* define fields default to be loaded at "new record" display time
* optional "other" text field for drop down menu/radio button/check box.

(Example for drop down: Where were you born? If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.)
* custom question numbers
* question name to name columns header in the downloaded document

==Field level settings==
*mandatory/non mandatory field option
*free text description field for further description and advice to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...
* option: allow access to results any time/after you've submitted/after close date/never

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons
** horizontal & vertical
* short text entry
* long text entry
* allocation
* checkbox
* customisable likert scale for rating
* ranking

===New question types===
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time (see next example)

(Example:
When do you usually take breakfast?
)

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-03-26T06:40:05Z

Kordan: /* Module settings page */

This page is for collecting feature requests for a new Survey module that replaces Survey, Questionnaire and Feedback.

==General features of the Module==
* translate previously built survery1, feedback and questionnaire at installation time
* upload exported feedback or questionnaires (survey1 doesn't export questionnaires templates)
* save instances of survey2 as a template to reuse it or export it
* import saved survey2 templates
* support for groups and groupings
* custom user survey2 page layout (as it already is in database module)
* download of submissions in txt, xls and ods
* conditional branching
* handle more than one input form layout (and find a way to allow this or that layout to this or that user).
* order survey fields in editing mode
* group fields in the page layout with fieldset
* relations between tables (Example: one record for the profile of my company one related record for each intervention request submitted by my company)
* email submissions to students/teachers/both/none
==Instance settings page==
* Access section: 20 types of survey, distinguished by:
:-> ppl who is allowed to R/O,
:-> ppl who is allowed to R/W,
:-> ppl who is allowed to delete a record
The reationale is: once a record has been submitted by a user, who is allowed to see it (R/O access)?, who is allowed to edit it (R/W access)?, who is allowed to delete it?

Combining all the options the come out 20 cases are defined as follows where:
:ALL means, all the people accessing the survey;
:GROUP means people belonging to the group of the user who submitted the record;
:OWNER is the user who submitted the record;
:NONE is none.
{| class="nicetable"
|-
! type
! R/O
! R/W
! delete
|-
| 1
| ALL
| ALL
| ALL
|-
| 2
| ALL
| ALL
| GROUP
|-
| 3
| ALL
| ALL
| OWNER
|-
| 4
| ALL
| ALL
| NONE
|-
| 5
| ALL
| GROUP
| GROUP
|-
| 6
| ALL
| GROUP
| OWNER
|-
| 7
| ALL
| GROUP
| NONE
|-
| 8
| ALL
| OWNER
| OWNER
|-
| 9
| ALL
| OWNER
| NONE
|-
| 10
| ALL
| NONE
| NONE
|-
| 11
| GROUP
| GROUP
| GROUP
|-
| 12
| GROUP
| GROUP
| OWNER
|-
| 13
| GROUP
| GROUP
| NONE
|-
| 14
| GROUP
| OWNER
| OWNER
|-
| 15
| GROUP
| OWNER
| NONE
|-
| 16
| GROUP
| NONE
| NONE
|-
| 17
| OWNER
| OWNER
| OWNER
|-
| 18
| OWNER
| OWNER
| NONE
|-
| 19
| OWNER
| NONE
| NONE
|-
| 20
| NONE
| NONE
| NONE
|}

*option: allow/deny save without submission
*option: anonymous survey or named responses
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*option: allow/deny submitted record deletion
*custom form and css
*download of submitted records in some standard format
* option: allow access to results any time/after you've submitted/after close date/never
** fine-grain control for result display at question level also
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check. (see next example)

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates (displayed on calendar)
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

=== Standard module settings ===

* support for groups and groupings
* permission control for which roles can create surveys

==Field level settings==
*mandatory/non mandatory field option
*free text description field for further description and advice to the completer
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...
* option: allow access to results any time/after you've submitted/after close date/never

==Question types==

Question types should be plug-ins so that they can be extended locally if required. The following list covers types which exist in at least one of the current survey modules.

* radio buttons
** horizontal & vertical
* short text entry
* long text entry
* allocation
* checkbox
* customisable likert scale for rating
* ranking

===New question types===
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time (see next example)

(Example:
When do you usually take breakfast?
)

==Result display==

* choose for a question whether to display results as
** a table
** a bar chart
** a pie chart
* option whether to show results immediately after submission, or a thank you message with link to results.

==Question management==

* questions can be copied within an activity
* question sets can be created as templates for re-use
* question sets can be used across multiple courses
* questions can be re-ordered within an activity
* question sets can be combined to create a questionnaire

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow update of submitted questionnaire as an option (not just a clean slate on the next go-round)
*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

==Answer Piping & Conditional Questions==

*Allow follow on questions related to the previous.
*Do You Smoke? Yes/No If Yes is selected a conditional question appears, How Many per Day, if No is selected move on to question 6 appears

*Answer Piping such as:
*Q1 Which dog breed do you prefer?
*Labrador
*Spaniel
*Collie
*Other

*Q2 In question 1 you stated you prefer the (Q1 Answer) as a breed, what do you like about it. [Where (Q1 Answer) is replaced with the chosen answer such as 'Labrador'
*Temperament
*Looks
*Colour
*Other

Development:Survey 2 brainstorm

2011-02-03T11:23:09Z

Kordan: /* Field level settings */

{{Moodle 2.1}}For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submission
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*option: allow/deny submitted record deletion
*custom form and css
*download of submitted records in some standard format
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check. (see next example)

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this (see next examples)
(Example 1:
Please, enter your seniority. (limited between 0 and 50 years)

Example 2:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time (see next example)

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2011-02-03T11:22:22Z

Kordan: /* Uncategorised requested features */

{{Moodle 2.1}}For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submission
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*option: allow/deny submitted record deletion
*custom form and css
*download of submitted records in some standard format
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check. (see next example)

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years) (see next example)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time (see next example)

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching (see next example)
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2011-02-03T11:22:04Z

Kordan: /* New fields types */

{{Moodle 2.1}}For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submission
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*option: allow/deny submitted record deletion
*custom form and css
*download of submitted records in some standard format
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check. (see next example)

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years) (see next example)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time (see next example)

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2011-02-03T11:21:41Z

Kordan: /* Field level settings */

{{Moodle 2.1}}For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submission
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*option: allow/deny submitted record deletion
*custom form and css
*download of submitted records in some standard format
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check. (see next example)

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years) (see next example)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box. (see next example)
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2011-02-03T11:21:16Z

Kordan: /* Module settings page */

{{Moodle 2.1}}For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submission
*option: allow/deny record modification after submission
*option: allow/deny the read only access to submitted records (see next example)
(Example: This option should appear like:
<code>
<div>Submitted answers are available/visible <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*option: allow/deny submitted record deletion
*custom form and css
*download of submitted records in some standard format
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check. (see next example)

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2011-02-03T11:15:52Z

Kordan: /* Module settings page */

{{Moodle 2.1}}For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny the access to submitted records
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*option: allow/deny submitted record deletion
*custom form and css
*download of submitted records in some standard format
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2011-02-03T11:15:28Z

Kordan: /* Module settings page */

{{Moodle 2.1}}For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny the access to submitted records
*option: allow/deny submitted record deletion
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*custom form and css
*download of submitted records in some standard format
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2011-02-03T11:15:03Z

Kordan: /* Module settings page */

{{Moodle 2.1}}For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny the access to submitted answers
*option: allow/deny submitted record deletion
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*custom form and css
*download of submitted records in some standard format
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Installing MSSQL for PHP

2011-01-26T14:31:09Z

Kordan: /* Using FreeTDS on Debian Lenny */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
I found the following solution using:
* PHP Version 5.2.6-1+lenny9
* Microsoft SQL Server Enterprise Edition, version: 9.00.4053.00
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>
At the end of the process, if all goes fine, you will find in the mssql section of phpinfo();

{| class="nicetable"
|-
! MSSQL Support
! enabled
|-
| Library version
| FreeTDS
|}

Once FreeTDS is correctly installed, don not forget to set it up following explanations in https://docs.moodle.org/en/FreeTDS

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] a new SQL Server 2005 Driver for PHP. This is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts and it overcomes the problems with the native SQL Server extension that was previously included with PHP.

This driver is the standard database layer for running Moodle 2 under Microsoft SQL Server databases. See [[Using the Microsoft SQL Server Driver for PHP]] the installation and configuration details.

This driver is only supported in Moodle 2.0 and up. You should use FreeTDS if you are installing an older version of Moodle.

==See also==
MDL-16497

MDL-15093

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Installing MSSQL for PHP

2011-01-26T11:16:49Z

Kordan: /* Using FreeTDS on Debian Lenny */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
I found the following solution using:
* PHP Version 5.2.6-1+lenny9
* Microsoft SQL Server Enterprise Edition, version: 9.00.4053.00
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>
At the end of the process, if all goes fine, you will find in the mssql section of phpinfo();

{| class="nicetable"
|-
! MSSQL Support
! enabled
|-
| Library version
| FreeTDS
|}

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Installing MSSQL for PHP

2011-01-26T11:13:06Z

Kordan: /* Using FreeTDS on Debian Lenny */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
I found the following solution using:
* PHP Version 5.2.6-1+lenny9
* Microsoft SQL Server Enterprise Edition, version: 9.00.4053.00
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>
At the end of the process, if all goes fine, you will find in the mssql section of phpinfo();
Library version: FreeTDS

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Installing MSSQL for PHP

2011-01-26T11:12:42Z

Kordan: /* Using FreeTDS on Debian Lenny */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
I found the following solution using:
* PHP Version 5.2.6-1+lenny9
* Microsoft SQL Server Enterprise Edition, version: 9.00.4053.00
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>
At the end of the process, if all goes fine, you will find in teh mssql section of phpinfo();
Library version: FreeTDS

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Installing MSSQL for PHP

2011-01-26T11:11:59Z

Kordan: /* Using FreeTDS on Debian Lenny */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
I found the following solution using:
* PHP Version 5.2.6-1+lenny9
* Microsoft SQL Server Enterprise Edition, version: 9.00.4053.00
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>
At the and you will find in teh mssql section of phpinfo();
Library version FreeTDS

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Installing MSSQL for PHP

2011-01-26T11:10:04Z

Kordan: /* Using FreeTDS on Debian Lenny */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
I found the following solution using:
* PHP Version 5.2.6-1+lenny9
* Microsoft SQL Server Enterprise Edition, version: 9.00.4053.00
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Installing MSSQL for PHP

2011-01-26T10:57:01Z

Kordan: /* Using FreeTDS on Debian Lenny */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
<pre>apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart</pre>

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Installing MSSQL for PHP

2011-01-26T10:55:44Z

Kordan: /* Using FreeTDS on Debian Lenny */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
apt-get install libsybdb5 freetds-common php5-sybase

/etc/init.d/apache2 restart

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Installing MSSQL for PHP

2011-01-26T10:55:16Z

Kordan: /* Using FreeTDS on Ubuntu by compiling an mssql.so extension */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].

== Using FreeTDS on Debian Lenny ==
apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Installing MSSQL for PHP

2011-01-26T10:54:38Z

Kordan: /* Using FreeTDS on Ubuntu by compiling an mssql.so extension */

{{Moodle 1.7}}{{Moodle 1.9}}{{Moodle 2.0}}
== Introduction ==

This short manual is suitable if you are trying to run Moodle 1.7 (and upwards) using the SQL*Server (MSSQL) RDBMS. Steps detailed below must be performed '''before''' installing Moodle itself.

Some of this may also apply if you wish to access an MSSQL server for external db authentication/enrollment.

First of all, minimum required version of MSSQL has been stabilised to MSSQL 2005 (v.9), although it '''might work with MSSQL 2000 (v.8) or newer'''. All the development process has been performed using MSSQL 2005 and there could be some '''unknown problems''' with previous releases.

While PHP comes with one, more or less, standard extension (mssql) that provides access to MSSQL databases, early we found some hard limits on it. Basically such default extension has some limits that prevent us to use it at all (you can find more info about these problems [[Development:XMLDB problems#MSSQL, PHP, UTF-8 and UCS-2|here]]).

So, in order to allow PHP (i.e. Moodle) to access to MSSQL DBs properly we have to install a '''mssql extension alternative''' to save us from the problems related above. See the sections below for details about the various options.

== Installation overview ==

1. Get MSSQL Server installed and running. ([http://www.microsoft.com/sql/editions/express/default.mspx A free limited version, SQL Server Express Edition] is available for testing.)
:Make sure that you choose mixed authentication (Windows and local accounts) to keep things simpler later. You'll be asked to define the "sa" account password (it's the default System Administrator account which has full access to all databases by default).

2. Make sure MS SQL Server can accept incoming TCP/IP connections on port 1433 (the standard one).
:You might need to explicitly allow this in your Windows firewall (see the Control Panel). You may also need to edit options in the :'''SQL Server Configuration Manager''' -> '''Network Configuration''' -> '''Protocols''' -> '''TCP/IP enabled'''

3. Open the "SQL Server Management Studio" and create a new empty database. If you are using the "sa" account then you don't need to do anything else here.

4. Configure these settings in your created (and still empty) database:

:* ANSI NULLS Enabled = true (ALTER DATABASE xxxx SET ANSI_NULLS ON)
:* Quoted Identifiers Enabled = true (ALTER DATABASE xxxx SET QUOTED_IDENTIFIER ON)
:* Moodle 2.0 only: Row Versioning Enabled (ALTER DATABASE xxxx SET READ_COMMITTED_SNAPSHOT ON)

5. Get PHP installed with a web server. Unless you want to do it under IIS or some other way, the packages on the [http://download.moodle.org Moodle download page] are a good solution.

6. Choose one of the following specific sections for your server to install the '''mssql extension alternative''' installed and running properly on your PHP box.

7. Set the following settings in your php.ini file
:* mssql.textlimit = 20971520
:* mssql.textsize = 20971520
:Also, don't forget to set one of the following '''alternatives''', in order to get all the data properly "slashed":
:* magic_quotes_gpc = Off '''or'''
:* magic_quotes_gpc = On '''and''' magic_quotes_sybase = On

8. With all this properly configured, you can continue with a [[Installing Moodle|standard Moodle installation]].

== Using FreeTDS on Windows ==

<p class="note">'''Important Note 1:''' Due to some previous bugs it's highly recommendable to use PHP >= 5.2.6 and FreeTDS 0.82 + post-release patches ([http://tracker.moodle.org/browse/MDL-14725 more info]).</p>

If your web server is on Windows, use '''php_dblib.dll'''. Despite the name, it's FreeTDS compiled for Windows. (Go to this page for information on [https://docs.moodle.org/en/FreeTDS Using FreeTDS for Unix].)

Originally we were using the DLLs available at [http://kromann.info/article.php?Id=11062598797760000 Frank Kromann's site], but they are outdated (using old versions of FreeTDS) and that has caused [http://tracker.moodle.org/browse/MDL-14725 some problems] in the past.

So, right now, the recommended way to use FreeTDS under Windows is to use PHP 5.2.x following the following instructions:

1. Download the appropriate copy of php_dblib.dll from the list below, and save it into your /PHP/ext directory.

{| border="1" align="center" cellpadding="5" style="text-align: center;"
|-
! PHP version !! [http://www.iis-aid.com/articles/my_word/difference_between_php_thread_safe_and_non_thread_safe_binaries Thread Safe] !! FreeTDS version !! Download URL
|-
| rowspan="2" | PHP 5.2.x (vc6) || Yes || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090302 patches || [http://download.moodle.org/download.php/dblib/php52/DBLIB_NOTS.zip Download!]
|-
| rowspan="2" | PHP 5.3.x (vc9) || Yes || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_TS.zip Download!]
|-
| No || 0.82 + 20090904 patches || [http://download.moodle.org/download.php/dblib/php53/DBLIB_NOTS.zip Download!]
|-
| colspan="4" | Thanks to [http://remote-learner.net/ Remote-Learner]] (Moodle [http://moodle.com/partners/ Partner]) and specially to Bryan Williams, donating one Visual C++ 6.0 Pro license to Moodle. Thanks to Trevor Johnson and his builds of the dblib extensions. Thanks to Daniele, Doug, Luis, Sean and many others by their collaboration in MDL-14725. Thanks to Frediano Ziglio and James K. Lowden from [http://freetds.org freetds.org] by their support. Thanks to Alastair Hole by providing the PHP 5.3 builds of the libraries. Thanks!
|}

(alternatively here you can find some [[Development:Compiling FreeTDS under Windows|instructions to build those freetds extensions under win32]] yourself)

2. FreeTDS requires the .NET Framework v1.1 to be installed. You can [http://www.microsoft.com/downloads/details.aspx?FamilyID=262d25e3-f589-4842-8157-034d1e7cf3a3&DisplayLang=en download it from the Microsoft website] along with its [http://www.microsoft.com/downloads/details.aspx?FamilyID=a8f5654f-088e-40b2-bbdb-a83353618b38&DisplayLang=en service pack]. Alternatively, if you do not wish to install this framework, you can [http://kromann.info/ms-libs/msvcr71.dll download the required DLL] from Frank's site, and save it into your /PHP root directory.

3. Edit your /PHP/php.ini file and add this line:

extension=php_dblib.dll

Make sure that any lines referring to the php_mssql.dll extension are DISABLED (commented out).

4. When the PHP engine loads the FreeTDS extension it needs to be passed certain infiormation in order to be able to connect to your Moodle database. To retrieve this information FreeTDS looks for a file called '''freetds.conf''' in the root folder of the server that PHP installed on (e.g. C:\).

'''freetds.conf''' should have the following structure:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

If you want to connect to a particular [http://msdn.microsoft.com/en-us/library/aa174516(SQL.80).aspx instance] of MSSQL you should specify the instance name:

[global]
host = xxx.xxx.xxx.xxx (host name or ip of the MSSQL server)
instance = xxx (instance name, e.g. INST2)
port = 1433
client charset = UTF-8
tds version = 8.0
text size = 20971520

'''Notes:'''
*You can configure FreeTDS to look for the freetds.conf file in any directory that you want - you don't have to use C:\. To do this create a SYSTEM environment variable called '''FREETDS''' and point it to the directory where you have installed the freetds.conf file. If you do not set this environment variable FreeTDS will look for the freetds.conf file in the C:\ folder, which is the default. One possible benefit of setting the FREETDS environment variable and using a different installation directory for freetds.conf is that C:\ is very predictable to a hacker that knows anything about FreeTDS and that is the first place that he would look if he wanted to compromise your system. So, using a different installation directory would just make your system stronger. See the FreeTDS [http://www.freetds.org/userguide/envvar.htm Setting the environment variables] documentation for more information about this FREETDS environment variable.

*Alternatively, you can [[Development:Compiling FreeTDS under Windows|recompile]] the FreeTDS extension yourself and change the default location to your preferred location at compile time. Then it is not necessary to create any environment variable. You must just ensure that freetds.conf is in the same folder that you specify when you compile php_dblib.dll.

*MSSQL is usually installed with port 1433 as the default. However, if the port was changed on your server when you installed MSSQL then you need to specify the correct port number.

5. Your Moodle '''config.php''' should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer. Alternatively you can use the config-dist.php file that comes with the Moodle package to create your own config.php file.

6. Restart or start your web server. If Moodle still cannot communicate with the database server, please turn display_startup_errors to "On" in your /PHP/php.ini file, then restart the web server and check for any errors that may indicate incorrect DLL versions or missing dependencies. These error reports, turned off by default in PHP, can be vital in locating a problem with new extension installations.

7. Database conection test, try this PHP script, just put in a text file called test.php change ('localhost', 'db_user', 'db_password') to suite your setup, and load from local host (http://localhost/test.php)...

<code php>
<?php
$link = mssql_connect('localhost', 'db_user', 'db_password');
if(!$link) {
echo'Could not connect';
die('Could not connect: ' . mssql_error());
}
echo'Successful connection';
mssql_close($link);
?>
</code>

8. Install Moodle as usual. Good luck!

=== Troubleshooting ===
If you encounter some problems you can try:
*check that you have DotNet framework 1.1 installed (later version are installed on Vista, but you could need this specific one)<br />
*enable TCP/IP for MSSQL: SQL Server 2005 Network Configuration -> Protocols for MSSQLSERVER -> TCP/IP (Enable) -> Properties -> Ip Addresses -> 127.0.0.1 (Active+Enable)<br />
*if you are using SQL Server 2005 and you have the error ''4004: Unicode data in a Unicode-only collation or ntext data cannot be sent to clients using DB-Library (such as ISQL) or ODBC version 3.7 or earlier'', try the ODBTP method (next chapter). The SQL Server complaining that it doesn't support pure Unicode via TDS or older versions of ODBC. Microsoft has deprecated DB-Library a long ago, in favor of ODBC, OLE DB, or SQL Native Client. Many new features of SQL 2005 aren't accessible via DB-Library so if you need them, you could have to switch away from tools based on TDS and DB-Library :(

== Using FreeTDS on Ubuntu by compiling an mssql.so extension ==
This is a good read to [http://www.robert-gonzalez.com/2009/02/18/building-the-php-ms-sql-server-extension-from-source-on-ubuntu-810/ building a FreeTDS based mssql extension for apache on Ubuntu].
== Using FreeTDS on Debian
apt-get install libsybdb5 freetds-common php5-sybase
/etc/init.d/apache2 restart

== Using ODBTP on Unix or Windows ==

You can download ODBTP from http://odbtp.sourceforge.net/. Also you will access to the documentation from the same page.

The downloaded package includes both the source code and some binaries to be installed in the server and some ready-to-use '''mssql extension alternatives''' for some platforms/PHP versions (so you won't need to compile it if your PHP server/version binary package is present).

First of all, we have to install the Win32 service that comes with the package. Let's assume that it's going to run in the same Win32 machine where your MSSQL server is running (although it can run in any other Win32 server in your network).

To do do, following the instructions present in http://odbtp.sourceforge.net/install.html, you must:

Do the following on the MSSQL server:
# Create a directory on the Windows host where the service program files will reside, i.e., md odbtp.
# Copy the files odbtpctl.exe, odbtpsrv.exe and odbtpsrv.ini files from the winservice directory into the directory created in step 1.
# Edit the file odbtpsrv.ini of the previous step and this line: <pre>MaxRequestSize=20971520</pre>
# Open a command prompt (cmd) window on the Windows host.
# Change to the directory to which the service program files were copied, i.e., cd odbtp.
# Run the following commands to install and start the service:
#* odbtpctl install
#* odbtpctl start
# With these steps you should have one new service running in your host called "odbtp". Verify it's present and running in the "Services" control panel.
# Don't forget to enable TCP/IP incoming connections to port 2799 in the host you have installed the service!

Now it's time to build the '''mssql extension alternative'''. First of all, verify if, in the downloaded package, under the "php" dir, there is one extension suitable for your PHP server/version. If it's present, you can simply copy it to the php/extensions dir in your PHP server and skip next points about compiling it from source. It's important to point that, inside each directory, you'll find '''two different''' libraries/dll files. The one that must be copied to the extensions dir is the one called '''"php_odbtp_mssql.xxx"'''!

If in the downloaded package isn't present the extension matching your PHP platform/version, you should build if from source files. To do that, just '''"configure, make, make install"'''. That will create some stuff under "/usr/local".

Now that you've successfully built ODBTP is time to create the '''mssql extension alternative''' that will provide us with the capacity of handling MSSQL DBs from within Moodle. To do so, just configure your PHP server adding this new option to the usual ones:

--with-odbtp-mssql

then, after the standard "make and make install" steps, your PHP server will be built with MSSQL support provided by ODBTP.

Do the following on the moodle webserver:
Finally, independently if we are using the binary extension provided in the download or if you have built it from source files, it's time to configure the extension.
1. To do so, add this lines, if no present, to your php.ini file:

extension=php_odbtp_mssql.dll

(only for Win32 PHP servers!)

2. And, for all the server platforms:

[odbtp]
odbtp.interface_file = "/path/to/your/odbtp.conf"
odbtp.datetime_format = mdyhmsf
odbtp.detach_default_queries = yes

(where ''"/path/to/your/odbtp.conf"'' is usually '''"/usr/local/etc/odbtp.conf"''' for Unix systems and '''"C:\odbtp\odbtp.conf"''' for Windows systems)

Then, edit such "odbtp.conf" file and put there these contents:

[global]
odbtp host = xxx.xxx.xxx (ip or hostname of the Win32 box running the ODBTP service i.e MSSQL server)
type = mssql
unicode sql = yes
use row cache = yes
right trim text = yes
var data size = 20971520

With this, your PHP server will be able to connect with the MSSQL DB server using ODBTP. From here, just continue with the installation.

Finally, if you find the ODBTP executables and '''mssql extension alternative''' in binary formats, it only will be necessary to install them in your server (binary packages...) without the need to recompile anything (just the php.ini and odbtp.conf edition steps above will be necessary). Of course, it will be really welcome to have all those binary alternatives documented here.

Once ODBTP is working, Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'mssql_n'; // Required
$CFG->dbhost = 'localhost'; // assuming MS SQL is on the same server, otherwise use an IP
$CFG->dbname = 'moodle'; // or whatever you called the database you created
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

If you don't have a config.php file yet, it can be generated as normal from the Moodle installer.

== Using ODBC on Windows ==
[[ODBC]] allows communication with an SQL database.
{{Not for production sites}}

1. Go to the '''Administrative Tools''' control panel, then the '''Data Sources (ODBC)''' panel.

2. Configure one new System/User DSN (call it, for example "moodle"). Dont forget to enable these options if the driver asks for them:

:* ANSI NULLS Enabled = true
:* Quoted Identifiers Enabled = true

3. Your Moodle config.php should include lines like these:

<code php>
$CFG->dbtype = 'odbc_mssql'; // Note this is different to all the other configs on this page!
$CFG->dbhost = 'moodle'; // Where this matches the Data source name you chose above
$CFG->dbname = ''; // Keep it blank!!
$CFG->dbuser = 'yourusername'; // I usually use the 'sa' account (dbowner perms are enough)
$CFG->dbpass = 'yourpassword';
$CFG->dbpersist = false;
$CFG->prefix = 'mdl_'; //Prefix, you can change it, but NEVER leave it blank.
</code>

4. Install Moodle as usual. Good luck!

== Using the SQL Server 2005 Driver for PHP from Microsoft ==
In July 2008 Microsoft [http://social.msdn.microsoft.com/forums/en-US/sqldriverforphp/thread/a10e5202-9e41-4ff8-a33e-fbcc7b951be2/ released] their new SQL Server 2005 Driver for PHP. It is a PHP extension that allows for the reading and writing of SQL Server data from within PHP scripts. However there are some limitations with this driver that make it incompatible with Moodle, e.g.:

* limitations with how it handles UTF-8 strings and
* it does not support the legacy mssql php driver function names

For more info see MDL-16497 and MDL-15093.

So, for now, you should not use this driver with Moodle 1.9.

== See Also ==
* [[Installing Moodle]]
* [[Errors FAQ]]
* Using Moodle [http://moodle.org/mod/forum/view.php?id=28 Installation problems forum]
* [[Beginning Administration FAQ]]
* [[Installing Oracle for PHP]]

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

Development:Survey 2 brainstorm

2010-11-26T10:26:51Z

Kordan: /* Uncategorised requested features */

{{Moodle 2.1}}For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny public submitted answers
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="radio" name="gender" value="0" checked="checked"/></code>F <code><input type="radio" name="gender" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2010-08-24T09:03:32Z

Kordan: /* Uncategorised requested features */

For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny public submitted answers
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="checkbox" name="F" value="0" checked="checked"/></code>F <code><input type="checkbox" name="M" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == F)
1b. Question relevant only for males? <code><select disabled="disabled"><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2010-08-24T09:00:27Z

Kordan: /* Module settings page */

For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny public submitted answers
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
)
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="checkbox" name="F" value="0" checked="checked"/></code>F <code><input type="checkbox" name="M" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == M)
1b. Question relevant only for males? <code><select><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2010-08-24T08:59:56Z

Kordan: /* Field level settings */

For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny public submitted answers
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born? <code><select name="dropdown_14" size="1"><option value="1" selected="selected">Spain</option><option value="2" >France</option><option value="3" >other, please specify</option></select> <input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" /></code>

If you choose "other" in the drop down menu the field will be enabled and become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="checkbox" name="F" value="0" checked="checked"/></code>F <code><input type="checkbox" name="M" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == M)
1b. Question relevant only for males? <code><select><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2010-08-24T08:55:38Z

Kordan: /* Uncategorised requested features */

For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny public submitted answers
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born?

<code php><select name="dropdown_14" size="1">
<option value="0"> </option>
<option value="1" >Spain</option>
<option value="2" >France</option>
<option value="3" >other</option>
</select>

<input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" />
</code>
If you choose "other" in the "dropdown_14" drop down menu the field "dropdown_14_other" will become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="checkbox" name="F" value="0" checked="checked"/></code>F <code><input type="checkbox" name="M" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == M)
1b. Question relevant only for males? <code><select><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)
)

Development:Survey 2 brainstorm

2010-08-24T08:55:14Z

Kordan: /* Uncategorised requested features */

For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny public submitted answers
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born?

<code php><select name="dropdown_14" size="1">
<option value="0"> </option>
<option value="1" >Spain</option>
<option value="2" >France</option>
<option value="3" >other</option>
</select>

<input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" />
</code>
If you choose "other" in the "dropdown_14" drop down menu the field "dropdown_14_other" will become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:

1. Gender: <code><input type="checkbox" name="F" value="0" checked="checked"/></code>F <code><input type="checkbox" name="M" value="1" /></code>M
1a. How many pregnancies have you had? <code><select><option value="0" selected="selected">0</option><option value="1">1</option><option value="2">2</option><option value="more">more</option></select></code> (should be disabled when answer 1 == M)
1b. Question relevant only for males? <code><select><option value="aa" selected="selected">aa</option><option value="bb">bb</option><option value="cc">cc</option><option value="more">other</option></select></code> (should be disabled when answer 1 == M)

Development:Survey 2 brainstorm

2010-08-24T08:18:52Z

Kordan:

For notes, discussion and eventually a full spec of the new Survey module for 2.1 that combines all the features of

# Survey
# Questionnaire
# Feedback

into one module.

This is the list of the frequently asked features request that moodle users addressed to me over last few years.
It may be a good starting point. The following list is NOT ordered by feature relevance.

==Module settings page==
*option: allow/deny save without submit
*option: allow/deny record modification after submit
*option: allow/deny public submitted answers
(Example: This option should appear like:
<code>
<div>Submitted answers are available <select name="dropdown_7" size="1">
<option value="0">to all users</option>
<option value="1" >to submitter only</option>
<option value="2" >to submitter group only</option>
</select></div>
</code>
*type of field (char(n), text, number, alphanumeric, boolean, date, picture, file, email, url...) with type check at submit time (and number of digit check for char(n) fields).

This information may not be used at field definition time but is useful for data verification/check.

(Example:
Please, enter your card ID: _______
This field should be defined, for instance, as char(7))
*opening and closing submission dates
*relations between tables
(Example:
one record for the profile of my company
one related record for each intervention request submitted by my company)

==Field level settings==
*mandatory/non mandatory field option
*define a range of valid answers for fields allowing this
(Example:
Please, enter your seniority. (limited between 0 and 50 years)

Example:
Date of birth: (limited between 18 and 100 years ago))
*define fields default to be loaded at "new record" display time
*optional "other" text field for drop down menu/radio button/check box.
(Example for drop down:

Where were you born?

<code php><select name="dropdown_14" size="1">
<option value="0"> </option>
<option value="1" >Spain</option>
<option value="2" >France</option>
<option value="3" >other</option>
</select>

<input type="text" name="dropdown_14_other" size="10" maxlength="10" value="" />
</code>
If you choose "other" in the "dropdown_14" drop down menu the field "dropdown_14_other" will become mandatory, otherwise it will be disabled.
)
*define read-only fields (auto filled by the software) like, current_date, user_name, record_ID...

==New fields types==
*short date (with month and years only, to answer question like: When had you the first evidence of this disease?)
*order list. A list of available items and the answer is supposed to order them.
*time

(Example:
When do you usually take breakfast?
)

==Uncategorised requested features==
*handle more than one view_single/view_list/find/input layout (and allow this or that layout to users on the basis of capabilities).

The idea is: On the basis of capability you will access your specific layout with only a field subset.
If you have this capability, you will find all the fields of the survey, otherwise you will find only a subset of them.

The same feature may be provided in the following way:
At fields level definition the course creator should be allowed to mark the field "field1" as
#visible and enabled to all
#visible to all but enabled to users with view_field1 capability only
#visible and enabled to users with view_field1 capability only

*allow course creator to add custom number to question inside layouts (i.e.: 1, 2, 2a, 2b, 3...) to respect questions hierarchy
*allow course creator to indent questions inside layouts to respect questions hierarchy (as it is already possible the indent of resources inside courses)
*conditional branching
(Example:
Gender: M F

if female: question for females only

if male: question for males only)

Moodle version history

2010-06-10T05:32:51Z

Kordan: /* Moodle 1.9 */

==Moodle 1.0==
*Moodle 1.0 - 20 August 2002
*Moodle 1.0.1 - 26 August 2002
*Moodle 1.0.2 - 2 September 2002
*Moodle 1.0.3 - 5 September 2002
*Moodle 1.0.4 - 10 September 2002
*Moodle 1.0.5 - 27 September 2002
*Moodle 1.0.6 - 26 October 2002
:: 1.0.6.1 - 6 Nov
:: 1.0.6.2 - 11 Nov
:: 1.0.6.3 - 14 Nov
:: 1.0.6.4 - 25 Nov
*Moodle 1.0.7 - 9 December 2002
*Moodle 1.0.8 - 7 January 2003
*Moodle 1.0.9 - 30 May 2003

==Moodle 1.1==
*Moodle 1.1 - 29 August 2003
*Moodle 1.1.1 - 11 September 2003

==Moodle 1.2==
*Moodle 1.2 - 20 March 2004
*Moodle 1.2.1 - 25 March 2004

==Moodle 1.3==
*Moodle 1.3 - 25 May 2004
*Moodle 1.3.1 - 4 June 2004
*Moodle 1.3.2 - 9 July 2004
*Moodle 1.3.3 - 16 July 2004
*Moodle 1.3.4 - 11 August 2004

==Moodle 1.4==
*Moodle 1.4 - 31 August 2004
*Moodle 1.4.1 - 12 September 2004
*Moodle 1.4.2 - 5 November 2004
*Moodle 1.4.3 - 21 December 2004
*Moodle 1.4.4 - 7 March 2005
*[[Moodle 1.4.5 release notes|Moodle 1.4.5]] - 7 May 2005

==Moodle 1.5==
*[[Moodle 1.5 release notes|Moodle 1.5]] - 5 June 2005
*[[Moodle 1.5.1 release notes|Moodle 1.5.1]] - 8 July 2005
*[[Moodle 1.5.2 release notes|Moodle 1.5.2]] - 16 July 2005
*[[Moodle 1.5.3 release notes|Moodle 1.5.3]] - 11 November 2005
*[[Moodle 1.5.4 release notes|Moodle 1.5.4]] - 21 May 2006

==Moodle 1.6==
*[[Moodle 1.6 release notes|Moodle 1.6]] - 20 June 2006
*[[Moodle 1.6.1 release notes|Moodle 1.6.1]] - 20 July 2006
*[[Moodle 1.6.2 release notes|Moodle 1.6.2]] - 12 September 2006
*[[Moodle 1.6.3 release notes|Moodle 1.6.3]] - 10 October 2006
*[[Moodle 1.6.4 release notes|Moodle 1.6.4]] - 17 January 2007
*[[Moodle 1.6.5 release notes|Moodle 1.6.5]] - 30 March 2007
*Moodle 1.6.6 - 11 January 2008
*Moodle 1.6.7 - 11 July 2008
*[[Moodle 1.6.8 release notes|Moodle 1.6.8]] - 15 October 2008
*[[Moodle 1.6.9 release notes|Moodle 1.6.9]] - 28 January 2009

==Moodle 1.7==
*[[Moodle 1.7 release notes|Moodle 1.7]] - 7 November 2006
*[[Moodle 1.7.1 release notes|Moodle 1.7.1]] - 17 January 2007
*[[Moodle 1.7.2 release notes|Moodle 1.7.2]] - 30 March 2007
*[[Moodle 1.7.3 release notes|Moodle 1.7.3]] - 11 October 2007
*[[Moodle 1.7.4 release notes|Moodle 1.7.4]] - 11 January 2008
*[[Moodle 1.7.5 release notes|Moodle 1.7.5]] - 11 July 2008
*[[Moodle 1.7.6 release notes|Moodle 1.7.6]] - 15 October 2008
*[[Moodle 1.7.7 release notes|Moodle 1.7.7]] - 28 January 2009

==Moodle 1.8==
*[[Moodle 1.8 release notes|Moodle 1.8]] - 30 March 2007
*[[Moodle 1.8.1 release notes|Moodle 1.8.1]] - 14 June 2007
*[[Moodle 1.8.2 release notes|Moodle 1.8.2]] - 8 July 2007
*[[Moodle 1.8.3 release notes|Moodle 1.8.3]] - 11 October 2007
*[[Moodle 1.8.4 release notes|Moodle 1.8.4]] - 11 January 2008
*[[Moodle 1.8.5 release notes|Moodle 1.8.5]] - 8 April 2008
*[[Moodle 1.8.6 release notes|Moodle 1.8.6]] - 11 July 2008
*[[Moodle 1.8.7 release notes|Moodle 1.8.7]] - 15 October 2008
*[[Moodle 1.8.8 release notes|Moodle 1.8.8]] - 28 January 2009
*[[Moodle 1.8.9 release notes|Moodle 1.8.9]] - 15 May 2009
*[[Moodle 1.8.10 release notes|Moodle 1.8.10]] - 26 October 2009
*[[Moodle 1.8.11 release notes|Moodle 1.8.11]] - 25 November 2009
*[[Moodle 1.8.12 release notes|Moodle 1.8.12]] - 27 March 2010

==Moodle 1.9==
*[[Moodle 1.9 release notes|Moodle 1.9]] - 3 March 2008
*[[Moodle 1.9.1 release notes|Moodle 1.9.1]] - 15 May 2008
*[[Moodle 1.9.2 release notes|Moodle 1.9.2]] - 11 July 2008
*[[Moodle 1.9.3 release notes|Moodle 1.9.3]] - 15 October 2008
*[[Moodle 1.9.4 release notes|Moodle 1.9.4]] - 28 January 2009
*[[Moodle 1.9.5 release notes|Moodle 1.9.5]] - 13 May 2009
*[[Moodle 1.9.6 release notes|Moodle 1.9.6]] - 21 October 2009
*[[Moodle 1.9.7 release notes|Moodle 1.9.7]] - 25 November 2009
*[[Moodle 1.9.8 release notes|Moodle 1.9.8]] - 25 March 2010
*[[Moodle 1.9.9 release notes|Moodle 1.9.9]] - 8 June 2010

[[Category:Release notes]]

[[fr:Historique des versions]]
[[es:Historia de las versiones]]
[[de:Versionshistorie]]

Development:Themes 2.0 creating your first theme

2010-05-14T14:20:38Z

Kordan: /* Starting to write excitement.css */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see you changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will of course cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case its 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in you favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells the Moodle the name of your theme, and if you ever have several config.php files open this will be help you identify which one you are looking at.

Next the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our themes config.php file is the definition of the layouts for our theme:
<div style="height:400px;overflow:auto;">
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>
</div>

What you are looking at is the different layouts for our theme. Why are there so many? because that is how many there are in Moodle, there is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout, unless there was specific reason to do so normally you would not need to create your own layouts, you could of course extend the base theme and use its layouts meaning you would only have to write CSS to achieve your desired look.

For each layout above you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Development:Themes 2.0|Themes 2.0]] for the full list.

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sute there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<div style="height:400px;overflow:auto;">
<code php>
<?php
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>
</div>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Development:Themes 2.0|Themes 2.0]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.navbar {padding-left: 1em;}
.breadcrumb li {color: #FFF;}
.breadcrumb li a {color: #FFF;}

.block {background-color: #013D6A;}
.block .header .title {color: #FFF;}
.block .header .title .block_action input {background-color: #FFF;}
.block .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.block .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:400px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 overriding a renderer]]

[[Category:Themes]]

Development:Themes 2.0 creating your first theme

2010-05-14T14:13:48Z

Kordan: /* Starting to write excitement.css */

{{Template:Themes}}{{Moodle 2.0}}This document describes how to create a theme for Moodle 2.0. It assumes you have some understanding of how themes within Moodle work as well as a good understanding of HTML and CSS.

===Theme designer mode===

Under normal operation Moodle does several things in the name of performance, one of these is to combine all of the CSS into one file, minimize it, cache it on the server, and then serve it. After the first request the cached version is served to greatly improve page performance.

What this means for you as a themer? When you make changes they will not be seen immediately. In fact you will need to tell Moodle to rebuild the cache that it is serving.
This isn't practical for designing themes of course so the '''theme designer mode''' was added. When enabled it tells Moodle not to combine or cache the CSS that gets delivered. This has the downside that page load times will take significantly longer, however you will see you changes immediately every time.

Theme designer mode may be enabled via ''Administration > Appearance > Themes > [[Theme settings]]''.

'''Warning''': Internet Explorer versions 6 and 7 have BIG problems when a site attempts to link to more than 31 stylesheets, in which case either a limited number or no styles get applied. Because Moodle sends up all of the CSS all of the time with theme designer mode turned on there is a very high chance you will get more than 31 stylesheets being included. This will of course cause major problems for Internet Explorer until theme designer mode is turned off.

==Getting started==

The first thing you need to do is create the directories and files you will be using, the first thing to create is the actual directory for your theme. This should be the name of your theme, in my case its 'excitement'. The directory should be located within the theme directory of Moodle, ./moodle/theme/excitement/ will be the directory I create.

Now within that directory we can immediately create several files that we know we are going to need.

So the files that we want to create are:
; config.php : All of our settings will go here.
; /style/ : This directory will contain all of our stylesheets.
; /style/excitement.css : All of our css will go in here.
; /pix/ : Into this directory we'll put a screen shot of our theme as well as our favicon and any images we use in CSS.
; /layout/ : Our layout files will end up in this directory.
; /layout/standard.php : This will be our one basic layout file.

So after this setup step you should have a directory structure similar to what is shown below.

[[image:Learn_to_theme_01.jpg]]

==Configuring our theme==

Open config.php in you favourite editor and start by adding the opening PHP tags '''<nowiki><?php</nowiki>'''.

Now we need to add the settings:

<code php>
$THEME->name = 'excitement';
</code>
Very simply this tells the Moodle the name of your theme, and if you ever have several config.php files open this will be help you identify which one you are looking at.

Next the parents for this theme.
<code php>
$THEME->parents = array('base');
</code>
This tells Moodle that my new theme ''`excitement`' wants to extend the base theme.

A theme can extend any number of themes. Rather than creating an entirely new theme and copying all of the CSS, you can simply create a new theme, extend the theme you like and just add the changes you want to your theme.

Also worth noting is the purpose of the base theme: it provides us with a basic layout and just enough CSS to make everything fall into place.

Now we will tell Moodle about our stylesheets:
<code php>
$THEME->sheets = array('excitement');
</code>

The final thing we need to add into our themes config.php file is the definition of the layouts for our theme:
<div style="height:400px;overflow:auto;">
<code php>
$THEME->layouts = array(
'base' => array(
'file' => 'standard.php',
'regions' => array(),
),
'standard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'course' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post'
),
'coursecategory' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'incourse' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'frontpage' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'admin' => array(
'file' => 'standard.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
'mydashboard' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'mypublic' => array(
'file' => 'standard.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),
'popup' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'frametop' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
'maintenance' => array(
'file' => 'standard.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true),
),
);

/** List of javascript files that need to be included on each page */
$THEME->javascripts = array();
$THEME->javascripts_footer = array();

</code>
</div>

What you are looking at is the different layouts for our theme. Why are there so many? because that is how many there are in Moodle, there is one for every general type of page. With my ''`excitement`'' theme I have chosen to use my own layout, unless there was specific reason to do so normally you would not need to create your own layouts, you could of course extend the base theme and use its layouts meaning you would only have to write CSS to achieve your desired look.

For each layout above you will notice the following four things are being set:
; file : This is the name of the layout file we want to use, it should always be located in the above themes layout directory. For us this is of course standard.php as we only have one layout file.
; regions : This is an array of block regions that our theme has. Each entry in here can be used to put blocks in when that layout is being used.
; defaultregion : If a layout has regions it should have a default region, this is where blocks get put when first added.
; options : These are special settings, anything that gets put into the options array is available later on when we are writing our layout file.

There are additional settings that can be defined in the config.php file - see [[Development:Themes 2.0|Themes 2.0]] for the full list.

==Writing the layout file==

The excitement theme has just one layout file.

The downside of this is that I have to make the layout file do everything I want which means I need to make use of some options (as defined in the layouts in config.php).

The upside is that I only need to maintain one file.

Other than maintenance, using multiple layout files provides many advantages to real world themes in that you can easily tweak and customise specific layouts to achieve the goals of the organisation using the theme.

So lets start writing standard.php, the layout file for my ''`excitement`'' theme.

===The top of the layout file===

<code php>
<?php
echo $OUTPUT->doctype(); ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title ?></title>
<?php echo $OUTPUT->standard_head_html() ?>
</head>
</code>

Lets look at the code that goes into this section:
<code php>
<?php
echo $OUTPUT->doctype(); ?>
</code>
This is very important and is required to go at the very top of the page. This tells Moodle to print out the document type tag that is determined by the settings within Moodle.

<code php>
<html <?php echo $OUTPUT->htmlattributes() ?>>
</code>
Here we open the HTML tag and then ask Moodle to print the attributes that should go inside it.

<code php>
<title><?php echo $PAGE->title ?></title>
</code>
Simply creates the title tag and asks Moodle to fill it in.

<code php>
<?php echo $OUTPUT->standard_head_html() ?>
</code>
Here we are asking Moodle to print all of the other tags and content that need to go into the head. This includes stylesheets, script tags, and inline JavaScript code.

===The page header===

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
<?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>
</code>

So there is a bit more going on here obviously.

<code php>
<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
</code>
Again much like what we did for the opening HTML tag in the head we have started writing the opening body tag and are then asking Moodle to give us the ID we should use for the body tag as well as the classes we should use.

<code php>
<?php echo $OUTPUT->standard_top_of_body_html() ?>
</code>
This very important call writes some critical bits of JavaScript into the page. It should always be located after the body tag as soon as possible.

<code php>
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
......
<?php } ?>
</code>
Here we are checking whether or not we need to print the header for the page. There are three checks we need to make here:
# '''$PAGE->heading''' : This checks to make sure that there is a heading for the page. This will have been set by the script and normally describes the page in a couple of words.
# '''empty($PAGE->layout_options['nonavbar'])''' : Now this check is looking at the layout options that we set in our config.php file. It is looking to see if the layout set 'nonavbar' => true.
# '''$PAGE->has_navbar()''' The third check is to check with the page whether it has a navigation bar to display.
If either there is a heading for this page or there is a navigation bar to display then we will display a heading.

Leading on from this lets assume that there is a header to print.
<code php>
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
.....
<?php } ?>
</code>
This line is simply saying if the page has a heading print it. In this case we run the first check above again just to make sute there is a heading, we then open a heading tag that we choose and ask the page to print the heading.

<code php>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div>
</code>
Here we are looking to print the menu and content that you see at the top of the page (usually to the right). We start by getting Moodle to print the login information for the current user. If the user is logged in this will be their name and a link to their profile, if not then it will be a link to login.

Next we check our page options to see whether a language menu should be printed. If in the layout definition within config.php it sets '''langmenu => true''' then we will print the language menu, a drop down box that lets the user change the language that Moodle displays in.

Finally the page also has a heading menu that can be printed. This heading menu is special HTML that the page you are viewing wants to add. It can be anything from drop down boxes to buttons and any number of each.

<code php>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</code>
The final part of the header.

Here we want to print the navigation bar for the page if there is one. To find out if there is one we run checks number 2 and 3 again and proceed if they pass.

Assuming there is a header then there are two things that we need to print. The first is the navigation bar. This is a component that the OUTPUT library knows about. The second is a button to shown on the page.

In both cases we can choose to wrap them in a div to make our life as a themer easier.

Well that is it for the header. There is a lot of PHP compared to the other sections of the layout file but it does not change and can be copied and pasted between themes.

===The page content===

I am going with the default two block regions plus the main content.

Because I have based this theme and layout file on the base theme the HTML looks a little intense. This is because it is a floating div layout where the content comes first and then we get the columns (even though one column will be to the left of the content.) Don't worry too much about it. When it comes to writing your own theme you can go about it as you choose.

<code php>
<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</div>
</div>
</div>
</code>

In regards to PHP this section is very easy. There are only three lines for the whole section one to get the main content and one for each block region.
<code php>
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</code>
This line prints the main content for the page.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</code>
This line gets all of the blocks and more particularly the content for the block region '''side-pre'''. This block region will be displayed to the left of the content.

<code php>
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</code>
Here we are getting the other block region '''side-post''' which will be displayed to the right of the content.

===The page footer===
Here we want to print the footer for the page, any content required by Moodle, and then close the last tags.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>

The section of code is responsible for printing the footer for the page.
<code php>
<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</code>
The first thing we do before printing the footer is check that we actually want to print it. This is done by checking the options for the layout as defined in the config.php file. If '''nofooter => true''' is set the we don't want to print the footer and should skip over this body of code.

Assuming we want to print a footer we proceed to create a div to house its content and then print the bits of the content that will make it up.
There are four things that the typical page footer will want to print:
; echo page_doc_link(get_string('moodledocslink')) : This will print a link to the Moodle.org help page for this particular page.
; echo $OUTPUT->login_info(); : This is the same as at the top of the page and will print the login information for the current user.
; echo $OUTPUT->home_link(); : This prints a link back to the Moodle home page for this site.
; echo $OUTPUT->standard_footer_html(); : This prints special HTML that is determined by the settings for the site. Things such as performance information or debugging will be printed by this line if they are turned on.

And the final line of code for our layout file is:
<code php>
<?php echo $OUTPUT->standard_end_of_body_html(); ?>
</code>
This is one of the most important lines of code in the layout file. It asks Moodle to print any required content into the page, and there will likely be a lot although most of it will not be visual.

It will instead be things such as inline scripts and JavaScript files required to go at the bottom of the page. If you forget this line its likely no JavaScript will work!

We've now written our layout file and it is all set to go. The complete source is below for reference. Remember if you want more practical examples simply look at the layout files located within the layout directory of other themes.

<div style="height:400px;overflow:auto;">
<code php>
<?php
echo $OUTPUT->doctype() ?>
<html <?php echo $OUTPUT->htmlattributes() ?>>
<head>
<title><?php echo $PAGE->title; ?></title>
<link rel="shortcut icon" href="<?php echo $OUTPUT->pix_url('favicon', 'theme')?>" />
<?php echo $OUTPUT->standard_head_html() ?>
</head>

<body id="<?php echo $PAGE->bodyid; ?>" class="<?php echo $PAGE->bodyclasses; ?>">
<?php echo $OUTPUT->standard_top_of_body_html() ?>
<div id="page">
<?php if ($PAGE->heading || (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar())) { ?>
<div id="page-header">
<?php if ($PAGE->heading) { ?>
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
if (!empty($PAGE->layout_options['langmenu'])) {
echo $OUTPUT->lang_menu();
}
echo $PAGE->headingmenu
?></div><?php } ?>
<?php if (empty($PAGE->layout_options['nonavbar']) && $PAGE->has_navbar()) { ?>
<div class="navbar clearfix">
<div class="breadcrumb"><?php echo $OUTPUT->navbar(); ?></div>
<div class="navbutton"> <?php echo $PAGE->button; ?></div>
</div>
<?php } ?>
</div>
<?php } ?>

<div id="page-content">
<div id="region-main-box">
<div id="region-post-box">
<div id="region-main-wrap">
<div id="region-main">
<div class="region-content">
<?php echo core_renderer::MAIN_CONTENT_TOKEN ?>
</div>
</div>
</div>
<div id="region-pre">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-pre') ?>
</div>
</div>
<div id="region-post">
<div class="region-content">
<?php echo $OUTPUT->blocks_for_region('side-post') ?>
</div>
</div>
</div>
</div>
</div>

<?php if (empty($PAGE->layout_options['nofooter'])) { ?>
<div id="page-footer" class="clearfix">
<p class="helplink"><?php echo page_doc_link(get_string('moodledocslink')) ?></p>
<?php
echo $OUTPUT->login_info();
echo $OUTPUT->home_link();
echo $OUTPUT->standard_footer_html();
?>
</div>
<?php } ?>
</div>
<?php echo $OUTPUT->standard_end_of_body_html() ?>
</body>
</html>
</code>
</div>

==Adding some CSS==
With config.php and standard.php both complete the theme is now usable and starting to look like a real theme, however if you change to it using the theme selector you will notice that it still lacks any style.

This of course is where CSS comes in. When writing code Moodle developers are strongly encouraged to not use inline styles anywhere. This is fantastic for us as themers because there is nothing (or at least very little) in Moodle that cannot be styled using CSS.

===Moodle CSS basics===

In Moodle 2.0 all of the CSS for the whole of Moodle is delivered all of the time! This was done for performance reasons. Moodle now reads in all of the CSS, combines it into one file, shrinks it removing any white space, caches it, and then delivers it.

'''What this means for you as a themer?'''

You will need to write good CSS that won't clash with any other CSS within Moodle.

Moodle is so big and complex,there is no way to ensure that classes don't get reused. What we can control however is the classes and id that get added to the body tag for every page. When writing CSS it is highly encouraged to make full use of these body classes, using them will help ensure the CSS you write has the least chance of causing conflicts.

You should also take the time to look at how the Moodle themes use CSS. Look at their use of the body classes and how they separate the CSS for the theme into separate files based on the region of Moodle it applies to.

Check out [[Development:Themes 2.0|Themes 2.0]] for more information about writing good CSS.

===Starting to write excitement.css===

<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.block {background-color: #013D6A;}
.block .header .title {color: #FFF;}
.block .header .title .block_action input {background-color: #FFF;}
.block .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.block .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}
</code>
[[image:Learn_to_theme_02.jpg|400px|thumb|Excitement theme screenshot]]
This isn't all of the CSS for the theme, but just enough to style the front page when the user is not logged in.
Remember this theme extends the base theme so there is already CSS for layout as well.

Note:
* The CSS is laid out in a single line format. This is done within the core themes for Moodle. It makes it quicker to read the selectors and see what is being styled.
* I have written my selectors to take into account the structure of the HTML (more than just the one tag I want to style). This helps further to reduce the conflicts that I may encounter.
* I use generic classes like ''.sideblock'' only where I want to be generic, as soon as I want to be specific I use the unique classes such as ''.block_calendar_month''

<br style="clear:right;" />

===Using images within CSS===

I will add two image files to the pix directory of my theme:
; /theme/excitement/pix/background.png : This will be the background image for my theme.
; /theme/excitement/pix/gradient.jpg : This will be a gradient I use for the header and headings.
I quickly created both of these images using gimp and simply saved them to the pix directory.
<code css>
html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
[[image:Learn_to_theme_03.jpg‎|400px|thumb|Excitement theme screenshot]]
The CSS above is the two new rules that I had to write to use my images within CSS.

The first rule sets the background image for the page to background.png

The second rule sets the background for headings, and the sideblocks to use gradient.jpg

You will notice that I did not need to write a path to the image. This is because Moodle has this special syntax that can be used and will be replaced when the CSS is parsed before delivery.
The advantage of using this syntax over writing the path in is that the path may change depending on where you are or what theme is being used.

Other themers may choose to extend your theme with their own; if you use this syntax then all they need to do to override the image is to create one with the same name in their themes directory.

You will also notice that I don't need to add the image files extension. This is because Moodle is smart enough to work out what extension the file uses. It also allows themers to override images with different formats.

<br style="clear:right" />
The following is the complete CSS for my theme:
<div style="overflow:auto;height:400px;">
<code css>
a {text-decoration: none;}
.addcoursebutton .singlebutton {text-align: center;}

h1.headermain {color: #fff;}
h2.main {border-bottom: 3px solid #013D6A;color: #013D6A;text-align: center;}
h2.headingblock {font-size: 18pt;margin-top: 0;background-color: #013D6A;color: #FFF;text-align: center;}
#page-header {background-color: #013D6A;border-bottom:5px solid #013D6A;}
#page-header .headermenu {color: #FFF;}
#page-header .headermenu a {color: #FDFF2A;}

.sideblock {background-color: #013D6A;}
.sideblock .header .title {color: #FFF;}
.sideblock .header .title .block_action input {background-color: #FFF;}
.sideblock .content {border: 1px solid #000;padding: 5px;background-color: #FFF;}
.sideblock .content .block_tree p {font-size: 80%;}

.block_settings_navigation_tree .content .footer {text-align: center;}
.block_settings_navigation_tree .content .footer .adminsearchform {margin-left: 5%;width: 90%;font-size: 9pt;}
.block_settings_navigation_tree .content .footer .adminsearchform #adminsearchquery {width: 95%;}

.block_calendar_month .content .calendar-controls a {color: #013D6A;font-weight: bold;}
.block_calendar_month .content .minicalendar td {border-color: #FFF;}
.block_calendar_month .content .minicalendar .day {color: #FFF;background-color: #013D6A;}
.block_calendar_month .content .minicalendar .day a {color: #FFF000;}
.block_calendar_month .content .minicalendar .weekdays th {border-width: 0;font-weight: bold;color: #013D6A;}
.block_calendar_month .content .minicalendar .weekdays abbr {border-width: 0;text-decoration: none;}

html {background-image:url([[pix:theme|background]]);}

h2.headingblock,
#page-header,
.sideblock,
.block_calendar_month .content .minicalendar .day {background-image:url([[pix:theme|gradient]]);background-repeat:repeat-x;background-color: #0273C8;}
</code>
</div>

==Adding a screenshot and favicon==
The final thing to do at this point is add both a screenshot for this theme as well as a favicon for it.
The screenshot will be shown in the theme selector screen and should be named ''screenshot.jpg''.
The favicon will be used when someone bookmarks this page.
Both images should be located in your themes pix directory as follows:
* /theme/excitement/pix/screenshot.jpg
* /theme/excitement/pix/favicon.ico

In the case of my theme I have taken a screenshot and added it to that directory, and because I don't really want to do anything special with the favicon I have copied it from /theme/base/pix/favicon.ico so that at least it will be recognisable as Moodle.

==See also==
* [[Development:Themes 2.0]]
* [[Development:Themes 2.0 overriding a renderer]]

[[Category:Themes]]