https://docs.moodle.org/dev/api.php?action=feedcontributions&feedformat=atom&user=RwijayaMoodleDocs - User contributions [en]2026-10-04T12:25:15ZUser contributionsMediaWiki 1.43.5https://docs.moodle.org/dev/index.php?title=HTML_Guidelines&diff=42834HTML Guidelines2013-11-01T09:11:42Z<p>Rwijaya: /* Header */</p>
<hr />
<div>==Purpose==<br />
The purpose of these HTML Guidelines it to provide the groundwork for a clear and consistent Document Object Model throughout Moodle, that allows for semantic definition of the content, in keeping with best practices from across the web. As a side affect, this should improve the ability to theme Moodle in a more consistent manner, and aid in improving the accessibility of Moodle's pages in general.<br />
<br />
==Header==<br />
Header usage should be hierarchical within page views<br />
Reference link: [[Standardize classnames and layout to facilitate theming]]<br />
<br />
* Headers should be hierarchical, with two or more &lt;h3&gt; under each &lt;h2&gt; and so forth. However an exception applied to front-page where multiple &lt;h2&gt; are allowed for displaying the page's items (eg: list of courses, list of categories, etc).<br />
* &lt;h2&gt; is the top-level header of the page content/central column and should only be used once within a page. However, there are couple of exceptions applied to level 2 heading:<br />
** Front-page is allowed to have multiple &lt;h2&gt;<br />
** External Tools (LTI) activity has setting to display the header. The setting name to display heading is 'Display activity name when launched' and the default value is set to true. If user disabled this setting, the header will not available on the page.<br />
* Headers should not be used for notification. Notification classes should be used for notification.<br />
* For H1 and H2 elements, no additional classes should be added. For H3 and below, some classes that describe the purpose of that heading such as sectionname, and others that provide functionality, such as dimmed_text, may be needed. Blanket and vague classnames should be eliminated (main, header, title, mdl-align, etc).<br />
* We shouldn't be wrapping a heading in a div just to allow it to be styled. This complicates the DOM, and defeats the purpose of any effort to standardize the appearance of headings across the page.<br />
<br />
<br />
Not this:<br />
<pre><br />
<h2 class="main">This is the top-level header</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">These is your score on XX activity.</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">You must make a selection to proceed.</h2><br />
<input type="submit" value="Generic submit button"><br />
</pre><br />
<br />
This: <br />
<pre><br />
<h2>This is the top-level header</h2><br />
<p>This paragraph gives additional information and explains what's to come.</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<div class="notifyproblem">You must make a selection to proceed.</div><br />
</pre><br />
<br />
===Block===<br />
Blocks should consist of the following:<br />
* Block's name should start at level 2<br />
* Block's alignment should used the definition in theme, unless it is forcely modified through Tinymce which is using inline styling.<br />
[[File:block.png]]<br />
<br />
==Activity page==<br />
The display for the activity's content should contained the following:<br />
* Course name with level 1 header<br />
* Activity name with level 2 header<br />
* Content header should start at level 3 and lower for its sub-content. Although Tinymce allowed the use of level 1 and 2, it should be avoided.<br />
* Use theme alignment for displaying the content.<br />
* Content styling such as: alignment, font-size, font-family should inherit from theme.<br />
[[File:activity.png]]<br />
<br />
==Update in core API:==<br />
As part of removing '.main' class from header tag, we have updated the following functions in core outputrenderer API file:<br />
===Heading===<br />
For this function we changed the default value for the classes parameter value from 'main' to null.<br />
<code php><br />
heading($text, $level = 2, $classes = 'main', $id = null)<br />
To<br />
heading($text, $level = 2, $classes = null, $id = null)<br />
</code><br />
<br />
===Heading with help===<br />
For this function we added two additional parameters to set the heading level and classname. The level parameter value is defaulted to 2 and classnames is defaulted to null.<br />
<code php><br />
heading_with_help($text, $helpidentifier, $component = 'moodle', $icon = '', $iconalt = '')<br />
To<br />
heading_with_help($text, $helpidentifier, $component = 'moodle', $icon = '', $iconalt = '', $level = 2, $classnames = null)<br />
</code><br />
<br />
The detailed of changes for the above functions is reported in MDL-41438.</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=HTML_Guidelines&diff=42328HTML Guidelines2013-09-13T06:06:12Z<p>Rwijaya: </p>
<hr />
<div>==Header==<br />
Header usage should be hierarchical within page views<br />
Reference link: [[Standardize classnames and layout to facilitate theming]]<br />
<br />
* Headers should be hierarchical, with two or more &lt;h3&gt; under each &lt;h2&gt; and so forth. However an exception applied to front-page where multiple &lt;h2&gt; are allowed for displaying the page's items (eg: list of courses, list of categories, etc).<br />
* &lt;h2&gt; is the top-level header of the page content/central column. There should be only one &lt;h2&gt; (except for front-page where multiple &lt;h2&gt; are allowed).<br />
* Headers should not be used for notification. Notification classes should be used for notification.<br />
* For H1 and H2 elements, no additional classes should be added. For H3 and below, some classes that describe the purpose of that heading such as sectionname, and others that provide functionality, such as dimmed_text, may be needed. Blanket and vague classnames should be eliminated (main, header, title, mdl-align, etc).<br />
* We shouldn't be wrapping a heading in a div just to allow it to be styled. This complicates the DOM, and defeats the purpose of any effort to standardize the appearance of headings across the page.<br />
<br />
<br />
Not this:<br />
<pre><br />
<h2 class="main">This is the top-level header</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">These is your score on XX activity.</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">You must make a selection to proceed.</h2><br />
<input type="submit" value="Generic submit button"><br />
</pre><br />
<br />
This: <br />
<pre><br />
<h2>This is the top-level header</h2><br />
<p>This paragraph gives additional information and explains what's to come.</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<div class="notifyproblem">You must make a selection to proceed.</div><br />
</pre><br />
<br />
===Block===<br />
Blocks should consist of the following:<br />
* Block's name should start at level 2<br />
* Block's alignment should used the definition in theme, unless it is forcely modified through Tinymce which is using inline styling.<br />
[[File:block.png]]<br />
<br />
==Activity page==<br />
The display for the activity's content should contained the following:<br />
* Course name with level 1 header<br />
* Activity name with level 2 header<br />
* Content header should start at level 3 and lower for its sub-content. Although Tinymce allowed the use of level 1 and 2, it should be avoided.<br />
* Use theme alignment for displaying the content.<br />
* Content styling such as: alignment, font-size, font-family should inherit from theme.<br />
[[File:activity.png]]<br />
<br />
==Update in core API:==<br />
As part of removing '.main' class from header tag, we have updated the following functions in core outputrenderer API file:<br />
===Heading===<br />
For this function we changed the default value for the classes parameter value from 'main' to null.<br />
<code php><br />
heading($text, $level = 2, $classes = 'main', $id = null)<br />
To<br />
heading($text, $level = 2, $classes = null, $id = null)<br />
</code><br />
<br />
===Heading with help===<br />
For this function we added two additional parameters to set the heading level and classname. The level parameter value is defaulted to 2 and classnames is defaulted to null.<br />
<code php><br />
heading_with_help($text, $helpidentifier, $component = 'moodle', $icon = '', $iconalt = '')<br />
To<br />
heading_with_help($text, $helpidentifier, $component = 'moodle', $icon = '', $iconalt = '', $level = 2, $classnames = null)<br />
</code><br />
<br />
The detailed of changes for the above functions is reported in MDL-41438.</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=File:block.png&diff=42327File:block.png2013-09-13T02:39:32Z<p>Rwijaya: Rwijaya uploaded a new version of &quot;File:block.png&quot;: Reverted to version as of 02:36, 13 September 2013</p>
<hr />
<div></div>Rwijayahttps://docs.moodle.org/dev/index.php?title=File:block.png&diff=42326File:block.png2013-09-13T02:38:25Z<p>Rwijaya: Rwijaya uploaded a new version of &quot;File:block.png&quot;: Reverted to version as of 07:36, 10 September 2013</p>
<hr />
<div></div>Rwijayahttps://docs.moodle.org/dev/index.php?title=File:block.png&diff=42325File:block.png2013-09-13T02:37:48Z<p>Rwijaya: Rwijaya uploaded a new version of &quot;File:block.png&quot;</p>
<hr />
<div></div>Rwijayahttps://docs.moodle.org/dev/index.php?title=File:block.png&diff=42324File:block.png2013-09-13T02:36:11Z<p>Rwijaya: Rwijaya uploaded a new version of &quot;File:block.png&quot;</p>
<hr />
<div></div>Rwijayahttps://docs.moodle.org/dev/index.php?title=HTML_Guidelines&diff=42302HTML Guidelines2013-09-10T07:37:16Z<p>Rwijaya: /* Block */</p>
<hr />
<div>==Header==<br />
Header usage should be hierarchical within page views<br />
Reference link: [[Standardize classnames and layout to facilitate theming]]<br />
<br />
* Headers should be hierarchical, with two or more &lt;h3&gt; under each &lt;h2&gt; and so forth. However an exception applied to front-page where multiple &lt;h2&gt; are allowed for displaying the page's items (eg: list of courses, list of categories, etc).<br />
* &lt;h2&gt; is the top-level header of the page content/central column. There should be only one &lt;h2&gt; (except for front-page where multiple &lt;h2&gt; are allowed).<br />
* Headers should not be used for notification. Notification classes should be used for notification.<br />
* For H1 and H2 elements, no additional classes should be added. For H3 and below, some classes that describe the purpose of that heading such as sectionname, and others that provide functionality, such as dimmed_text, may be needed. Blanket and vague classnames should be eliminated (main, header, title, mdl-align, etc).<br />
* We shouldn't be wrapping a heading in a div just to allow it to be styled. This complicates the DOM, and defeats the purpose of any effort to standardize the appearance of headings across the page.<br />
<br />
<br />
Not this:<br />
<pre><br />
<h2 class="main">This is the top-level header</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">These is your score on XX activity.</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">You must make a selection to proceed.</h2><br />
<input type="submit" value="Generic submit button"><br />
</pre><br />
<br />
This: <br />
<pre><br />
<h2>This is the top-level header</h2><br />
<p>This paragraph gives additional information and explains what's to come.</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<div class="notifyproblem">You must make a selection to proceed.</div><br />
</pre><br />
<br />
===Block===<br />
Blocks should consist of the following:<br />
* Block's name should start at level 2<br />
* Block's alignment should used the definition in theme, unless it is forcely modified through Tinymce which is using inline styling.<br />
[[File:block.png]]<br />
<br />
==Activity page==<br />
The display for the activity's content should contained the following:<br />
* Course name with level 1 header<br />
* Activity name with level 2 header<br />
* Content header should start at level 3 and lower for its sub-content. Although Tinymce allowed the use of level 1 and 2, it should be avoided.<br />
* Use theme alignment for displaying the content.<br />
* Content styling such as: alignment, font-size, font-family should inherit from theme.<br />
[[File:activity.png]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=File:block.png&diff=42301File:block.png2013-09-10T07:36:11Z<p>Rwijaya: </p>
<hr />
<div></div>Rwijayahttps://docs.moodle.org/dev/index.php?title=HTML_Guidelines&diff=42300HTML Guidelines2013-09-10T07:32:39Z<p>Rwijaya: </p>
<hr />
<div>==Header==<br />
Header usage should be hierarchical within page views<br />
Reference link: [[Standardize classnames and layout to facilitate theming]]<br />
<br />
* Headers should be hierarchical, with two or more &lt;h3&gt; under each &lt;h2&gt; and so forth. However an exception applied to front-page where multiple &lt;h2&gt; are allowed for displaying the page's items (eg: list of courses, list of categories, etc).<br />
* &lt;h2&gt; is the top-level header of the page content/central column. There should be only one &lt;h2&gt; (except for front-page where multiple &lt;h2&gt; are allowed).<br />
* Headers should not be used for notification. Notification classes should be used for notification.<br />
* For H1 and H2 elements, no additional classes should be added. For H3 and below, some classes that describe the purpose of that heading such as sectionname, and others that provide functionality, such as dimmed_text, may be needed. Blanket and vague classnames should be eliminated (main, header, title, mdl-align, etc).<br />
* We shouldn't be wrapping a heading in a div just to allow it to be styled. This complicates the DOM, and defeats the purpose of any effort to standardize the appearance of headings across the page.<br />
<br />
<br />
Not this:<br />
<pre><br />
<h2 class="main">This is the top-level header</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">These is your score on XX activity.</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">You must make a selection to proceed.</h2><br />
<input type="submit" value="Generic submit button"><br />
</pre><br />
<br />
This: <br />
<pre><br />
<h2>This is the top-level header</h2><br />
<p>This paragraph gives additional information and explains what's to come.</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<div class="notifyproblem">You must make a selection to proceed.</div><br />
</pre><br />
<br />
===Block===<br />
Blocks should consist of the following:<br />
* Block's name should start at level 2<br />
* Block's alignment should used the definition in theme, unless it is forcely modified through Tinymce which is using inline styling.<br />
<br />
==Activity page==<br />
The display for the activity's content should contained the following:<br />
* Course name with level 1 header<br />
* Activity name with level 2 header<br />
* Content header should start at level 3 and lower for its sub-content. Although Tinymce allowed the use of level 1 and 2, it should be avoided.<br />
* Use theme alignment for displaying the content.<br />
* Content styling such as: alignment, font-size, font-family should inherit from theme.<br />
[[File:activity.png]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=File:activity.png&diff=42299File:activity.png2013-09-10T07:32:05Z<p>Rwijaya: Rwijaya uploaded a new version of &quot;File:activity.png&quot;</p>
<hr />
<div></div>Rwijayahttps://docs.moodle.org/dev/index.php?title=File:activity.png&diff=42298File:activity.png2013-09-10T07:27:37Z<p>Rwijaya: </p>
<hr />
<div></div>Rwijayahttps://docs.moodle.org/dev/index.php?title=HTML_Guidelines&diff=42297HTML Guidelines2013-09-10T07:26:10Z<p>Rwijaya: </p>
<hr />
<div>==Header==<br />
Header usage should be hierarchical within page views<br />
Reference link: [[Standardize classnames and layout to facilitate theming]]<br />
<br />
* Headers should be hierarchical, with two or more &lt;h3&gt; under each &lt;h2&gt; and so forth. However an exception applied to front-page where multiple &lt;h2&gt; are allowed for displaying the page's items (eg: list of courses, list of categories, etc).<br />
* &lt;h2&gt; is the top-level header of the page content/central column. There should be only one &lt;h2&gt; (except for front-page where multiple &lt;h2&gt; are allowed).<br />
* Headers should not be used for notification. Notification classes should be used for notification.<br />
* For H1 and H2 elements, no additional classes should be added. For H3 and below, some classes that describe the purpose of that heading such as sectionname, and others that provide functionality, such as dimmed_text, may be needed. Blanket and vague classnames should be eliminated (main, header, title, mdl-align, etc).<br />
* We shouldn't be wrapping a heading in a div just to allow it to be styled. This complicates the DOM, and defeats the purpose of any effort to standardize the appearance of headings across the page.<br />
<br />
<br />
Not this:<br />
<pre><br />
<h2 class="main">This is the top-level header</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">These is your score on XX activity.</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">You must make a selection to proceed.</h2><br />
<input type="submit" value="Generic submit button"><br />
</pre><br />
<br />
This: <br />
<pre><br />
<h2>This is the top-level header</h2><br />
<p>This paragraph gives additional information and explains what's to come.</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<div class="notifyproblem">You must make a selection to proceed.</div><br />
</pre><br />
<br />
===Block===<br />
Blocks should consist of the following:<br />
* Block's name should start at level 2<br />
* Block's alignment should used the definition in theme, unless it is forcely modified through Tinymce which is using inline styling.<br />
<br />
==Activity page==<br />
The display for the activity's content should contained the following:<br />
* Course name with level 1 header<br />
* Activity name with level 2 header<br />
* Content header should start at level 3 and lower for its sub-content. Although Tinymce allowed the use of level 1 and 2, it should be avoided.<br />
* Use theme alignment for displaying the content.<br />
* Content styling such as: alignment, font-size, font-family should inherit from theme.</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=HTML_Guidelines&diff=42256HTML Guidelines2013-09-03T05:31:05Z<p>Rwijaya: </p>
<hr />
<div>==Header==<br />
Header usage should be hierarchical within page views<br />
Reference link: [[Standardize classnames and layout to facilitate theming]]<br />
<br />
* Headers should be hierarchical, with two or more &lt;h3&gt; under each &lt;h2&gt; and so forth. However an exception applied to front-page where multiple &lt;h2&gt; are allowed for displaying the page's items (eg: list of courses, list of categories, etc).<br />
* &lt;h2&gt; is the top-level header of the page content/central column. There should be only one &lt;h2&gt; (except for front-page where multiple &lt;h2&gt; are allowed).<br />
* Headers should not be used for notification. Notification classes should be used for notification.<br />
* We shouldn't even need the .main class, or any other additional classes used to alter the appearance of the header. The fact that the header is located in the central column/main content area, and is a header, should be enough. The only reason we need it is because we're recruiting headers for other purposes. Some cases, such as dimmed_text and other classes that are needed to allow for added functionality are an exception to this rule. The objective is to standardize the heading, without removing functionality for indicating an element won't be visible to students etc.<br />
<br />
Not this:<br />
<pre><br />
<h2 class="main">This is the top-level header</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">These is your score on XX activity.</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">You must make a selection to proceed.</h2><br />
<input type="submit" value="Generic submit button"><br />
</pre><br />
<br />
This: <br />
<pre><br />
<h2>This is the top-level header</h2><br />
<p>This paragraph gives additional information and explains what's to come.</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<div class="notifyproblem">You must make a selection to proceed.</div><br />
</pre></div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Peer_reviewing&diff=42147Peer reviewing2013-08-21T08:17:57Z<p>Rwijaya: </p>
<hr />
<div>These are points to consider while peer-reviewing issues. Further explanation below.<br />
<br />
[] Syntax<br />
[] Whitespace<br />
[] Output<br />
[] Language<br />
[] Databases<br />
[] Testing (instructions and automated tests)<br />
[] Security<br />
[] Documentation<br />
[] Git<br />
[] Sanity check<br />
<br />
Acceptable check-marks are Y (for yes), N (for no) or - (for not applicable). All N check-marks should be accompanied by an explanation of the problem that still needs to be addressed.<br />
<br />
==Syntax==<br />
To allow the community of Moodle developers to work together, conventions should be followed.<br />
<br />
* The code is easy to understand and, where it isn't, comments have been provided.<br />
* Variables are named correctly (all lower case, no camel-case, no underscores).<br />
* Functions are named correctly (all lower case, no camel-case, underscores allowed).<br />
* PHP DocBlocks have been updated and adhere to [[Coding_style#Documentation_and_comments|coding style guide]].<br />
* Where functions are being removed, the [[Deprecation]] process is followed.<br />
* The code doesn't use [[Deprecated_functions_in_2.0|deprecated functions]].<br />
* $_GET, $_POST, $_REQUEST, $_COOKIE, and $_SESSION are never used.<br />
<br />
See the [[Coding style]] guide for details.<br />
<br />
==Whitespace==<br />
Unnecessary whitespace changes can cause conflicts when committing code.<br />
<br />
Ensure that:<br />
* there are no unnecessary blank lines in the new code;<br />
* blank lines do not contain spaces;<br />
* there are no unnecessary changes to whitespace in other areas on the file;<br />
<br />
==Output==<br />
Output needs to be controlled by renderers to achieve consistency and correct application of themes.<br />
<br />
Ensure that:<br />
* output renders are used to generate output strings, including HTML tags;<br />
* HTML output is valid XHTML;<br />
* no inline styles have been used in HTML output (everything has to be in CSS);<br />
* CSS has been added to the appropriate CSS files (base, specific area, sometimes canvas); and<br />
* the code doesn't use buffered output unless absolutely necessary.<br />
<br />
feedback any notices (E_STRICT, etc) seen into the MDL.<br />
<br />
==Language==<br />
To achieve appropriate internationalisation of Moodle, language strings must be managed correctly.<br />
<br />
Ensure that:<br />
* new language strings are named correctly (all lower case, no camel-case, underscores are permissible in some cases);<br />
* language strings are used instead of hard-coded strings for text output;<br />
* language strings have not been removed or renamed in stable branches (permitted only in master); and<br />
* AMOS commands have been specified when moving, copying, or deleting language strings.<br />
<br />
==Databases==<br />
DB calls are the greatest performance bottleneck in Moodle.<br />
<br />
If there is SQL code you can test quickly then do so. <br />
<br />
Ensure that:<br />
* there are minimal DB calls (no excessive use of the DB); and<br />
* the code uses SQL compatible with all the supported DB engines (check all selected fields appear in an 'order by' clause).<br />
<br />
==Testing instructions and automated tests==<br />
It is the developer's responsibility to test code before integration. Issues should not be sent for peer review without tests so that the peer reviewer can assess their quality and use them to consider the scope of the issue.<br />
<br />
Ensure that:<br />
* there are specific testing instructions that state how, as well as what, to test. Please ensure that the testing instructions are in the correct format: [https://docs.moodle.org/dev/Behat Behat gherkin];<br />
* new unit tests have been added when there is a change in functionality; and<br />
* '''unit tests pass''' for related areas where changes have been made.<br />
* '''Behat tests pass''' for related areas where changes have been made, especially when it involved UI changes.<br />
<br />
==Security==<br />
The user community relies on Moodle being responsibly secure.<br />
<br />
Ensure that:<br />
* user login is checked where an identity is needed;<br />
* sesskey values are checked before all write actions where appropriate (some read actions as well);<br />
* capabilities are checked where roles differ; and<br />
* if the issue itself is a [[Security|security]] issue, the [[Process#Security_issues|security process]] is being followed.<br />
** Ensure that the fix is '''not''' available in a public repository (ie. a personal Github account); stand-alone patches should be provided instead.<br />
** The issue will not be integrated until just before the next minor version release.<br />
<br />
==Documentation==<br />
Work does not stop when code is integrated.<br />
<br />
Ensure that:<br />
* Appropriate [[Tracker_issue_labels|labels]] have been added when there has been a function change, particularly<br />
** qa_test_required (significant functional change),<br />
** docs_required (any functional change, usually paired with ui_change),<br />
** dev_docs_required (any change to APIs, usually paired with api_chage),<br />
** ui_change (any functional change, usually paired with docs_required, except ui_change remains permanetly), and<br />
** api_change (any change to APIs that devs will need to know about, usually paired with dev_docs_required, except api_change remains permanetly).<br />
<br />
==Git==<br />
Ensure that:<br />
* the commit message includes the tracker issue number and ideally the component (ideal format is <code>MDL-xxxx Component: Commit message</code>);<br />
* the commit message makes sense and describes what is going on in the patch. (see [[Commit_cheat_sheet]] for some guidance)<br />
* the Git history is clean and the work has been rebased to logical commits; and<br />
* the original author of the work provided as a patch has been given credit within the commit (as author of in the commit message if changes were made).<br />
<br />
==Sanity check==<br />
Ensure that:<br />
* the code seems to solve the described problem completely within its reported scope (and further issues have been created to resolve remaining parts or further refactoring);<br />
* the code makes sense in relation to the broader codebase (look at the whole function, not just the altered code); and<br />
* the developer has searched for and fixed other areas that may also have been affected by the same problem.<br />
<br />
==See Also==<br />
* [http://moodle.org/plugins/view.php?plugin=local_codechecker Code checker plugin]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=HTML_Guidelines&diff=42127HTML Guidelines2013-08-19T06:08:35Z<p>Rwijaya: Created page with "==Header== Header usage should be hierarchical within page views Reference link: Standardize classnames and layout to facilitate theming * Headers should be hierarchical,..."</p>
<hr />
<div>==Header==<br />
Header usage should be hierarchical within page views<br />
Reference link: [[Standardize classnames and layout to facilitate theming]]<br />
<br />
* Headers should be hierarchical, with two or more &lt;h3&gt; under each &lt;h2&gt; and so forth. <br />
* &lt;h2&gt; is the top-level header of the page content/central column. There should be only one &lt;h2&gt;<br />
* Headers should not be used for notification. Notification classes should be used for notification.<br />
* We shouldn't even need the .main class. The fact that the header is located in the central column/main content area, and is a header, should be enough. The only reason we need it is because we're recruiting headers for other purposes. <br />
<br />
Not this:<br />
<pre><br />
<h2 class="main">This is the top-level header</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">These is your score on XX activity.</h2><br />
<p>A paragraph of content.</p><br />
<h2 class="main">You must make a selection to proceed.</h2><br />
<input type="submit" value="Generic submit button"><br />
</pre><br />
<br />
This: <br />
<pre><br />
<h2>This is the top-level header</h2><br />
<p>This paragraph gives additional information and explains what's to come.</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<h3>Content sub-header</h3><br />
<p>More paragraph content content content</p><br />
<div class="notifyproblem">You must make a selection to proceed.</div><br />
</pre></div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Timeformat&diff=35606Timeformat2012-09-21T09:05:42Z<p>Rwijaya: /* Timeformat settings */</p>
<hr />
<div>{{Infobox Project<br />
|name = Timeformat<br />
|state = In Development<br />
|tracker = http://tracker.moodle.org/browse/MDL-11094<br />
|discussion = <br />
|assignee = Rossiani Wijaya<br />
}}<br />
<br />
==Timeformat settings==<br />
Administrator can change the following location settings in ''Settings > Site administration > Location > Location settings > Time display format''.<br />
User can change the timeformat setting in ''my profile settings > edit profile > timeformat''.<br />
<br />
==Timeformat options==<br />
There are three options available for displaying timeformat:<br />
# Default<br />
# 12 hours<br />
# 24 hours<br />
<br />
====Default format====<br />
The default value for timeformat is specify according to the language that used to display the content for the site.<br />
<br />
Both site and user setting is automatically assign to ''Default'' value.<br />
<br />
====12 hours format====<br />
Hour is display between 0-12. In addition, this format will also display the AM/PM time definition. An example for displaying the time for 3 O'clock in the afternoon is 3:00 pm.<br />
<br />
====24 hours format====<br />
Hour is display between 0-24. An example for displaying the time for 3 O'clock in the afternoon is 15:00.<br />
<br />
==Hierarchy for timeformat ==<br />
If user specify their timeformat setting, it would overwrite the site setting.</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Timeformat&diff=35605Timeformat2012-09-21T08:50:14Z<p>Rwijaya: </p>
<hr />
<div>{{Infobox Project<br />
|name = Timeformat<br />
|state = In Development<br />
|tracker = http://tracker.moodle.org/browse/MDL-11094<br />
|discussion = <br />
|assignee = Rossiani Wijaya<br />
}}<br />
<br />
==Timeformat settings==<br />
Administrator can change the following location settings in ''Settings > Site administration > Advanced features > Time display format''.<br />
User can change the timeformat setting in ''my profile settings > edit profile > timeformat''.<br />
<br />
==Timeformat options==<br />
There are three options available for displaying timeformat:<br />
# Default<br />
# 12 hours<br />
# 24 hours<br />
<br />
====Default format====<br />
The default value for timeformat is specify according to the language that used to display the content for the site.<br />
<br />
Both site and user setting is automatically assign to ''Default'' value.<br />
<br />
====12 hours format====<br />
Hour is display between 0-12. In addition, this format will also display the AM/PM time definition. An example for displaying the time for 3 O'clock in the afternoon is 3:00 pm.<br />
<br />
====24 hours format====<br />
Hour is display between 0-24. An example for displaying the time for 3 O'clock in the afternoon is 15:00.<br />
<br />
==Hierarchy for timeformat ==<br />
If user specify their timeformat setting, it would overwrite the site setting.</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Timeformat&diff=35595Timeformat2012-09-18T06:33:47Z<p>Rwijaya: </p>
<hr />
<div>{{Infobox Project<br />
|name = Timeformat<br />
|state = In Development<br />
|tracker = http://tracker.moodle.org/browse/MDL-11094<br />
|discussion = <br />
|assignee = Rossiani Wijaya<br />
}}<br />
<br />
{{Managing a Moodle site}}<br />
==Timeformat settings==<br />
Administrator can change the following location settings in ''Settings > Site administration > Advanced features > Time display format''.<br />
User can change the timeformat setting in ''my profile settings > edit profile > timeformat''.<br />
<br />
==Timeformat options==<br />
There are three options available for displaying timeformat:<br />
# Default<br />
# 12 hours<br />
# 24 hours<br />
<br />
====Default format====<br />
The default value for timeformat is specify according to the language that used to display the content for the site.<br />
<br />
Both site and user setting is automatically assign to ''Default'' value.<br />
<br />
====12 hours format====<br />
Hour is display between 0-12. An example for displaying the time for 3 O'clock in the afternoon is 3:00 pm.<br />
<br />
====24 hours format====<br />
Hour is display between 0-24. An example for displaying the time for 3 O'clock in the afternoon is 15:00.<br />
<br />
==Hierarchy for timeformat ==<br />
If user specify their timeformat setting, it would overwrite the site setting.</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Timeformat&diff=35594Timeformat2012-09-18T06:13:40Z<p>Rwijaya: </p>
<hr />
<div>{{Infobox Project<br />
|name = Timeformat<br />
|state = In Development<br />
|tracker = http://tracker.moodle.org/browse/MDL-11094<br />
|discussion = <br />
|assignee = Rossiani Wijaya<br />
}}<br />
<br />
<br />
{{Managing a Moodle site}}<br />
==Timeformat settings==<br />
Administrator can change the following location settings in ''Settings > Site administration > Advanced features > Time display format''.<br />
User can change the timeformat setting in ''my profile settings > edit profile > timeformat''.<br />
<br />
====Default timeformat====<br />
The default value for timeformat is specify according to the language that used to display the content for the site.<br />
<br />
Both site and user setting is automatically assign to ''Default'' value.<br />
<br />
====Hierarchy for timeformat ====<br />
If user specify their timeformat setting, it would overwrite the site setting.<br />
<br />
====Options value for timeformat ====<br />
There are two options available for displaying timeformat:<br />
1. 12 hours<br />
2. 24 hours<br />
<br />
====Examples for timeformat ====<br />
An example for displaying the time for 3 O'clock in the afternoon:<br />
- 12 hours format: 3:00 pm<br />
- 24 hours format: 15:00</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Timeformat&diff=35593Timeformat2012-09-18T05:14:31Z<p>Rwijaya: Created page with "{{Infobox Project |name = Timeformat |state = In Development |tracker = http://tracker.moodle.org/browse/MDL-11094 |discussion = |assignee = Rossiani Wijaya }} {{Managing a Mo..."</p>
<hr />
<div>{{Infobox Project<br />
|name = Timeformat<br />
|state = In Development<br />
|tracker = http://tracker.moodle.org/browse/MDL-11094<br />
|discussion = <br />
|assignee = Rossiani Wijaya<br />
}}<br />
<br />
<br />
{{Managing a Moodle site}}<br />
==Timeformat settings==<br />
Administrator can change the following location settings in ''Settings > Site administration > Advanced features > Time display format''.<br />
User can change the timeformat setting in ''my profile settings > edit profile > timeformat''.<br />
<br />
====Default timeformat====<br />
The default value for timeformat is specify according to the language that used to display the content for the site.<br />
<br />
Both site and user setting is automatically assign to ''Default'' value.<br />
<br />
====Hierarchy for timeformat ====<br />
If user specify their timeformat setting, it would overwrite the site setting.</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31885Portfolio plugins2012-01-27T09:39:33Z<p>Rwijaya: /* mnet_publishes */</p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
<br />
===File access===<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Example==<br />
<br />
==Template==<br />
Please refer to portfolio goodledocs plugins ([http://git.moodle.org/gw?p=moodle.git;a=tree;f=portfolio/googledocs;h=6d5e67e99545dc7430df5ad065d4d5da8945417d;hb=master portfolio/googledocs/]) as template reference to start with.<br />
<br />
==Naming convention==<br />
<br />
Plugin class name should start with portfolio_plugin_'''''PLUGINNAME'''''. This class should also extends from '''portfolio_plugin_push_base''' or '''portfolio_plugin_pull_base'''.<br />
<code php><br />
class portfolio_plugin_foo extends portfolio_plugin_push_base {}<br />
</code><br />
For more information regarding naming convention, please refer to: [[Frankenstyle|Frankenstyle page]]<br />
<br />
==File structure==<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "''foo''"<br />
<br />
# Create a new directory in portfolio/ for the new plugin. The name for this directory should refer to plugin's name, for example: portfolio''/foo''.<br />
# Create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
# Create a ''lib.php'' inside the plugin directory, for example: portfolio/foo'''/lib.php'''.<br />
# Create the necessary subclass to make our plugin work. The subclass must be called portfolio_plugin'''''_PLUGINNAME''''' (eg: portfolio_plugin_foo) and directly extend either ''portfolio_plugin_push_base'' or ''portfolio_plugin_pull_base''. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it.<br />
# Create file for plugin language strings:<br />
## create directory '''lang/''' and subdirectory '''$language/''' within the plugin, for example: portfolio/foo'''/lang/$language/'''. English (en) language must exist as this language will be use as default language string. <br />
## create php file using this naming convention, portfolio_'''PLUGINNAME'''.php, for example: /portfolio/foo/lang/en/'''portfolio_foo.php'''<br />
# Optionally, this plugin could store some information in database. In order to store data to database, create '''db/''' directory within the plugin directory, for example: portfolio/foo/'''db/'''. Also, create '''install.xml''' for the table schema. For further details using database table, please refer to: [[XMLDB editor]] and [[Database_FAQ#XMLDB|Database FAQ > XMLDB]].<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
==Interfacing to APIs==<br />
<br />
===Methods you must override===<br />
<br />
====Static functions====<br />
<br />
=====get_name=====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
====Class methods====<br />
<br />
=====prepare_package=====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
=====send_package=====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
=====get_interactive_continue_url=====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
=====verify_file_request_params (pull only)=====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
=====expected_time=====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
===Methods you can override===<br />
<br />
====Static functions====<br />
<br />
=====plugin_sanity_check=====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
=====has_admin_config=====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
=====get_allowed_config=====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====allows_multiple_instances=====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
=====allows_multiple_exports=====<br />
By default, all plugin support multiple export configured. However, if it require a redirect for authentication and doesn't support dynamic constructed urls to return to, overide this to return false.<br />
<br />
=====file_mime_check=====<br />
This function need to be override to return false, if the file type have restriction on mimetypes.<br />
<br />
====Class methods====<br />
=====supported_formats=====<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
=====has_user_config=====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
=====has_export_config=====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
=====admin_config_form=====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
=====user_config_form=====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
=====export_config_form=====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
=====admin_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
=====user_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====export_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====get_export_summary=====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
=====steal_control=====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
=====post_control=====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
=====get_allowed_user_config=====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====get_allowed_export_config=====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
=====instance_sanity_check=====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
=====send_file (pull only)=====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
=====cleanup=====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
=====mnet_publishes (''deprecated on Moodle 2.0'')=====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
=====get_static_continue_url=====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
=====resolve_static_continue_url=====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
===Methods you shouldn't really override===<br />
<br />
====Static functions====<br />
<br />
=====create_instance=====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
====Class methods====<br />
<br />
=====__construct=====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
=====save=====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
=====delete=====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
=====set_export_config=====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
<br />
==Database tables==<br />
In case we need to have a database table that holds some specific information used for the portfolio plugin, we will need to create the file ''/portfolio/foo/lib/'''install.xml''''' with the table schema contained within it.<br />
<br />
To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.<br />
<br />
Up-to-date documentation on upgrading portfolio plugin, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]<br />
<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31884Portfolio plugins2012-01-27T09:17:22Z<p>Rwijaya: </p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
<br />
===File access===<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Example==<br />
<br />
==Template==<br />
Please refer to portfolio goodledocs plugins ([http://git.moodle.org/gw?p=moodle.git;a=tree;f=portfolio/googledocs;h=6d5e67e99545dc7430df5ad065d4d5da8945417d;hb=master portfolio/googledocs/]) as template reference to start with.<br />
<br />
==Naming convention==<br />
<br />
Plugin class name should start with portfolio_plugin_'''''PLUGINNAME'''''. This class should also extends from '''portfolio_plugin_push_base''' or '''portfolio_plugin_pull_base'''.<br />
<code php><br />
class portfolio_plugin_foo extends portfolio_plugin_push_base {}<br />
</code><br />
For more information regarding naming convention, please refer to: [[Frankenstyle|Frankenstyle page]]<br />
<br />
==File structure==<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "''foo''"<br />
<br />
# Create a new directory in portfolio/ for the new plugin. The name for this directory should refer to plugin's name, for example: portfolio''/foo''.<br />
# Create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
# Create a ''lib.php'' inside the plugin directory, for example: portfolio/foo'''/lib.php'''.<br />
# Create the necessary subclass to make our plugin work. The subclass must be called portfolio_plugin'''''_PLUGINNAME''''' (eg: portfolio_plugin_foo) and directly extend either ''portfolio_plugin_push_base'' or ''portfolio_plugin_pull_base''. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it.<br />
# Create file for plugin language strings:<br />
## create directory '''lang/''' and subdirectory '''$language/''' within the plugin, for example: portfolio/foo'''/lang/$language/'''. English (en) language must exist as this language will be use as default language string. <br />
## create php file using this naming convention, portfolio_'''PLUGINNAME'''.php, for example: /portfolio/foo/lang/en/'''portfolio_foo.php'''<br />
# Optionally, this plugin could store some information in database. In order to store data to database, create '''db/''' directory within the plugin directory, for example: portfolio/foo/'''db/'''. Also, create '''install.xml''' for the table schema. For further details using database table, please refer to: [[XMLDB editor]] and [[Database_FAQ#XMLDB|Database FAQ > XMLDB]].<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
==Interfacing to APIs==<br />
<br />
===Methods you must override===<br />
<br />
====Static functions====<br />
<br />
=====get_name=====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
====Class methods====<br />
<br />
=====prepare_package=====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
=====send_package=====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
=====get_interactive_continue_url=====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
=====verify_file_request_params (pull only)=====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
=====expected_time=====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
===Methods you can override===<br />
<br />
====Static functions====<br />
<br />
=====plugin_sanity_check=====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
=====has_admin_config=====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
=====get_allowed_config=====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====allows_multiple_instances=====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
=====allows_multiple_exports=====<br />
By default, all plugin support multiple export configured. However, if it require a redirect for authentication and doesn't support dynamic constructed urls to return to, overide this to return false.<br />
<br />
=====file_mime_check=====<br />
This function need to be override to return false, if the file type have restriction on mimetypes.<br />
<br />
====Class methods====<br />
=====supported_formats=====<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
=====has_user_config=====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
=====has_export_config=====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
=====admin_config_form=====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
=====user_config_form=====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
=====export_config_form=====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
=====admin_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
=====user_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====export_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====get_export_summary=====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
=====steal_control=====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
=====post_control=====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
=====get_allowed_user_config=====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====get_allowed_export_config=====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
=====instance_sanity_check=====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
=====send_file (pull only)=====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
=====cleanup=====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
=====mnet_publishes=====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
=====get_static_continue_url=====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
=====resolve_static_continue_url=====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
===Methods you shouldn't really override===<br />
<br />
====Static functions====<br />
<br />
=====create_instance=====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
====Class methods====<br />
<br />
=====__construct=====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
=====save=====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
=====delete=====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
=====set_export_config=====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
<br />
==Database tables==<br />
In case we need to have a database table that holds some specific information used for the portfolio plugin, we will need to create the file ''/portfolio/foo/lib/'''install.xml''''' with the table schema contained within it.<br />
<br />
To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.<br />
<br />
Up-to-date documentation on upgrading portfolio plugin, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]<br />
<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31883Portfolio plugins2012-01-27T09:00:42Z<p>Rwijaya: </p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
<br />
===File access===<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Example==<br />
<br />
==Template==<br />
Please refer to portfolio goodledocs plugins ([http://git.moodle.org/gw?p=moodle.git;a=tree;f=portfolio/googledocs;h=6d5e67e99545dc7430df5ad065d4d5da8945417d;hb=master portfolio/googledocs/]) as template reference to start with.<br />
<br />
==Naming convention==<br />
<br />
Plugin class name should start with portfolio_plugin_'''''PLUGINNAME'''''. This class should also extends from '''portfolio_plugin_push_base''' or '''portfolio_plugin_pull_base'''.<br />
<code php><br />
class portfolio_plugin_foo extends portfolio_plugin_push_base {}<br />
</code><br />
For more information regarding naming convention, please refer to: [[Frankenstyle|Frankenstyle page]]<br />
<br />
==File structure==<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "''foo''"<br />
<br />
# Create a new directory in portfolio/ for the new plugin. The name for this directory should refer to plugin's name, for example: portfolio''/foo''.<br />
# Create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
# Create a ''lib.php'' inside the plugin directory, for example: portfolio/foo'''/lib.php'''.<br />
# Create the necessary subclass to make our plugin work. The subclass must be called portfolio_plugin'''''_PLUGINNAME''''' (eg: portfolio_plugin_foo) and directly extend either ''portfolio_plugin_push_base'' or ''portfolio_plugin_pull_base''. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it.<br />
# Create file for plugin language strings:<br />
## create directory '''lang/''' and subdirectory '''$language/''' within the plugin, for example: portfolio/foo'''/lang/$language/'''. English (en) language must exist as this language will be use as default language string. <br />
## create php file using this naming convention, portfolio_'''PLUGINNAME'''.php, for example: /portfolio/foo/lang/en/'''portfolio_foo.php'''<br />
# Optionally, this plugin could store some information in database. In order to store data to database, create '''db/''' directory within the plugin directory, for example: portfolio/foo/'''db/'''. Also, create '''install.xml''' for the table schema. For further details using database table, please refer to: [[XMLDB editor]] and [[Database_FAQ#XMLDB|Database FAQ > XMLDB]].<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
==Interfacing to APIs==<br />
<br />
===Methods you must override===<br />
<br />
====Static functions====<br />
<br />
=====get_name=====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
====Class methods====<br />
<br />
=====prepare_package=====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
=====send_package=====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
=====get_interactive_continue_url=====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
=====verify_file_request_params (pull only)=====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
=====expected_time=====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
===Methods you can override===<br />
<br />
====Static functions====<br />
<br />
=====plugin_sanity_check=====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
=====has_admin_config=====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
=====get_allowed_config=====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====allows_multiple_instances=====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
====Class methods====<br />
=====supported_formats=====<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
=====has_user_config=====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
=====has_export_config=====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
=====admin_config_form=====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
=====user_config_form=====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
=====export_config_form=====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
=====admin_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
=====user_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====export_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====get_export_summary=====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
=====steal_control=====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
=====post_control=====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
=====get_allowed_user_config=====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====get_allowed_export_config=====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
=====instance_sanity_check=====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
=====send_file (pull only)=====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
=====cleanup=====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
=====mnet_publishes=====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
=====get_static_continue_url=====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
=====resolve_static_continue_url=====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
===Methods you shouldn't really override===<br />
<br />
====Static functions====<br />
<br />
=====create_instance=====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
====Class methods====<br />
<br />
=====__construct=====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
=====save=====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
=====delete=====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
=====set_export_config=====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
<br />
==Database tables==<br />
In case we need to have a database table that holds some specific information used for the portfolio plugin, we will need to create the file ''/portfolio/foo/lib/'''install.xml''''' with the table schema contained within it.<br />
<br />
To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.<br />
<br />
Up-to-date documentation on upgrading portfolio plugin, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]<br />
<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31871Portfolio plugins2012-01-27T06:32:42Z<p>Rwijaya: </p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
<br />
===File access===<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Example==<br />
<br />
==Template==<br />
Please refer to portfolio goodledocs plugins ([http://git.moodle.org/gw?p=moodle.git;a=tree;f=portfolio/googledocs;h=6d5e67e99545dc7430df5ad065d4d5da8945417d;hb=master portfolio/googledocs/]) as template reference to start with.<br />
<br />
==Naming convention==<br />
<br />
Plugin class name should start with portfolio_plugin_'''''PLUGINNAME'''''. This class should also extends from '''portfolio_plugin_push_base''' or '''portfolio_plugin_pull_base'''.<br />
<code php><br />
class portfolio_plugin_foo extends portfolio_plugin_push_base {}<br />
</code><br />
For more information regarding naming convention, please refer to: [[Frankenstyle|Frankenstyle page]]<br />
<br />
==File structure==<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "''foo''"<br />
<br />
# Create a new directory in portfolio/ for the new plugin. The name for this directory should refer to plugin's name, for example: portfolio''/foo''.<br />
# Create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
# Create a ''lib.php'' inside the plugin directory, for example: portfolio/foo'''/lib.php'''.<br />
# Create the necessary subclass to make our plugin work. The subclass must be called portfolio_plugin'''''_PLUGINNAME''''' (eg: portfolio_plugin_foo) and directly extend either ''portfolio_plugin_push_base'' or ''portfolio_plugin_pull_base''. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it.<br />
# Create file for plugin language strings:<br />
## create directory '''lang/''' and subdirectory '''$language/''' within the plugin, for example: portfolio/foo'''/lang/$language/'''. English (en) language must exist as this language will be use as default language string. <br />
## create php file using this naming convention, portfolio_'''PLUGINNAME'''.php, for example: /portfolio/foo/lang/en/'''portfolio_foo.php'''<br />
# Optionally, this plugin could store some information in database. In order to store data to database, create '''db/''' directory within the plugin directory, for example: portfolio/foo/'''db/'''. Also, create '''install.xml''' for the table schema. For further details using database table, please refer to: [[XMLDB editor]] and [[Database_FAQ#XMLDB|Database FAQ > XMLDB]].<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
==Interfacing to APIs==<br />
<br />
===Methods you must override===<br />
<br />
====Static functions====<br />
<br />
=====get_name=====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
====Class methods====<br />
<br />
=====prepare_package=====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
=====send_package=====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
=====get_interactive_continue_url=====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
=====verify_file_request_params (pull only)=====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
=====expected_time=====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
===Methods you can override===<br />
<br />
====Static functions====<br />
<br />
<br />
=====supported_formats=====<br />
<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
=====plugin_sanity_check=====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
=====has_admin_config=====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
=====get_allowed_config=====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====allows_multiple_instances=====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
====Class methods====<br />
<br />
=====has_user_config=====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
=====has_export_config=====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
=====admin_config_form=====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
=====user_config_form=====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
=====export_config_form=====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
=====admin_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
=====user_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====export_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====get_export_summary=====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
=====steal_control=====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
=====post_control=====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
=====get_allowed_user_config=====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====get_allowed_export_config=====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
=====instance_sanity_check=====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
=====send_file (pull only)=====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
=====cleanup=====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
=====mnet_publishes=====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
=====get_static_continue_url=====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
=====resolve_static_continue_url=====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
===Methods you shouldn't really override===<br />
<br />
====Static functions====<br />
<br />
=====create_instance=====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
====Class methods====<br />
<br />
=====__construct=====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
=====save=====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
=====delete=====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
=====set_export_config=====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
<br />
==Database tables==<br />
In case we need to have a database table that holds some specific information used for the portfolio plugin, we will need to create the file ''/portfolio/foo/lib/'''install.xml''''' with the table schema contained within it.<br />
<br />
To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.<br />
<br />
Up-to-date documentation on upgrading portfolio plugin, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]<br />
<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31868Portfolio plugins2012-01-27T06:05:29Z<p>Rwijaya: </p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
<br />
===File access===<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Example==<br />
<br />
==Template==<br />
Please refer to portfolio goodledocs plugins ([http://git.moodle.org/gw?p=moodle.git;a=tree;f=portfolio/googledocs;h=6d5e67e99545dc7430df5ad065d4d5da8945417d;hb=master portfolio/googledocs/]) as template to start with.<br />
<br />
==Naming convention==<br />
<br />
Plugin class name should start with portfolio_plugin_'''''PLUGINNAME'''''. This class should also extends from '''portfolio_plugin_push_base''' or '''portfolio_plugin_pull_base'''.<br />
<code php><br />
class portfolio_plugin_foo extends portfolio_plugin_push_base {}<br />
</code><br />
For more information regarding naming convention, please refer to: [[Frankenstyle|Frankenstyle page]]<br />
<br />
==File structure==<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "''foo''"<br />
<br />
# Create a new directory in portfolio/ for the new plugin. The name for this directory should refer to plugin's name, for example: portfolio''/foo''.<br />
# Create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
# Create a ''lib.php'' inside the plugin directory, for example: portfolio/foo'''/lib.php'''.<br />
# Create the necessary subclass to make our plugin work. The subclass must be called portfolio_plugin'''''_PLUGINNAME''''' (eg: portfolio_plugin_foo) and directly extend either ''portfolio_plugin_push_base'' or ''portfolio_plugin_pull_base''. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it.<br />
# Create file for plugin language strings:<br />
## create directory '''lang/''' and subdirectory '''$language/''' within the plugin, for example: portfolio/foo'''/lang/$language/'''. English (en) language must exist as this language will be use as default language string. <br />
## create php file using this naming convention, portfolio_'''PLUGINNAME'''.php, for example: /portfolio/foo/lang/en/'''portfolio_foo.php'''<br />
# Optionally, this plugin could store some information in database. In order to store data to database, create '''db/''' directory within the plugin directory, for example: portfolio/foo/'''db/'''. Also, create '''install.xml''' for the table schema. For further details using database table, please refer to: [[XMLDB editor]] and [[Database_FAQ#XMLDB|Database FAQ > XMLDB]].<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
==Interfacing to APIs==<br />
<br />
===Methods you must override===<br />
<br />
====Static functions====<br />
<br />
=====get_name=====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
====Class methods====<br />
<br />
=====prepare_package=====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
=====send_package=====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
=====get_interactive_continue_url=====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
=====verify_file_request_params (pull only)=====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
=====expected_time=====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
===Methods you can override===<br />
<br />
====Static functions====<br />
<br />
<br />
=====supported_formats=====<br />
<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
=====plugin_sanity_check=====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
=====has_admin_config=====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
=====get_allowed_config=====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====allows_multiple_instances=====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
====Class methods====<br />
<br />
=====has_user_config=====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
=====has_export_config=====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
=====admin_config_form=====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
=====user_config_form=====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
=====export_config_form=====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
=====admin_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
=====user_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====export_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====get_export_summary=====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
=====steal_control=====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
=====post_control=====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
=====get_allowed_user_config=====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====get_allowed_export_config=====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
=====instance_sanity_check=====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
=====send_file (pull only)=====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
=====cleanup=====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
=====mnet_publishes=====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
=====get_static_continue_url=====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
=====resolve_static_continue_url=====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
===Methods you shouldn't really override===<br />
<br />
====Static functions====<br />
<br />
=====create_instance=====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
====Class methods====<br />
<br />
=====__construct=====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
=====save=====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
=====delete=====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
=====set_export_config=====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
<br />
==Database tables==<br />
In case we need to have a database table that holds some specific information used for the portfolio plugin, we will need to create the file ''/portfolio/foo/lib/'''install.xml''''' with the table schema contained within it.<br />
<br />
To create the install.xml file, use the [[XMLDB editor]]. See [[Database_FAQ#XMLDB|Database FAQ > XMLDB]] for further details.<br />
<br />
Up-to-date documentation on upgrading portfolio plugin, as well as providing new capabilities and events to the system, can be found under [https://docs.moodle.org/dev/Installing_and_upgrading_plugin_database_tables#install.php Installing and Upgrading Plugin Database Tables]<br />
<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31820Portfolio plugins2012-01-27T03:31:47Z<p>Rwijaya: </p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
Help files behave a little differently, you need to make portfolio/type/foo/lang/$language/help/foo/helpfile.html (this surprised me).<br />
<br />
Both normal strings and helpfiles should be called using module portfolio_foo for non core plugins. For core plugins, normal strings should be called using portfolio_foo but helpstrings should be called using portfolio/<br />
<br />
===File access===<br />
<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Example==<br />
<br />
==Template==<br />
Please refer to portfolio goodledocs plugins ([http://git.moodle.org/gw?p=moodle.git;a=tree;f=portfolio/googledocs;h=6d5e67e99545dc7430df5ad065d4d5da8945417d;hb=master portfolio/googledocs/]) as template to start with.<br />
<br />
==Naming convention==<br />
<br />
Plugin class name should start with <tt>portfolio_plugin_xxx</tt>, where xxx refer to the name of the plugin. This class should also extends from <tt>portfolio_plugin_push_base</tt> or <tt>portfolio_plugin_pull_base</tt>.<br />
<code php><br />
class portfolio_plugin_foo extends portfolio_plugin_push_base {}<br />
</code><br />
For more information regarding naming convention, please refer to: [[Frankenstyle|Frankenstyle page]]<br />
<br />
==File structure==<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "<tt>foo</tt>"<br />
<br />
# Create a new directory in <tt>portfolio/</tt> with the name of your plugin, for example, <tt>portfolio/foo</tt>.<br />
# Create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
# Provide a <tt>db/</tt> directory with an <tt>install.xml</tt> and <tt>upgrade.php</tt> along the same lines. These are optional.<br />
# Create a <tt>lib.php</tt> inside the plugin directory, for example: <tt>portfolio/foo/lib.php</tt>.<br />
# Create the necessary subclass to make our plugin work. It must be called <tt>portfolio_plugin_PLUGINNAME</tt> and directly extend either <tt>portfolio_plugin_push_base</tt>, or <tt>portfolio_plugin_pull_base</tt>. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it. portfolio_plugin_pull_base adds just one extra further abstract function (see below)<br />
<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
==Interfacing to APIs==<br />
<br />
===Methods you must override===<br />
<br />
====Static functions====<br />
<br />
=====get_name=====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
====Class methods====<br />
<br />
=====prepare_package=====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
=====send_package=====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
=====get_interactive_continue_url=====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
=====verify_file_request_params (pull only)=====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
=====expected_time=====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
===Methods you can override===<br />
<br />
====Static functions====<br />
<br />
<br />
=====supported_formats=====<br />
<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
=====plugin_sanity_check=====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
=====has_admin_config=====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
=====get_allowed_config=====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====allows_multiple_instances=====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
====Class methods====<br />
<br />
=====has_user_config=====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
=====has_export_config=====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
=====admin_config_form=====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
=====user_config_form=====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
=====export_config_form=====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
=====admin_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
=====user_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====export_config_validation=====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
=====get_export_summary=====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
=====steal_control=====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
=====post_control=====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
=====get_allowed_user_config=====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
=====get_allowed_export_config=====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
=====instance_sanity_check=====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
=====send_file (pull only)=====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
=====cleanup=====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
=====mnet_publishes=====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
=====get_static_continue_url=====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
=====resolve_static_continue_url=====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
===Methods you shouldn't really override===<br />
<br />
====Static functions====<br />
<br />
=====create_instance=====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
====Class methods====<br />
<br />
=====__construct=====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
=====save=====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
=====delete=====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
=====set_export_config=====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
<br />
<br />
==Database tables==<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31803Portfolio plugins2012-01-25T10:02:13Z<p>Rwijaya: </p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "foo"<br />
<br />
Create a new directory in portfolio/ with the name of your plugin, for example, portfolio/foo.<br />
<br />
You need to create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
<br />
You can also provide a db/ directory with an install.xml and upgrade.php along the same lines. These are optional.<br />
<br />
Create a lib.php inside this directory.<br />
<br />
Now we're going to create the necessary subclass to make our plugin work. It must be called portfolio_plugin_foo and directly extend either portfolio_plugin_push_base, or portfolio_plugin_pull_base. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it. portfolio_plugin_pull_base adds just one extra further abstract function (see below)<br />
<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
Help files behave a little differently, you need to make portfolio/type/foo/lang/$language/help/foo/helpfile.html (this surprised me).<br />
<br />
Both normal strings and helpfiles should be called using module portfolio_foo for non core plugins. For core plugins, normal strings should be called using portfolio_foo but helpstrings should be called using portfolio/<br />
<br />
===File access===<br />
<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Example==<br />
<br />
==Template==<br />
Please refer to portfolio goodledocs plugins ([http://git.moodle.org/gw?p=moodle.git;a=tree;f=portfolio/googledocs;h=6d5e67e99545dc7430df5ad065d4d5da8945417d;hb=master portfolio/googledocs/]) as template to start with.<br />
<br />
==Naming convention==<br />
<br />
Plugin class name should start with <tt>portfolio_plugin_xxx</tt>, where xxx refer to the name of the plugin. This class should also extends from <tt>portfolio_plugin_push_base</tt> or <tt>portfolio_plugin_pull_base</tt>.<br />
<code php><br />
class portfolio_plugin_foo extends portfolio_plugin_push_base {}<br />
</code><br />
For more information regarding naming convention, please refer to: [[Frankenstyle|Frankenstyle page]]<br />
<br />
==Methods you must override==<br />
<br />
===Static functions===<br />
<br />
====get_name====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
===Class methods===<br />
<br />
====prepare_package====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
====send_package====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
====get_interactive_continue_url====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
====verify_file_request_params (pull only)====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
====expected_time====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
==Methods you can override==<br />
<br />
===Static functions===<br />
<br />
<br />
====supported_formats====<br />
<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
====plugin_sanity_check====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
====has_admin_config====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
====get_allowed_config====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
====allows_multiple_instances====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
===Class methods===<br />
<br />
====has_user_config====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
====has_export_config====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
====admin_config_form====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
====user_config_form====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
====export_config_form====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
====admin_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
====user_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
====export_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
====get_export_summary====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
====steal_control====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
====post_control====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
====get_allowed_user_config====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
====get_allowed_export_config====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
====instance_sanity_check====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
====send_file (pull only)====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
====cleanup====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
====mnet_publishes====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
====get_static_continue_url====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
====resolve_static_continue_url====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
==Methods you shouldn't really override==<br />
<br />
===Static functions===<br />
<br />
====create_instance====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
===Class methods===<br />
<br />
====__construct====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
====save====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
====delete====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
====set_export_config====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31786Portfolio plugins2012-01-25T09:20:20Z<p>Rwijaya: /* Example */</p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "foo"<br />
<br />
Create a new directory in portfolio/ with the name of your plugin, for example, portfolio/foo.<br />
<br />
You need to create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
<br />
You can also provide a db/ directory with an install.xml and upgrade.php along the same lines. These are optional.<br />
<br />
Create a lib.php inside this directory.<br />
<br />
Now we're going to create the necessary subclass to make our plugin work. It must be called portfolio_plugin_foo and directly extend either portfolio_plugin_push_base, or portfolio_plugin_pull_base. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it. portfolio_plugin_pull_base adds just one extra further abstract function (see below)<br />
<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
Help files behave a little differently, you need to make portfolio/type/foo/lang/$language/help/foo/helpfile.html (this surprised me).<br />
<br />
Both normal strings and helpfiles should be called using module portfolio_foo for non core plugins. For core plugins, normal strings should be called using portfolio_foo but helpstrings should be called using portfolio/<br />
<br />
===File access===<br />
<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Methods you must override==<br />
<br />
===Static functions===<br />
<br />
====get_name====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
===Class methods===<br />
<br />
====prepare_package====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
====send_package====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
====get_interactive_continue_url====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
====verify_file_request_params (pull only)====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
====expected_time====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
==Methods you can override==<br />
<br />
===Static functions===<br />
<br />
<br />
====supported_formats====<br />
<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
====plugin_sanity_check====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
====has_admin_config====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
====get_allowed_config====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
====allows_multiple_instances====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
===Class methods===<br />
<br />
====has_user_config====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
====has_export_config====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
====admin_config_form====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
====user_config_form====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
====export_config_form====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
====admin_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
====user_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
====export_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
====get_export_summary====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
====steal_control====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
====post_control====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
====get_allowed_user_config====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
====get_allowed_export_config====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
====instance_sanity_check====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
====send_file (pull only)====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
====cleanup====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
====mnet_publishes====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
====get_static_continue_url====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
====resolve_static_continue_url====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
==Methods you shouldn't really override==<br />
<br />
===Static functions===<br />
<br />
====create_instance====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
===Class methods===<br />
<br />
====__construct====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
====save====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
====delete====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
====set_export_config====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31785Portfolio plugins2012-01-25T09:19:02Z<p>Rwijaya: /* Example */</p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
==Example==<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "foo"<br />
<br />
Create a new directory in portfolio/ with the name of your plugin, for example, portfolio/foo.<br />
<br />
You need to create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
<br />
You can also provide a db/ directory with an install.xml and upgrade.php along the same lines. These are optional.<br />
<br />
Create a lib.php inside this directory.<br />
<br />
Now we're going to create the necessary subclass to make our plugin work. It must be called portfolio_plugin_foo and directly extend either portfolio_plugin_push_base, or portfolio_plugin_pull_base. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it. portfolio_plugin_pull_base adds just one extra further abstract function (see below)<br />
<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
Help files behave a little differently, you need to make portfolio/type/foo/lang/$language/help/foo/helpfile.html (this surprised me).<br />
<br />
Both normal strings and helpfiles should be called using module portfolio_foo for non core plugins. For core plugins, normal strings should be called using portfolio_foo but helpstrings should be called using portfolio/<br />
<br />
===File access===<br />
<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Methods you must override==<br />
<br />
===Static functions===<br />
<br />
====get_name====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
===Class methods===<br />
<br />
====prepare_package====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
====send_package====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
====get_interactive_continue_url====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
====verify_file_request_params (pull only)====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
====expected_time====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
==Methods you can override==<br />
<br />
===Static functions===<br />
<br />
<br />
====supported_formats====<br />
<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
====plugin_sanity_check====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
====has_admin_config====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
====get_allowed_config====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
====allows_multiple_instances====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
===Class methods===<br />
<br />
====has_user_config====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
====has_export_config====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
====admin_config_form====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
====user_config_form====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
====export_config_form====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
====admin_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
====user_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
====export_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
====get_export_summary====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
====steal_control====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
====post_control====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
====get_allowed_user_config====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
====get_allowed_export_config====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
====instance_sanity_check====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
====send_file (pull only)====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
====cleanup====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
====mnet_publishes====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
====get_static_continue_url====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
====resolve_static_continue_url====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
==Methods you shouldn't really override==<br />
<br />
===Static functions===<br />
<br />
====create_instance====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
===Class methods===<br />
<br />
====__construct====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
====save====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
====delete====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
====set_export_config====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Portfolio_plugins&diff=31733Portfolio plugins2012-01-25T07:30:16Z<p>Rwijaya: </p>
<hr />
<div>==Introduction==<br />
Implementing this plugin will allow you to publish files to all kinds of external document repository systems (eg: mahara, flickr, picasa, etc).<br />
<br />
==Example==<br />
For the purposes of this tutorial, it will be assumed you want to create a plugin called "foo"<br />
<br />
Create a new directory in portfolio/type/ with the name of your plugin, for example, portfolio/type/foo.<br />
<br />
You need to create the standard [[version.php]] in here that you would normally create for most other plugin types in Moodle.<br />
<br />
You can also provide a db/ directory with an install.xml and upgrade.php along the same lines. These are optional.<br />
<br />
Create a lib.php inside this directory.<br />
<br />
Now we're going to create the necessary subclass to make our plugin work. It must be called portfolio_plugin_foo and directly extend either portfolio_plugin_push_base, or portfolio_plugin_pull_base. The only real differences between them are that one pushes the package directly to the remote system (usually via a HTTP POST, but could be filesystem based), and the other type (pull) requires the remote system to request it. portfolio_plugin_pull_base adds just one extra further abstract function (see below)<br />
<br />
Read the phpdoc documentation for the base classes for further information about each function, including the arguments it takes and the expected return type. The following documentation serves as an overview.<br />
<br />
===Error handling===<br />
Your code should always throw exceptions of type portfolio_plugin_exception. You should NOT call error or print_error or whatever, and also any third party exceptions should really be caught and rethrown although most of the time other exceptions will be caught too by the portfolio code (although this will trigger a warning in debug mode)<br />
<br />
===Language packs===<br />
<br />
If your plugin isn't going into core, you will need a language structure inside it, for example, portfolio/type/foo/lang/$language/. <br />
Help files behave a little differently, you need to make portfolio/type/foo/lang/$language/help/foo/helpfile.html (this surprised me).<br />
<br />
Both normal strings and helpfiles should be called using module portfolio_foo for non core plugins. For core plugins, normal strings should be called using portfolio_foo but helpstrings should be called using portfolio/<br />
<br />
===File access===<br />
<br />
'''All''' of the handling of files using the Files API should go through the portfolio exporter object. There are various helper methods you can use (see prepare_package documentation) in the exporter object. The reason for this is that this object is mocked during unit tests so that files don't actually get moved around while tests are running.<br />
<br />
==Methods you must override==<br />
<br />
===Static functions===<br />
<br />
====get_name====<br />
<br />
Return a localized name for this plugin. Usually just something like:<br />
<br />
<code php><br />
get_string('pluginname', 'portfolio_yourplugin'); <br />
</code><br />
<br />
This is enforced as an abstract function rather than a loose fuzzy dependence on a language string for maximum ease when developing a new plugin (it's blindly obvious you must implement it ;) )<br />
<br />
===Class methods===<br />
<br />
====prepare_package====<br />
<br />
Does anything necessary to prepare the package for sending. This might be writing out a metadata manifest file, or zipping up all the files in the temporary directory. This is called after the corresponding prepare_package method in the caller, which writes files out to a temporary location. Files can then be retrieved from there using $this->get('exporter')->get_tempfiles, which returns an array of stored_file objects. You can zip files using $this->get('exporter')->zip_tempfiles. You '''must''' not use the files api directly.<br />
<br />
====send_package====<br />
<br />
Actually send the package to the remote system (this might be just sending an xmlrpc request to say a file is ready for the remote system to fetch, (in which case you must set the $file member variable for portfolio/file.php later, or actually transfering the file). You can retrieve the files the caller has written out using $this->get('exporter')->get_tempfiles() which returns an array of stored_file objects.<br />
<br />
====get_interactive_continue_url====<br />
<br />
Return a url to present to the user as a 'continue to their portfolio' link. This can return false, although then you might want to implement get_extra_finish_options. See also get_static_continue_url and resolve_static_continue_url<br />
<br />
<br />
====verify_file_request_params (pull only)====<br />
<br />
When remote systems request files, access control check is delegated to the plugin, by passing the array of request parameters. Should this function return false, access to the file will be denied.<br />
<br />
<br />
====expected_time====<br />
<br />
How long a transfer can reasonably expect to take. This function is passed the estimate from the caller (which usually takes into account filesize) and can either agree with it by returning whatever it is given, or override it. There are three options, PORTFOLIO_TIME_LOW, PORTFOLIO_TIME_MODERATE, and PORTFOLIO_TIME_HIGH. The first means the user will not be asked if they want to wait for the transfer or not, they will just wait. The second and third mean they'll be given the option (and in the case of the third, advised not to)<br />
<br />
==Methods you can override==<br />
<br />
===Static functions===<br />
<br />
<br />
====supported_formats====<br />
<br />
The formats this plugin can support. At export time, both the plugin and the caller are polled for which formats they can support, and then the intersection is used to determine the export format. In the case that the intersection is greater than 1, the user is asked for their selection.<br />
<br />
The available formats you can choose from are in portfolio_supported_formats and are constants PORTFOLIO_FORMAT_XXX. By default the parent class defines PORTFOLIO_FORMAT_FILE.<br />
<br />
====plugin_sanity_check====<br />
<br />
If the plugin depends on some other part of Moodle being configured in a particular way (for example if your plugin relies on using mnet for transport and mnet is off), you can override this function. It is called frequently in different places in the code, and whenever a non empty value is returned (an error code), all instances of your plugin will be set to invisible.<br />
<br />
====has_admin_config====<br />
<br />
If your plugin has some admininistrative configuration settings (rather than by the user), override this plugin to return true. You must also override admin_config_form and get_allowed_config. You can also override admin_config_validation.<br />
<br />
<br />
====get_allowed_config====<br />
<br />
Because most of the handling of the getting and setting of admin entered configuration data happens in the parent class, with no need to be overridden in the subclasses, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
====allows_multiple_instances====<br />
<br />
By default, all plugins can have multiple instances configured. If it's only sensible for your plugin to be able to have one instance configured, override this to return false.<br />
<br />
===Class methods===<br />
<br />
====has_user_config====<br />
<br />
If your plugin can be configured in the user profile section, override this function to return true. You must also override user_config_form and get_allowed_user_config. You can also override user_config_validation.<br />
<br />
====has_export_config====<br />
<br />
If your plugin can have further (user) configuration during export, override this function to return true. You must also override export_config_form, get_export_summary and get_allowed_export_config. You can additionally override export_config_validation.<br />
<br />
====admin_config_form====<br />
<br />
This function can actually be called statically or non statically, depending on whether it's for editing an existing instance of the plugin, or for creating a new one. It's passed an mform object by reference, as are the other two config form functions, to add elements to it. If you override this you don't need to handle setting the data of the elements (when editing), that's done in the caller, using get_allowed_config. You can also override admin_config_validation.<br />
<br />
====user_config_form====<br />
<br />
If your plugin has overridden has_user_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override user_config_validation.<br />
<br />
====export_config_form====<br />
<br />
If your plugin has overridden has_export_config to return true, you must implement this function. It takes a moodleform object as a parameter (passed by reference) to have additional elements added to it by this function. You can also override export_config_validation.<br />
<br />
====admin_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. This function can be called statically or non statically.<br />
<br />
====user_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
====export_config_validation====<br />
<br />
This follows the exact same format as the validation() function in the moodleform object. <br />
<br />
====get_export_summary====<br />
<br />
If your plugin has overridden has_export_config, you must implement this to display nicely to the user on the confirmation screen. It should return an array of config options, the keys being nice strings to display to the user and the values being the selected config values.<br />
<br />
====steal_control====<br />
<br />
During any part of the export process, a plugin can completely steal control away from portfolio/add.php. This is useful, for example, for plugins that need the user go to log into a remote system and grant an application access. It could be also used for a completely custom screen provided by the plugin. If you need this, override this function to return a url, and the user will be redirected there. When you're finished, return to $CFG->wwwroot/portfolio/add.php?postcontrol=1 and processing will continue. If you override this, it might be useful to also override post_control.<br />
<br />
====post_control====<br />
<br />
After control is returned after steal_control, post_control will be called before the next stage is processed, and passed any request parameters. For an example of how this is used, see the box.net plugin, which uses steal_control to redirect to box.net to get the user to authenticate and then box.net redirects back to a url passing an authentication token to use for the rest of the session. Since it's part of the request parameters, it's passed through to post_control, which stores whatever it needs before the next stage.<br />
<br />
====get_allowed_user_config====<br />
<br />
Because the setting and getting of user entered configuration data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed.<br />
<br />
====get_allowed_export_config====<br />
<br />
Because the setting and getting of per-export config data happens in the parent class, this method is responsible for letting the parent class know what fields are allowed (note that if you store non-user entered config data you must implement this function)<br />
<br />
====instance_sanity_check====<br />
<br />
Similar to plugin_sanity_check although operates on an instance basis. Again, returning anything non empty here will be taken as an error string, and the instance set to invisible.<br />
<br />
====send_file (pull only)====<br />
<br />
Sends the file to STDOUT (the browser in the case of the download plugin but may be an external system requesting it) - this function gets called when portfolio/file.php is requested and by default just passes the contents of the file straight through to the browser, unencrypted. The other pull plugin this far is mahara, and it doesn't implement this function as the file is retrieved via an xmlrpc request and sent back encrypted and base64 encoded.<br />
<br />
====cleanup====<br />
<br />
if you've stashed anything in extra database tables, you can implement this function to clean them up. this is called on cron to cleanup expired transfers, as well as after a successful transfer.<br />
<br />
====mnet_publishes====<br />
<br />
return array of xmlrpc service methods for mnet (see mahara implementation for more detail)<br />
<br />
====get_static_continue_url====<br />
<br />
In some cases, the transfer is logged from somewhere other than the interactive browser session (eg when a pull plugin completes the transfer before the browser is redirected to the finish page). The static_continue_url is the one that is finally logged and inserted into the log table, and used to display later to the user (in the Transfer log screen under portfolios in their profile). This, combined with resolve_static_continue_url, are used to generate a new url later to the user.<br />
<br />
For example, the mahara plugin generates an interactive continue url based on an mnet session, and it contains the mnet sessionid.<br />
The static continue url just contains the "wantsurl" part of that in mahara - eg artefact/file/<br />
resolve_static_continue_url converts the static url into a new mnet jump session url.<br />
<br />
====resolve_static_continue_url====<br />
<br />
See get_static_continue_url.<br />
<br />
<br />
<br />
==Methods you shouldn't really override==<br />
<br />
===Static functions===<br />
<br />
====create_instance====<br />
<br />
Creates an instance of the given plugin. As well as plugin and name, this can also be passed initial admin config. Returns an object of the correct subclass.<br />
<br />
===Class methods===<br />
<br />
====__construct====<br />
<br />
Constructor for the plugin. Subclasses don't need to override this.<br />
<br />
====save====<br />
<br />
Saves data stored in the object back to the database and resets the dirty flag.<br />
<br />
====delete====<br />
<br />
Deletes this instance and all configuration data associated with it completely from the database<br />
<br />
====set_export_config====<br />
<br />
I had originally made this function final in the base class, but the box.net plugin needs to override it for dependent export config that's a bit funky.<br />
[[Category:Portfolios]]<br />
<br />
[[Category:Plugins]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Calendar_API&diff=31516Calendar API2012-01-17T06:35:42Z<p>Rwijaya: </p>
<hr />
<div>The Calendar API allows you to add and modify events in the calendar for user, groups, courses, or the whole site.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events from everything users have access to.<br />
<br />
If your plugin generates calendar events (such as due dates) then you need to add your events to the calendar.<br />
<br />
==File locations==<br />
<br />
All the calendar code is located in /calendar/lib.php. You need to include this file in your script if you intend to use it.<br />
<br />
<br />
==The calendar_event class==<br />
<br />
In general functionality of calendar_event() class are to create, update and delete events.<br />
<br />
===Creating new event===<br />
Creating new calendar event to database by defining some properties for the event. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to create event for the hook.<br />
<code php><br />
calendar_event::create($properties)<br />
</code><br />
<br />
===Updating event===<br />
Updating an existing event in database by providing at least an event id. If the event is a repeated events, the rest of series event will also be updated (depending on the properties value of repeateditall). This function could also be use to insert new event to database If the requested event is not exist in database. The optional parameter $checkcapability is use to check user's capability to edit/add event. By default $checkcapability parameter is set to true. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to update the hook event.<br />
<code php><br />
calendar_event::update($data, $checkcapability = true)<br />
</code><br />
<br />
===Deleting event===<br />
Deleting an existing event in database. The optional parameter $deleterepeated is use as indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also deleting all associated files related to the event's editor context.<br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to delete event for the hook.<br />
<code php><br />
calendar_event::delete($deleterepeated = false)<br />
</code><br />
<br />
===Event hook===<br />
The capability to use hook to perform specific action to calendar event. This requires setting up $CFG->calendar and include external calendar file in $CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php').<br />
<code php><br />
calendar_event_hook($action, array $args)<br />
</code><br />
<br />
==Functions==<br />
List of function for calendar and calendar_event.<br />
<br />
===Retrieve or print calendar's information===<br />
<code php><br />
calendar_get_default_courses()<br />
calendar_get_days()<br />
calendar_get_starting_weekday()<br />
calendar_day_representation($tstamp, $now = false, $usecommonwords = true)<br />
calendar_time_representation($time)<br />
calendar_wday_name($englishname)<br />
calendar_days_in_month($month, $year)<br />
calendar_get_link_href($linkbase, $d, $m, $y)<br />
calendar_get_mini($courses, $groups, $users, $cal_month = false, $cal_year = false)<br />
calendar_get_popup($is_today, $event_timestart, $popupcontent = '') <br />
calendar_add_month($month, $year)<br />
calendar_sub_month($month, $year)<br />
calendar_get_module_cached(&$coursecache, $modulename, $instance) <br />
calendar_get_course_cached(&$coursecache, $courseid)<br />
calendar_print_month_selector($name, $selected)<br />
</code><br />
<br />
===Control calendar display===<br />
<code php><br />
calendar_top_controls($type, $data)<br />
calendar_filter_controls(moodle_url $returnurl)<br />
calendar_preferences_button(stdClass $course)<br />
calendar_set_filters(array $courseeventsfrom, $ignorefilters = false)<br />
calendar_get_link_previous($text, $linkbase, $d, $m, $y, $accesshide = false)<br />
calendar_get_link_next($text, $linkbase, $d, $m, $y, $accesshide = false)<br />
</code><br />
<br />
===Retrieve calendar_event information===<br />
<code php><br />
calendar_get_allowed_types(&$allowed, $course = null)<br />
calendar_add_event_allowed($event) <br />
calendar_edit_event_allowed($event)<br />
calendar_user_can_add_event($course)<br />
calendar_show_event_type($type, $user = null)<br />
calendar_set_event_type_display($type, $display = null, $user = null)<br />
calendar_get_events($tstart, $tend, $users, $groups, $courses, $withduration = true, $ignorehidden = true)<br />
calendar_events_by_day($events, $month, $year, &$eventsbyday, &$durationbyday, &$typesbyday, &$courses) <br />
calendar_get_upcoming($courses, $groups, $users, $daysinfuture, $maxevents, $fromtime = 0)<br />
calendar_get_block_upcoming($events, $linkhref = NULL)<br />
calendar_format_event_time($event, $now, $linkparams = null, $usecommonwords = true, $showtime = 0)<br />
calendar_add_event_metadata($event)<br />
</code><br />
<br />
==Examples==<br />
The following are examples of using the basic calendar_event API in Moodle.<br />
<br />
===Example to create new event===<br />
Creating new calendar event for closing feedback date.<br />
<code php><br />
$event = new stdClass;<br />
$event->name = get_string('stop', 'feedback').' '.$feedback->name;<br />
$event->description = format_module_intro('feedback', $feedback, $feedback->coursemodule);<br />
$event->courseid = $feedback->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'feedback';<br />
$event->instance = $feedback->id;<br />
$event->eventtype = 'close';<br />
$event->timestart = $feedback->timeclose;<br />
$event->visible = instance_is_visible('feedback', $feedback);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
===Updating existing calendar event===<br />
Simple example of updating exiting event through moodle form.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
===Deleting existing calendar event===<br />
Simple example of deleting existing event from database.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==See also==<br />
<br />
* [[:en:Calendar|Calendar user docs]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Calendar_API&diff=31473Calendar API2012-01-16T07:43:34Z<p>Rwijaya: /* The calendar_event class */</p>
<hr />
<div>The Calendar API allows you to add and modify events in the calendar for user, groups, courses, or the whole site.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events from everything users have access to.<br />
<br />
If your plugin generates calendar events (such as due dates) then you need to add your events to the calendar.<br />
<br />
==File locations==<br />
<br />
All the calendar code is located in /calendar/lib.php. You need to include this file in your script if you intend to use it.<br />
<br />
<br />
==The calendar_event class==<br />
<br />
In general functionality of calendar_event() class are to create, update and delete events.<br />
<br />
===Creating new event===<br />
Creating new calendar event to database by defining some properties for the event. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to create event for the hook.<br />
<code php><br />
calendar_event::create($properties)<br />
</code><br />
<br />
===Updating event===<br />
Updating an existing event in database by providing at least an event id. If the event is a repeated events, the rest of series event will also be updated (depending on the properties value of repeateditall). This function could also be use to insert new event to database If the requested event is not exist in database. The optional parameter $checkcapability is use to check user's capability to edit/add event. By default $checkcapability parameter is set to true. <br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to update the hook event.<br />
<code php><br />
calendar_event::update($data, $checkcapability=true)<br />
</code><br />
<br />
===Deleting event===<br />
Deleting an existing event in database. The optional parameter $deleterepeated is use as indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also deleting all associated files related to the event's editor context.<br />
<br />
If event hook is used, it will also call self::calendar_event_hook() to delete event for the hook.<br />
<code php><br />
calendar_event::delete($deleterepeated=false)<br />
</code><br />
<br />
===Event hook===<br />
The capability to use hook to perform specific action to calendar event. This requires setting up $CFG->calendar and include external calendar file in $CFG->dirroot .'/calendar/'. $CFG->calendar .'/lib.php').<br />
<code php><br />
calendar_event_hook($action, array $args)<br />
</code><br />
<br />
==Examples==<br />
The following are examples of using the basic calendar_event API in Moodle.<br />
<br />
===Example to create new event===<br />
Creating new calendar event for closing feedback date.<br />
<code php><br />
$event = new stdClass;<br />
$event->name = get_string('stop', 'feedback').' '.$feedback->name;<br />
$event->description = format_module_intro('feedback', $feedback, $feedback->coursemodule);<br />
$event->courseid = $feedback->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'feedback';<br />
$event->instance = $feedback->id;<br />
$event->eventtype = 'close';<br />
$event->timestart = $feedback->timeclose;<br />
$event->visible = instance_is_visible('feedback', $feedback);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
===Updating existing calendar event===<br />
Simple example of updating exiting event through moodle form.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
===Deleting existing calendar event===<br />
Simple example of deleting existing event from database.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==See also==<br />
<br />
* [[:en:Calendar|Calendar user docs]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Calendar_API&diff=31468Calendar API2012-01-16T07:20:29Z<p>Rwijaya: /* Examples */</p>
<hr />
<div>The Calendar API allows you to add and modify events in the calendar for user, groups, courses, or the whole site.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events from everything users have access to.<br />
<br />
If your plugin generates calendar events (such as due dates) then you need to add your events to the calendar.<br />
<br />
==File locations==<br />
<br />
All the calendar code is located in /calendar/lib.php. You need to include this file in your script if you intend to use it.<br />
<br />
<br />
==The calendar_event class==<br />
<br />
In general functionality of calendar_event() class are to create, update and delete events.<br />
<br />
===Creating new event===<br />
Creating new calendar event to database by defining some properties for the event.<br />
<code><br />
calendar_event::create($properties)<br />
</code><br />
<br />
===Updating event===<br />
Updating an existing event in database by providing at least an event id. If the event is a repeated events, the rest of series event will also be updated (depending on the properties value of repeateditall). This function could also be use to insert new event to database If the requested event is not exist in database. The optional parameter $checkcapability is use to check user's capability to edit/add event. By default $checkcapability parameter is set to true. <br />
<code><br />
calendar_event::update($data, $checkcapability=true)<br />
</code><br />
<br />
===Deleting event===<br />
Deleting an existing event in database. The optional parameter $deleterepeated is use as indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also deleting all associated files related to the event's editor context.<br />
<code><br />
calendar_event::delete($deleterepeated=false)<br />
</code><br />
<br />
==Examples==<br />
The following are examples of using the basic calendar_event API in Moodle.<br />
<br />
===Example to create new event===<br />
Creating new calendar event for closing feedback date.<br />
<code php><br />
$event = new stdClass;<br />
$event->name = get_string('stop', 'feedback').' '.$feedback->name;<br />
$event->description = format_module_intro('feedback', $feedback, $feedback->coursemodule);<br />
$event->courseid = $feedback->course;<br />
$event->groupid = 0;<br />
$event->userid = 0;<br />
$event->modulename = 'feedback';<br />
$event->instance = $feedback->id;<br />
$event->eventtype = 'close';<br />
$event->timestart = $feedback->timeclose;<br />
$event->visible = instance_is_visible('feedback', $feedback);<br />
$event->timeduration = 0;<br />
<br />
calendar_event::create($event);<br />
</code><br />
<br />
===Updating existing calendar event===<br />
Simple example of updating exiting event through moodle form.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
<br />
$data = $mform->get_data();<br />
$event->update($data);<br />
</code><br />
<br />
===Deleting existing calendar event===<br />
Simple example of deleting existing event from database.<br />
<code php><br />
$eventid = required_param('id', PARAM_INT);<br />
$event = calendar_event::load($eventid);<br />
$event->delete($repeats);<br />
</code><br />
<br />
==See also==<br />
<br />
* [[:en:Calendar|Calendar user docs]]</div>Rwijayahttps://docs.moodle.org/dev/index.php?title=Calendar_API&diff=31464Calendar API2012-01-16T06:57:55Z<p>Rwijaya: /* The calendar_event class */</p>
<hr />
<div>The Calendar API allows you to add and modify events in the calendar for user, groups, courses, or the whole site.<br />
<br />
==Overview==<br />
<br />
The Moodle [[:en:Calendar|Calendar]] collects and displays calendar events from everything users have access to.<br />
<br />
If your plugin generates calendar events (such as due dates) then you need to add your events to the calendar.<br />
<br />
==File locations==<br />
<br />
All the calendar code is located in /calendar/lib.php. You need to include this file in your script if you intend to use it.<br />
<br />
<br />
==The calendar_event class==<br />
<br />
In general functionality of calendar_event() class are to create, update and delete events.<br />
<br />
===Creating new event===<br />
Creating new calendar event to database by defining some properties for the event.<br />
<code><br />
calendar_event::create($properties)<br />
</code><br />
<br />
===Updating event===<br />
Updating an existing event in database by providing at least an event id. If the event is a repeated events, the rest of series event will also be updated (depending on the properties value of repeateditall). This function could also be use to insert new event to database If the requested event is not exist in database. The optional parameter $checkcapability is use to check user's capability to edit/add event. By default $checkcapability parameter is set to true. <br />
<code><br />
calendar_event::update($data, $checkcapability=true)<br />
</code><br />
<br />
===Deleting event===<br />
Deleting an existing event in database. The optional parameter $deleterepeated is use as indicator to remove the rest of repeated events. The default value for $deleterepeated is true. Deleting an event will also deleting all associated files related to the event's editor context.<br />
<code><br />
calendar_event::delete($deleterepeated=false)<br />
</code><br />
<br />
==Examples==<br />
<br />
Adding an event to the calendar<br />
<br />
<br />
Dealing with files<br />
<br />
<br />
etc<br />
<br />
==See also==<br />
<br />
* [[:en:Calendar|Calendar user docs]]</div>Rwijaya