MoodleDocs - User contributions [en]

Using images in a theme

2015-03-04T21:03:47Z

Cttxg: /* See also */ Adding MoodleBites YouTube video link

{{Template:Themes}}
==A little background==
Moodle 2.0 has introduced a new improved method of making use of images within its pages enabling theme designers to take full control over what images are being used and when possible ensures images are passed through Moodle's new performance caching system to obtain the best possible performance.

$CFG->themewww and custom pix in Moodle 1.9 and lower are gone from Moodle 2.0 and have been replaced by this new system.

==Before we start==

# Make sure you have a theme and images to work with, one that you have a backup of just in case.
# Take note of your theme's main layout file e.g. ''standard.php''.
# Take note of your theme's main CSS file e.g. ''core.css''.
# Turn on '''Theme designer mode'''.

==Image locations within Moodle==

There are three main areas in which images are located - core, plugin and theme.

Core images are used throughout Moodle and are stored in ''moodle/pix''.

The pix directory contains the following subdirectories:

:''a'' - Icons that are not widely used
:''c'' - Calendar-related icons
:''f'' - File icons for different file types
:''g'' - Default user icons and thumbnails
:''i'' - General icons
:''m'' - Currency symbols
:''s'' - Smileys
:''t'' - General icons
:''u'' - User icons and thumbnails
:''y'' - YUI icons

Plugin images are used by plugins and are stored within the plugin's directory e.g. ''mod/forum/*'' or ''blocks/navigation/*''

Theme images are used in themes and are stored in the ''pix'' subdirectory of a theme.

==Adding new images to your theme==

To add new images to your theme, such as a background image or a logo, you should start by creating a pix directory within your themes directory.

Lets assume you have two images, gradient.png and logo.jpg. Copy both files to your themes pix directory.

The plan is to use gradient.png as the background image for your theme (in CSS) and use logo.jpg in the header (in your theme's layout file).

===Using images within CSS===

Moodle parses all CSS files. When theme designer mode is off, Moodle combines them into a handful of large CSS files that get cached and served. At the same time Moodle also looks at the CSS and replaces special syntax rules.

<div style='padding:10px;background-color:#f7f7f7;border:1px dashed #123456'><nowiki>[[pix:theme|</nowiki><span style='color:#336699;font-weight:bold;'><nowiki>path/to/image/</nowiki></span><span style='color:#33993A;font-weight:bold;'>imagename</span><nowiki>]]</nowiki></div>

The above pattern is looked for by Moodle and gets replaced with the correct image URL when found.
You should note the following things about this pattern when using your own images within CSS:

# The bits in black don't change
# The bit in blue is the path to your image within the pix directory. It shouldn't start with a / but should end with one.
# The bit in green is the filename ('''no need to include the file extension''')

To use background.png as the background for our pages, add the following line of CSS to the themes core.css.
<code css>
body {background-image:url([[pix:theme|gradient]]);}
</code>

Before we look at how to use your own images within your themes layout files we should first look at how this changes if the image is in a sub directory.

Lets assume gradient.png is located here: '''pix/myimages/gradients/gradient.png'''

The CSS would need to be as follows:
<code css>
body {background-image:url([[pix:theme|myimages/gradients/gradient]]);}
</code>

If you want to refer to an image belonging to a plugin, you can do it like this:

<code css>
body {background-image:url([[pix:quiz|icon]]);}
body {background-image:url([[pix:qtype_ddmarker|grid]]);}
</code>

That refers to mod/quiz/pix/icon.png/gif and question/type/ddmarker/pix/grid.png/gif respectively (or whatever icons you have put in your theme to override these).

===Using your images within your layout files===

To use logo.jpg within the header of the layout file, open the layout file e.g. general.php and find the correct spot to put your logo.

<code php>
....
<div id="page-header" class="clearfix">

<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
echo $OUTPUT->lang_menu();
echo $PAGE->headingmenu;
?></div>
</div>
....
</code>

To achieve this I simply need to add the following line of code:
<code php>
<img src="<?php echo $OUTPUT->pix_url('logo', 'theme'); ?>" alt="" />
</code>
As before, the image's file extension is not needed as Moodle finds it automatically.

Combined the solution is very simple:
<code php>
....
<div id="page-header" class="clearfix">
<img src="<?php echo $OUTPUT->pix_url('logo', 'theme'); ?>" alt="" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
<div class="headermenu"><?php
echo $OUTPUT->login_info();
echo $OUTPUT->lang_menu();
echo $PAGE->headingmenu;
?></div>
</div>
....
</code>

The only other thing to consider is how this example would look if logo.jpg was located in a subfolder e.g. '''pix/myimages/logos/logo.jpg'''.

The code for this would be:
<code php>
<img src="<?php echo $OUTPUT->pix_url('myimages/logos/logo', 'theme'); ?>" alt="" />
</code>
'''Note that'theme' above means the word theme, and not the name of your theme'''

==Overriding images in your theme==

Overriding images within your theme can be an important part of creating and/or modifying themes.

As mentioned, there are three main areas for images within Moodle, core, plugins, and themes. Obviously we won't be overriding theme images as we are in a theme and have full control over that already which just leaves core and plugin images that you may want to override.

Within your theme create the following two directories:
; /pix_core/ : This is where your images to override core images will need to be.
; /pix_plugins/ : This is where images to override plugins will need to be.

Next, copy the images that you wish to override into either the pix_core or pix_plugins directory. You need to replicate the directory structure that the images are located in.

The following two examples illustrate how this works for both core and plugin images.

===Overriding core images===
For this example I am going to override the following two images:
# '''moodle/pix/help.gif''' This image is used for all help image icons and is shown throughout Moodle.
# '''moodle/pix/i/info.gif''' This image is used in several places, most notably the front page if the combo list is being displayed.

So first up help.gif. This is the most basic example of overriding an image. Because the image is directly within Moodle's pix directory we can simply place our new help image into our themes pix_core directory. There's nothing more to it!

The second example if not really any more difficult. Because the image is located within the subdirectory '''i''' we must create a sub directory within our pix_core directory into which we will copy our new help image. That is, the image ends up at '''/pix_core/i/info.png''' inside your theme folder. And again done!

You should also note that, as with any other image in Moodle, the extension doesn't matter. If you want to replace help.gif with a help.png you can just put the png into the correct directory. As long as the filename is the same Moodle will find it.

===Overriding plugin images===
This is a little bit more difficult than overriding core images, but not too much so. For this example, let's say I want to override the following two plugin images:
# '''moodle/mod/forum/icon.gif''' This is the icon that is used everywhere for the forum.
# '''moodle/blocks/customblock/activate.png''' This is an icon in a custom block I have installed.

First up, the forum icon. Just as with core images, we need to put the image in the correct directory structure. In this case it is going to be within our theme's pix_plugins directory.

Here we need to create the directory structure between '''/mod/''' and the image, so we need the following structure '''/pix_plugins/mod/forum/''' and into the final forum directory we put our replacement image.

The second example is done in exactly the same way, but with the blocks path. We simply need to put our replacement image in '''/pix_plugins/blocks/customblock/''' and it will automatically be overridden.

When looking for an overriding image the following path is used.

# theme (static)
# themename => mytheme
# area => pix_plugins for plugin images, pix_core for core images, pix for theme images.
# plugin type => booktool for the book tool sub plugin for example.
# plugin name => print for the name of the sub plugin.
# file name => book for the name of the image.

It then searches for the image with the following extensions gif, png, jpg, jpeg in that order.

So you end up with:
<code>
/theme/themename/area/plugintype/pluginname/filename.gif
</code>

==Example: Silkicons theme==
As an example of how this all looks when done I have attached a screen shot of a theme I quickly created using the Silk icon set created by Mark James available at [http://famfamfam.com/lab/icons/silk/ http://famfamfam.com/lab/icons/silk/].

[[Image:Silkicon.theme.screenshot.jpg]]

I have also uploaded the this file to this forum discussion if you would like to check it out for yourself.
[http://moodle.org/mod/forum/discuss.php?d=151581 http://moodle.org/mod/forum/discuss.php?d=151581]

==See also==

* [[Plugins]]
* [[Replacing icons with CSS3]]
* [http://youtu.be/g_9VM9OMs3Y Adding Images to your Theme] MoodleBites video on YouTube

Using Moodle forum discussions:
* [http://moodle.org/mod/forum/discuss.php?d=151581 Using images within your themes (and the silk icon theme)]
* [http://moodle.org/mod/forum/discuss.php?d=151581#p689883 choosing images based on the users current language]
* [http://moodle.org/mod/forum/discuss.php?d=157935&parent=691903 how to add a category(categorias) img-bullet]

Themes

2015-01-24T08:50:02Z

Cttxg: /* See also */ Adding MoodleBites YouTube video link

This page is a starting point for Moodle theme developers.

For documentation on installing and using themes, please see the [[:en:Themes|Themes user documentation]] and [[:en:Themes FAQ|Themes FAQ]].

Moodle has a powerful themes system that allows for a variety of effects through the use of XHTML and CSS.

* [[Themes overview]]
* [[Creating a theme]] - A quick step by step guide to creating your first theme.
* [[Cloning a theme]]
* [[Using images in a theme]] - How to use and override images within your theme.
* [[Creating a theme settings page]] - Looks at how to add a setting page making your theme easily customisable.
* [[Extending the theme custom menu]] - Customising the custom menu.
* [[Overriding a renderer]] - A tutorial on creating a custom renderer and changing the HTML Moodle produces.
* [[Theme checklist]] - Things that you might miss when you think you have finished your theme.
* [[Clean theme]] (new in 2.5) - How to copy and customise the Clean theme to create your own theme.
* [https://moodle.org/mod/forum/discuss.php?d=224651 How to add a 'Watermark' as a background image to your theme.]

==See also==

* [[:Category:Themes|List of all themes-related developer documentation]]
* [http://youtu.be/K3MYE8am7M4 Install a New Theme] MoodleBites video on YouTube

[[Category:Themes]]

Clean theme

2015-01-23T21:06:20Z

Cttxg: /* See also */ Adding MoodleBites YouTube video link

{{Template:Themes}}{{Moodle 2.5}}This document describes how to copy and customise the Clean (bootstrapbase) theme so that you can build on this to create a theme of your own. It assumes you have some understanding of how themes work within Moodle 2.5, as well as a basic understanding of HTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.3.x and 2.4.x, and 2.5.x it is important to understand that this tutorial is only valid for the Moodle 2.5+ Clean theme.

==Getting started==

From your Moodle '''theme''' directory '''right click''' on the '''clean''' theme and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of clean'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So rename this folder to your choosen theme name, using only lower case letters, and if needed, underscores. For the purpose of this tutorial we will call the theme 'cleantheme'.

On opening 'cleantheme' you will find several files and sub-directories which have files within them.

These are:
; config.php : Where all the theme configurations are made. ''(contains some elements that require renaming)''
; lib.php : Where all the functions for the themes settings are found. ''(contains some elements that require renaming)''
; settings.php : Where all the setting for this theme are created. ''(contains some elements that require renaming)''
; version.php : Where the version number and plugin componant information is kept. ''(contains some elements that require renaming)''
; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_clean.php : This file contains all the language strings for your theme. ''(contains some elements that require renaming as well as the filename itself)''
; /layout/ : This directory contains all the layout files for this theme.
; /layout/columns1.php : Layout file for a one column layout (content only).
; /layout/columns2.php : Layout file for a two column layout (side-pre and content).
; /layout/columns3.php : Layout file for a three column layout (side-pre, content and side-post) and the front page.
; /layout/embedded.php : Embedded layout file for embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible.
; /layout/maintenance.php : Maintenance layout file which does not have any blocks, links, or API calls that would lead to database or cache interaction.
; /layout/secure.php : Secure layout file for safebrowser and securewindow.
; /style/ : This directory contains all the CSS files for this theme.
; /style/custom.css : This is where all the settings CSS is generated.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.

==Renaming Elements==

The problem when '''cloning''' a theme is that you need to rename all those instances where the old theme name occurs, in this case '''clean'''. So using the above list as a guide, search through and change all the instances of the theme name 'clean' to 'cleantheme'. This includes the filename of the lang/en/theme_clean.php. You need to change this to 'theme_cleantheme.php'.

==Installing your theme==

Once all the changes to the name have been made, you can safely install the theme. If you are already logged in just refreshing the browser should trigger your Moodle site to begin the install 'Plugins Check'. If not then navigate to Administration > Notifications.

Once your theme is successfully installed you can select it and begin to modify it using the custom settings page found by navigating to Administration > Site Administration > Appearance > Themes >> and then click on (Cleantheme) or whatever you renamed your theme to, from the list of theme names that appear at this point in the side block.

==Include a renderer in a bootstrap based theme==

If you need to override any renderers in your theme, then make sure you override the renderers by extending the parent theme renderers, which in this case is bootstrapbase. For example the class that you need to start your renderer with is as follows...

<code php>
class theme_yourtheme_core_renderer extends theme_bootstrapbase_core_renderer {

}
</code>

...where ''''yourtheme'''' requires you to change it to your theme name otherwise it will not work.

(Please note: The normal recipe <tt>class theme_'''yourtheme'''_core_renderer extends core_renderer</tt> is wrong for themes whose parent theme uses renderers, because this method will ultimately conflict with the parent theme's renderers.)

==See also==
* [http://youtu.be/ctEYt_z2bNE Cloning the Clean Theme] MoodleBites video on YouTube
* [http://www.somerandomthoughts.com/blog/2013/05/08/moodle-2-5-and-the-bootstrap-based-theme-clean/ Moodle 2.5 and the Bootstrap based theme – Clean] blog post by Gavin Henrick
* [http://basbrands.nl/blog/2013/05/21/building-with-bootstrap/ Building With Bootstrap] blog post by Bas Brands
* [https://moodle.org/mod/forum/discuss.php?d=239967 Problems cloning "clean" theme] Discussion in ''Themes'' Forum

Cloning a theme

2015-01-23T21:04:23Z

Cttxg: /* See also */ Adding MoodleBites YouTube video link

{{Template:Themes}}This document describes how to clone a theme from an existing Moodle 2 theme. It assumes you have some understanding of how themes work within Moodle, as well as a basic understanding of XHTML and CSS. Also, because of the rapid development within Moodle, resulting in a number of versions available namely 2.0.x, 2.1.x 2.2.x 2.3.x 2.4.x and soon to be announced Moodle 2.5.x it is important to know that this tutorial is valid for ONLY Moodle Boxxie theme, and as such does not take into account the various other elements you will find in other Moodle versions of themes like Afterburner, Formal White, Sky High, to name but a few. If you are looking to clone one of these themes then checkout my new tutorials. [https://docs.moodle.org/dev/Themes_2.2_how_to_clone_a_Moodle_2.2_theme How to clone a Moodle 2.2 theme].

==Getting started==

Since this is a very easy introduction to creating a custom theme, the first thing to create is a copy of the version of the theme you want to clone. For the purpose of this tutorial, we will be cloning '''Boxxie''', which is one of several Moodle '''core''' themes. There are other themes you can 'clone' which are a little harder to do, but once you are familiar with this easy one, you can tackle the harder ones later.

OK...let's get started. From your Moodle '''theme''' directory '''right click''' on '''boxxie''' and then '''''copy''' and '''paste''''' back into your Moodle '''theme''' directory. You should now have a folder called '''Copy of boxxie'''. If you '''right click''' this folder you are given the option to '''Rename''' it. So let's rename this folder to '''foxxie''' (or to whatever name you want to call your '''cloned''' theme). It is important to use only lower case letters and underscores.

If you open the '''foxxie''' directory you will find several directories, sub-directories and files within it. One of these sub-directories '''''lang/en/''''' contain a file called '''theme_boxxie.php''' which will need to be re-named to '''theme_foxxie.php'''. But we shall address this later. For now just familiarise yourself with what you find in the '''foxxie''' directory.

These are:
; config.php : Where all the theme configurations are made.
; /lang/ : This directory contains all language sub-directories for other languages if and when you want to add them.
; /lang/en/ : This sub-directory contains your language files, in this case ''English''.
; /lang/en/theme_boxxie.php : This file contains all the language strings for your theme.
; /layout/ : This directory contains all the layout files for this theme.
; /layout/frontpage.php : Layout file for front page.
; /layout/general.php : Layout file for all pages other than the front page.
; /layout/embedded.php : Layout file for embedded pages.
; /style/ : This directory contains all the CSS files for this theme.
; /style/core.css : Contains all the CSS rules for this theme.
; /style/boilerplate.css : Contains all the ''reset'' CSS rules for this theme.
; /pix/ : This directory contains a screen shot of this theme as well as a favicon and any images used in the theme.
; /pix/tabs : This contains all the tab images for this theme.

==Renaming Elements==

The problem when '''cloning''' a theme is that you need to rename all those instances where the theme name, in this case '''boxxie''', occurs. The first place to look is '''config.php''', where you need to change the theme name.
<code php>
$THEME->name = 'boxxie';

////////////////////////////////////////////////////
// Name of the theme. Most likely the name of
// the directory in which this file resides.
////////////////////////////////////////////////////
</code>

The next place to look, as mentioned above, is '''lang/en/theme_boxxie.php'''. This file, as well as needing to be renamed, also needs some of its content renaming too. So before we forget, let's '''right click''' on this file and '''rename''' it '''theme_foxxie.php''' before we open it.

=== Language Strings ===

When you open '''theme_foxxie.php''' the first thing you will see are the '''credits''' for the theme.
<code php>
/**
* Strings for component 'theme_boxxie', language 'en', branch 'MOODLE_20_STABLE'
*
* @package moodlecore
* @copyright 2010 Patrick Malley
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
</code>
Here you will need to change the reference from '''boxxie''' to '''foxxie''', you can leave the rest of this as it is.

The next things you will find in this file are what are known as the '''language strings'''. These are used for any customised '''''words'' or ''phrases''''' used in a theme. And because this is in the '''foxxie/lang/en/''' directory all the $strings are in English. But if you wanted to add some foreign words and phrases for whenever a user switched languages, you just need to create a new sub-directory in the '''foxxie/lang/''' directory for the language files you need to add there, and then copy and paste this file to that new sub-directory. For example: '''foxxie/lang/it/theme_foxxie.php''' (where '''it''' is the code which represents the Italian language). We will explore the Language aspect of themes in another Moodle Doc. So let's just concentrate on the changes we need to make to rest of the contents of '''theme_foxxie.php'''.

<code php>
$string['pluginname'] = 'Boxxie';
$string['region-side-post'] = 'Right';
$string['region-side-pre'] = 'Left';
</code>

In the $string section above, the only thing you need to change here is the '''pluginname''' from '''boxxie''' to '''foxxie'''.

In this next section, the '''choosereadme''', which is written in XHTML and is the contents of the page that you will see when selecting '''Foxxie''' in the Theme Selector. However, you are advised to read what is actually written there and change it accordingly, renaming 'Boxxie' to 'Foxxie', and changing the contents of this part to suit yourself. You might not want to keep all that is written here. You could actually condense it, but that's up to you. Just as long as you give credit, where credit is due, to the original theme designer by stating something on similar lines to what I have written below.

<code php>
$string['choosereadme'] = 'Foxxie is a customised Moodle theme
by Mary Evans based on the original Boxxie theme by Patrick Malley';
</code>

Now open version.php file and change $plugin->component

<code php>
$plugin->component = 'theme_foxxie';
</code>

==Recipe for the Impatient==
For those who want a minimal set of instructions to semi-blindly blast through this:

'''1.''' Copy ''[moodleroot]/theme/boxxie'' to ''[moodleroot]/theme/foxxie''

'''2.''' Rename ''[moodleroot]/theme/foxxie/lang/en/theme_boxxie.php'' to ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php''

'''3.''' In ''[moodleroot]/theme/foxxie/lang/en/theme_foxxie.php'', replace any instances of "boxxie" with "foxxie", likewise for "Boxxie" and "Foxxie".

'''4.''' Edit ''[moodleroot]/theme/foxxie/config.php'' to replace instance(s) of "boxxie" with "foxxie".

'''5.''' Edit ''[moodleroot]/theme/foxxie/version.php'' to replace instance(s) of "boxxie" with "foxxie".

==Appendix==
Please Note: All theme names, directory names, and file names MUST be in lowercase.

==See also==

* [http://youtu.be/ctEYt_z2bNE Cloning the Clean Theme] MoodleBites video on YouTube
* [[Making a horizontal dock]] - Modifying the dock to make it horizontal.
* [[Styling and customising the dock]] - How to style and customise the dock.
* [[Adding theme upgrade code]]
* [[Theme changes in 2.0]]
* [[jQuery]]

[[es:Clonar un tema]]

Creating a theme settings page

2014-07-25T07:16:11Z

Cttxg: /* Finishing settings.php */ Correcting the $choices options

{{Template:Themes}}This document looks at how to create a settings page for your Moodle 2.x.x theme and how to make use of those settings within the CSS and layout files for your theme.

This is a pretty advanced topic and will require that you have at least an intermediate knowledge of PHP, CSS, and development in general.

==Before we begin==
[[Image:Theme.settings.page.03.png|350px|thumb|Our end goal. The settings page.]]
[[Image:Theme.settings.page.10.png|350px|thumb|And what it can do.]]
There is a huge body of knowledge that we must cover in following through this document and as such I think the best way to write this is as a tutorial.

My intentions for this tutorial are to replicate the standard theme but with a settings page that allows the administrator to set a background colour, set a logo to use with the page, and probably several other minor settings to change the way in which the theme is displayed.

I will start this tutorial by creating a new theme which will be largely a copy/paste of the current standard theme. I expect that anyone working through this tutorial has previously read the tutorial I wrote on [[Themes 2.0 creating your first theme|creating your first theme]]. If you haven't go read it now because I'm not going to go into much detail until we get to the actual process of customising the theme and introducing the settings page.

So before we finally get this started please ensure you can check off everything on the following requirements list.
* Have a Moodle installation that has already been installed and configured and is ready to use.
* Have full read/write access to that installation.
* Be prepared to delete that installation at the end of this... we will destroy it!
* Have a development environment prepared and ready to use. This includes:
** Your favourite editor installed, running, and pointed at the themes directory of your installation.
** Your browser open and your site visible.
** A bottomless coffee pot... decaf won't help you with this one.
* Have set the following settings:
** '''themedesignermode''' if you don't know what this is please read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.
** '''allowthemechangeonurl''' turn this on, it allows you to change themes on the URL and is very handy when developing themes. ''Site Administration > Appearance > Themes > Theme settings''
** '''langstringcache''' if you don't turn this off you won't see your strings when they are added. ''Site Administration > Language > Language settings''
* And finally an insane ambition to create a customisable theme.

For those interested the theme that I create throughout this tutorial can be downloaded from the forum post in which I announce this document: http://moodle.org/mod/forum/discuss.php?d=152053
<br style="clear:right;" />

==Our goals for this tutorial==
The following is just a list goals that I hope to achieve during this tutorial. They are laid out here so that I can easily refer back to them and so that you can easily find them.
# Create a new theme called '''demystified''' based upon the standard theme within Moodle 2.0.
# Make some minor changes to that theme to allow us to more easily see what is going on.
# Create a settings page for the demystified theme.
# Add several settings to our settings page.
# Use some of those settings to alter our CSS.
# Use the rest of those settings within our layout file..
# Discuss the good, the bad, and limits of what we have just created.

So I can see you are all very excited about this point and that you would love to know what settings we are going to create; So here they are:

A setting to ...
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

==Creating the demystified theme==
Before we start here I want to remind you that I am going to look at this only briefly as I am making the assumption that you have read the [[Themes 2.0 creating your first theme|creating your first theme]] tutorial.

Well lets get into it....

The first thing we need to do is create a directory for our theme which we will call demystified.

So within your Moodle directory create the following folder '''moodle/theme/demystified'''. At the same time you can also create the following files and folders which we will get to soon.
* The file '''moodle/theme/demystified/config.php''' for our config information.
* The directory '''moodle/theme/demystified/layout''' for our layout files.
* The directory '''moodle/theme/demystified/style''' for our css files.
* The file '''moodle/theme/demystified/style/core.css''' which will contain our special CSS.

Next we will copy the layout files from the base theme to our new theme demystified. We are basing the demystified theme on the standard theme however that doesn't use it's own layout files it uses the base theme's layout files so those are the ones we want.

The reason that we are coping these layout files is that later on in this tutorial we will be modifying them to make use of our new settings... so copy all of the layout files from '''moodle/theme/base/layout''' to '''moodle/theme/demystified/layout'''.

There should be three files that you just copied:
# embedded.php
# frontpage.php
# general.php

Now we need to populate demystified/config.php with the settings for our new theme. They are as follows:
<code php>
$THEME->name = 'demystified';
</code>
Simply sets the name of our theme.

<code php>
$THEME->parents = array('standard','base');
</code>
This theme is extending both the standard theme and the base theme. Remember when extending a theme you also need to extend its parents or things might not work correctly.

<code php>
$THEME->sheets = array('core');
</code>
This tells our theme that we want to use the file '''demystified/style/core.css''' with this theme.

<div style="height:300px;overflow-y:scroll;">
<code php>
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
// Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible
'embedded' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
);
</code>
</div>
Now that all looks very complicated however its really not too bad as it is just copied from the base theme's config.php file. We can do this because we copied the layout files from the base theme to begin with and for the time being there are no changes that we wish to make. Simply open up '''theme/base/config.php''' and copy the layouts from there.

And that is it. The config.php file for our demystified theme is complete. The full source is shown below:
<div style="height:300px;overflow-y:scroll;">
<code php>
<?php

// This file is part of Moodle - http://moodle.org/
//
// Moodle is free software: you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Moodle is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Moodle. If not, see <http://www.gnu.org/licenses/>.

/**
* The demystified theme config file
*
* This theme was created to document the process of adding a settings page to a theme
*
* @copyright 2010 Sam Hemelryk
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/

// The name of our theme
$THEME->name = 'demystified';

// The other themes this theme extends
$THEME->parents = array('standard','base');

// The CSS files this theme uses (located in the style directory)
$THEME->sheets = array('core');

// The layout definitions for this theme
$THEME->layouts = array(
// Most backwards compatible layout without the blocks - this is the layout used by default
'base' => array(
'file' => 'general.php',
'regions' => array(),
),
// Standard layout with blocks, this is recommended for most pages with general information
'standard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Main course page
'course' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
'coursecategory' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// part of course, typical for modules - default page layout if $cm specified in require_login()
'incourse' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// The site home page.
'frontpage' => array(
'file' => 'frontpage.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
// Server administration scripts.
'admin' => array(
'file' => 'general.php',
'regions' => array('side-pre'),
'defaultregion' => 'side-pre',
),
// My dashboard page
'mydashboard' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
'options' => array('langmenu'=>true),
),
// My public page
'mypublic' => array(
'file' => 'general.php',
'regions' => array('side-pre', 'side-post'),
'defaultregion' => 'side-post',
),
'login' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('langmenu'=>true),
),

// Pages that appear in pop-up windows - no navigation, no blocks, no header.
'popup' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// No blocks and minimal footer - used for legacy frame layouts only!
'frametop' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('nofooter'=>true),
),
// Embeded pages, like iframe/object embeded in moodleform - it needs as much space as possible
'embedded' => array(
'file' => 'embedded.php',
'regions' => array(),
'options' => array('nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
// Used during upgrade and install, and for the 'This site is undergoing maintenance' message.
// This must not have any blocks, and it is good idea if it does not have links to
// other places - for example there should not be a home link in the footer...
'maintenance' => array(
'file' => 'general.php',
'regions' => array(),
'options' => array('noblocks'=>true, 'nofooter'=>true, 'nonavbar'=>true, 'nocustommenu'=>true),
),
);
</code>
</div>

The screenshot below shows both the directory structure we have now created and the theme presently.

[[Image:Theme.settings.page.01.png]]

To view the theme so far open you browser and enter the URL of your site followed by '''?theme=demystified'''. You should see the theme that we just created which will look exactly like the base standard theme.

The final thing that we want to do is add a little bit of CSS to the demystified theme that will both visually set this theme apart from the standard theme and second build a the base which our settings can later extend.

I added the following snippet of CSS to the file '''demystified/style/core.css'''.
<code css>
html {background-color:#DDD;}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
</code>

The CSS that we have just added to our theme sets a couple of colours on the front page. Presently this is the only CSS I will add, I know it isn't complete by any means but it achieves it's purpose as the screenshot below illustrates.

[[Image:Theme.settings.page.02.png|715px|thumb|left|The newly styles demystified theme]]<br style="clear:both;" />

And with that I will move on to the real purpose of this tutorial, creating the settings page

==Setting up the settings page==
With the demystified theme set up it is time to create the settings page. This is where the real PHP fun begins.

For those of you who happen to be familiar with development of modules, blocks or other plugin types you have probably encountered settings pages before and this is not going to be any different.

However for those who haven't which I imagine is most of you this is going to be quite a challenge. I will try to walk through this step by step however if at any point you get stuck don't hesitate to ask in the forums as I imagine you will get a speedy response.

===How settings pages work in Moodle===
Settings pages can be used by nearly every plugin type, of which themes is of course one. The way in which it all works isn't too tricky to understand.

All of the settings for Moodle can be configured through the administrator interfaces when logged in. I am sure that everyone here has seen those pages and has changed a setting or two before so you will all know what I am talking about. Well the settings page for a theme is no different. It will be shown in the administration pages tree under '''Appearance > Themes''' and all we have to do is tell Moodle what settings there are.

This is done by creating a settings.php file within our theme into which we will add code that tells Moodle about the settings we want to add/use.

When telling Moodle about each setting we are simply creating a new ''admin_setting'' instance of the type we want and the properties we want and then adding it to our settings page.

There is really not much more too it at this level. Things can get very complex very fast so the best thing we can do now is start creating our settings.php file for the demystified theme and see where it leads us.

===Creating the settings page===
So as mentioned before we need a settings.php file which we will create now. To begin with create the file '''theme/demystified/settings.php''' and open it in your favourite editor so its ready to go.

Before we start adding code however lets just remember the settings that we want to create:
* change the background colour (CSS).
* set the path to an image that we will use as a logo on all pages (Layout files).
* override the width of the block regions (CSS).
* allow a note to be added to the footer of all pages (Layout files).
* allow custom CSS to be written to do anything the user wants. (CSS)

Alright.

Now thinking about this the first setting is as basic as it gets, all we need is a text box that the user can type a colour into.

The second is to allow a logo to be used in the header of each page. What we want here is a path but should it be a physical path e.g. C:/path/to/image.png or should it be a web path e.g. <nowiki>http://mysite.com/path/to/image.png</nowiki>?
For the purpose of this tutorial I am going to go with a web path because it is going to be easier to code and will hopefully be a little easier to understand to begin with.

The third setting is a little more complex. For this I want a drop down box with some specific widths that the administrator can select.

The forth and the fifth settings are both pretty straight forward, there we want a textarea into which the user can enter what ever they want and we will do something useful with it.

Now that we have an understanding about the settings we wish to define pull up your editor and lets start coding....

<code php>
<?php

/**
* Settings for the demystified theme
*/

$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));
</code>
This is the first bit of code we must enter, the first line is of course just the opening php tag, secondly we have a comment that describes this file, and then we get create a new '''admin_settingspage object'''.

This admin_settingspage object that we have just created is a representation of our settings page and is the what we add our new settings to. When creating it we give it two arguments, first the name of the page which is in this case '''theme_''themename''''' and the title for the page which we get with the get_string method.

At the moment I'm not going to worry about adding the string, we will get to that later once we have defined all of our settings.

====Background colour====

With the page now created as ''$temp'' lets add our first setting: Background colour.

<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);
</code>
Thankfully this isn't as difficult as it initially looks.

The first line of code is creating a variable for the name of the background colour setting. In this case it is '''theme_demystified/backgroundcolor'''.

The name is very important, for the setting to be usable we have to follow a strict naming convention. '''theme_''themename''/''settingname''''' where '''''themename''''' is the name of the theme the setting belongs to and '''''settingname''''' is the name for the setting by which we will use it.

The second line of code creates a variable that contains the title of the setting. This is what the user sees to the right of the setting on the settings page and should be a short description of the setting. Here we are again using the ''get_string'' method so we will need to remember to add that string later on.

The third line of code sets the description. This should describe what the setting does or how it works and again we will use the get_string method.

The fourth line creates a variable that will be used as the default value for the setting. Because this setting is a colour we want an HTML colour to be the default value.

The fifth line is where we put it all together. Here we create a new '''admin_setting_configtext''' object. This object will represent the background colour setting.

When we create it we need to give it 6 different things.
# The name of the setting. In this case we have a variable '''$name'''.
# The title for this setting. We used the variable '''$title'''.
# The description of the setting '''$description'''.
# The default value for the setting. '''$default''' is the variable this.
# The type of value we want the user to enter. For this we have used PARAM_CLEAN which tells Moodle to get rid of any nasties from what the user enters.
# The size of the field. In our case 12 characters will be plenty.

The sixth and final line of code adds our newly created setting to the administration page we created earlier.

That is it we have successfully created and added our first setting, however there are several more to settings to do, and there are a couple of important things that you need to be aware of before we move on.

First: There are several different types of settings that you can create and add to a page, and each one may differ in what they need you to give them. In this case it was name, title, description, default, type, and size. However other settings will likely require different things. Smart editors like Netbeans or Eclipse can tell you what is required, otherwise you will need to research it.

Second: Normally settings are declared on one line as follows:
<code php>
$temp->add(new admin_setting_configtext('theme_demystified/backgroundcolor', get_string('backgroundcolor','theme_demystified'), get_string('backgroundcolordesc', 'theme_demystified'), '#DDD', PARAM_CLEAN, 12));
</code>
While this is structurally identical as all we have done is move everything onto one line and do away with the variables it is a little harder to read when you are learning all of this.

====The logo file====
Time to create the second setting that will allow the user to enter a URL to an image they wish to use as the logo on their site.
<code php>
// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);
</code>
The first thing that you will notice about this setting that it is very similar to the first setting, in fact all we have changed is the name, title, description, and default value. We have however changed the value type from PARAM_CLEAN to PARAM_URL, this makes sure the user enters a URL. You will also notice that for this one we don't set a size for the field as we have no idea how long the URL will be.

====Block region width====
The third setting should allow the user to set a width for the block regions that will be used as columns.

For this setting I want to do something a little different from the previous two, here I want to use a select box so that the user selects a width for the column from a list I provide.
<code php>
// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);
</code>
So looking at the code: The first four lines you will recognise. $name, $title, $description, and $default are all being set.

The fifth line of code however introduces something new. Of course in order to have a select box we have to have options, in this case we have an array of options stored in the variable $choices.

The array of options is constructed of a collection of '''''value''' => '''label''''' pairs. Notice how we don't add '''px''' to the value. This is is very intentional as later on I need to do a little bit of math with that value so we need it to be a number.

The lines after should look familiar again, the only difference being that instead of a ''admin_setting_configtext'' setting we have created a ''admin_setting_configselect'' for which we must give the choices for the select box as the fifth argument.

Woohoo, we've just created our first select box setting.

====Foot note====
Now to create the foot note setting. Here we want the user to be able to enter some arbitrary text that will be used in the footer of the page. For this I want the user to be able to enter some HTML so I will create an editor setting.
<code php>
// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);
</code>
How simple is that!

It is just about identical to the first two settings except that for this we have created a ''admin_setting_confightmleditor'' setting rather than a text setting.

Note: You can also set the columns and rows for the editor setting using the fifth and sixth arguments.

====Custom CSS====
The final setting is to allow the user to add some custom CSS to the theme that will be used on every page. I want this to be a plain textarea into which the user can enter CSS.
<code php>
// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);
</code>
Just like the editor or text settings. It's getting very easy now!

====Finishing settings.php====
With all of our settings defined and added to our page that we created right at the beginning it is time to finish it all off.
<code php>
// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
The above line of code is the final line for the page. It is adding the page that we have created '''$temp''' to the admin tree structure. In this case it is adding it to the themes branch.

The following is the completed source for our settings.php ..... for your copy/paste pleasure.
<div style='height:300px;overflow:auto;'>
<code php>
<?php

/**
* Settings for the demystified theme
*/

// Create our admin page
$temp = new admin_settingpage('theme_demystified', get_string('configtitle','theme_demystified'));

// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$setting = new admin_setting_configtext($name, $title, $description, $default, PARAM_CLEAN, 12);
$temp->add($setting);

// Logo file setting
$name = 'theme_demystified/logo';
$title = get_string('logo','theme_demystified');
$description = get_string('logodesc', 'theme_demystified');
$setting = new admin_setting_configtext($name, $title, $description, '', PARAM_URL);
$temp->add($setting);

// Block region width
$name = 'theme_demystified/regionwidth';
$title = get_string('regionwidth','theme_demystified');
$description = get_string('regionwidthdesc', 'theme_demystified');
$default = 200;
$choices = array(150=>'150px', 170=>'170px', 200=>'200px', 240=>'240px', 290=>'290px', 350=>'350px', 420=>'420px');
$setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
$temp->add($setting);

// Foot note setting
$name = 'theme_demystified/footnote';
$title = get_string('footnote','theme_demystified');
$description = get_string('footnotedesc', 'theme_demystified');
$setting = new admin_setting_confightmleditor($name, $title, $description, '');
$temp->add($setting);

// Custom CSS file
$name = 'theme_demystified/customcss';
$title = get_string('customcss','theme_demystified');
$description = get_string('customcssdesc', 'theme_demystified');
$setting = new admin_setting_configtextarea($name, $title, $description, '');
$temp->add($setting);

// Add our page to the structure of the admin tree
$ADMIN->add('themes', $temp);
</code>
</div>

===Creating a language file and adding our strings===
As I'm sure none of you have forgotten, throughout the creation of the our settings.php page, we used a lot of strings that I mentioned we would set later on. Well now is the time to set those strings.

First up create the following directories and file for our language strings:
* Directory '''theme/demystified/lang'''
* Directory '''theme/demystified/lang/en'''
* File '''theme/demystified/lang/theme_demystified.php'''

What we have created here is the required structure for Moodle to start looking for language strings.

First Moodle locates the lang directory, once found it looks within that directory for another directory that uses the character code for the language the user has selected, by default this is '''en''' for English. Once that is found it looks for the appropriate language file, in this case '''theme_demystified.php''' from which it will load all language strings for our theme.

If English isn't your chosen language simply replace the ''en'' directory with one that uses your chosen languages character code (two letters).

We can now add our language strings to '''theme/demystified/lang/theme_demystified.php'''. Copy and paste the following lines of PHP into this file.
<code php>
<?php

/**
* This file contains the strings used by the demystified theme
*/

$string['backgroundcolor'] = 'Background colour';
$string['backgroundcolordesc'] = 'This sets the background colour for the theme.';
$string['configtitle'] = 'Demystified theme';
$string['customcss'] = 'Custom CSS';
$string['customcssdesc'] = 'Any CSS you enter here will be added to every page allowing your to easily customise this theme.';
$string['footnote'] = 'Footnote';
$string['footnotedesc'] = 'The content from this textarea will be displayed in the footer of every page.';
$string['logo'] = 'Logo';
$string['logodesc'] = 'Enter the URL to an image to use as the logo for this site. Should be http://www.yoursite.com/path/to/logo.png';
$string['pluginname'] = 'Demystified';
$string['regionwidth'] = 'Column width';
$string['regionwidthdesc'] = 'This sets the width of the two block regions that form the left and right columns.';
</code>

In the above lines of code I have added an entry for each language string we used within ''settings.php''. When adding language strings like this make sure you use single quotes and try to keep things alphabetical - it helps greatly when managing strings.

Now when we view the settings page there will not be any errors or strings missing.

===Having a look at what we have created===
Now that we have created our settings page (settings.php) and added all of the language strings it is time to have a look at things in your browser.

Open your browser and enter the URL to your site. When you arrive at your site login as an administrator.

If you are not redirected to view the new settings change your URL to <nowiki>http://www.yoursite.com/admin/</nowiki> and your will see a screen to set the new theme settings we have just created. This lets us know that everything has worked correctly.

At any point now you are able to log in as administrator and within the settings block browse to '''Site administration > Appearance > Themes > Demystified theme''' to change those settings.

The screenshot below shows you what you should see at this point:

[[Image:Theme.settings.page.03.png|715px|thumb|left|The settings page we just created]]
<br style="clear:both;" />

==Using the settings in CSS==
With the settings page now created and operational it is time to make use of our new settings. The settings that we want to use within our CSS is as follows:

; backgroundcolor : Will be used to set the background colour in CSS.
; regionwidth : Will be the width of the column for CSS.
; customcss : Will be some custom CSS to add to our stylesheet.

At this point those names are the names we used for our setting with the slash and everything before it having been removed.

Before we start tearing into some code it is important that we have a look at what we are going to do and how we are going to go about it.

===How it all works within Moodle===
The first thing to understand is that while Moodle allows you to create a settings page and automates it inclusion and management right into the administration interfaces there is no smart equivalent for using the settings. This is simply because there is no way to predict how people will want to use the settings.

However don't think of this as a disadvantage, in fact it is quite the contrary. Although we can't just ''use'' our settings we can take full control over how and where we use them. It means it will take a little more code but in the end that will work to our advantage as we can do anything we want.

Moodle does help us out a little but not in an obvious way. The first thing that Moodle does is look for a config variable '''csspostprocess''' that should be the name of a function which we want called to make any changes to the CSS after it has been prepared.

The second thing Moodle does is include a lib.php from the theme's directory if one exists (also for the themes the current theme extends.) which ensures that as long as we write our code within '''theme/demystified/lib.php''' it will be included and ready to be used.

The third and final thing Moodle does that will help us out here is ensure that by the time any of code is ready to execute the settings have been prepared and are ready to be used within a theme config object which is passed into our ''csspostprocess'' function.

===Our plan===
As you have already probably guessed we will need to create a function to make the changes to the CSS that we want. We will then set the theme config option '''$THEME->csspostprocess''' to the name of our function.

By doing this when Moodle builds the CSS file it will call our function afterwards with the CSS and the theme object that contains our setting.

Now we know that we will use the ''csspostprocess'' function but how are we going to change the CSS, we could get the function to add CSS, or we could get the function to replace something within the CSS. My personal preference is to replace something within the CSS, just like what is happening with images. If you want to use an image within CSS you would write <nowiki>[[pix:theme|imagename]]</nowiki>.

For settings I am going to use <nowiki>[[setting:settingname]]</nowiki>, this way it looks a bit like something you are already familiar with.

What we need to decide upon next is the best way in which to replace our settings tag with the settings that the user has set.

There are two immediate options available to us:
# Make the ''csspostprocess'' function do all the work.
# Make the ''csspostprocess'' function call a separate function for each setting.
Solution 1 might sound like the simplest however it is going to result in a '''VERY''' complex function. Remember the user might have left settings blank or entered something that wouldn't be valid so we would need to make the sure there is some validation and a good default.
Because of this I think that solution 2 is the better solution.

So we are going to need a ''csspostprocess'' function and then a function for each of the three settings we have that will do the replacements.
<code php>
// This is our css post process function
function demystified_process_css($css, $theme) {};
// This replaces [[setting:backgroundcolor]] with the background colour
function demystified_set_backgroundcolor($css, $backgroundcolor) {};
// This replaces [[setting:regionwidth]] with the correct region width
function demystified_set_regionwidth() {$css, $regionwidth};
// This replaces [[setting:customcss]] with the custom css
function demystified_set_customcss() {$css, $customcss};
</code>

What you should note about the above functions is that they all start with the theme's name. This is required to ensure that the functions are named uniquely as it is VERY unlikely that someone has already created these functions.

So with our plan set out lets start writing the code.

===Writing the code===
The very first thing that we need to do is create a lib.php for our theme into which our css processing functions are going to go. So please at this point create '''theme/demystified/lib.php''' and open it in your editor ready to go.

The first bit of code we have to write is the function that will be called by Moodle to do the processing '''demystified_process_css'''.

Before we start out please remember that the wonderful thing about coding is that there is any number of solutions to a problem. The solutions that you are seeing here in this tutorial are solutions that I have come up with to meet fulfil the needs of the tutorial without being so complex that they are hard to understand. This probably isn't how I would go about it normally but this is a little easier to understand for those who aren't overly familiar with PHP and object orientation.

====The function: demystified_process_css====

<code php>
function demystified_process_css($css, $theme) {

if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);

if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);

return $css;
}
</code>

So lets look at the things that make up this function:

<code php>
function demystified_process_css($css, $theme) {
//.....
return $css
}
</code>

This of course is the function declaration.

The function gets given two variables, the first '''$css''' is a pile of CSS as one big string, and the second is the theme object '''$theme''' that contains all of the configuration, options, and settings for our theme.

It then returns the ''$css'' variable, essentially returning the modified CSS.

<code php>
//...
if (!empty($theme->settings->backgroundcolor)) {
$backgroundcolor = $theme->settings->backgroundcolor;
} else {
$backgroundcolor = null;
}
$css = demystified_set_backgroundcolor($css, $backgroundcolor);
//...
</code>

Here we are processing our first setting ''backgroundcolor''.

The first thing that we need to do is check whether it has been set and whether it has a value. If it has then we store that value in '''$backgroundcolor'''. It is doesn't have a value then we set ''$backgroundcolor'' to null. This ensures that ''$backgroundcolor'' is set because if it isn't then you are going to get a notice (if you have debugging on).

The final line of this block calls the function '''demystified_set_backgroundcolor'''. We haven't written this function yet but we will shortly. When we call it we give it the ''$css'' variable that contains all of the CSS and we give it the background colour variable ''$backgroundcolor''. Once this function is finished it returns the ''$css'' variable with all of the changes made much like how our css processing function works.

What you should also note about this code is this:
<code php>
$theme->settings->backgroundcolor
</code>
As mentioned earlier ''$theme'' is an object that contains all of the configuration and settings for our theme. The ''$theme'' object has a $settings property which contains all of the settings for our theme, and finally the settings property contains a variable backgroundcolor that is the value the user entered for that setting. That is how we get a settings value.

<code php>
if (!empty($theme->settings->regionwidth)) {
$regionwidth = $theme->settings->regionwidth;
} else {
$regionwidth = null;
}
$css = demystified_set_regionwidth($css, $regionwidth);

if (!empty($theme->settings->customcss)) {
$customcss = $theme->settings->customcss;
} else {
$customcss = null;
}
$css = demystified_set_customcss($css, $customcss);
</code>

These two routines are nearly identical to the routine above. For both the regionwidth and the customcss we make sure it has a value and then store it in a variable. We then call the relevant function to make the changes for that setting.

Now that we have the general processing function it is time to write the three functions we have used but not written, ''demystified_set_backgroundcolor'', ''demystified_set_regionwidth'', ''demystified_set_customcss''.

====The function: demystified_set_backgroundcolor====

First up demystified_set_backgroundcolor.

<code php>
/**
* Sets the background colour variable in CSS
*
* @param string $css
* @param mixed $backgroundcolor
* @return string
*/
function demystified_set_backgroundcolor($css, $backgroundcolor) {
$tag = '[[setting:backgroundcolor]]';
$replacement = $backgroundcolor;
if (is_null($replacement)) {
$replacement = '#DDDDDD';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

Ok so what is happening here?

First we need a variable '''$tag''' that contains the tag we are going to replace. As mentioned earlier we are going to use tags that look like the image tags you are already familiar with ''<nowiki>[[setting:settingname]]</nowiki>'', in this case ''<nowiki>[[setting:backgroundcolor]]</nowiki>''.

Next I am going to create a variable called '''$replacement''' into which I put '''$backgroundcolor'''.

The '''IF''' statement that comes next checks ''$replacement'' to make sure it is not null. If it is then we need to set it to a default value. In this case I have used ''#DDD'' as that was the default for the settings.

The line after the IF statement puts it all together. The ''str_replace'' function that we are calling takes three arguments in this order:
# The text to search for.
# The text to replace it with.
# The text to do the replacement in.
It then returns the text with all of the replacements made. So in this case we are replacing the tag with the background colour and it is returning the changed CSS.

The final thing is to return the ''$css'' variable which now contains the correct background colour.

====The function: demystified_set_regionwidth====

Next we have the demystified_set_regionwidth function.
<code php>
/**
* Sets the region width variable in CSS
*
* @param string $css
* @param mixed $regionwidth
* @return string
*/
function demystified_set_regionwidth($css, $regionwidth) {
$tag = '[[setting:regionwidth]]';
$doubletag = '[[setting:regionwidthdouble]]';
$replacement = $regionwidth;
if (is_null($replacement)) {
$replacement = 200;
}
$css = str_replace($tag, $replacement.'px', $css);
$css = str_replace($doubletag, ($replacement*2).'px', $css);
return $css;
}
</code>

This function is very similar to the above function however there is one key thing we are doing different. We are doing two replacements.

# The first replacement is for the width that the user selected. In this case I am replacing the tag ''<nowiki>[[setting:regionwidth]]</nowiki>'' with the width.
# The second replacement is for the width x 2. This is because the page layout requires that the width be doubled for some of the CSS. Here I will replace ''<nowiki>[[setting:regionwidthdouble]]</nowiki>'' with the doubled width.

Remember because it is still just a number we need to add '''px''' to the end of each before we do the replacement.

So the overall process of this function is:
# Define the two tags as '''$tag''' and '''$doubletag'''.
# Make '''$replacement''' the region width ''$regionwidth''.
# Set ''$replacement'' to a default value of 200 is it is null.
# Replace '''<nowiki>[[setting:regionwidth]]</nowiki>''' with the width.
# Replace '''<nowiki>[[setting:regionwidthdouble]]</nowiki>''' with the width x 2.
# Return the changed CSS.

====The function: demystified_set_customcss====

The final function that we need to write is the demystified_set_customcss function.
<code php>
/**
* Sets the custom css variable in CSS
*
* @param string $css
* @param mixed $customcss
* @return string
*/
function demystified_set_customcss($css, $customcss) {
$tag = '[[setting:customcss]]';
$replacement = $customcss;
if (is_null($replacement)) {
$replacement = '';
}
$css = str_replace($tag, $replacement, $css);
return $css;
}
</code>

This function is just like the first function. I'm going to let you work it out on your own.

And that is it no more PHP... Hallelujah I can hear you yelling. The final thing we need to do is tell our theme about the functions we have written and put the settings tags into the CSS.

===Finishing it all off===

So there are two things we have to do in order to complete this section and have our the settings page implemented and our settings being used.

First we need to tell our theme that we want to use the function ''demystified_process_css'' as the ''csspostprocess'' function. This is done very simply by adding the following line of PHP to the bottom of our theme's config.php file '''theme/demystified/config.php'''.

<code php>
$THEME->csspostprocess = 'demystified_process_css';
</code>

With that done the only thing left is to add the settings tag into the CSS. Remember those settings tags are:

; <nowiki>[[setting:backgroundcolor]]</nowiki> : We need to add this where ever we want the background colour setting to be used.
; <nowiki>[[setting:regionwidth]]</nowiki> : We need to add this where ever we want to set the width of the block regions.
; <nowiki>[[setting:regionwidthdouble]]</nowiki> : We need to add this where ever we want to set the doubled width of the block regions.
; <nowiki>[[setting:customcss]]</nowiki> : We need to add this to the bottom of the CSS file that we want the custom CSS added to.

So lets make those changes in CSS now, open up your ''core.css'' file and replace the CSS with the CSS below:
<code css>
/** Background color is a setting **/
html {background-color:[[setting:backgroundcolor]];}
body {margin:30px;padding:0;border:1px solid #333;border-width:0 10px 0 10px;background-color:#333;}
body #page {background-color:#FFF;position:relative;top:-10px;}
.block .header {background-image:none;background-color:#0C5CAC;border:1px solid #0C5CAC;color:#FFF;}
.block {border-color:#4BA7FF;background-color:#DDEEFF;}
.block .content {background-color:#F1F8FF;}
a:link,
a:visited {color:#0C5CAC;}
a:hover {color:#C77500;}
#page #page-header {background-color:#0C5CAC;margin:0;padding:0;width:100%;color:#fff;}
#page #page-header a:link, #page #page-header a:visited {color:#FFAC02}
#page #page-header .navbar, #page #page-header .navbar a:link, #page #page-header .navbar a:visited {color:#0C5CAC;}
/** Override the region width **/
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
/** Custom CSS **/
[[setting:customcss]]
</code>

You will notice that <nowiki>[[setting:backgroundcolor]]</nowiki> has been used for the html tags background colour:
<code css>
html {background-color:[[setting:backgroundcolor]];}
</code>

We have also set the width of the block regions by adding <nowiki>[[setting:regionwidth]]</nowiki> as the width for region-pre and region-post as shown below:
<code css>
#page-content #region-main-box {left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidthdouble]];}
#page-content #region-main-box #region-post-box #region-pre {width:[[setting:regionwidth]];left:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-post {width:[[setting:regionwidth]];}
#page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidthdouble]];}
.side-pre-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-pre-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box {margin-left:-[[setting:regionwidth]];}
.side-post-only #page-content #region-main-box #region-post-box #region-main-wrap #region-main {margin-left:[[setting:regionwidth]];}
</code>
You'll notice here that we have to set several different widths and margins using the regionwidth setting and make use of the special regionwidthdouble setting that we added.

The final thing that we did was add the <nowiki>[[setting:customcss]]</nowiki> to the bottom of the file to ensure that the custom CSS comes last (and therefore can override all other CSS).

And with that we are finished. The screenshot below shows how this now looks in the browser if I set the background colour setting to '''<span style='color:#FFA800;'>#FFA800</span>''' and made the column width 240px;

[[Image:Theme.settings.page.04.png|715px|thumb|left|Our settings in action]]<br style="clear:both;" />

==Using the settings within our layout files==
Now that we have utilised the first three settings within our theme's CSS file it is time to implement the other two settings within the layout files so that they are written directly into the page.

You'll be glad to know this is no where near as difficult as utilising settings within a CSS file although it still does require a little bit of PHP.

First up is the logo setting. Into this setting the user is able to enter the URL to an image to use as the logo for the site. In my case I want this to be just a background logo on top of which I want to position the page header.

Before I start there is one thing I need to do however and that is create a default logo background that gets shown if the user hasn't set a specific logo file. To do this I simply created an image '''logo.jpg''' and put it into a pix directory within the demystified theme. You should end up with '''theme/demystified/pix/logo.jpg'''.

Next open up the front-page layout file ''theme/demystified/layout/frontpage.php''. At the top of the file is the PHP that checks what blocks regions the page has and a bit of other stuff. Well right below the existing bit of PHP we want to add the following code:
<code php>
if (!empty($PAGE->theme->settings->logo)) {
$logourl = $PAGE->theme->settings->logo;
} else {
$logourl = $OUTPUT->pix_url('logo', 'theme');
}
</code>
What we are doing here is creating a variable called $logourl that will contain the URL to a logo file that was either entered by the user or if they left it blank is that of our default logo file.

There are two things that you should notice about this. First the logo setting can be retrieved through '''$PAGE->theme->settings->logo''' and second we get the default logo url by calling '''$OUTPUT->pix_url('logo', 'theme')'''.

Now that we have the logo URL we are going to use we need to add an image to the header section of the page as shown below:
<code php>
<div id="page-header" class="clearfix">
<img class="sitelogo" src="<?php echo $logourl;?>" alt="Custom logo here" />
<h1 class="headermain"><?php echo $PAGE->heading ?></h1>
....
</code>

If you save that and browse to your sites front page you will notice that the logo file is now being shown. Hooray. However it is probably not styled too nicely so lets quickly fix that. Open up the core.css file and add the following lines of CSS to the bottom of the file.
<code css>
#page-header {position:relative;min-height:100px;}
#page-header .sitelogo {float:left;}
#page-header .headermain {position:absolute;left:0.5em;top:50px;margin:0;float:none;font-size:40px;}
</code>
These three lines position the image correctly and if you now refresh everything should appear perfectly.

With the logo done the last setting we need to deal with is the footnote setting. The idea with this setting was that the administrator could enter some text into the editor and it would be displayed in the footer of the page.

This is probably the easiest setting to implement.

Within the front page layout file that we edited above add the following lines below those we added previously.

<code php>
if (!empty($PAGE->theme->settings->footnote)) {
$footnote = $PAGE->theme->settings->footnote;
} else {
$footnote = '';
}
</code>

Here we are just collecting the footnote into a variable '''$footnote''' and setting a default footnote comment if the user hasn't entered one.

We can now echo the $footnote variable within the page footer. This can be done as shown below.

<code php>

<div id="page-footer">
<div class="footnote"><?php echo $footnote; ?></div>
<p class="helplink">
<?php echo page_doc_link(get_string('moodledocslink')) ?>
</p>
</code>

And with that done we are finished! Congratulations if you got this far.

The screenshot below shows the demystified theme we have just created that is styled by the settings page.

[[Image:Theme.settings.page.05.png|715px|thumb|left|My finished demystified theme]]<br style="clear:both" />

==Testing our creation==
Congratulations to you! If you've made it this far you have done very well. Now it is time to have a look at what we have created and give it a quick test run.

So in this tutorial we have achieved the following:

* We created a theme called demystified that is based on the standard theme.
* We added a settings page to our new theme.
* We added the following settings to our settings page:
** We can set a background colour through the admin interface.
** We can change the logo of the site.
** We can change the block region width.
** We can add a footnote to the page footer
** We can add some custom CSS to seal the deal.
* Those settings were then used in the CSS files for our theme.
* They were also used in the layout files for our theme.
* And here we are testing it all.

The screenshots below show my testing process and I change each setting and view the outcome. The great thing about this is that with theme designer mode on you see the changes as soon as the form refreshes.

[[Image:Theme.settings.page.06.png|300px|thumb|left|Default settings]]
[[Image:Theme.settings.page.07.png|300px|thumb|left|Changed the background colour setting]]
[[Image:Theme.settings.page.08.png|300px|thumb|left|Changed the logo and region width]]
[[Image:Theme.settings.page.09.png|300px|thumb|left|Added a footnote]]
[[Image:Theme.settings.page.10.png|300px|thumb|left|Added some custom CSS]]
<br style="clear:both" />

==The different settings you can use==
During this tutorial we use four different kinds of settings, a text box, text area, a select (dropdown) and the editor however as I'm sure you have all guessed there is many more some of which will certainly be useful for theme settings.

The following are examples of some of the different settings. I should add that these build upon what we have already done within the tutorial but are not included in the download.

===Colour picker===
[[Image:Theme.settings.page.11.png|400px|thumb|The colour picker]]
I can hear you all asking now 'Why didn't you mention this one earlier?' well the answer is simple it didn't exist when I first wrote the tutorial. It is an admin setting that I wrote several days after because of the fantastic effort people were putting into trying out settings pages.

A bit about the colour picker. First up it is a text box that when the page loads turns into a colour picker that can be used to select a colour and can even preview the selected colour in the page (by clicking the preview button). It is designed to be very easy to use and the code is just about as simple as creating a normal text box setting.

In the image to the left I have replaced the background colour setting we created during the tutorial with the colour picker. Lets have a look at the code involved for that.
<code php>
// Background colour setting
$name = 'theme_demystified/backgroundcolor';
$title = get_string('backgroundcolor','theme_demystified');
$description = get_string('backgroundcolordesc', 'theme_demystified');
$default = '#DDD';
$previewconfig = array('selector'=>'html', 'style'=>'backgroundColor');
$setting = new admin_setting_configcolourpicker($name, $title, $description, $default, $previewconfig);
$temp->add($setting);
</code>
So first thing you should notice is that the first four lines of code have not changed at all!

The first change we have is to create a variable '''$previewconfig'''.
This variable is used to tell the colour picker what to do when the user clicks the preview button. It should be an array that contains two things, first a selector, and second a style.
# The selector is a CSS selector like ''.page .header h2''.
# The style is a what should change, there are two immediate values it can be, either '''backgroundColor''' or '''color'''.
In my case the selector is '''html''' to target the html tag and the style is backgroundColor to change the background colour.

The second change is to use '''admin_setting_configcolourpicker''' instead of ''admin_setting_configtext''. The arguments are nearly identical as well except that there is an extra argument to which we give the '''$previewconfig''' variable.

And that is it! it is all you need to get the colour picker up and running.

'''Extra note:''' The $previewconfig variable is optional. If you don't want a preview button the simply set ''$previewconfig = null''

==Common pitfalls and useful notes==

This section is really just a collection of pointers, tips, notes, and other short useful stuff that may be of use to those attempting this tutorial.

# First up and most importantly there are very few limitations to what you achieve in this fashion.
# If you get stuck or need a hand ask in the forums, there's always someone round who can help.
# If you do something really cool let us know, I know everyone in the community loves finding our what others are achieving.
# You don't have to use ''admin_settingpage'' you can also use '''admin_externalpage''' if you prefer. It should be noted however that it is not the preferred way to do it as admin_externalpage's were only left in Moodle 2.0 for backwards compatibility (although they are more flexible one day they will be deprecated or removed). Thank you to Darryl for raising this.
# If you find that your language strings aren't being used (you are getting language string notices) and you have double checked that you have turned '''langstringcache''' off then you may need to delete the language cache directory. This is located in the moodledata directory for you installation: moodledata/cache/lang/*. You should delete the directory for your chosen language by default ''en''.

==See also==

* [[Adding theme upgrade code]]
* [[Styling and customising the dock]]
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=152053 Theme 2.0: Adding a settings page to your theme] forum discussion

Talk:Dialogue 2.0 specification

2011-07-20T00:39:06Z

Cttxg: adding note about more than one teacher being able to see/participate

Notes to remember - sometimes there is more than one teacher who needs to see all / participate any with an easy way to set this (instead of tweaking roles & permissions)

Dialogue 2.0 specification

2010-09-13T21:58:58Z

Cttxg: /* Group support */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
* Teacher posts the same message to all students in ‘Course A’, future enrolled students also receive the same message. Individual conversation created between teacher and each student. Multiple replies are allowed.
* Teacher posts the same message to all members of ‘Group A’, future group members also receive the same message. Individual conversation created between teacher and each user (any role) in ‘Group A’. Multiple replies are allowed.
* Teacher posts the same message to specific students in ‘Course A’. Individual conversation created between teacher and each student. Multiple replies are allowed.
* Teacher posts a message to a specific student in ‘Course A’. Individual conversation created between teacher and specific student . Student can view but not reply. Multiple followup replies are allowed for teacher.
* Student posts a message to a specific teacher in ‘Course A’. Individual conversation created between teacher and student. Multiple followup replies are allowed.
* Teacher A leaves, Teacher B needs to manage all conversations to allow followup replies, close and delete.
* Specific Student (eg Class Rep with own role) posts a message to all students in ‘Course A’. Individual conversation created between Class Rep and each student. Multiple followup replies are allowed.
* Specific Student (eg Class Rep with own role) posts a message to a specific student in ‘Course A’. Individual conversation created between Class Rep and specific student. Multiple followup replies are allowed.
* Specific Student posts a message into a specific role (eg Class Rep role). Individual conversation created between specific student and Class Rep. Multiple followup replies are allowed.
* All Teachers can view and participate in any existing conversation in a shared teaching situation.

=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User will see all groups listed in the recipient picker. User can open a conversation with any user or group of users.

==== Separate groups mode ====
User will see groups they are a member of listed in the recipient picker. User can open a conversation with any user in a group they are a member of.

User with capability moodle/site:accessallgroups with permission allow will see all groups listed in the recipient picker and can open a conversation with any user regardless of group membership.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
The following options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled notification will include post content and a link to specific dialogue conversation. If not enabled notification will include post title and a link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id of this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the dialogue
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user id of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
Restoring a 1.9x backup into a 2.0 Moodle? TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010

Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T21:50:02Z

Cttxg: /* Usage scenarios */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
* Teacher posts the same message to all students in ‘Course A’, future enrolled students also receive the same message. Individual conversation created between teacher and each student. Multiple replies are allowed.
* Teacher posts the same message to all members of ‘Group A’, future group members also receive the same message. Individual conversation created between teacher and each user (any role) in ‘Group A’. Multiple replies are allowed.
* Teacher posts the same message to specific students in ‘Course A’. Individual conversation created between teacher and each student. Multiple replies are allowed.
* Teacher posts a message to a specific student in ‘Course A’. Individual conversation created between teacher and specific student . Student can view but not reply. Multiple followup replies are allowed for teacher.
* Student posts a message to a specific teacher in ‘Course A’. Individual conversation created between teacher and student. Multiple followup replies are allowed.
* Teacher A leaves, Teacher B needs to manage all conversations to allow followup replies, close and delete.
* Specific Student (eg Class Rep with own role) posts a message to all students in ‘Course A’. Individual conversation created between Class Rep and each student. Multiple followup replies are allowed.
* Specific Student (eg Class Rep with own role) posts a message to a specific student in ‘Course A’. Individual conversation created between Class Rep and specific student. Multiple followup replies are allowed.
* Specific Student posts a message into a specific role (eg Class Rep role). Individual conversation created between specific student and Class Rep. Multiple followup replies are allowed.
* All Teachers can view and participate in any existing conversation in a shared teaching situation.

=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any user in any visible group.

==== Separate groups mode ====
User can open a conversation with any other user in a group they are a member of. User with capability moodle/site:accessallgroups with permission allow can open a conversation with any user regardless of group membership.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
The following options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled notification will include post content and a link to specific dialogue conversation. If not enabled notification will include post title and a link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id of this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the dialogue
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user id of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
Restoring a 1.9x backup into a 2.0 Moodle? TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010

Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T21:44:54Z

Cttxg: /* Usage scenarios */ updated wording for scenarios

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
* Teacher posts the same message to all students in ‘Course A’, future enrolled students also receive the same message. Individual conversation created between teacher and each student. Multiple replies are allowed.
* Teacher posts the same message to all members of ‘Group A’, future group members also receive the same message. Individual conversation created between teacher and each user (any role) in ‘Group A’. Multiple replies are allowed.
* Teacher posts the same message to specific students in ‘Course A’. Individual conversation created between teacher and each student. Multiple replies are allowed.
* Teacher posts a message to a specific student in ‘Course A’. Individual conversation created between teacher and specific student . Student can view but not reply. Multiple followup replies are allowed for teacher.
* Student posts a message to a specific teacher in ‘Course A’. Individual conversation created between teacher and student. Multiple followup replies are allowed.
* Teacher A leaves, Teacher B needs to manage all conversations to allow followup replies, close and delete.
* Specific Student (eg Class Rep with own role) posts a message to all students in ‘Course A’. Individual conversation created between Class Rep and each student. Multiple followup replies are allowed.
* Specific Student (eg Class Rep with own role) posts a message to a specific student in ‘Course A’. Individual conversation created between Class Rep and specific student. Multiple followup replies are allowed.
* Students posts a message into a specific role (eg Class Rep role). Individual conversation created between specific student and Class Rep. Multiple followup replies are allowed.
* All Teachers can view and participate in any existing conversation in a shared teaching situation.

=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any user in any visible group.

==== Separate groups mode ====
User can open a conversation with any other user in a group they are a member of. User with capability moodle/site:accessallgroups with permission allow can open a conversation with any user regardless of group membership.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
The following options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled notification will include post content and a link to specific dialogue conversation. If not enabled notification will include post title and a link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id of this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the dialogue
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user id of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
Restoring a 1.9x backup into a 2.0 Moodle? TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010

Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T06:47:52Z

Cttxg: /* Usage scenarios */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
* Teacher posts the same message in a conversation to all students in ‘Course A’, future enrolled students also receive the same conversation. Multiple followup replies are allowed.
* Teacher posts the same message in a conversation to all members of ‘Group A’, future group members also receive the same conversation. All roles in ‘Group A’ receive the conversation. Multiple followup replies are allowed.
* Teacher posts the same message in a conversation to specific students in ‘Course A’. Multiple followup replies are allowed.
* Teacher posts a message in a conversation to a specific student in ‘Course A’. Student can view but not respond. Multiple followup replies are not allowed.
* Student posts a message in a conversation to a specific teacher in ‘Course A’. Multiple followup replies are allowed.
* Teacher A leaves, Teacher B needs to transfer ownership of conversations to allow followup replies, close and delete.
* Specific Student (eg Class Rep with own role) posts a message in a conversation to all students in ‘Course A’. Multiple followup replies are allowed.
* Specific Student (eg Class Rep with own role) posts a message in a conversation to a specific student in ‘Course A’. Multiple followup replies are allowed.
* Students posts a message in a conversation to a specific student(eg Class Rep with own role). Multiple followup replies are allowed.
* All Teachers can view and participate in any existing conversation in a shared teaching situation.

=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any user in any visible group.

==== Separate groups mode ====
User can open a conversation with any other user in a group they are a member of. User with capability moodle/site:accessallgroups with permission allow can open a conversation with any user regardless of group membership.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
The following options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled notification will include post content and a link to specific dialogue conversation. If not enabled notification will include post title and a link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id of this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the dialogue
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user id of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T06:47:09Z

Cttxg: /* Usage scenarios */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
* Teacher posts the same message in a conversation to all students in ‘Course A’, future enrolled students also receive the same conversation. Multiple followup replies are allowed.
* Teacher posts the same message in a conversation to all members of ‘Group A’, future group members also receive the same conversation. All roles in ‘Group A’ receive the conversation. Multiple followup replies are allowed.
* Teacher posts the same message in a conversation to specific students in ‘Course A’. Multiple followup replies are allowed.
* Teacher posts a message in a conversation to a specific student in ‘Course A’. Student can view but not respond. Multiple followup replies are not allowed.
* Student posts a message in a conversation to a specific teacher in ‘Course A’. Multiple followup replies are allowed.
* Teacher A leaves, Teacher B needs to transfer ownership of conversations to allow followup replies, close and delete.
* Specific Student (eg Class Rep with own role) posts a message in a conversation to all students in ‘Course A’. Multiple followup replies are allowed.
* Specific Student (eg Class Rep with own role) posts a message in a conversation to a specific student in ‘Course A’. Multiple followup replies are allowed.
* Students posts a message in a conversation to a specific role (eg Class Rep role). Multiple followup replies are allowed.
* All Teachers can view and participate in any existing conversation in a shared teaching situation.

=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any user in any visible group.

==== Separate groups mode ====
User can open a conversation with any other user in a group they are a member of. User with capability moodle/site:accessallgroups with permission allow can open a conversation with any user regardless of group membership.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
The following options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled notification will include post content and a link to specific dialogue conversation. If not enabled notification will include post title and a link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id of this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the dialogue
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user id of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T06:28:25Z

Cttxg: /* dialogue_read */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
*Teacher sends same course welcome message to all students in “Course A” including future students. Not other roles. Multiple messages.
*Teacher sends same group welcome message to all members of “Group A” including future members. All roles in “Group A”. Multiple messages.
*Teacher sends same message to some students. Multiple messages.
*A Teacher can send “Message” to a student. Student can view but not respond. Single user message.
*A Student can send “Message” to a Teacher. But not to other students. Single user message.
*Teacher A leaves, Teacher B needs to close a Dialogue that posts to all Students.
*A specific Student (eg Class Rep with specified role) can send a “Message” to all students. Ongoing conversation allowed.
*A Student can send a “Message” to a specific students (eg Class Rep with specified role). Ongoing conversation allowed.
*All Teachers can view and participate in any existing conversation in a shared teaching situation.
=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any user in any visible group.

==== Separate groups mode ====
User can open a conversation with any other user in a group they are a member of. User with capability moodle/site:accessallgroups with permission allow can open a conversation with any user regardless of group membership.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
The following options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled notification will include post content and a link to specific dialogue conversation. If not enabled notification will include post title and a link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id of this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the dialogue
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user id of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T06:25:58Z

Cttxg: /* dialogue */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
*Teacher sends same course welcome message to all students in “Course A” including future students. Not other roles. Multiple messages.
*Teacher sends same group welcome message to all members of “Group A” including future members. All roles in “Group A”. Multiple messages.
*Teacher sends same message to some students. Multiple messages.
*A Teacher can send “Message” to a student. Student can view but not respond. Single user message.
*A Student can send “Message” to a Teacher. But not to other students. Single user message.
*Teacher A leaves, Teacher B needs to close a Dialogue that posts to all Students.
*A specific Student (eg Class Rep with specified role) can send a “Message” to all students. Ongoing conversation allowed.
*A Student can send a “Message” to a specific students (eg Class Rep with specified role). Ongoing conversation allowed.
*All Teachers can view and participate in any existing conversation in a shared teaching situation.
=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any user in any visible group.

==== Separate groups mode ====
User can open a conversation with any other user in a group they are a member of. User with capability moodle/site:accessallgroups with permission allow can open a conversation with any user regardless of group membership.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
The following options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled notification will include post content and a link to specific dialogue conversation. If not enabled notification will include post title and a link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id of this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the dialogue
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user if of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T06:19:05Z

Cttxg: /* Dialogue module instance options */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
*Teacher sends same course welcome message to all students in “Course A” including future students. Not other roles. Multiple messages.
*Teacher sends same group welcome message to all members of “Group A” including future members. All roles in “Group A”. Multiple messages.
*Teacher sends same message to some students. Multiple messages.
*A Teacher can send “Message” to a student. Student can view but not respond. Single user message.
*A Student can send “Message” to a Teacher. But not to other students. Single user message.
*Teacher A leaves, Teacher B needs to close a Dialogue that posts to all Students.
*A specific Student (eg Class Rep with specified role) can send a “Message” to all students. Ongoing conversation allowed.
*A Student can send a “Message” to a specific students (eg Class Rep with specified role). Ongoing conversation allowed.
*All Teachers can view and participate in any existing conversation in a shared teaching situation.
=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any user in any visible group.

==== Separate groups mode ====
User can open a conversation with any other user in a group they are a member of. User with capability moodle/site:accessallgroups with permission allow can open a conversation with any user regardless of group membership.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
The following options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled notification will include post content and a link to specific dialogue conversation. If not enabled notification will include post title and a link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the workshop
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user if of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T06:11:00Z

Cttxg: /* Separate groups mode */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
*Teacher sends same course welcome message to all students in “Course A” including future students. Not other roles. Multiple messages.
*Teacher sends same group welcome message to all members of “Group A” including future members. All roles in “Group A”. Multiple messages.
*Teacher sends same message to some students. Multiple messages.
*A Teacher can send “Message” to a student. Student can view but not respond. Single user message.
*A Student can send “Message” to a Teacher. But not to other students. Single user message.
*Teacher A leaves, Teacher B needs to close a Dialogue that posts to all Students.
*A specific Student (eg Class Rep with specified role) can send a “Message” to all students. Ongoing conversation allowed.
*A Student can send a “Message” to a specific students (eg Class Rep with specified role). Ongoing conversation allowed.
*All Teachers can view and participate in any existing conversation in a shared teaching situation.
=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any user in any visible group.

==== Separate groups mode ====
User can open a conversation with any other user in a group they are a member of. User with capability moodle/site:accessallgroups with permission allow can open a conversation with any user regardless of group membership.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
Follow options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled will include post content and link to specific dialogue conversation else will new post type message and link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the workshop
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user if of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T06:09:42Z

Cttxg: /* Visible groups mode */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
*Teacher sends same course welcome message to all students in “Course A” including future students. Not other roles. Multiple messages.
*Teacher sends same group welcome message to all members of “Group A” including future members. All roles in “Group A”. Multiple messages.
*Teacher sends same message to some students. Multiple messages.
*A Teacher can send “Message” to a student. Student can view but not respond. Single user message.
*A Student can send “Message” to a Teacher. But not to other students. Single user message.
*Teacher A leaves, Teacher B needs to close a Dialogue that posts to all Students.
*A specific Student (eg Class Rep with specified role) can send a “Message” to all students. Ongoing conversation allowed.
*A Student can send a “Message” to a specific students (eg Class Rep with specified role). Ongoing conversation allowed.
*All Teachers can view and participate in any existing conversation in a shared teaching situation.
=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any user in any visible group.

==== Separate groups mode ====
User can open a conversation with any person in a group they are a member of unless has capability moodle/site:accessallgroups with permission allow.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
Follow options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled will include post content and link to specific dialogue conversation else will new post type message and link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the workshop
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user if of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T05:19:59Z

Cttxg: /* Auto open multiple */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
*Teacher sends same course welcome message to all students in “Course A” including future students. Not other roles. Multiple messages.
*Teacher sends same group welcome message to all members of “Group A” including future members. All roles in “Group A”. Multiple messages.
*Teacher sends same message to some students. Multiple messages.
*A Teacher can send “Message” to a student. Student can view but not respond. Single user message.
*A Student can send “Message” to a Teacher. But not to other students. Single user message.
*Teacher A leaves, Teacher B needs to close a Dialogue that posts to all Students.
*A specific Student (eg Class Rep with specified role) can send a “Message” to all students. Ongoing conversation allowed.
*A Student can send a “Message” to a specific students (eg Class Rep with specified role). Ongoing conversation allowed.
*All Teachers can view and participate in any existing conversation in a shared teaching situation.
=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.

If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending on time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any person in any visible group.
==== Separate groups mode ====
User can open a conversation with any person in a group they are a member of unless has capability moodle/site:accessallgroups with permission allow.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
Follow options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled will include post content and link to specific dialogue conversation else will new post type message and link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the workshop
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user if of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T05:11:18Z

Cttxg: /* Glossary */

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
*Teacher sends same course welcome message to all students in “Course A” including future students. Not other roles. Multiple messages.
*Teacher sends same group welcome message to all members of “Group A” including future members. All roles in “Group A”. Multiple messages.
*Teacher sends same message to some students. Multiple messages.
*A Teacher can send “Message” to a student. Student can view but not respond. Single user message.
*A Student can send “Message” to a Teacher. But not to other students. Single user message.
*Teacher A leaves, Teacher B needs to close a Dialogue that posts to all Students.
*A specific Student (eg Class Rep with specified role) can send a “Message” to all students. Ongoing conversation allowed.
*A Student can send a “Message” to a specific students (eg Class Rep with specified role). Ongoing conversation allowed.
*All Teachers can view and participate in any existing conversation in a shared teaching situation.
=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of a dialogue activity module.
|-
| Conversation
| An instance of communication between two users within a dialogue activity. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.
If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending of time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any person in any visible group.
==== Separate groups mode ====
User can open a conversation with any person in a group they are a member of unless has capability moodle/site:accessallgroups with permission allow.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
Follow options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled will include post content and link to specific dialogue conversation else will new post type message and link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the workshop
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user if of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

Dialogue 2.0 specification

2010-09-13T05:10:04Z

Cttxg: /* Introduction */ email and backup info added

This page tracks and summarises the progress of rewrite of the [[Dialogue]] module for Moodle 2.0. {{Moodle 2.0}}
{| class="nicetable" style="float: right;"
|-
! colspan="2" | Dialogue 2.0 specification
|-
| Status
| '''Draft'''
|-
| Tracker
| http://tracker.moodle.org/browse/CONTRIB-2059 | CONTRIB-2059
|}

== Introduction ==
The Dialogue module allows students or teachers to start a two-way conversation with another person. The Dialogue is a course activity that can be useful when the teacher wants a place to give private feedback to a student on their online activity. For example, if a student is participating in a language forum and made a grammatical error that the teacher wants to point out without embarrassing the student, a dialogue is the perfect place. A dialogue activity would also be an excellent way for counselors within an institution to interact with students - all activities are logged and email is available but not necessarily required. The Dialogue is also a useful alternative to email or private Messages as the conversations are located within a course. The Dialogue module can be backed up with other course activities.
=== Usage scenarios ===
*Teacher sends same course welcome message to all students in “Course A” including future students. Not other roles. Multiple messages.
*Teacher sends same group welcome message to all members of “Group A” including future members. All roles in “Group A”. Multiple messages.
*Teacher sends same message to some students. Multiple messages.
*A Teacher can send “Message” to a student. Student can view but not respond. Single user message.
*A Student can send “Message” to a Teacher. But not to other students. Single user message.
*Teacher A leaves, Teacher B needs to close a Dialogue that posts to all Students.
*A specific Student (eg Class Rep with specified role) can send a “Message” to all students. Ongoing conversation allowed.
*A Student can send a “Message” to a specific students (eg Class Rep with specified role). Ongoing conversation allowed.
*All Teachers can view and participate in any existing conversation in a shared teaching situation.
=== Design goals ===
# Retain existing functionality.
# Enhance usage scenarios, flexibility and control.
# Enhance user interface.

== Glossary ==
{| class="nicetable"
|-
! Term
! Definition
|-
| Dialogue
| An instance of an dialogue activity module.
|-
| Conversation
| An instance of communication between to two users within a dialogue. Follow vertical linear pattern.
|-
| Reply
| A message posted in reply to conversational text.
|}

== User interface mock-ups ==
=== Dialogue listing ===
[[Image:DRAFT dialogue2.0 mockup-mainindex.png | sample | 600px]]

=== Dialogue view ===
[[Image:DRAFT dialogue2.0 mockup-readnpost.png | sample | 600px]]

[[Image:DRAFT dialogue2.0 mockup-closed.png | sample | 600px]]

=== Dialogue new ===
==== Recipient picker ====
'''Basic features'''
Use a standard drop down for single recipient selection.

[[Image:DRAFT dialogue2.0 mockup-recipentpicker.png]]

Multiple user selection

[[Image:DRAFT dialogue2.0 mockup-standardmultirecipentpicker.png | sample | 600px]]

Use standard multiple user selection interface as found in enrol users, groups e.t.c

'''Advanced features'''
Ajax recipient picker, must be able to handle both single and multiple recipient selection.

[[Image: DRAFT_dialogue2.0_mockup-ajaxrecipentpicker.png | sample | 300px ]]

== Implementation plan ==
=== Multiple dialogue open ===
If user has capability mod/dialogue:openmultiple with permission set to allow, they can select multiple users to open a conversation with that will contain the same subject, body, attachment(s).

=== Auto open multiple ===
If a user has the capability mod/dialogue:autoopenmultiple with permission set to allow, they can open a automated conversation that will contain the same subject, body, attachment(s) with:
* "All Participants" -> All course members
Any newly enrolled users will receive dialogue.
If in group mode
* "A Group" -> All members in that group.
* "Multiple Groups" -> e.g Group A, Group C will open with any member of a selected group.
Any new group member will receive dialogue.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a dialogue with.

This information will be stored to a new table '''mdl_dialogue_automated''' this will allow user to delete conversation at anytime if they want to stop opening conversations with newly enrolled users or group members. Depending of time, could also add a date range option to control opening.

=== Group support ===
==== Visible groups mode ====
User can open a conversation with any person in any visible group.
==== Separate groups mode ====
User can open a conversation with any person in a group they are a member of unless has capability moodle/site:accessallgroups with permission allow.

'''Note:''' New capability mod/dialogue:receive will also determine what roles (student, teacher e.t.c) a user can open a conversation with.

=== File attachments ===
==== File API ====
Use filemanager element in the formslib to get one or more file from user for each post, file(s) stored permanently for future viewing.

=== Notifications ===
==== Messaging API ====
Setup messageprovider for routing notifications.

==== Dialogue module instance options ====
Follow options can be configured when creating a new dialogue module instance or updating/editing a dialogue module instance.
*Enable notifications
:Allow notifications, passed on to Messaging API.
*Include post content in notification
:If enabled will include post content and link to specific dialogue conversation else will new post type message and link to specific dialogue conversation.

=== Event API ===
'''user_enrolled()'''
:Can be used for any automated opening of dialogues for new course participants when all participants were selected in a multi-open dialogue.

'''groups_member_added()'''
:Can be used for any automated opening of dialogues for new group members when group(s) were elected in a multi-open dialogue.

'''user_unenrolled()'''
:Cleanup function, delete any dialogues that user is a recipient.

=== Navigation functions ===
'''dialogue_extend_navigation($navref, $course, $module, $cm)'''
:Can use for dialogue unread count, filters(All, Unread, Read e.t.c) providing direct linking.
'''dialogue_extend_settings_navigation(settings_navigation $settingsnav, navigation_node $dialoguenode)'''
:Can use for showing automated multiple open dialogue???

=== Logging ===
Dialogue events that will be logged.
* open
* view
* reply
* edit
* close
* delete

=== Database structures ===
[[Image:DRAFT_dialogue2.0_schema.png | sample | 600px ]]
==== dialogue ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| intro
| text (medium)
|
| the description/assignment of the workshop
|
|-
| introformat
| int (3)
| 0
| the format of the intro field
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|-
| edittime
| int (10)
| 0
|
|-
| maxattachments
| int (3)
| 1
| number of attachments
|
|-
| maxbytes
| int (10)
| 100000
| maximum size of the one attached file
|
|-
| notifications
| int (2)
| 1
| allow post notifications, will use MessagingAPI
|
|-
| notificationcontent
| int (2)
| 0
| include post content in notification
|
|}

==== dialogue_conversations ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipientid
| int (10)
| 0
| user id of person who is to receive conversation
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| lastreply
| int (2)
| 0
| reply id of last post in the conversation
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| closed
| int (2)
| 0
| flag to indicate if conversation has been closed
|
|-
| deleted
| int (2)
| 0
| flag to indicate conversation as deleted
| '''???''' Unsure
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_replies ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to.
|
|-
| parentid
| int (10)
| 0
| the previous reply if exists, else if 0 directly follows conversation
| '''???''' unsure
|-
| ownerid
| int (10)
| 0
| user id of person who posted reply
|
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| attachment
| int (2)
| 0
| if post contains attachment(s)
|
|-
| sent
| int (2)
| 0
| flag to indicate if message has been sent to recipient
|
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

==== dialogue_read ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| userid
| int (10)
| 0
| user if of person who viewed conversation or reply
|
|-
| dialogueid
| int (10)
| 0
| the dialogue id that the conversation relates to.
|
|-
| conversationid
| int (10)
| 0
| the conversation id that reply relates to
|
|-
| replyid
| int (10)
| 0
| the reply id, can be 0 if user has just viewed start of conversation
|
|-
| firstread
| int (10)
| 0
| datetime first read
|
|-
| lastread
| int (10)
| 0
| datetime last read
|
|}

==== dialogue_automated ====
{| class="nicetable"
|-
! Field
! Type
! Default
! Description
! Notes
|-
| '''id'''
| int (10)
|
| auto-numbered
|
|-
| course
| int (10)
| 0
| the course id this dialogue
|
|-
| dialogueid
| int (10)
| 0
| the dialogue instance id
|
|-
| subject
| varchar (255)
| ''
| brief summary of message
|
|-
| ownerid
| int (10)
| 0
| user id of person who started conversation
|
|-
| recipients
| text (small)
| 0
| indicators for "All participants" or selected groups
| serialised array or object
|-
| text
| text (medium)
| ''
| message text
|
|-
| format
| int (3)
| 0
| the format type of message
|
|-
| timestart
| int (10)
| 0
| the datetime start range, users enrolled after will receive
| '''???''' may be later implemented
|-
| timeend
| int (10)
| 0
| the datetime end range, users enrolled before will receive
| '''???''' may be later implemented
|-
| timemodified
| int (10)
| 0
| the timestamp when the module was modified
|
|}

=== Capabilities and Permissions ===
{| class="nicetable"
|-
! Capability
! Description
! Role permissions(defaults)
! Notes
|-
| mod/dialogue:open
| Open a dialogue with single recipient
| teacher
|
|-
| mod/dialogue:receive
| Can receive a dialogue
| student
| Can be used to control what roles are displayed in the recipient picker
|-
| mod/dialogue:reply
| Can reply to a dialogue
| teacher, student
|
|-
| mod/dialogue:closeown
| Can close a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteown
| Can delete a dialogue if have ownership
| teacher, student
|
|-
| mod/dialogue:deleteownreply
| Can delete own reply
| teacher, student
| Add ability to delete last reply in dialogue thread. '''Maybe/Maybe not?'''
|-
| mod/dialogue:openmultiple
| Can start a dialogue with multiple recipients
| teacher
| For sending the same dialogue to multiple recipients. Used for targeting particular group(s) of users or whole class.
|-
| mod/dialogue:autoopenmultiple
| Can start a automated dialogue with course participants or group members which includes future members.
| teacher
|
|-
| mod/dialogue:viewany
| view any conversation, reply
| administrator
|
|-
| mod/dialogue:replyany
| can reply in any conversation to any reply
| administrator
|
|-
| mod/dialogue:closeany
| can close any conversation
| administrator
|
|-
| mod/dialogue:deleteany
| can delete any conversation
| administrator
|
|}

=== Backup and Restore ===
Create backup and restore functions under 2.0

'''1.9x'''
TO-DO

=== Upgrade Process ===
Will need to map existing table structure to new table structure once finalised.

=== Translations ===
Current 1.9x translations
* en English
* de Deutsch German
* es Español Spanish
* it Italiano Italian

== Project schedule ==
=== Milestone 1 ===
Date: 28/09/2010
Goal: The specification is reviewed and agreed on by the community. The implementation plan is transferred into sub-tasks in the tracker
[[Category:Contributed code]]

User:Teresa Gibbison

2009-07-08T03:34:22Z

Cttxg: New page: Moodle Administrator for the University of Waikato, Hamilton, NZ. I have been working with Moodle since 2004 having previously worked on two eCDF Funded projects and as the Moodle Administ...

Moodle Administrator for the University of Waikato, Hamilton, NZ. I have been working with Moodle since 2004 having previously worked on two eCDF Funded projects and as the Moodle Administration Specialist at the Waikato Institute of Technology.