MoodleDocs - User contributions [en]

MoodleNet/Contributing

2019-06-04T16:04:11Z

Mayel: /* How we collaborate */

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

== Contribution guidelines ==

=== How we collaborate ===

First off, thank you for considering contributing to MoodleNet!

Our aim is for this project to make you feel welcome as a contributor. We hugely value the comments and contributions of community members in the various publicly-accessible areas in use, which currently are:

* Home: [https://moodle.com/moodlenet Project Wiki]
* [https://docs.moodle.org/dev/MoodleNet/Code_of_Conduct Code of conduct]
* Code: [https://gitlab.com/moodlenet GitLab]
* Feature/improvement requests: [https://changemap.co/moodle/moodlenet/ ChangeMap]
* Issue tracking: [https://tracker.moodle.org/projects/MDLNET?selectedItem=com.atlassian.jira.jira-projects-plugin:components-page Moodle Tracker (Jira)]
* Discussion: [https://moodle.org/mod/forum/view.php?id=8352 MoodleNet forum]
* Chat: [https://t.me/moodlenet_devs Telegram (for developers)]

=== Other useful information ===

* It’s early days for MoodleNet, so we’re focused on laying down the foundations for the project. This means that you won’t find much usable code yet.
* We’re working as openly and transparently as possible with this project. As a contributor or member of the MoodleNet community, almost everything you come across will link to some other things that you should have access to. If you don’t have access, and you think you should, just ask!
* We're planning to resurrect our monthly [https://docs.moodle.org/dev/MoodleNet/Community-calls community calls] in 2019, which you’ll find announced on [https://blog.moodle.net/ our blog].

=== We practice [https://2017.ind.ie/ethical-design/ Ethical Design] ===

We endeavour to build technology that respects human rights, human effort, and human experience, and hope you will join in this effort.

[[File:ethical-design.png|600px|Ethical Design diagram]]

''Find out more about ethical design at: https://2017.ind.ie/ethical-design''

== How Can I Contribute? ==

=== Submitting Feature Requests, Enhancement Suggestions or Bug Reports ===

This section guides you through submitting a ✨ feature request, 💄 enhancement suggestions, and 🐛 bug reports for MoodleNet - anything from errors and crashes, to minor improvements, to completely new features.

When you post an issue, please include as many details as possible. '''Fill in the issue template''' (available below) to help us resolve issues faster.

All issue tickets should be “bite-sized”, and definitely no more than a sprint’s worth of coding work (currently we do 2 week sprints). Larger tasks/projects are represented as [https://tracker.moodle.org/browse/MDLNET-26?jql=project%20%3D%20MDLNET%20AND%20issuetype%20%3D%20Epic Epics].

=== Before making a submission ===

Please go through the checklist below before posting any ✨ 💄 🐛

* '''Check if you’re using the latest version''' of MoodleNet and all its relevant components and if you can get the desired behaviour by changing some config settings.
* '''Check if there’s already a community extension or app which provides that enhancement.'''
* '''Perform a cursory search''' in the feature/improvement list and issue tracker to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
* Never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to [mailto:moodlenet-moderators@moodle.com moodlenet-moderators@moodle.com].

'''''Note:''' If you find a '''Closed''' issue that seems like it is the same thing that you’re experiencing, open a new issue and include a link to the original issue in the body of your new one.''

=== Suggesting Features & Enhancements ===

If you find yourself wishing for a feature that doesn’t exist in MoodleNet, you are probably not alone. There are probably others out there with similar needs. Make a post on [https://changemap.co/moodle/moodlenet/ ChangeMap] which describes the feature you would like to see, why you need it, and how it might work.

Open an issue providing the following information:

* '''Use a clear and descriptive title''' for the issue to identify the suggestion.
* '''Provide a description of the suggested enhancement''' in as many details as possible, including the steps that you imagine you (as a user) would take if the feature you’re requesting existed.
* '''Describe the current behaviour''' and '''explain which behaviour you would like to see instead''' and why.
* '''Include screenshots and animated GIFs''' which help you demonstrate the steps or point out the parts of MoodleNet which the suggestion is related to. You can use a tool called [https://www.cockos.com/licecap/ LICEcap] to record GIFs on macOS and Windows, and [https://github.com/colinkeenan/silentcast Silentcast] or [https://github.com/GNOME/byzanz Byzanz] on Linux.
* '''Provide specific examples to demonstrate the enhancements'''. If possible, include drawings, screenshots, or gifs of similar features in another app.
* '''Explain why this enhancement would be useful''' to most participants of MoodleNet and isn’t something that can or should be implemented as a community extension.
* '''List some other communities, platforms or apps where this enhancement exists.'''

=== Reporting Bugs 🐛 ===

Open an issue providing the following information by filling in issue template below, explaining the problem and including additional details to help maintainers reproduce the problem:

* '''Use a clear and descriptive title''' for the issue to identify the problem.
* '''Describe the exact steps which reproduce the problem''' in as many details as possible. For example, start by explaining where you started in MoodleNet, and then which actions you took. When listing steps, '''don’t just say what you did, but explain how you did it'''. For example, if you moved the cursor to the end of a line, explain if you used the mouse or a keyboard shortcut, and if so which one?
* '''Provide specific examples to demonstrate the steps'''. Include links to files, screenshots, or copy/pasteable snippets, which you use in those examples. If you’re providing snippets in the issue, use Markdown code blocks.
* '''Describe the behaviour you observed after following the steps''' and point out what exactly is the problem with that behaviour.
* '''Explain which behaviour you expected to see instead and why.'''
* '''Include screenshots and animated GIFs''' which show you following the described steps and clearly demonstrate the problem. You can use [https://www.cockos.com/licecap/ this tool] to record GIFs on macOS and Windows, and [https://github.com/colinkeenan/silentcast this tool] or [https://github.com/GNOME/byzanz this tool] on Linux.
* '''If you’re reporting a crash''', include a crash report with error logs.
* '''If the problem wasn’t triggered by a specific action''', describe what you were doing before the problem happened and share more information using the guidelines below.

Provide more context by answering these questions:

* '''Did the problem start happening recently''' (e.g. after updating to a new version) or was this always a problem?
* If the problem started happening recently, '''can you reproduce the problem in an older version?''' What’s the most recent version in which the problem doesn’t happen?
* '''Can you reliably reproduce the issue?''' If not, provide details about how often the problem happens and under which conditions it normally happens.
* If the problem is related to a user or item (eg. collection or resource), '''does the problem happen for all of them or only some?''' Does the problem happen only when working with local (originating from your MoodleNet instance) or remote ones, with items of a specific type (e.g. only PDFs)? Is there anything else special about the users or items in question?

Include details about your configuration and environment:

* '''Which version of each component are you using?'''
* '''What’s the name and version of the OS you’re using'''?
* '''Are you running in a virtual machine?''' If so, which VM software are you using and which operating systems and versions are used for the host and the guest?

-----

=== Template for submitting issues ===

==== Description ====

[Description of the issue]

==== Steps to Reproduce ====

# [First Step]
# [Second Step]
# [and so on…]

==== Expected behaviour: ====

[What you expect to happen]

==== Actual behaviour: ====

[What actually happens]

==== Reproduces how often: ====

[What percentage of the time does it reproduce?]

==== Versions ====

[What MoodleNet instance you’re using, and the versions of each relevant app or component, including your OS and browser.]

==== Additional Information ====

[Any additional information, configuration or data that might be necessary to reproduce the issue.]

-----

=== Contributing ===

A common misconception about contributing to free and open source projects is that you need to contribute code. In fact, it’s often the other parts of a project that are most overlooked. You’ll do the project a huge favour by offering to pitch in with these types of contributions!

Even if you like to write code, other types of contributions are a great way to get involved with a project and meet other community members. Building those relationships may open up unexpected opportunities.

==== Do you like to design? 🎨 ====

* Restructure layouts to improve the project's usability
* Conduct user research to reorganise and refine the project's navigation or menus
* Create art for icons and app screens

==== Do you like to write? 🖉 ====

* Write and improve the project's documentation
* Write tutorials for the project
* Curate a wiki page of examples showing how the project can be used

==== Do you like organising? 📥 ====

* Link to duplicate issues, and suggest new issue labels, to keep things organised
* Go through open issues and suggest revisiting or closing old ones
* Ask clarifying questions on recently opened issues to move the discussion forward

==== Do you like helping people? 🙋‍♀️====

* Answer questions about the project on forums and other sites
* Answer questions for people on open issues

==== Do you like helping others code? 👐 ====

* Review code on other people’s submissions
* Write tutorials for how a project can be used
* Offer to mentor another contributor

==== Do you like to code? 🔩 ====

* Find an open issue to tackle
* Offer to help write a new feature
* Improve tooling, testing & deployment options
* Read the **next section for guidelines**

---

=== Contributing Code ===

Unsure where to begin contributing? You can start by looking through issues tagged with:

* [https://www.firsttimersonly.com <code>first-timers-only</code>]- issues which should only require a few lines of code, and a test or two.
* <code>help-wanted</code> - issues which should be a bit more involved than <code>first-timers-only</code> issues.

==== Modularity ====

MoodleNet is a large project that is intentionally very modular — it will be made up of many components in many repositories. When you initially consider contributing, you might be unsure about which of those repositories should implement the functionality you want to add or improve - the project maintainers can help with that.

==== Local development ====

MoodleNet and all packages can be developed locally. For instructions on how to do this, please see the documentation (TBD).

==== Coding & git practices ====

* We use GitLab’s merge requests as our code review tool
* We encourage any dev to comment on merge requests and we think of the merge request not as a “please approve my code” but as a space for co-developing.
* We develop features on separate branches identified by issue numbers.
* We use merge to <code>develop</code> (not rebase) so that commits related to an issue can be retroactively explored.
* We don’t currently use release branches or tags because we don’t have release management at this phase of development.

==== How to make changes ====

* Make your changes on a seperate branch which includes an issue number e.g. <code>1234-some-new-feature</code> where 1234 is the issue number where the feature is documented. Make sure the branch is based on <code>develop</code>.
* Do not commit changes to files that are irrelevant to your feature or bugfix.
* Use commit messages descriptive of your changes.
* Push to the upstream of your new branch.
* Create a merge request at GitLab.

==== Git commit messages ====

* Limit the first line to 72 characters or less, referencing relevant issue numbers
* Be as descriptive as you want after the first line
* Consider starting the commit message with an applicable emoji (see Issue & Commit Categories below)

==== Merge requests ====

* Follow the code styleguides (TBD).
* Document new code based on the documentation styleguide (TBD)
* Each merge request should implement ONE feature or bugfix. If you want to add or fix more than one thing, submit more than one merge request.
* Fill in the merge request template below
* Include relevant issue number(s) in the merge request title
* Include screenshots or animated GIFs in your merge request whenever possible.
* End all files with a newline

==== Template for merge requests ====

* Description of the change
* Applicable issue numbers
* Alternate designs/implementations
* Benefits of this implementation
* Possible drawbacks
* Why should this be part of a core component?
* Testing process

-----

==== Issue & Commit Categories ====

* 🚑 `critical` : Critical hotfix!
* 💄 `enhancement` : General improvements.
* ✨ `feature` : New features.
* 🐛 `bug` : Confirmed bugs, or reports that are likely to be bugs.
* 🙋‍♀️ `question` : Questions (e.g. how can I do X?)
* 📮 `feedback` : General feedback.
* 🎨 `ui` : Visual design.
* 📜 `copy` : Text in the apps, or translations.
* ℹ️ `documentation` : Documentation.
* 🏇 `performance` : Performance.
* 🔒 `security` : Security.
* 🔌 `api` : MoodleNet's APIs.
* 👽 `external` : External libraries or API integrations.
* ⚠️ `exception` : Uncaught exceptions.
* 🔥 `crash` : Crash.
* 🔣 `encoding` : Character encoding or data serialization issue.
* 🚚 `cleanup` : Removing, moving or refactoring code or files.
* ✅ `tests` : Testing

==== Issue Status ====

* 💬 `discussion` : Discussion to clarify this issue is ongoing.
* 🔜 `todo` : This has been discussed and now needs work.
* 🔁 `needs-more-info` : More information needs to be collected about these problems or feature requests (e.g. steps to reproduce).
* 💡 `idea` : Needs to be discussed further. Could be a feature request which might be good to first implement as a community extension.
* 🚧 `in-progress` : Someone is working on this...
* 🙏 `help-wanted` : The MoodleNet core team would appreciate help from the community in resolving these issues.
* 🌱 `first-timers-only` : Less complex issues which would be good first issues to work on for users who want to contribute.
* 🔢 `needs-reproduction` : Likely bugs, but haven't been reliably reproduced.
* 🔴 `blocked` : Blocked on other issues.
* 2️⃣ `duplicate` : Duplicate of another issue, i.e. has been reported before.
* 🙅 `wontfix` : The MoodleNet core team has decided not to fix these issues (or add these features) for now, because they're working as intended, or some other reason.
* 🚮 `invalid` : Issues which are not valid (e.g. spam or submitted by error).

==== Merge Request Status ====

* 🚧 `in-progress` : Still being worked on, more changes will follow.
* 🚏 `needs-review` : Needs code review and approval from maintainers.
* 🔍 `under-review` : Being reviewed by maintainers.
* 🔧 `changes-required` : Needs to be updated based on review comments and then reviewed again.
* 👀 `needs-testing` : Needs manual testing.

---

== Credits ==
The following documents have greatly helped us put this together. A big thank you to their authors and contributors!
* [https://www.contributor-covenant.org/version/1/4/code-of-conduct Contributor Covenant]
* [https://opensource.guide Open Source Guides]
* [https://github.com/holochain/holochain-proto/wiki/Development-Protocols Holochain's Development Protocols]
* [https://github.com/atom/atom/blob/master/CONTRIBUTING.md Atom's contributing guide]

MoodleNet/Contributing

2019-06-04T16:03:51Z

Mayel: /* How we collaborate */

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

== Contribution guidelines ==

=== How we collaborate ===

First off, thank you for considering contributing to MoodleNet!

Our aim is for this project to make you feel welcome as a contributor. We hugely value the comments and contributions of community members in the various publicly-accessible areas in use, which currently are:

* Home: [https://moodle.com/moodlenet Project Wiki]
* [https://docs.moodle.org/dev/MoodleNet/Code_of_Conduct Code of conduct]
* Code: [https://gitlab.com/moodlenet GitLab]
* Feature/improvement requests: [https://changemap.co/moodle/moodlenet/ ChangeMap]
* Issue tracking: [https://tracker.moodle.org/projects/MDLNET?selectedItem=com.atlassian.jira.jira-projects-plugin:components-page Moodle Tracker (Jira)]
* Discussion: [https://moodle.org/mod/forum/view.php?id=8352 MoodleNet forum]
* Chat: [https://t.me/moodlenet_devs Telegram]

=== Other useful information ===

* It’s early days for MoodleNet, so we’re focused on laying down the foundations for the project. This means that you won’t find much usable code yet.
* We’re working as openly and transparently as possible with this project. As a contributor or member of the MoodleNet community, almost everything you come across will link to some other things that you should have access to. If you don’t have access, and you think you should, just ask!
* We're planning to resurrect our monthly [https://docs.moodle.org/dev/MoodleNet/Community-calls community calls] in 2019, which you’ll find announced on [https://blog.moodle.net/ our blog].

=== We practice [https://2017.ind.ie/ethical-design/ Ethical Design] ===

We endeavour to build technology that respects human rights, human effort, and human experience, and hope you will join in this effort.

[[File:ethical-design.png|600px|Ethical Design diagram]]

''Find out more about ethical design at: https://2017.ind.ie/ethical-design''

== How Can I Contribute? ==

=== Submitting Feature Requests, Enhancement Suggestions or Bug Reports ===

This section guides you through submitting a ✨ feature request, 💄 enhancement suggestions, and 🐛 bug reports for MoodleNet - anything from errors and crashes, to minor improvements, to completely new features.

When you post an issue, please include as many details as possible. '''Fill in the issue template''' (available below) to help us resolve issues faster.

All issue tickets should be “bite-sized”, and definitely no more than a sprint’s worth of coding work (currently we do 2 week sprints). Larger tasks/projects are represented as [https://tracker.moodle.org/browse/MDLNET-26?jql=project%20%3D%20MDLNET%20AND%20issuetype%20%3D%20Epic Epics].

=== Before making a submission ===

Please go through the checklist below before posting any ✨ 💄 🐛

* '''Check if you’re using the latest version''' of MoodleNet and all its relevant components and if you can get the desired behaviour by changing some config settings.
* '''Check if there’s already a community extension or app which provides that enhancement.'''
* '''Perform a cursory search''' in the feature/improvement list and issue tracker to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
* Never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to [mailto:moodlenet-moderators@moodle.com moodlenet-moderators@moodle.com].

'''''Note:''' If you find a '''Closed''' issue that seems like it is the same thing that you’re experiencing, open a new issue and include a link to the original issue in the body of your new one.''

=== Suggesting Features & Enhancements ===

If you find yourself wishing for a feature that doesn’t exist in MoodleNet, you are probably not alone. There are probably others out there with similar needs. Make a post on [https://changemap.co/moodle/moodlenet/ ChangeMap] which describes the feature you would like to see, why you need it, and how it might work.

Open an issue providing the following information:

* '''Use a clear and descriptive title''' for the issue to identify the suggestion.
* '''Provide a description of the suggested enhancement''' in as many details as possible, including the steps that you imagine you (as a user) would take if the feature you’re requesting existed.
* '''Describe the current behaviour''' and '''explain which behaviour you would like to see instead''' and why.
* '''Include screenshots and animated GIFs''' which help you demonstrate the steps or point out the parts of MoodleNet which the suggestion is related to. You can use a tool called [https://www.cockos.com/licecap/ LICEcap] to record GIFs on macOS and Windows, and [https://github.com/colinkeenan/silentcast Silentcast] or [https://github.com/GNOME/byzanz Byzanz] on Linux.
* '''Provide specific examples to demonstrate the enhancements'''. If possible, include drawings, screenshots, or gifs of similar features in another app.
* '''Explain why this enhancement would be useful''' to most participants of MoodleNet and isn’t something that can or should be implemented as a community extension.
* '''List some other communities, platforms or apps where this enhancement exists.'''

=== Reporting Bugs 🐛 ===

Open an issue providing the following information by filling in issue template below, explaining the problem and including additional details to help maintainers reproduce the problem:

* '''Use a clear and descriptive title''' for the issue to identify the problem.
* '''Describe the exact steps which reproduce the problem''' in as many details as possible. For example, start by explaining where you started in MoodleNet, and then which actions you took. When listing steps, '''don’t just say what you did, but explain how you did it'''. For example, if you moved the cursor to the end of a line, explain if you used the mouse or a keyboard shortcut, and if so which one?
* '''Provide specific examples to demonstrate the steps'''. Include links to files, screenshots, or copy/pasteable snippets, which you use in those examples. If you’re providing snippets in the issue, use Markdown code blocks.
* '''Describe the behaviour you observed after following the steps''' and point out what exactly is the problem with that behaviour.
* '''Explain which behaviour you expected to see instead and why.'''
* '''Include screenshots and animated GIFs''' which show you following the described steps and clearly demonstrate the problem. You can use [https://www.cockos.com/licecap/ this tool] to record GIFs on macOS and Windows, and [https://github.com/colinkeenan/silentcast this tool] or [https://github.com/GNOME/byzanz this tool] on Linux.
* '''If you’re reporting a crash''', include a crash report with error logs.
* '''If the problem wasn’t triggered by a specific action''', describe what you were doing before the problem happened and share more information using the guidelines below.

Provide more context by answering these questions:

* '''Did the problem start happening recently''' (e.g. after updating to a new version) or was this always a problem?
* If the problem started happening recently, '''can you reproduce the problem in an older version?''' What’s the most recent version in which the problem doesn’t happen?
* '''Can you reliably reproduce the issue?''' If not, provide details about how often the problem happens and under which conditions it normally happens.
* If the problem is related to a user or item (eg. collection or resource), '''does the problem happen for all of them or only some?''' Does the problem happen only when working with local (originating from your MoodleNet instance) or remote ones, with items of a specific type (e.g. only PDFs)? Is there anything else special about the users or items in question?

Include details about your configuration and environment:

* '''Which version of each component are you using?'''
* '''What’s the name and version of the OS you’re using'''?
* '''Are you running in a virtual machine?''' If so, which VM software are you using and which operating systems and versions are used for the host and the guest?

-----

=== Template for submitting issues ===

==== Description ====

[Description of the issue]

==== Steps to Reproduce ====

# [First Step]
# [Second Step]
# [and so on…]

==== Expected behaviour: ====

[What you expect to happen]

==== Actual behaviour: ====

[What actually happens]

==== Reproduces how often: ====

[What percentage of the time does it reproduce?]

==== Versions ====

[What MoodleNet instance you’re using, and the versions of each relevant app or component, including your OS and browser.]

==== Additional Information ====

[Any additional information, configuration or data that might be necessary to reproduce the issue.]

-----

=== Contributing ===

A common misconception about contributing to free and open source projects is that you need to contribute code. In fact, it’s often the other parts of a project that are most overlooked. You’ll do the project a huge favour by offering to pitch in with these types of contributions!

Even if you like to write code, other types of contributions are a great way to get involved with a project and meet other community members. Building those relationships may open up unexpected opportunities.

==== Do you like to design? 🎨 ====

* Restructure layouts to improve the project's usability
* Conduct user research to reorganise and refine the project's navigation or menus
* Create art for icons and app screens

==== Do you like to write? 🖉 ====

* Write and improve the project's documentation
* Write tutorials for the project
* Curate a wiki page of examples showing how the project can be used

==== Do you like organising? 📥 ====

* Link to duplicate issues, and suggest new issue labels, to keep things organised
* Go through open issues and suggest revisiting or closing old ones
* Ask clarifying questions on recently opened issues to move the discussion forward

==== Do you like helping people? 🙋‍♀️====

* Answer questions about the project on forums and other sites
* Answer questions for people on open issues

==== Do you like helping others code? 👐 ====

* Review code on other people’s submissions
* Write tutorials for how a project can be used
* Offer to mentor another contributor

==== Do you like to code? 🔩 ====

* Find an open issue to tackle
* Offer to help write a new feature
* Improve tooling, testing & deployment options
* Read the **next section for guidelines**

---

=== Contributing Code ===

Unsure where to begin contributing? You can start by looking through issues tagged with:

* [https://www.firsttimersonly.com <code>first-timers-only</code>]- issues which should only require a few lines of code, and a test or two.
* <code>help-wanted</code> - issues which should be a bit more involved than <code>first-timers-only</code> issues.

==== Modularity ====

MoodleNet is a large project that is intentionally very modular — it will be made up of many components in many repositories. When you initially consider contributing, you might be unsure about which of those repositories should implement the functionality you want to add or improve - the project maintainers can help with that.

==== Local development ====

MoodleNet and all packages can be developed locally. For instructions on how to do this, please see the documentation (TBD).

==== Coding & git practices ====

* We use GitLab’s merge requests as our code review tool
* We encourage any dev to comment on merge requests and we think of the merge request not as a “please approve my code” but as a space for co-developing.
* We develop features on separate branches identified by issue numbers.
* We use merge to <code>develop</code> (not rebase) so that commits related to an issue can be retroactively explored.
* We don’t currently use release branches or tags because we don’t have release management at this phase of development.

==== How to make changes ====

* Make your changes on a seperate branch which includes an issue number e.g. <code>1234-some-new-feature</code> where 1234 is the issue number where the feature is documented. Make sure the branch is based on <code>develop</code>.
* Do not commit changes to files that are irrelevant to your feature or bugfix.
* Use commit messages descriptive of your changes.
* Push to the upstream of your new branch.
* Create a merge request at GitLab.

==== Git commit messages ====

* Limit the first line to 72 characters or less, referencing relevant issue numbers
* Be as descriptive as you want after the first line
* Consider starting the commit message with an applicable emoji (see Issue & Commit Categories below)

==== Merge requests ====

* Follow the code styleguides (TBD).
* Document new code based on the documentation styleguide (TBD)
* Each merge request should implement ONE feature or bugfix. If you want to add or fix more than one thing, submit more than one merge request.
* Fill in the merge request template below
* Include relevant issue number(s) in the merge request title
* Include screenshots or animated GIFs in your merge request whenever possible.
* End all files with a newline

==== Template for merge requests ====

* Description of the change
* Applicable issue numbers
* Alternate designs/implementations
* Benefits of this implementation
* Possible drawbacks
* Why should this be part of a core component?
* Testing process

-----

==== Issue & Commit Categories ====

* 🚑 `critical` : Critical hotfix!
* 💄 `enhancement` : General improvements.
* ✨ `feature` : New features.
* 🐛 `bug` : Confirmed bugs, or reports that are likely to be bugs.
* 🙋‍♀️ `question` : Questions (e.g. how can I do X?)
* 📮 `feedback` : General feedback.
* 🎨 `ui` : Visual design.
* 📜 `copy` : Text in the apps, or translations.
* ℹ️ `documentation` : Documentation.
* 🏇 `performance` : Performance.
* 🔒 `security` : Security.
* 🔌 `api` : MoodleNet's APIs.
* 👽 `external` : External libraries or API integrations.
* ⚠️ `exception` : Uncaught exceptions.
* 🔥 `crash` : Crash.
* 🔣 `encoding` : Character encoding or data serialization issue.
* 🚚 `cleanup` : Removing, moving or refactoring code or files.
* ✅ `tests` : Testing

==== Issue Status ====

* 💬 `discussion` : Discussion to clarify this issue is ongoing.
* 🔜 `todo` : This has been discussed and now needs work.
* 🔁 `needs-more-info` : More information needs to be collected about these problems or feature requests (e.g. steps to reproduce).
* 💡 `idea` : Needs to be discussed further. Could be a feature request which might be good to first implement as a community extension.
* 🚧 `in-progress` : Someone is working on this...
* 🙏 `help-wanted` : The MoodleNet core team would appreciate help from the community in resolving these issues.
* 🌱 `first-timers-only` : Less complex issues which would be good first issues to work on for users who want to contribute.
* 🔢 `needs-reproduction` : Likely bugs, but haven't been reliably reproduced.
* 🔴 `blocked` : Blocked on other issues.
* 2️⃣ `duplicate` : Duplicate of another issue, i.e. has been reported before.
* 🙅 `wontfix` : The MoodleNet core team has decided not to fix these issues (or add these features) for now, because they're working as intended, or some other reason.
* 🚮 `invalid` : Issues which are not valid (e.g. spam or submitted by error).

==== Merge Request Status ====

* 🚧 `in-progress` : Still being worked on, more changes will follow.
* 🚏 `needs-review` : Needs code review and approval from maintainers.
* 🔍 `under-review` : Being reviewed by maintainers.
* 🔧 `changes-required` : Needs to be updated based on review comments and then reviewed again.
* 👀 `needs-testing` : Needs manual testing.

---

== Credits ==
The following documents have greatly helped us put this together. A big thank you to their authors and contributors!
* [https://www.contributor-covenant.org/version/1/4/code-of-conduct Contributor Covenant]
* [https://opensource.guide Open Source Guides]
* [https://github.com/holochain/holochain-proto/wiki/Development-Protocols Holochain's Development Protocols]
* [https://github.com/atom/atom/blob/master/CONTRIBUTING.md Atom's contributing guide]

MoodleNet/Contributing

2019-05-09T09:25:15Z

Mayel: /* How we collaborate */

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

== Contribution guidelines ==

=== How we collaborate ===

First off, thank you for considering contributing to MoodleNet!

Our aim is for this project to make you feel welcome as a contributor. We hugely value the comments and contributions of community members in the various publicly-accessible areas in use, which currently are:

* Home: [https://moodle.com/moodlenet Project Wiki]
* [https://docs.moodle.org/dev/MoodleNet/Code_of_Conduct Code of conduct]
* Code: [https://gitlab.com/moodlenet GitLab]
* Feature/improvement requests: [https://changemap.co/moodle/moodlenet/ ChangeMap]
* Issue tracking: [https://tracker.moodle.org/projects/MDLNET?selectedItem=com.atlassian.jira.jira-projects-plugin:components-page Moodle Tracker (Jira)]
* Discussion: [https://moodle.org/mod/forum/view.php?id=8352 MoodleNet forum]
* Chat: Telegram (TBC)

=== Other useful information ===

* It’s early days for MoodleNet, so we’re focused on laying down the foundations for the project. This means that you won’t find much usable code yet.
* We’re working as openly and transparently as possible with this project. As a contributor or member of the MoodleNet community, almost everything you come across will link to some other things that you should have access to. If you don’t have access, and you think you should, just ask!
* We're planning to resurrect our monthly [https://docs.moodle.org/dev/MoodleNet/Community-calls community calls] in 2019, which you’ll find announced on [https://blog.moodle.net/ our blog].

=== We practice [https://2017.ind.ie/ethical-design/ Ethical Design] ===

We endeavour to build technology that respects human rights, human effort, and human experience, and hope you will join in this effort.

[[File:ethical-design.png|600px|Ethical Design diagram]]

''Find out more about ethical design at: https://2017.ind.ie/ethical-design''

== How Can I Contribute? ==

=== Submitting Feature Requests, Enhancement Suggestions or Bug Reports ===

This section guides you through submitting a ✨ feature request, 💄 enhancement suggestions, and 🐛 bug reports for MoodleNet - anything from errors and crashes, to minor improvements, to completely new features.

When you post an issue, please include as many details as possible. '''Fill in the issue template''' (available below) to help us resolve issues faster.

All issue tickets should be “bite-sized”, and definitely no more than a sprint’s worth of coding work (currently we do 2 week sprints). Larger tasks/projects are represented as [https://tracker.moodle.org/browse/MDLNET-26?jql=project%20%3D%20MDLNET%20AND%20issuetype%20%3D%20Epic Epics].

=== Before making a submission ===

Please go through the checklist below before posting any ✨ 💄 🐛

* '''Check if you’re using the latest version''' of MoodleNet and all its relevant components and if you can get the desired behaviour by changing some config settings.
* '''Check if there’s already a community extension or app which provides that enhancement.'''
* '''Perform a cursory search''' in the feature/improvement list and issue tracker to see if the enhancement has already been suggested. If it has, add a comment to the existing issue instead of opening a new one.
* Never report security related issues, vulnerabilities or bugs including sensitive information to the issue tracker, or elsewhere in public. Instead sensitive bugs must be sent by email to [mailto:moodlenet-moderators@moodle.com moodlenet-moderators@moodle.com].

'''''Note:''' If you find a '''Closed''' issue that seems like it is the same thing that you’re experiencing, open a new issue and include a link to the original issue in the body of your new one.''

=== Suggesting Features & Enhancements ===

If you find yourself wishing for a feature that doesn’t exist in MoodleNet, you are probably not alone. There are probably others out there with similar needs. Make a post on [https://changemap.co/moodle/moodlenet/ ChangeMap] which describes the feature you would like to see, why you need it, and how it might work.

Open an issue providing the following information:

* '''Use a clear and descriptive title''' for the issue to identify the suggestion.
* '''Provide a description of the suggested enhancement''' in as many details as possible, including the steps that you imagine you (as a user) would take if the feature you’re requesting existed.
* '''Describe the current behaviour''' and '''explain which behaviour you would like to see instead''' and why.
* '''Include screenshots and animated GIFs''' which help you demonstrate the steps or point out the parts of MoodleNet which the suggestion is related to. You can use a tool called [https://www.cockos.com/licecap/ LICEcap] to record GIFs on macOS and Windows, and [https://github.com/colinkeenan/silentcast Silentcast] or [https://github.com/GNOME/byzanz Byzanz] on Linux.
* '''Provide specific examples to demonstrate the enhancements'''. If possible, include drawings, screenshots, or gifs of similar features in another app.
* '''Explain why this enhancement would be useful''' to most participants of MoodleNet and isn’t something that can or should be implemented as a community extension.
* '''List some other communities, platforms or apps where this enhancement exists.'''

=== Reporting Bugs 🐛 ===

Open an issue providing the following information by filling in issue template below, explaining the problem and including additional details to help maintainers reproduce the problem:

* '''Use a clear and descriptive title''' for the issue to identify the problem.
* '''Describe the exact steps which reproduce the problem''' in as many details as possible. For example, start by explaining where you started in MoodleNet, and then which actions you took. When listing steps, '''don’t just say what you did, but explain how you did it'''. For example, if you moved the cursor to the end of a line, explain if you used the mouse or a keyboard shortcut, and if so which one?
* '''Provide specific examples to demonstrate the steps'''. Include links to files, screenshots, or copy/pasteable snippets, which you use in those examples. If you’re providing snippets in the issue, use Markdown code blocks.
* '''Describe the behaviour you observed after following the steps''' and point out what exactly is the problem with that behaviour.
* '''Explain which behaviour you expected to see instead and why.'''
* '''Include screenshots and animated GIFs''' which show you following the described steps and clearly demonstrate the problem. You can use [https://www.cockos.com/licecap/ this tool] to record GIFs on macOS and Windows, and [https://github.com/colinkeenan/silentcast this tool] or [https://github.com/GNOME/byzanz this tool] on Linux.
* '''If you’re reporting a crash''', include a crash report with error logs.
* '''If the problem wasn’t triggered by a specific action''', describe what you were doing before the problem happened and share more information using the guidelines below.

Provide more context by answering these questions:

* '''Did the problem start happening recently''' (e.g. after updating to a new version) or was this always a problem?
* If the problem started happening recently, '''can you reproduce the problem in an older version?''' What’s the most recent version in which the problem doesn’t happen?
* '''Can you reliably reproduce the issue?''' If not, provide details about how often the problem happens and under which conditions it normally happens.
* If the problem is related to a user or item (eg. collection or resource), '''does the problem happen for all of them or only some?''' Does the problem happen only when working with local (originating from your MoodleNet instance) or remote ones, with items of a specific type (e.g. only PDFs)? Is there anything else special about the users or items in question?

Include details about your configuration and environment:

* '''Which version of each component are you using?'''
* '''What’s the name and version of the OS you’re using'''?
* '''Are you running in a virtual machine?''' If so, which VM software are you using and which operating systems and versions are used for the host and the guest?

-----

=== Template for submitting issues ===

==== Description ====

[Description of the issue]

==== Steps to Reproduce ====

# [First Step]
# [Second Step]
# [and so on…]

==== Expected behaviour: ====

[What you expect to happen]

==== Actual behaviour: ====

[What actually happens]

==== Reproduces how often: ====

[What percentage of the time does it reproduce?]

==== Versions ====

[What MoodleNet instance you’re using, and the versions of each relevant app or component, including your OS and browser.]

==== Additional Information ====

[Any additional information, configuration or data that might be necessary to reproduce the issue.]

-----

=== Contributing ===

A common misconception about contributing to free and open source projects is that you need to contribute code. In fact, it’s often the other parts of a project that are most overlooked. You’ll do the project a huge favour by offering to pitch in with these types of contributions!

Even if you like to write code, other types of contributions are a great way to get involved with a project and meet other community members. Building those relationships may open up unexpected opportunities.

==== Do you like to design? 🎨 ====

* Restructure layouts to improve the project's usability
* Conduct user research to reorganise and refine the project's navigation or menus
* Create art for icons and app screens

==== Do you like to write? 🖉 ====

* Write and improve the project's documentation
* Write tutorials for the project
* Curate a wiki page of examples showing how the project can be used

==== Do you like organising? 📥 ====

* Link to duplicate issues, and suggest new issue labels, to keep things organised
* Go through open issues and suggest revisiting or closing old ones
* Ask clarifying questions on recently opened issues to move the discussion forward

==== Do you like helping people? 🙋‍♀️====

* Answer questions about the project on forums and other sites
* Answer questions for people on open issues

==== Do you like helping others code? 👐 ====

* Review code on other people’s submissions
* Write tutorials for how a project can be used
* Offer to mentor another contributor

==== Do you like to code? 🔩 ====

* Find an open issue to tackle
* Offer to help write a new feature
* Improve tooling, testing & deployment options
* Read the **next section for guidelines**

---

=== Contributing Code ===

Unsure where to begin contributing? You can start by looking through issues tagged with:

* [https://www.firsttimersonly.com <code>first-timers-only</code>]- issues which should only require a few lines of code, and a test or two.
* <code>help-wanted</code> - issues which should be a bit more involved than <code>first-timers-only</code> issues.

==== Modularity ====

MoodleNet is a large project that is intentionally very modular — it will be made up of many components in many repositories. When you initially consider contributing, you might be unsure about which of those repositories should implement the functionality you want to add or improve - the project maintainers can help with that.

==== Local development ====

MoodleNet and all packages can be developed locally. For instructions on how to do this, please see the documentation (TBD).

==== Coding & git practices ====

* We use GitLab’s merge requests as our code review tool
* We encourage any dev to comment on merge requests and we think of the merge request not as a “please approve my code” but as a space for co-developing.
* We develop features on separate branches identified by issue numbers.
* We use merge to <code>develop</code> (not rebase) so that commits related to an issue can be retroactively explored.
* We don’t currently use release branches or tags because we don’t have release management at this phase of development.

==== How to make changes ====

* Make your changes on a seperate branch which includes an issue number e.g. <code>1234-some-new-feature</code> where 1234 is the issue number where the feature is documented. Make sure the branch is based on <code>develop</code>.
* Do not commit changes to files that are irrelevant to your feature or bugfix.
* Use commit messages descriptive of your changes.
* Push to the upstream of your new branch.
* Create a merge request at GitLab.

==== Git commit messages ====

* Limit the first line to 72 characters or less, referencing relevant issue numbers
* Be as descriptive as you want after the first line
* Consider starting the commit message with an applicable emoji (see Issue & Commit Categories below)

==== Merge requests ====

* Follow the code styleguides (TBD).
* Document new code based on the documentation styleguide (TBD)
* Each merge request should implement ONE feature or bugfix. If you want to add or fix more than one thing, submit more than one merge request.
* Fill in the merge request template below
* Include relevant issue number(s) in the merge request title
* Include screenshots or animated GIFs in your merge request whenever possible.
* End all files with a newline

==== Template for merge requests ====

* Description of the change
* Applicable issue numbers
* Alternate designs/implementations
* Benefits of this implementation
* Possible drawbacks
* Why should this be part of a core component?
* Testing process

-----

==== Issue & Commit Categories ====

* 🚑 `critical` : Critical hotfix!
* 💄 `enhancement` : General improvements.
* ✨ `feature` : New features.
* 🐛 `bug` : Confirmed bugs, or reports that are likely to be bugs.
* 🙋‍♀️ `question` : Questions (e.g. how can I do X?)
* 📮 `feedback` : General feedback.
* 🎨 `ui` : Visual design.
* 📜 `copy` : Text in the apps, or translations.
* ℹ️ `documentation` : Documentation.
* 🏇 `performance` : Performance.
* 🔒 `security` : Security.
* 🔌 `api` : MoodleNet's APIs.
* 👽 `external` : External libraries or API integrations.
* ⚠️ `exception` : Uncaught exceptions.
* 🔥 `crash` : Crash.
* 🔣 `encoding` : Character encoding or data serialization issue.
* 🚚 `cleanup` : Removing, moving or refactoring code or files.
* ✅ `tests` : Testing

==== Issue Status ====

* 💬 `discussion` : Discussion to clarify this issue is ongoing.
* 🔜 `todo` : This has been discussed and now needs work.
* 🔁 `needs-more-info` : More information needs to be collected about these problems or feature requests (e.g. steps to reproduce).
* 💡 `idea` : Needs to be discussed further. Could be a feature request which might be good to first implement as a community extension.
* 🚧 `in-progress` : Someone is working on this...
* 🙏 `help-wanted` : The MoodleNet core team would appreciate help from the community in resolving these issues.
* 🌱 `first-timers-only` : Less complex issues which would be good first issues to work on for users who want to contribute.
* 🔢 `needs-reproduction` : Likely bugs, but haven't been reliably reproduced.
* 🔴 `blocked` : Blocked on other issues.
* 2️⃣ `duplicate` : Duplicate of another issue, i.e. has been reported before.
* 🙅 `wontfix` : The MoodleNet core team has decided not to fix these issues (or add these features) for now, because they're working as intended, or some other reason.
* 🚮 `invalid` : Issues which are not valid (e.g. spam or submitted by error).

==== Merge Request Status ====

* 🚧 `in-progress` : Still being worked on, more changes will follow.
* 🚏 `needs-review` : Needs code review and approval from maintainers.
* 🔍 `under-review` : Being reviewed by maintainers.
* 🔧 `changes-required` : Needs to be updated based on review comments and then reviewed again.
* 👀 `needs-testing` : Needs manual testing.

---

== Credits ==
The following documents have greatly helped us put this together. A big thank you to their authors and contributors!
* [https://www.contributor-covenant.org/version/1/4/code-of-conduct Contributor Covenant]
* [https://opensource.guide Open Source Guides]
* [https://github.com/holochain/holochain-proto/wiki/Development-Protocols Holochain's Development Protocols]
* [https://github.com/atom/atom/blob/master/CONTRIBUTING.md Atom's contributing guide]

MoodleNet

2019-03-20T09:30:05Z

Mayel:

[[File:Moodlenet-logo.png|400px]]

Short URL: '''https://moodle.com/moodlenet'''

<div style="background-color:yellow; padding:10px; text-align:center; font-size:1.2em; margin-bottom:1%;">Interested in contributing to this project? [https://docs.moodle.org/dev/MoodleNet/Contributing Click here!]</div>

''Note: This page describes a new project started in 2017. For the legacy mechanism of inter-connecting multiple Moodle and Mahara sites into a network, please see the [https://docs.moodle.org/en/MNet MNet] page.''

== What is MoodleNet? ==

MoodleNet sustainably empowers communities of educators to share and learn from each other to improve the quality of education. It is a new open social media platform for educators, focussed on professional development and open content. It will be an integral part of the Moodle ecosystem. This is the wiki about the project, and will be updated as the project develops.

[[File:MoodleNet_overview_(v0.9).png|thumb|Latest project overview (v0.9)|link=http://bit.ly/2Bjvie7
]]

* [https://new.moodle.net/ new.moodle.net] - project homepage
* [https://blog.moodle.net/ Blog] - official project updates by the team
* [https://docs.moodle.org/dev/MoodleNet/Contributing Contributing] - ways to get involved!
* [https://docs.moodle.org/dev/MoodleNet/Code_of_Conduct Code of Conduct] - how to act to ensure a positive community environment

== Documentation ==

There are some further details in this [https://docs.moodle.org/dev/MoodleNet_whitepaper draft white paper] from early 2018.

[[File:moodlenet-prototype.png|thumb|Prototype overview from the May 2018 MoodleNet design sprint|link=https://blog.moodle.net/2018/prototype-overview/]]

* [https://docs.moodle.org/dev/MoodleNet/inspiration Inspiration]
* [https://docs.moodle.org/dev/MoodleNet-research Other research]
* [https://docs.moodle.org/dev/MoodleNet-consultancy MoodleNet consultancy]
* [https://docs.moodle.org/dev/MoodleNet/tech/ Tech choices]
* [https://docs.moodle.org/dev/MoodleNet/VPD Value Proposition Design]
* [https://docs.moodle.org/dev/MoodleNet/Sustainability Sustainability]
* [https://docs.moodle.org/dev/MoodleNet/Security Security]
* [https://docs.moodle.org/dev/MoodleNet/FAQ FAQ]

[[File:MoodleNet-technical-diagram.png|thumb|MoodleNet tech stack|link=https://docs.moodle.org/dev/MoodleNet/tech/]]

== Next steps ==

* [https://changemap.co/moodle/moodlenet/ Suggestions from users]
* [https://bit.ly/epic-MN Milestones & work in progress]
* [https://docs.moodle.org/dev/MoodleNet/Testing Beta testing]
* [https://docs.moodle.org/dev/MoodleNet/Roadmap Roadmap]
* [https://docs.moodle.org/dev/MoodleNet/Decision_Log Decision log]

== Meetings and events ==

* [https://blog.moodle.net/2018/sign-up-feedback/ Barcelona workweek (November 2018)]
* [https://docs.moodle.org/dev/MoodleNet/MootUS18-workshop MoodleMoot US (October 2018)]
* [https://docs.moodle.org/dev/MoodleNet/MozFest18-workshop Mozilla Festival workshop (October 2018)]
* [https://docs.moodle.org/dev/MoodleNet/Front-end_dev_workshop Front-end development workshop (September 2018)]
* [https://blog.moodle.net/2018/alt-c/ ALT-C presentation (September 2018)]
* [https://docs.moodle.org/dev/MountainMoot18 MountainMoot session (July 2018)]
* [https://docs.moodle.org/dev/MoodleNet-MootES18 MoodleMoot Spain session (June 2018)]
* [https://docs.moodle.org/dev/MoodleNet/Design_Sprint Design Sprint (May 2018)]
* [https://blog.moodle.net/2018/project-moodlenet-overview-v0-4/ UK & Ireland MoodleMoot sessions (March 2018)]
* [https://docs.moodle.org/dev/MoodleNet-MootUS17 Miami MoodleMoot sessions (Nov 2017)]

== Credits ==
Icons from [https://www.flaticon.com flaticon.com]

[[es:MoodleNet]]

MoodleNet/Beta testing

2019-01-04T10:18:35Z

Mayel: /* Open registrations */

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

[[File:moodlenet-testing-approach.png|thumb|400px]]

== Timeline ==

Right now, the plan for 2019 is:

* January
** Open applications to the beta testing programme
** Create two HQ-run MoodleNet instances (English and Spanish)
** Invite 100 people to take part in the testing, based on meeting certain criteria (language, location, experience, etc.)
* February
** Receive daily/regular feedback from these 100 testers, and improve MoodleNet iteratively
** Once we're happy with progress, give 10 invites to each test user, increasing the number of people using MoodleNet to 1,000
* March
** Test federation between HQ-run instances
** Continue iteration based on feedback
** Start developing Moodle Core plugin
* April
** Test Moodle Core plugin
** Test federation with non-HQ instances
* May
** Integrate Moodle Core plugin in 3.7

----

== Approach to testing ==

=== Why? ===
''Why does MoodleNet exist?''

MoodleNet exists to better connect the existing Moodle community, and also to attract new educators. To date, the only Moodle-provided way for educators and other users to share content has been within their Moodle Core installation, backing up and importing activities, or by sharing entire courses. MoodleNet will be an upgrade to this, connecting educators via a Moodle-provided open social media platform which focuses on professional development and open content.

=== What? ===
''What is the value proposition we're testing?''

We have done some [https://docs.moodle.org/dev/MoodleNet/VPD Value Proposition Design] for different groups using MoodleNet and have decided that it will begin life as a place for educators to curate and share collections of resources. Our hypothesis is that the problem of discovery for educators cannot be solved by simply providing a more powerful search engine for the millions of resources already available. This is for at least three reasons:

* Learning is a ''social'' activity - and likewise teaching should be something that is not done entirely on one's own
* Search engines rely on ''already knowing'' what you're looking for - which is not always the case when planning a lesson, scheme of work, or course
* Individual resources exist in a wider context - including their relation to other resources, the educator's approach to learning, and where the 'classroom' is located

Initially, then, MoodleNet will be a simple web-based application allowing educators to form communities that curate collections of resources. Most of these, we imagine, will be free and openly-licensed, although MoodleNet will be resource-agnostic. Uploading resources directly to MoodleNet is out of scope for the first phase of testing, as we need to decide our approach to file hosting.

=== How? ===
''How are we going to test MoodleNet?''

In early January 2019, we'll put out a call for educators to be involved in MoodleNet testing. We can use something simple such as a Google Form for this, ensuring that there is a privacy notice that they have to agree to on the application.

We're looking for a diverse mix of educators, with our only limiting factor being their ability to speak English and/or Spanish. The kind of information we're looking to capture to make a selection includes:

* Name
* Location (country)
* Languages(s) spoken
* Current role
* Subject area(s)
* Teaching experience (years)
* Moodle experience (years)
* Resource-sharing sites currently used
* Social networks currently used
* Reason(s) for wanting to be involved in testing

We're interested in every aspect of how they decide to use MoodleNet, including:

* The communities and collections they decide to create
* What type of collections they create ''(subject-based? topic-based? other?)''
* The number and type of communities they decide to join
* How and when they use tags
* What kind of comments they add in collections
* How they respond to a 10-item limit on resource collections

=== Who? ===
''Who is going to be involved in the testing?''

The plan is to recruit 100 people to test MoodleNet. Although we need learning technologists, system administrators, and other techies to test it eventually, our initial focus should be on early-adopter educators. These will agree our [http://bit.ly/2FvqrM0 Guidelines for Contributors] and agree to give us regular feedback.

We should aim to have 50 people on the English-speaking HQ MoodleNet instance, and 50 people on the Spanish-speaking instance. On both, we need a mix of:

* Moodlers / non-Moodlers
* Experienced / inexperienced teachers
* Genders
* Experience with other social networks and OER repositories
* Educational sectors

=== When? ===
''When will the testing take place? what comes next?''

The first phase of testing MoodleNet is scheduled to begin week beginning January 21st. We need to have a testing period long enough that allows us to observe behaviours and make changes, but short enough so that it's a focused effort. Therefore, we're proposing a three-week period from Monday 21st January to Monday 11th February.

After this, we need to test at least three more things:

* '''Inviting a new cohort of users''' - we're envisaging that this will be done by giving every existing (active) user 10 invites. That theoretically takes us from 100 to 1,000 users of MoodleNet.
* '''Federation''' - first of all we can test this between HQ-run instances, but we then need to allow users and organisations to set up their own MoodleNet instances
* '''Moodle plugin''' - users should be able to send MoodleNet collections to their Moodle Core installation, and resources from Moodle Core to MoodleNet

The last of these is not well-scoped yet, for a variety of reasons. However, we're aiming for the Moodle plugin to be integrated into Moodle Core 3.7 in May 2019. The major blocker is a decision to be made about how to deal with uploaded resources. Previous proposals around Moodle Core installations hosting files have been rejected, as this was based on initial testing with MoodleCloud.

=== Where? ===
''Where will users go to test MoodleNet and give their feedback?''

There will be two HQ-run MoodleNet instances that beta testers can sign up to. We are planning for feedback to be captured in several ways:

* '''In-situ''' - when testers perform an action such as create a community, add a resource, or make a comment, they will have the opportunity to give feedback on the experience (including suggestions to improve it). This is for tweaks to the existing functionality and interface.
* '''[https://changemap.co/moodle/moodlenet/ Changemap]''' - when testers have requests around new functionality, integrations, or approach, they can use this tool.
* '''[https://moodle.org/mod/forum/view.php?id=8352 Forum]''' - more public feedback and wider philosophical speculations can be posted to the existing MoodleNet forum

== Details ==

This section is a work in progress.

=== Pilot (100 users) ===

Although MoodleNet will eventually feature a lot more functionality, in the first instance we're aiming to test a very specific value proposition: ''do educators want to join communities to curate collections of resources?''

So for this initial test, users will be able to:

* Create a profile
* Create, join, and leave a community
* Create, add to, and follow collections
* Add resources to collections
* Start (and reply to) discussions within communities and collections
* Be notified about activity within joined communities, followed collections (+recommendations)
* Moderate a community (basic)

=== Pilot (1,000) users ===

We'll be continuing to iterate based on user feedback during the pilot, using [https://changemap.co/moodle/moodlenet/ Changemap]. In addition to this, we have planned the ability for users to:

* Invite someone to create a MoodleNet account
* Sign-in with social accounts
* Follow other users
* Add other users to a contact list
* View a list other users' joined communities and followed collections via their profile
* Flag a resource/collection/community/profile as inappropriate
* Provide additioanl community moderator functionality
* Show 'related' communities and collections
* Like/favourite/star comments within communities and collections
* Like/favourite/star resources within collections
* Select a tag to find related communities, collections, and profiles
* Be reminded to post and keep their profile up-to-date by 'MoodleBot'

=== Open registrations ===

By the time we allow anyone to register, we want MoodleNet to be federated. This is something that we've been building towards since the start, and means that anyone will be able to install their own MoodleNet instance and have it be part of the wider MoodleNet network. So there's a lot of technical work to do with that, but by this stage we envisage users will be able to:

* Set up their own MoodleNet instance and connect to the wider network via ActivityPub
* Create an Emoji ID to help with identity across federated instances
* Use an admin interface to control sharing within an instance or community
* Easily share a link to a community, collection, or profile on social media
* Search for resources
* See 'recent activity' on user profiles (likes, follows, discussions, last active)
* Invite someone from your contact list to join a community
* Block other users
* Pull in resources from third-party sites via API (e.g. Creative Commons Beta Search)
* Send a MoodleNet collection to a Moodle Core site

MoodleNet/Security

2019-01-04T09:51:49Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

[https://moodle.com Moodle] takes security, privacy and user control seriously, and want to put them front and centre of our project.

=== Goals ===

* MoodleNet users can understand the distinctions between public data and private data/metadata on MoodleNet.
* Users know where their private data/metadata resides and who has access to it, and can access, export, and delete it.
* Protect private user data/metadata, not just from hackers but also (as much as is possible) from other users, instance admins, community moderators, and external applications
* Secure from malicious creation, alteration or deletion of public data
* GDPR compliance

Moodle is both a developer of open source self-hosted software, and a cloud service provider with users in the European Union. As a result, we are putting user privacy, data sovereignty, and GDPR compliance into our security plans, including asking both the Moodle community and outside experts to review our approaches and implementations.

=== Challenges ===

[https://moodle.com/moodlenet MoodleNet] will be challenging to keep secure, as it is:

* open source, both back-end and front-end
* self-hosted by diverse organisations
* federated (data is transmitted between different hosted instances)

This means there are more attack surfaces compared to typical proprietary, centralised platforms, but also means that hackers and even users can review every part of MoodleNet and make sure that it works as expected. This should result in more secure software, and higher trust in the application and its ecosystem.

=== Bug bounty programme ===

Maintaining effective security is a community effort, so if you find a security bug that could potentially impact the security or privacy of MoodleNet users, please report it, with our thanks and potentially a cash reward.

<blockquote>“We obviously can’t hire enough engineers to protect against every possible vulnerability, but we can use our bug bounty program to add on-demand expertise where we need it and continuous coverage nearly everywhere else.” – Frank, founder of Nextcloud
</blockquote>

We’re hoping that a well-managed security bug bounty program will help us demonstrate how seriously we take privacy.

We believe in transparency about our security, so any valid vulnerabilities discovered are always publicly disclosed after a grace period, to give time for a fix to be developed and deployed by as many self-hosted instances as possible.

During the initial beta phase, Moodle will be hosting the only official instance(s) of MoodleNet, so will be able to quickly deploy the first wave of security fixes. The developers will be aware when the bounty program will start and have time to prepare for the work to receive some real scrutiny.

'''By participating in the MoodleNet bounty program, you agree to be bound by the rules in this document and the [https://docs.moodle.org/dev/MoodleNet/Code_of_Conduct MoodleNet Code of Conduct].'''

=== Rewards ===

Depending on their impact, issues may qualify for a monetary reward; all reports are reviewed on a case-by-case basis, though here are some guidelines:

* Critical: $800 - i.e gaining remote code execution on the server or full database access.
* High: $400 - i.e. gaining access to private data of any other user.
* Medium: $200 - i.e. limited disclosure of private user data or attacks granting access to a single users’ user session (e.g. XSS)
* Low: $100 - i.e. very limited disclosure of user data or attacks involving a high amount of unlikely user interaction

Only bugs that show a clear exploit that puts users or their private data at risk are eligible for rewards, not theoretical vectors. Multiple vulnerabilities caused by one underlying issue will be awarded one bounty. We only reward the first reporter of a vulnerability. Public disclosure of the vulnerability prior to resolution may cancel a pending reward.

We are aware these rewards may be lower than those offered by bigger, more mature, software projects, but we think that starting this bounty programme at such an early stage of the project might mean that many bugs will be found and fixed early, and thus result in less security exposure for our users.

Found a bug that isn’t a security issue? While we can’t offer you a monetary reward in that case, we will acknowledge the issue and happily accept reports for it.

=== Scope (final scope TBD upon bounty programme launch) ===

* CommonsPub, the ActivityPub server used by MoodleNet: https://gitlab.com/OpenCoop/CommonsPub/Server
* MoodleNet back-end: https://gitlab.com/moodlenet/servers/federated
* MoodleNet front-end: https://gitlab.com/moodlenet/clients/react
* Server configurations: https://gitlab.com/moodlenet/servers/deploy

=== Responsible Disclosure Guidelines ===

We are committed to working with security researchers to verify, reproduce, and respond to legitimate reported vulnerabilities. You can help us by following these simple guidelines:

* Alert us about the vulnerability as soon as you become aware of it
* Follow up with details needed to reproduce and validate the vulnerability and a Proof of Concept (PoC) as soon as possible (if not detailed enough to reproduce the issue, it will not be eligible for a reward)
* Act in good faith to avoid privacy violations, destruction of data, and interruption or degradation of services
* Do not access or modify users’ private data, without explicit permission of the owner. Only interact with your own accounts or test accounts for security research purposes;
* Contact Moodle HQ (or the instance admin) immediately if you do inadvertently encounter user data. Do not view, alter, save, store, transfer, or otherwise access the data, and immediately purge any local information upon reporting the vulnerability;
* Give us time to correct the issue before disclosing it to other parties (if after waiting a reasonable amount of time, we seem clearly unable or unwilling to do anything about it, please do hold us accountable!)

MoodleNet/Beta testing

2018-12-06T11:34:07Z

Mayel: /* Checklist */

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

[[File:moodlenet-testing-approach.png|thumb|400px]]

== Timeline ==

Right now, the plan for 2019 is:

* January
** Open applications to the beta testing programme
** Create two HQ-run MoodleNet instances (English and Spanish)
** Invite 100 people to take part in the testing, based on meeting certain criteria (language, location, experience, etc.)
* February
** Receive daily/regular feedback from these 100 testers, and improve MoodleNet iteratively
** Once we're happy with progress, give 10 invites to each test user, increasing the number of people using MoodleNet to 1,000
* March
** Test federation between HQ-run instances
** Continue iteration based on feedback
** Start developing Moodle Core plugin
* April
** Test Moodle Core plugin
** Test federation with non-HQ instances
* May
** Integrate Moodle Core plugin in 3.7

----

== Approach to testing ==

=== Why? ===
''Why does MoodleNet exist?''

MoodleNet exists to better connect the existing Moodle community, and also to attract new educators. To date, the only Moodle-provided way for educators and other users to share content has been within their Moodle Core installation, backing up and importing activities, or by sharing entire courses. MoodleNet will be an upgrade to this, connecting educators via a Moodle-provided open social media platform which focuses on professional development and open content.

=== What? ===
''What is the value proposition we're testing?''

We have done some [https://docs.moodle.org/dev/MoodleNet/VPD Value Proposition Design] for different groups using MoodleNet and have decided that it will begin life as a place for educators to curate and share collections of resources. Our hypothesis is that the problem of discovery for educators cannot be solved by simply providing a more powerful search engine for the millions of resources already available. This is for at least three reasons:

* Learning is a ''social'' activity - and likewise teaching should be something that is not done entirely on one's own
* Search engines rely on ''already knowing'' what you're looking for - which is not always the case when planning a lesson, scheme of work, or course
* Individual resources exist in a wider context - including their relation to other resources, the educator's approach to learning, and where the 'classroom' is located

Initially, then, MoodleNet will be a simple web-based application allowing educators to form communities that curate collections of resources. Most of these, we imagine, will be free and openly-licensed, although MoodleNet will be resource-agnostic. Uploading resources directly to MoodleNet is out of scope for the first phase of testing, as we need to decide our approach to file hosting.

=== How? ===
''How are we going to test MoodleNet?''

In early January 2019, we'll put out a call for educators to be involved in MoodleNet testing. We can use something simple such as a Google Form for this, ensuring that there is a privacy notice that they have to agree to on the application.

We're looking for a diverse mix of educators, with our only limiting factor being their ability to speak English and/or Spanish. The kind of information we're looking to capture to make a selection includes:

* Name
* Location (country)
* Languages(s) spoken
* Current role
* Subject area(s)
* Teaching experience (years)
* Moodle experience (years)
* Resource-sharing sites currently used
* Social networks currently used
* Reason(s) for wanting to be involved in testing

We're interested in every aspect of how they decide to use MoodleNet, including:

* The communities and collections they decide to create
* What type of collections they create ''(subject-based? topic-based? other?)''
* The number and type of communities they decide to join
* How and when they use tags
* What kind of comments they add in collections
* How they respond to a 10-item limit on resource collections

=== Who? ===
''Who is going to be involved in the testing?''

The plan is to recruit 100 people to test MoodleNet. Although we need learning technologists, system administrators, and other techies to test it eventually, our initial focus should be on early-adopter educators. These will agree our [http://bit.ly/2FvqrM0 Guidelines for Contributors] and agree to give us regular feedback.

We should aim to have 50 people on the English-speaking HQ MoodleNet instance, and 50 people on the Spanish-speaking instance. On both, we need a mix of:

* Moodlers / non-Moodlers
* Experienced / inexperienced teachers
* Genders
* Experience with other social networks and OER repositories
* Educational sectors

=== When? ===
''When will the testing take place? what comes next?''

The first phase of testing MoodleNet is scheduled to begin week beginning January 21st. We need to have a testing period long enough that allows us to observe behaviours and make changes, but short enough so that it's a focused effort. Therefore, we're proposing a three-week period from Monday 21st January to Monday 11th February.

After this, we need to test at least three more things:

* '''Inviting a new cohort of users''' - we're envisaging that this will be done by giving every existing (active) user 10 invites. That theoretically takes us from 100 to 1,000 users of MoodleNet.
* '''Federation''' - first of all we can test this between HQ-run instances, but we then need to allow users and organisations to set up their own MoodleNet instances
* '''Moodle plugin''' - users should be able to send MoodleNet collections to their Moodle Core installation, and resources from Moodle Core to MoodleNet

The last of these is not well-scoped yet, for a variety of reasons. However, we're aiming for the Moodle plugin to be integrated into Moodle Core 3.7 in May 2019. The major blocker is a decision to be made about how to deal with uploaded resources. Previous proposals around Moodle Core installations hosting files have been rejected, as this was based on initial testing with MoodleCloud.

=== Where? ===
''Where will users go to test MoodleNet and give their feedback?''

There will be two HQ-run MoodleNet instances that beta testers can sign up to. We are planning for feedback to be captured in several ways:

* '''In-situ''' - when testers perform an action such as create a community, add a resource, or make a comment, they will have the opportunity to give feedback on the experience (including suggestions to improve it). This is for tweaks to the existing functionality and interface.
* '''[https://changemap.co/moodle/moodlenet/ Changemap]''' - when testers have requests around new functionality, integrations, or approach, they can use this tool.
* '''[https://moodle.org/mod/forum/view.php?id=8352 Forum]''' - more public feedback and wider philosophical speculations can be posted to the existing MoodleNet forum

=== Checklist ===

''[TO COMPLETE]''

We need to ensure that the following things are complete by week beginning January 7th:

* Beta tester application form
* Privacy statement
* Contribution guidelines
*

The following needs to be complete by week beginning January 14th:

* Front-end and backend functionality for [https://gitlab.com/moodlenet/project/meta/wikis/List-of-intentions-of-MoodleNet-users-(verb-based) list of verb-based user intentions] (not including federation and Moodle Core integration)
* Decisions about which applicants to invite to beta testing
* Moderation & Administration tools
*

MoodleNet/Beta testing

2018-12-06T11:32:58Z

Mayel: /* When? */

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

[[File:moodlenet-testing-approach.png|thumb|400px]]

== Timeline ==

Right now, the plan for 2019 is:

* January
** Open applications to the beta testing programme
** Create two HQ-run MoodleNet instances (English and Spanish)
** Invite 100 people to take part in the testing, based on meeting certain criteria (language, location, experience, etc.)
* February
** Receive daily/regular feedback from these 100 testers, and improve MoodleNet iteratively
** Once we're happy with progress, give 10 invites to each test user, increasing the number of people using MoodleNet to 1,000
* March
** Test federation between HQ-run instances
** Continue iteration based on feedback
** Start developing Moodle Core plugin
* April
** Test Moodle Core plugin
** Test federation with non-HQ instances
* May
** Integrate Moodle Core plugin in 3.7

----

== Approach to testing ==

=== Why? ===
''Why does MoodleNet exist?''

MoodleNet exists to better connect the existing Moodle community, and also to attract new educators. To date, the only Moodle-provided way for educators and other users to share content has been within their Moodle Core installation, backing up and importing activities, or by sharing entire courses. MoodleNet will be an upgrade to this, connecting educators via a Moodle-provided open social media platform which focuses on professional development and open content.

=== What? ===
''What is the value proposition we're testing?''

We have done some [https://docs.moodle.org/dev/MoodleNet/VPD Value Proposition Design] for different groups using MoodleNet and have decided that it will begin life as a place for educators to curate and share collections of resources. Our hypothesis is that the problem of discovery for educators cannot be solved by simply providing a more powerful search engine for the millions of resources already available. This is for at least three reasons:

* Learning is a ''social'' activity - and likewise teaching should be something that is not done entirely on one's own
* Search engines rely on ''already knowing'' what you're looking for - which is not always the case when planning a lesson, scheme of work, or course
* Individual resources exist in a wider context - including their relation to other resources, the educator's approach to learning, and where the 'classroom' is located

Initially, then, MoodleNet will be a simple web-based application allowing educators to form communities that curate collections of resources. Most of these, we imagine, will be free and openly-licensed, although MoodleNet will be resource-agnostic. Uploading resources directly to MoodleNet is out of scope for the first phase of testing, as we need to decide our approach to file hosting.

=== How? ===
''How are we going to test MoodleNet?''

In early January 2019, we'll put out a call for educators to be involved in MoodleNet testing. We can use something simple such as a Google Form for this, ensuring that there is a privacy notice that they have to agree to on the application.

We're looking for a diverse mix of educators, with our only limiting factor being their ability to speak English and/or Spanish. The kind of information we're looking to capture to make a selection includes:

* Name
* Location (country)
* Languages(s) spoken
* Current role
* Subject area(s)
* Teaching experience (years)
* Moodle experience (years)
* Resource-sharing sites currently used
* Social networks currently used
* Reason(s) for wanting to be involved in testing

We're interested in every aspect of how they decide to use MoodleNet, including:

* The communities and collections they decide to create
* What type of collections they create ''(subject-based? topic-based? other?)''
* The number and type of communities they decide to join
* How and when they use tags
* What kind of comments they add in collections
* How they respond to a 10-item limit on resource collections

=== Who? ===
''Who is going to be involved in the testing?''

The plan is to recruit 100 people to test MoodleNet. Although we need learning technologists, system administrators, and other techies to test it eventually, our initial focus should be on early-adopter educators. These will agree our [http://bit.ly/2FvqrM0 Guidelines for Contributors] and agree to give us regular feedback.

We should aim to have 50 people on the English-speaking HQ MoodleNet instance, and 50 people on the Spanish-speaking instance. On both, we need a mix of:

* Moodlers / non-Moodlers
* Experienced / inexperienced teachers
* Genders
* Experience with other social networks and OER repositories
* Educational sectors

=== When? ===
''When will the testing take place? what comes next?''

The first phase of testing MoodleNet is scheduled to begin week beginning January 21st. We need to have a testing period long enough that allows us to observe behaviours and make changes, but short enough so that it's a focused effort. Therefore, we're proposing a three-week period from Monday 21st January to Monday 11th February.

After this, we need to test at least three more things:

* '''Inviting a new cohort of users''' - we're envisaging that this will be done by giving every existing (active) user 10 invites. That theoretically takes us from 100 to 1,000 users of MoodleNet.
* '''Federation''' - first of all we can test this between HQ-run instances, but we then need to allow users and organisations to set up their own MoodleNet instances
* '''Moodle plugin''' - users should be able to send MoodleNet collections to their Moodle Core installation, and resources from Moodle Core to MoodleNet

The last of these is not well-scoped yet, for a variety of reasons. However, we're aiming for the Moodle plugin to be integrated into Moodle Core 3.7 in May 2019. The major blocker is a decision to be made about how to deal with uploaded resources. Previous proposals around Moodle Core installations hosting files have been rejected, as this was based on initial testing with MoodleCloud.

=== Where? ===
''Where will users go to test MoodleNet and give their feedback?''

There will be two HQ-run MoodleNet instances that beta testers can sign up to. We are planning for feedback to be captured in several ways:

* '''In-situ''' - when testers perform an action such as create a community, add a resource, or make a comment, they will have the opportunity to give feedback on the experience (including suggestions to improve it). This is for tweaks to the existing functionality and interface.
* '''[https://changemap.co/moodle/moodlenet/ Changemap]''' - when testers have requests around new functionality, integrations, or approach, they can use this tool.
* '''[https://moodle.org/mod/forum/view.php?id=8352 Forum]''' - more public feedback and wider philosophical speculations can be posted to the existing MoodleNet forum

=== Checklist ===

''[TO COMPLETE]''

We need to ensure that the following things are complete by week beginning January 7th:

* Beta tester application form
* Privacy statement
* Contribution guidelines
*

The following needs to be complete by week beginning January 14th:

* Front-end and backend functionality for [https://gitlab.com/moodlenet/project/meta/wikis/List-of-intentions-of-MoodleNet-users-(verb-based) list of verb-based user intentions] (not including federation and Moodle Core integration)
* Decisions about which applicants to invite to beta testing
* Administration tools
*

MoodleNet/Beta testing

2018-12-06T11:29:23Z

Mayel: /* How? */

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

[[File:moodlenet-testing-approach.png|thumb|400px]]

== Timeline ==

Right now, the plan for 2019 is:

* January
** Open applications to the beta testing programme
** Create two HQ-run MoodleNet instances (English and Spanish)
** Invite 100 people to take part in the testing, based on meeting certain criteria (language, location, experience, etc.)
* February
** Receive daily/regular feedback from these 100 testers, and improve MoodleNet iteratively
** Once we're happy with progress, give 10 invites to each test user, increasing the number of people using MoodleNet to 1,000
* March
** Test federation between HQ-run instances
** Continue iteration based on feedback
** Start developing Moodle Core plugin
* April
** Test Moodle Core plugin
** Test federation with non-HQ instances
* May
** Integrate Moodle Core plugin in 3.7

----

== Approach to testing ==

=== Why? ===
''Why does MoodleNet exist?''

MoodleNet exists to better connect the existing Moodle community, and also to attract new educators. To date, the only Moodle-provided way for educators and other users to share content has been within their Moodle Core installation, backing up and importing activities, or by sharing entire courses. MoodleNet will be an upgrade to this, connecting educators via a Moodle-provided open social media platform which focuses on professional development and open content.

=== What? ===
''What is the value proposition we're testing?''

We have done some [https://docs.moodle.org/dev/MoodleNet/VPD Value Proposition Design] for different groups using MoodleNet and have decided that it will begin life as a place for educators to curate and share collections of resources. Our hypothesis is that the problem of discovery for educators cannot be solved by simply providing a more powerful search engine for the millions of resources already available. This is for at least three reasons:

* Learning is a ''social'' activity - and likewise teaching should be something that is not done entirely on one's own
* Search engines rely on ''already knowing'' what you're looking for - which is not always the case when planning a lesson, scheme of work, or course
* Individual resources exist in a wider context - including their relation to other resources, the educator's approach to learning, and where the 'classroom' is located

Initially, then, MoodleNet will be a simple web-based application allowing educators to form communities that curate collections of resources. Most of these, we imagine, will be free and openly-licensed, although MoodleNet will be resource-agnostic. Uploading resources directly to MoodleNet is out of scope for the first phase of testing, as we need to decide our approach to file hosting.

=== How? ===
''How are we going to test MoodleNet?''

In early January 2019, we'll put out a call for educators to be involved in MoodleNet testing. We can use something simple such as a Google Form for this, ensuring that there is a privacy notice that they have to agree to on the application.

We're looking for a diverse mix of educators, with our only limiting factor being their ability to speak English and/or Spanish. The kind of information we're looking to capture to make a selection includes:

* Name
* Location (country)
* Languages(s) spoken
* Current role
* Subject area(s)
* Teaching experience (years)
* Moodle experience (years)
* Resource-sharing sites currently used
* Social networks currently used
* Reason(s) for wanting to be involved in testing

We're interested in every aspect of how they decide to use MoodleNet, including:

* The communities and collections they decide to create
* What type of collections they create ''(subject-based? topic-based? other?)''
* The number and type of communities they decide to join
* How and when they use tags
* What kind of comments they add in collections
* How they respond to a 10-item limit on resource collections

=== Who? ===
''Who is going to be involved in the testing?''

The plan is to recruit 100 people to test MoodleNet. Although we need learning technologists, system administrators, and other techies to test it eventually, our initial focus should be on early-adopter educators. These will agree our [http://bit.ly/2FvqrM0 Guidelines for Contributors] and agree to give us regular feedback.

We should aim to have 50 people on the English-speaking HQ MoodleNet instance, and 50 people on the Spanish-speaking instance. On both, we need a mix of:

* Moodlers / non-Moodlers
* Experienced / inexperienced teachers
* Genders
* Experience with other social networks and OER repositories
* Educational sectors

=== When? ===
''When will the testing take place? what comes next?''

The first phase of testing MoodleNet is scheduled to begin week beginning January 21st. We need to have a testing period long enough that allows us to observe behaviours and make changes, but short enough so that it's a focused effort. Therefore, we're proposing a three-week period from Monday 21st January to Monday 11th February.

After this, we need to test at least three more things:

* '''Inviting a new cohort of users''' - we're envisaging that this will be done by giving every existing (active) user 10 invites. That theoretically takes us from 100 to 1,000 users of MoodleNet.
* '''Federation''' - first of all we can test this between HQ-run instances, but we then need to allow users and organisations to set up their own MoodleNet instances
* '''Moodle plugin''' - users should be able to send MoodleNet collections to their Moodle Core installation, and resources from Moodle Core to MoodleNet

The last of these is not well-scoped yet, for a variety of reasons. However, we're aiming for the Moodle plugin to be integrated into Moodle Core 3.7 in May 2019. The major blocker is a decision to be made about how to deal with uploaded resources. Previous proposals around Moodle Core installations hosting files have been rejected, as has basing initial testing on MoodleCloud.

=== Where? ===
''Where will users go to test MoodleNet and give their feedback?''

There will be two HQ-run MoodleNet instances that beta testers can sign up to. We are planning for feedback to be captured in several ways:

* '''In-situ''' - when testers perform an action such as create a community, add a resource, or make a comment, they will have the opportunity to give feedback on the experience (including suggestions to improve it). This is for tweaks to the existing functionality and interface.
* '''[https://changemap.co/moodle/moodlenet/ Changemap]''' - when testers have requests around new functionality, integrations, or approach, they can use this tool.
* '''[https://moodle.org/mod/forum/view.php?id=8352 Forum]''' - more public feedback and wider philosophical speculations can be posted to the existing MoodleNet forum

=== Checklist ===

''[TO COMPLETE]''

We need to ensure that the following things are complete by week beginning January 7th:

* Beta tester application form
* Privacy statement
* Contribution guidelines
*

The following needs to be complete by week beginning January 14th:

* Front-end and backend functionality for [https://gitlab.com/moodlenet/project/meta/wikis/List-of-intentions-of-MoodleNet-users-(verb-based) list of verb-based user intentions] (not including federation and Moodle Core integration)
* Decisions about which applicants to invite to beta testing
* Administration tools
*

MoodleNet/Beta testing

2018-12-06T11:26:11Z

Mayel: /* Why? */

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

[[File:moodlenet-testing-approach.png|thumb|400px]]

== Timeline ==

Right now, the plan for 2019 is:

* January
** Open applications to the beta testing programme
** Create two HQ-run MoodleNet instances (English and Spanish)
** Invite 100 people to take part in the testing, based on meeting certain criteria (language, location, experience, etc.)
* February
** Receive daily/regular feedback from these 100 testers, and improve MoodleNet iteratively
** Once we're happy with progress, give 10 invites to each test user, increasing the number of people using MoodleNet to 1,000
* March
** Test federation between HQ-run instances
** Continue iteration based on feedback
** Start developing Moodle Core plugin
* April
** Test Moodle Core plugin
** Test federation with non-HQ instances
* May
** Integrate Moodle Core plugin in 3.7

----

== Approach to testing ==

=== Why? ===
''Why does MoodleNet exist?''

MoodleNet exists to better connect the existing Moodle community, and also to attract new educators. To date, the only Moodle-provided way for educators and other users to share content has been within their Moodle Core installation, backing up and importing activities, or by sharing entire courses. MoodleNet will be an upgrade to this, connecting educators via a Moodle-provided open social media platform which focuses on professional development and open content.

=== What? ===
''What is the value proposition we're testing?''

We have done some [https://docs.moodle.org/dev/MoodleNet/VPD Value Proposition Design] for different groups using MoodleNet and have decided that it will begin life as a place for educators to curate and share collections of resources. Our hypothesis is that the problem of discovery for educators cannot be solved by simply providing a more powerful search engine for the millions of resources already available. This is for at least three reasons:

* Learning is a ''social'' activity - and likewise teaching should be something that is not done entirely on one's own
* Search engines rely on ''already knowing'' what you're looking for - which is not always the case when planning a lesson, scheme of work, or course
* Individual resources exist in a wider context - including their relation to other resources, the educator's approach to learning, and where the 'classroom' is located

Initially, then, MoodleNet will be a simple web-based application allowing educators to form communities that curate collections of resources. Most of these, we imagine, will be free and openly-licensed, although MoodleNet will be resource-agnostic. Uploading resources directly to MoodleNet is out of scope for the first phase of testing, as we need to decide our approach to file hosting.

=== How? ===
''How are we going to test MoodleNet?''

In early January 2019, we'll put out a call for educators to be involved in MoodleNet testing. We can use something simple such as a Google Form for this, ensuring that there is a privacy notice that they have to agree to on the application.

We're looking for a diverse mix of educators, with our only limiting factor being their ability to speak English and/or Spanish. The kind of information we're looking to capture to make a selection includes:

* Name
* Location (country)
* Languages(s) spoken
* Current role
* Subject area(s)
* Teaching experience (years)
* Moodle experience (years)
* Resource-sharing sites currently used
* Social networks currently used
* Reason(s) for wanting to be involved in testing

We're interested in every aspect of how they decide to use MoodleNet, including:

* The communities and collections they decide to create
* What type of collections they create ''(subject-based? topic-based? other?)''
* The number and type of communities they decide to join
* How and when they use tags
* What kind of comments they add to resources
* How they respond to a 10-item limit on resource collections

=== Who? ===
''Who is going to be involved in the testing?''

The plan is to recruit 100 people to test MoodleNet. Although we need learning technologists, system administrators, and other techies to test it eventually, our initial focus should be on early-adopter educators. These will agree our [http://bit.ly/2FvqrM0 Guidelines for Contributors] and agree to give us regular feedback.

We should aim to have 50 people on the English-speaking HQ MoodleNet instance, and 50 people on the Spanish-speaking instance. On both, we need a mix of:

* Moodlers / non-Moodlers
* Experienced / inexperienced teachers
* Genders
* Experience with other social networks and OER repositories
* Educational sectors

=== When? ===
''When will the testing take place? what comes next?''

The first phase of testing MoodleNet is scheduled to begin week beginning January 21st. We need to have a testing period long enough that allows us to observe behaviours and make changes, but short enough so that it's a focused effort. Therefore, we're proposing a three-week period from Monday 21st January to Monday 11th February.

After this, we need to test at least three more things:

* '''Inviting a new cohort of users''' - we're envisaging that this will be done by giving every existing (active) user 10 invites. That theoretically takes us from 100 to 1,000 users of MoodleNet.
* '''Federation''' - first of all we can test this between HQ-run instances, but we then need to allow users and organisations to set up their own MoodleNet instances
* '''Moodle plugin''' - users should be able to send MoodleNet collections to their Moodle Core installation, and resources from Moodle Core to MoodleNet

The last of these is not well-scoped yet, for a variety of reasons. However, we're aiming for the Moodle plugin to be integrated into Moodle Core 3.7 in May 2019. The major blocker is a decision to be made about how to deal with uploaded resources. Previous proposals around Moodle Core installations hosting files have been rejected, as has basing initial testing on MoodleCloud.

=== Where? ===
''Where will users go to test MoodleNet and give their feedback?''

There will be two HQ-run MoodleNet instances that beta testers can sign up to. We are planning for feedback to be captured in several ways:

* '''In-situ''' - when testers perform an action such as create a community, add a resource, or make a comment, they will have the opportunity to give feedback on the experience (including suggestions to improve it). This is for tweaks to the existing functionality and interface.
* '''[https://changemap.co/moodle/moodlenet/ Changemap]''' - when testers have requests around new functionality, integrations, or approach, they can use this tool.
* '''[https://moodle.org/mod/forum/view.php?id=8352 Forum]''' - more public feedback and wider philosophical speculations can be posted to the existing MoodleNet forum

=== Checklist ===

''[TO COMPLETE]''

We need to ensure that the following things are complete by week beginning January 7th:

* Beta tester application form
* Privacy statement
* Contribution guidelines
*

The following needs to be complete by week beginning January 14th:

* Front-end and backend functionality for [https://gitlab.com/moodlenet/project/meta/wikis/List-of-intentions-of-MoodleNet-users-(verb-based) list of verb-based user intentions] (not including federation and Moodle Core integration)
* Decisions about which applicants to invite to beta testing
* Administration tools
*

MoodleNet/tech

2018-11-05T16:03:56Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

An area to document the tech decisions we've made, and our approaches (mostly work in progress) to current or future problems.

[[File:MoodleNet-technical-diagram.png|thumb|link=https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL]]

* [https://docs.moodle.org/dev/MoodleNet/tech/architecture Technical architecture] - how is the platform going to be set up?
* [https://docs.moodle.org/dev/MoodleNet/tech/stack Tech stack] - why did we choose Elixir?
* [https://docs.moodle.org/dev/MoodleNet/tech/Moodle_integration MoodleNet integrations with Moodle]
* How to have a [https://gitlab.com/moodlenet/contacts-import "find my friends" feature without compromising privacy]
* [https://gitlab.com/moodlenet/project/meta/wikis/activitypub-and-activitystreams ActivityStreams-based metadata schemas]
* [https://gitlab.com/moodlenet/project/meta/wikis/databases-and-models Database schema] for the federated server
* [https://gitlab.com/moodlenet/project/meta/wikis Various notes (messy!)]

MoodleNet/tech

2018-09-06T09:30:08Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

An area to document the tech decisions we've made, and our approaches (mostly work in progress) to current or future problems.

[[File:MoodleNet-technical-diagram.png|thumb|link=https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL]]

* [https://docs.moodle.org/dev/MoodleNet/tech/architecture Technical architecture] - how is the platform going to be set up?
* [https://docs.moodle.org/dev/MoodleNet/tech/stack Tech stack] - why did we choose Elixir?
* [https://docs.moodle.org/dev/MoodleNet/tech/Moodle_integration MoodleNet integrations with Moodle]
* How to have a [https://gitlab.com/moodlenet/contacts-import "find my friends" feature without compromising privacy]
* [https://gitlab.com/moodlenet/architecture/issues/1#note_94925974 Database schema] for the federated server
* [https://gitlab.com/moodlenet/architecture/issues/1#note_95144351 ActivityStreams-based metadata schemas]
* [https://gitlab.com/moodlenet/meta/wikis/home Various notes (messy!)]

MoodleNet/tech

2018-09-06T09:28:46Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

An area to document the tech choices and decisions we've made.

[[File:MoodleNet-technical-diagram.png|thumb|link=https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL]]

* [https://docs.moodle.org/dev/MoodleNet/tech/architecture Technical architecture] - how is the platform going to be set up?
* [https://docs.moodle.org/dev/MoodleNet/tech/stack Tech stack] - why did we choose Elixir?
* [https://docs.moodle.org/dev/MoodleNet/tech/Moodle_integration MoodleNet integrations with Moodle]
* How to have a [https://gitlab.com/moodlenet/contacts-import "find my friends" feature without compromising privacy]
* [https://gitlab.com/moodlenet/architecture/issues/1#note_94925974 Database schema] for the federated server
* [https://gitlab.com/moodlenet/architecture/issues/1#note_95144351 ActivityStreams-based metadata schemas]
* [https://gitlab.com/moodlenet/meta/wikis/home Various notes (messy!)]

MoodleNet/tech

2018-09-06T09:27:03Z

Mayel:

MoodleNet/tech

2018-09-06T09:26:52Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

An area to document the tech choices and decisions we've made.

[[File:MoodleNet-technical-diagram.png|thumb|link=https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL]]

* [https://docs.moodle.org/dev/MoodleNet/tech/architecture Technical architecture] - how is the platform going to be set up?
* [https://docs.moodle.org/dev/MoodleNet/tech/stack Tech stack] - why did we choose Elixir?
* [https://docs.moodle.org/dev/MoodleNet/tech/Moodle_integration MoodleNet integrations with Moodle]
* How to have a [https://gitlab.com/moodlenet/contacts-import "find my friends" feature without compromising privacy]
* [https://gitlab.com/moodlenet/architecture/issues/1#note_94925974 Database schema] for the federated server
* [https://gitlab.com/moodlenet/architecture/issues/1#note_94925974 Database schema] for the federated server
* [https://gitlab.com/moodlenet/architecture/issues/1#note_95144351 ActivityStreams-based metadata schemas]

MoodleNet/tech

2018-09-06T09:24:24Z

Mayel:

MoodleNet/tech/architecture

2018-09-06T09:20:06Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet Tech index]

''Note: terms in bold are defined in the glossary at the end of the document.
''
----

There are broadly three approaches we can take to building out MoodleNet’s platform architecture. These are:

# Fully peer-to-peer
# Fully federated
# Federated with HQ API-as-a-service
# Centralised SaaS

This page explains why we have chosen to focus on the federated with HQ API-as-a-service option. A document outlining three of the potential architectural approaches is also available at http://bit.ly/2yjF8y6. We believe that creating MoodleNet with a federated architecture combined with a HQ API-as-a-service will balance an open approach with a sustainable way of managing the project.

Irrespective of architectural decision, we plan for MoodleNet to be consistent with Moodle’s philosophy of libre software. Moodle Core is licensed under the GNU General Public License (GNU GPL), which is compatible with the GNU Affero General Public License (GNU AGPL) that we intend to use for MoodleNet. The latter is recommended for software being run over a network. Like Moodle Core, MoodleNet is an open source platform, meaning that anyone can adapt, extend or modify the software for both commercial and non-commercial projects without any licensing fees.

----

== Federated with HQ API service ==
Moodle HQ will run a MoodleNet HQ '''API-as-a-service''' serving as a central index of information across the network. This enables consistent discovery and search experiences across all MoodleNet '''instances''' (including the one provided by Moodle HQ).

Each '''MoodleNet instance''' stores the full data of local users, communities, and collections (including personal information, private messages, and public comments/discussions).

The database of the MoodleNet HQ API service contains lists of all public communities, collections, resources, and users across the network, along with a copy of some metadata. A search index also sits behind the API to enable fast and accurate search results. Each item always refers back to the originating MoodleNet instance for the full data (e.g. membership, permissions, comments/discussions).

In practice, this means that the MoodleNet network, while '''federated''', is reliant upon the MoodleNet HQ API service for search and discovery. This provides users with a better and more consistent experience, reducing fragmentation and spreading the shared content more widely, and also gives Moodle HQ more control over the overall network.

Another HQ API service, the Moodle resources repository, could also provides hosting for Moodle course content that users share on MoodleNet. This could later be facilitated with P2P file sharing protocols like '''IPFS'''.

This network can also be based on existing '''protocols''' and '''standards''' to form a '''decentralised''' collection of nodes that send, receive, and store data. The data handling module can be based on an extended ActivityStreams data format and at least some of the APIs on the ActivityPub protocol to ensure compatibility between systems.

[[File:MoodleNet-technical-diagram.png|thumb|link=https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL]]

Interactive diagram: https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL

Advantages of a federated network:
* Robust and resilient
* Scales horizontally
* Private data stays on each user’s home instance
* Each instance is responsible for its content (moderation of discussions, etc)
* Standards-based but also extensible
* Open

Advantages of HQ API service:
* Some Moodle HQ influence over the network
* Consistent network-wide search and discovery experiences
* No duplication of resources for core functions like the indexing of resources from OER APIs, global search indexing, and Moodle resource hosting
* Each instance is still responsible for its content (moderation of discussions, etc)
* Moodle HQ controls the evolution/standardisation of content/metadata types and formats

Disadvantages of HQ API service:
* Single point of failure (HQ API service operated by Moodle HQ).
* Moodle HQ may be responsible for the content that shows up in search / discovery
* Some infrastructure costs for Moodle HQ
* Slightly higher number of components

----

== Glossary ==

ActivityPub - a standard decentralised social networking protocol based on ActivityStreams.

ActivityStreams - a standard format for syndicating social activities.

API - Application Programming Interface. A set of definitions, protocols, and tools for building application software, to enable communication between various components.

API-as-a-service - Software as a Service (SaaS) primarily exposed as an API.

Canonical - the main or reference location for something (eg. canonical URL)

Data handling module - a database abstraction library, using an ORM approach, which would have added support for caching and federation (when applicable).

Decentralisation - the process by which the activities of a network are distributed or delegated away from a central, authoritative location or group.

Federation - the ability for decentralised systems to send data to one another in a standardised way, to prevent fragmentation of the network. Email is a great example of a federated system.

GNU AGPL - a free, copyleft license published by the Free Software Foundation, and based on version 3 of the GNU General Public License (GPL) and the Affero General Public License. This license is compatible with the GPL and is recommended for any software that will commonly be run over a network.

GNU GPL - a widely used free software license guaranteeing end users the freedom to run, study, share and modify the libre software.

Instance - See also node. Can refer to an independently-hosted version of a software package.

IPFS - the InterPlanetary File System is a new hypermedia distribution protocol, addressed by content and identities. IPFS enables the creation of completely distributed applications. It aims to make the web faster, safer, and more open.

Libre software - software that is distributed under terms that allow users to run the software for any purpose as well as to study, change, and distribute it (and any adapted versions).

Metadata - data that provides information about other data. For educational resources, it could describe various aspects of the material, including grade level, subject area, and content type or format.

MoodleNet instance - an independently-hosted version of MoodleNet.

Moodle instance - an independently-hosted version of Moodle Core.

Node - a member of a decentralised network, which can sometimes serve as client, sometimes as server. See also instance.

Open Source - a decentralized software-development model that encourages open collaboration, with products such as source code, blueprints, and documentation freely available to the public.

ORM - Object-relational mapping, used to create a ‘virtual object database’ which can then be referenced programmatically (with less code and more flexibility as to the underlying data storage).

Protocol - a defined set of rules and formats that determine how data is transmitted.

SaaS - Software as a Service. Web-based software that’s centrally hosted and made available to use (free or by subscription).

Scaling horizontally - implies adding more nodes to a system to support its growth, for example installing copies of the same software on three web servers instead of just one.

Scaling vertically - implies adding resources (like CPUs or memory) to a single server in a system to support its growth.

Search index - a component of search engines which collects, parses, and stores data to facilitate fast and accurate search and information retrieval. Index design incorporates interdisciplinary concepts from linguistics, cognitive psychology, mathematics, informatics, and computer science.

Standard - a collection of agreed specifications, usually organised by a standards body such as the W3C.

MoodleNet/tech/architecture

2018-09-06T09:17:45Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet Tech index]

''Note: terms in bold are defined in the glossary at the end of the document.
''
----

There are broadly three approaches we can take to building out MoodleNet’s platform architecture. These are:

# Fully peer-to-peer
# Fully federated
# Federated with HQ API-as-a-service [Note: this is the architecture approach that was selected]
# Centralised SaaS

This document outlines three of the potential architectural approaches, and explains why we have chosen to focus on the second option. We believe that creating MoodleNet with a federated architecture combined with a HQ API-as-a-service will balance an open approach with a sustainable way of managing the project.

Irrespective of architectural decision, we plan for MoodleNet to be consistent with Moodle’s philosophy of libre software. Moodle Core is licensed under the GNU General Public License (GNU GPL), which is compatible with the GNU Affero General Public License (GNU AGPL) that we intend to use for MoodleNet. The latter is recommended for software being run over a network. Like Moodle Core, MoodleNet is an open source platform, meaning that anyone can adapt, extend or modify the software for both commercial and non-commercial projects without any licensing fees.

----

== Federated with HQ API service ==
Moodle HQ will run a MoodleNet HQ '''API-as-a-service''' serving as a central index of information across the network. This enables consistent discovery and search experiences across all MoodleNet '''instances''' (including the one provided by Moodle HQ).

Each '''MoodleNet instance''' stores the full data of local users, communities, and collections (including personal information, private messages, and public comments/discussions).

The database of the MoodleNet HQ API service contains lists of all public communities, collections, resources, and users across the network, along with a copy of some metadata. A search index also sits behind the API to enable fast and accurate search results. Each item always refers back to the originating MoodleNet instance for the full data (e.g. membership, permissions, comments/discussions).

In practice, this means that the MoodleNet network, while '''federated''', is reliant upon the MoodleNet HQ API service for search and discovery. This provides users with a better and more consistent experience, reducing fragmentation and spreading the shared content more widely, and also gives Moodle HQ more control over the overall network.

Another HQ API service, the Moodle resources repository, could also provides hosting for Moodle course content that users share on MoodleNet. This could later be facilitated with P2P file sharing protocols like '''IPFS'''.

This network can also be based on existing '''protocols''' and '''standards''' to form a '''decentralised''' collection of nodes that send, receive, and store data. The data handling module can be based on an extended ActivityStreams data format and at least some of the APIs on the ActivityPub protocol to ensure compatibility between systems.

[[File:MoodleNet-technical-diagram.png|thumb|link=https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL]]

Interactive diagram: https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL

Advantages of a federated network:
* Robust and resilient
* Scales horizontally
* Private data stays on each user’s home instance
* Each instance is responsible for its content (moderation of discussions, etc)
* Standards-based but also extensible
* Open

Advantages of HQ API service:
* Some Moodle HQ influence over the network
* Consistent network-wide search and discovery experiences
* No duplication of resources for core functions like the indexing of resources from OER APIs, global search indexing, and Moodle resource hosting
* Each instance is still responsible for its content (moderation of discussions, etc)
* Moodle HQ controls the evolution/standardisation of content/metadata types and formats

Disadvantages of HQ API service:
* Single point of failure (HQ API service operated by Moodle HQ).
* Moodle HQ may be responsible for the content that shows up in search / discovery
* Some infrastructure costs for Moodle HQ
* Slightly higher number of components

----

== Glossary ==

ActivityPub - a standard decentralised social networking protocol based on ActivityStreams.

ActivityStreams - a standard format for syndicating social activities.

API - Application Programming Interface. A set of definitions, protocols, and tools for building application software, to enable communication between various components.

API-as-a-service - Software as a Service (SaaS) primarily exposed as an API.

Canonical - the main or reference location for something (eg. canonical URL)

Data handling module - a database abstraction library, using an ORM approach, which would have added support for caching and federation (when applicable).

Decentralisation - the process by which the activities of a network are distributed or delegated away from a central, authoritative location or group.

Federation - the ability for decentralised systems to send data to one another in a standardised way, to prevent fragmentation of the network. Email is a great example of a federated system.

GNU AGPL - a free, copyleft license published by the Free Software Foundation, and based on version 3 of the GNU General Public License (GPL) and the Affero General Public License. This license is compatible with the GPL and is recommended for any software that will commonly be run over a network.

GNU GPL - a widely used free software license guaranteeing end users the freedom to run, study, share and modify the libre software.

Instance - See also node. Can refer to an independently-hosted version of a software package.

IPFS - the InterPlanetary File System is a new hypermedia distribution protocol, addressed by content and identities. IPFS enables the creation of completely distributed applications. It aims to make the web faster, safer, and more open.

Libre software - software that is distributed under terms that allow users to run the software for any purpose as well as to study, change, and distribute it (and any adapted versions).

Metadata - data that provides information about other data. For educational resources, it could describe various aspects of the material, including grade level, subject area, and content type or format.

MoodleNet instance - an independently-hosted version of MoodleNet.

Moodle instance - an independently-hosted version of Moodle Core.

Node - a member of a decentralised network, which can sometimes serve as client, sometimes as server. See also instance.

Open Source - a decentralized software-development model that encourages open collaboration, with products such as source code, blueprints, and documentation freely available to the public.

ORM - Object-relational mapping, used to create a ‘virtual object database’ which can then be referenced programmatically (with less code and more flexibility as to the underlying data storage).

Protocol - a defined set of rules and formats that determine how data is transmitted.

SaaS - Software as a Service. Web-based software that’s centrally hosted and made available to use (free or by subscription).

Scaling horizontally - implies adding more nodes to a system to support its growth, for example installing copies of the same software on three web servers instead of just one.

Scaling vertically - implies adding resources (like CPUs or memory) to a single server in a system to support its growth.

Search index - a component of search engines which collects, parses, and stores data to facilitate fast and accurate search and information retrieval. Index design incorporates interdisciplinary concepts from linguistics, cognitive psychology, mathematics, informatics, and computer science.

Standard - a collection of agreed specifications, usually organised by a standards body such as the W3C.

MoodleNet/tech/Moodle integration

2018-09-06T09:16:06Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet tech index]

= MoodleNet integration with Moodle core =

Note: This document is available with extra screenshots at: [https://www.google.com/url?q=http://bit.ly/2mBAZgq&sa=D&ust=1536228177969000 http://bit.ly/2mBAZgq] 

== What we're trying to achieve ==

Users need to be able to easily: 

# Share content from their Moodle (entire courses or specific activities) to MoodleNet
# Search and import any type of MoodleNet resources from within their Moodle
# Import any type of resources[[#cmnt1|[a]]][[#cmnt2|[b]]] they come across when browsing MoodleNet into their Moodle



It would be nice if users could:

# Preview Moodle-specific resources on MoodleNet, without/before having to import them into their Moodle
# Sign into MoodleNet with their existing Moodle account
# Sign into their Moodle with their MoodleNet account

=== Where in Moodle could MoodleNet be integrated? ===

* Login / Registration (sign in to your Moodle with your MoodleNet account, and vice versa)
* Global search
* Create new course
* Add an activity or resource
* Rich text editors -> Insert media -> Browse repositories
* Share course
* Share activity

== Options for previewing Moodle-specific content[[#cmnt3|[c]]] ==

The most challenging functionality to implement is allowing users to preview Moodle-specific content (resources/activities) from MoodleNet before importing content into their Moodle course 



Because of all the different types of data possible, it seems obvious that we should leverage Moodle Core for this, with dedicated plugin(s). Here are options we’ve identified:

# Temporary course on user’s Moodle site - Add a "preview" UX flow to Moodle's import functionality, so that when a user clicks “preview” the content is seamlessly (1 step only) imported as a new course into their Moodle site, so the user can browse the content and if they’re satisfied they can then actually “import” (copy) the sections/activities they want into their existing course, or "delete the preview".

* Pro: Mostly involves tweaking some Moodle UX and plugins.
* Con: Users (or admins) might not feel comfortable importing random content from the web into their production Moodle instance.
* Con: Slower, more friction.

 Option 1 is most likely what we’re implementing for the MoodleNet MVP.

<ol start="2">
<li>Moodle HQ-run preview site - Auto-import the content to one big dedicated preview site (powered by Moodle).</li></ol>

* Pro: The content could be imported in the background as soon as it’s shared, and always be instantly accessible for previewing.
* Con: Educators would have read-only access.
* Con: The preview site would get massive and probably slow over time (solution could be to split the content between several sites).
* Con: Requires adding an automatic mode (controllable by command line) to the import plugin.

<ol start="3">
<li>Temporary Moodle site at subdomain of moodle.net - Auto-import the content on a temporary Moodle site (similar to [https://www.google.com/url?q=https://demo.moodle.net&sa=D&ust=1536228177979000 https://demo.moodle.net]) which gets deleted after X hours/days.</li></ol>

* Pro: Educators can get read-write access.
* Pro: There’s already a system in place to do this.
* Con: Slower, more friction.
* Con: Requires adding an automatic mode (controllable by command line) to the import plugin.

<ol start="4">
<li>Import to user’s MoodleCloud site[[#cmnt4|[d]]] - Import the content to the user's personal MoodleCloud site (or a separate personal test site?)</li></ol>

* Pro: User is in full control.
* Pro: Could make this a premium feature.
* Con: Requires the user to sign up for a MoodleCould site (solution could be to add an opt-in option that automatically does that when they join MoodleNet).
* Con: Slower, more friction.

== Options for importing content from around the web ==

TBD depending on the type content and where it’s coming from. Some examples:

* YouTube or Vimeo video: embedded in Page module
* Video file: linked (URL module) from original source?
* PDF: linked (URL module) from original source, or copied (File module)?
* Word document: linked (URL module) from original source, or copied (File module), or converted to HTML (Page module)?
* etc...

== Where the current Moodle.net is integrated with Moodle ==

=== Context ===

The existing Moodle.net allows users to share Moodle courses with the community. These courses are shared and, after moderation, appear via a searchable interface at [https://www.google.com/url?q=https://moodle.net&sa=D&ust=1536228177983000 https://moodle.net] and in Moodle Core’s ‘Community Finder’ functionality.

=== 1. Moodle.net registration ===

To submit a course to Moodle.net, the user’s Moodle site must be registered. An admin of the Moodle instance first needs to fill in Moodle.net registration form, which is main source of [https://www.google.com/url?q=https://moodle.net/stats/&sa=D&ust=1536228177983000 Moodle usage stats]. Users are blocked from sharing content to Moodle.net before this is done (but they can search & import content). Note that sites that are not publicly-accessible on the internet, or using a non-standard port are [https://www.google.com/url?q=https://docs.moodle.org/35/en/error/local_hub/cannotregisterbadport&sa=D&ust=1536228177984000 not able to register].

Admins are told that by registering:

* You'll be one of the first to find out about important notifications such as security alerts and new Moodle releases.
* You can access and activate mobile push notifications from your Moodle site through our free Moodle Mobile app.
* You are contributing to our Moodle statistics of the worldwide community, which help us improve Moodle and our community sites.
* If you wish, your site can be included in the list of registered Moodle sites in your country. [Unlisted / Name only / Name + URL]

Required fields: 

* Country
* Admin email address



Optional fields:

* Name
* Site listing in directory?
* Description
* Language
* Notifications about important security and technical issues?
* Updates about Moodle news and features?



The following information will be sent to contribute to overall statistics only. It will not be made public on any site listing.

* Moodle release (3.5)
* Number of courses (3)
* Number of users (3)
* Number of role assignments (3)
* Number of posts (0)
* Number of questions (0)
* Number of resources (0)
* Number of badges (0)
* Number of issued badges (0)
* Average number of participants (1.00)
* Average number of course modules (5.00)
* Mobile services enabled (Yes)
* Mobile notifications enabled (No)
* Number of users with registered mobile devices (1)
* Number of active users with registered mobile devices which are receiving notifications (0)

==== Next steps regarding registration ====

* Check structure of API and code that handles registration between Moodle & Moodle.net (both sides)
* Check if we can override this functionality with a plugin (for backward compatibility with old Moodle versions)
* Decide what changes (if any) need to be made to the data collected
* Decide if registration could be done by any teacher-level account instead of just admins (i.e. registering with the MoodleNet core API service, to collect stats & enable MoodleNet search)
* Add new sign-in functionality ([https://www.google.com/url?q=https://docs.moodle.org/35/en/OAuth_2_services&sa=D&ust=1536228177989000 OAuth] client) for users to connect their Moodle account to their MoodleNet account (i.e. authenticating with their MoodleNet instance's API, to enable personalised MoodleNet search, and sharing & importing of resources). An OAuth client is available as a core part of Moodle.
* Potentially [https://www.google.com/url?q=https://github.com/projectestac/moodle-local_oauth&sa=D&ust=1536228177989000 turn Moodle into an OAuth server] so that users can sign into MoodleNet with their existing Moodle accounts (especially useful for on-boarding, to avoid having to re-enter personal details). This would mean adding a plugin. 

=== 2. Search & import courses ===

The 'Community Finder' function allows searching for resources on Moodle.net and is currently available as a 'block' that needs to be added manually (not ideal).[[#cmnt5|[e]]][[#cmnt6|[f]]]

It can be used with simple keyword search, or with advanced filtering.

‘Visit Demo' function for resources currently is just an optional link to a public course that needs to be hosted somewhere (submitted as part of 'sharing', not ideal).

‘Install’ function has 8 steps/screens.

==== Next steps regarding search & import ====

* Create new Moodle plugin(s) to handle search of MoodleNet content, in these places:

* Global search
* Create course
* Add an activity or resource
* Rich text editors -> Insert media -> Browse repositories

* Unless MoodleNet provides ‘preview’ functionality for Moodle content[[#cmnt7|[g]]][[#cmnt8|[h]]][[#cmnt9|[i]]], decide if instead of the user selecting which sections/resources to import before seeing them, they all get imported into a new course so the user can afterwards delete those they don’t need (or copy/move only those they need into an existing course).
* In any case, create new import plugin with simplified UX (1 or 2 steps max) and make it explicitly about ‘importing’ rather than ‘restoring’.
* If the import plugin doesn’t already, make it check upfront for compatibility with the Moodle version and list of plugins, and if necessary tell the user what they need to ask their admin before they can import that content. (Only admins can install plugins, and MoodleCloud doesn't allow extra plugins, but fortunately only a minority of content seems to depend on 3rd party activity plugins).

=== 3. Share ===

Step 1 is for choosing if you want to export or just open up your course to the public.

Step 2 is pre-filled with metadata from the course and includes list of subjects from Australian standard (used to be hierarchical, only allows selecting on subject), and some other fields which contain the same options as seen in the search filters above.

Step 3 has the following toggles:

* Anonymize user information
* Include user role assignments
* Include activities and resources
* Include blocks
* Include filters
* Include comments
* Include badges
* Include calendar events
* Include user completion details
* Include course logs
* Include grade history
* Include question bank
* Include groups and groupings
* Include competencies



Step 4 allows selecting/deselecting which activities to share (this should be moved to before step 2).



Step 5 is a review of previous options (backup options, not incl. course metadata weirdly). The main button here says ‘Perform backup’ rather than ‘Share to MoodleNet’.[[#cmnt10|[j]]]



Step 6 contents are packaged as an mbz file and uploaded to moodle.net

The mbz is a zip with xml files and other content (including subfolders for plugin content). The format doesn't seem to be documented but should contain all the info we need (eg. what Moodle version it came from, and the list of required plugins).



Step 7 - the upload then goes in moderation queue (Mary) before being published.



After sharing, there’s a status screen available

==== Next steps regarding sharing ====

* Add sharing function at section & activity level (currently only available at course level).
* Simplify UX (1 or 2 steps max) and make it explicitly about ‘sharing’ rather than ‘backup’.
* Possibly move all metadata input to a screen on MoodleNet (where it can also be edited later) rather than it being part of Moodle.
* Review all metadata fields.
* ‘Publisher’ will be the MoodleNet user who is doing the sharing.
* ‘Creator’ could be prefilled with the MoodleNet accounts of the Moodle users who created the course (or activities therein), if known.
* Decide on list of licensing options, and what should be the default.



== References ==

=== Relevant Documentation ===

* General docs: [https://www.google.com/url?q=https://docs.moodle.org/dev/Main_Page&sa=D&ust=1536228178000000 https://docs.moodle.org/dev/Main_Page] 
* Plugin diff. types: [https://www.google.com/url?q=https://docs.moodle.org/dev/Plugin_types&sa=D&ust=1536228178001000 https://docs.moodle.org/dev/Plugin_types]
* Existing plugins: [https://www.google.com/url?q=https://moodle.org/plugins/&sa=D&ust=1536228178001000 https://moodle.org/plugins/]
* Tutorial: [https://www.google.com/url?q=https://docs.moodle.org/dev/Tutorial&sa=D&ust=1536228178002000 https://docs.moodle.org/dev/Tutorial]
* API: [https://www.google.com/url?q=https://docs.moodle.org/dev/Web_services&sa=D&ust=1536228178002000 https://docs.moodle.org/dev/Web_services]
* This tool might be useful for command-line ops: [https://www.google.com/url?q=http://moosh-online.com&sa=D&ust=1536228178003000 http://moosh-online.com]

=== Relevant Moodle plugin types ===

Other than modifying Moodle Core (which would make our integration not be backwards compatible with older Moodle versions), this is the plugin architecture that is available for us to plug into Moodle:

* Simple HTML/PHP block: [https://www.google.com/url?q=https://docs.moodle.org/dev/Blocks&sa=D&ust=1536228178003000 https://docs.moodle.org/dev/Blocks]
* Repository (allow Moodle to bring contents in from external repositories): [https://www.google.com/url?q=https://docs.moodle.org/dev/Repository_plugins&sa=D&ust=1536228178004000 https://docs.moodle.org/dev/Repository_plugins]
* Portfolio (allow to publish files to all kinds of external document repository systems) [https://www.google.com/url?q=https://docs.moodle.org/dev/Portfolio_plugins&sa=D&ust=1536228178004000 https://docs.moodle.org/dev/Portfolio_plugins]
* Global search: [https://www.google.com/url?q=https://docs.moodle.org/dev/Search_engines&sa=D&ust=1536228178005000 https://docs.moodle.org/dev/Search_engines]
* Authentication / OAuth: [https://www.google.com/url?q=https://docs.moodle.org/dev/Authentication_plugins&sa=D&ust=1536228178005000 https://docs.moodle.org/dev/Authentication_plugins][https://www.google.com/url?q=https://docs.moodle.org/35/en/OAuth_2_authentication&sa=D&ust=1536228178006000 https://docs.moodle.org/35/en/OAuth_2_authentication]
* External tool source / LTI [https://www.google.com/url?q=https://docs.moodle.org/dev/External_tool_source&sa=D&ust=1536228178006000 https://docs.moodle.org/dev/External_tool_source][https://www.google.com/url?q=https://en.wikipedia.org/wiki/Learning_Tools_Interoperability&sa=D&ust=1536228178006000 https://en.wikipedia.org/wiki/Learning_Tools_Interoperability]
* Adding protocols to the API: [https://www.google.com/url?q=https://docs.moodle.org/dev/Webservice_protocols&sa=D&ust=1536228178007000 https://docs.moodle.org/dev/Webservice_protocols]

MoodleNet/tech

2018-09-06T09:15:46Z

Mayel:

MoodleNet/tech/Moodle integration

2018-09-06T09:14:37Z

Mayel: /* Options for previewing Moodle-specific content[c] */

= MoodleNet integration with Moodle core =

Note: This document is available with extra screenshots at: [https://www.google.com/url?q=http://bit.ly/2mBAZgq&sa=D&ust=1536228177969000 http://bit.ly/2mBAZgq] 

== What we're trying to achieve ==

Users need to be able to easily: 

# Share content from their Moodle (entire courses or specific activities) to MoodleNet
# Search and import any type of MoodleNet resources from within their Moodle
# Import any type of resources[[#cmnt1|[a]]][[#cmnt2|[b]]] they come across when browsing MoodleNet into their Moodle



It would be nice if users could:

# Preview Moodle-specific resources on MoodleNet, without/before having to import them into their Moodle
# Sign into MoodleNet with their existing Moodle account
# Sign into their Moodle with their MoodleNet account

=== Where in Moodle could MoodleNet be integrated? ===

* Login / Registration (sign in to your Moodle with your MoodleNet account, and vice versa)
* Global search
* Create new course
* Add an activity or resource
* Rich text editors -> Insert media -> Browse repositories
* Share course
* Share activity

== Options for previewing Moodle-specific content[[#cmnt3|[c]]] ==

The most challenging functionality to implement is allowing users to preview Moodle-specific content (resources/activities) from MoodleNet before importing content into their Moodle course 



Because of all the different types of data possible, it seems obvious that we should leverage Moodle Core for this, with dedicated plugin(s). Here are options we’ve identified:

# Temporary course on user’s Moodle site - Add a "preview" UX flow to Moodle's import functionality, so that when a user clicks “preview” the content is seamlessly (1 step only) imported as a new course into their Moodle site, so the user can browse the content and if they’re satisfied they can then actually “import” (copy) the sections/activities they want into their existing course, or "delete the preview".

* Pro: Mostly involves tweaking some Moodle UX and plugins.
* Con: Users (or admins) might not feel comfortable importing random content from the web into their production Moodle instance.
* Con: Slower, more friction.

 Option 1 is most likely what we’re implementing for the MoodleNet MVP.

<ol start="2">
<li>Moodle HQ-run preview site - Auto-import the content to one big dedicated preview site (powered by Moodle).</li></ol>

* Pro: The content could be imported in the background as soon as it’s shared, and always be instantly accessible for previewing.
* Con: Educators would have read-only access.
* Con: The preview site would get massive and probably slow over time (solution could be to split the content between several sites).
* Con: Requires adding an automatic mode (controllable by command line) to the import plugin.

<ol start="3">
<li>Temporary Moodle site at subdomain of moodle.net - Auto-import the content on a temporary Moodle site (similar to [https://www.google.com/url?q=https://demo.moodle.net&sa=D&ust=1536228177979000 https://demo.moodle.net]) which gets deleted after X hours/days.</li></ol>

* Pro: Educators can get read-write access.
* Pro: There’s already a system in place to do this.
* Con: Slower, more friction.
* Con: Requires adding an automatic mode (controllable by command line) to the import plugin.

<ol start="4">
<li>Import to user’s MoodleCloud site[[#cmnt4|[d]]] - Import the content to the user's personal MoodleCloud site (or a separate personal test site?)</li></ol>

* Pro: User is in full control.
* Pro: Could make this a premium feature.
* Con: Requires the user to sign up for a MoodleCould site (solution could be to add an opt-in option that automatically does that when they join MoodleNet).
* Con: Slower, more friction.

== Options for importing content from around the web ==

TBD depending on the type content and where it’s coming from. Some examples:

* YouTube or Vimeo video: embedded in Page module
* Video file: linked (URL module) from original source?
* PDF: linked (URL module) from original source, or copied (File module)?
* Word document: linked (URL module) from original source, or copied (File module), or converted to HTML (Page module)?
* etc...

== Where the current Moodle.net is integrated with Moodle ==

=== Context ===

The existing Moodle.net allows users to share Moodle courses with the community. These courses are shared and, after moderation, appear via a searchable interface at [https://www.google.com/url?q=https://moodle.net&sa=D&ust=1536228177983000 https://moodle.net] and in Moodle Core’s ‘Community Finder’ functionality.

=== 1. Moodle.net registration ===

To submit a course to Moodle.net, the user’s Moodle site must be registered. An admin of the Moodle instance first needs to fill in Moodle.net registration form, which is main source of [https://www.google.com/url?q=https://moodle.net/stats/&sa=D&ust=1536228177983000 Moodle usage stats]. Users are blocked from sharing content to Moodle.net before this is done (but they can search & import content). Note that sites that are not publicly-accessible on the internet, or using a non-standard port are [https://www.google.com/url?q=https://docs.moodle.org/35/en/error/local_hub/cannotregisterbadport&sa=D&ust=1536228177984000 not able to register].

Admins are told that by registering:

* You'll be one of the first to find out about important notifications such as security alerts and new Moodle releases.
* You can access and activate mobile push notifications from your Moodle site through our free Moodle Mobile app.
* You are contributing to our Moodle statistics of the worldwide community, which help us improve Moodle and our community sites.
* If you wish, your site can be included in the list of registered Moodle sites in your country. [Unlisted / Name only / Name + URL]

Required fields: 

* Country
* Admin email address



Optional fields:

* Name
* Site listing in directory?
* Description
* Language
* Notifications about important security and technical issues?
* Updates about Moodle news and features?



The following information will be sent to contribute to overall statistics only. It will not be made public on any site listing.

* Moodle release (3.5)
* Number of courses (3)
* Number of users (3)
* Number of role assignments (3)
* Number of posts (0)
* Number of questions (0)
* Number of resources (0)
* Number of badges (0)
* Number of issued badges (0)
* Average number of participants (1.00)
* Average number of course modules (5.00)
* Mobile services enabled (Yes)
* Mobile notifications enabled (No)
* Number of users with registered mobile devices (1)
* Number of active users with registered mobile devices which are receiving notifications (0)

==== Next steps regarding registration ====

* Check structure of API and code that handles registration between Moodle & Moodle.net (both sides)
* Check if we can override this functionality with a plugin (for backward compatibility with old Moodle versions)
* Decide what changes (if any) need to be made to the data collected
* Decide if registration could be done by any teacher-level account instead of just admins (i.e. registering with the MoodleNet core API service, to collect stats & enable MoodleNet search)
* Add new sign-in functionality ([https://www.google.com/url?q=https://docs.moodle.org/35/en/OAuth_2_services&sa=D&ust=1536228177989000 OAuth] client) for users to connect their Moodle account to their MoodleNet account (i.e. authenticating with their MoodleNet instance's API, to enable personalised MoodleNet search, and sharing & importing of resources). An OAuth client is available as a core part of Moodle.
* Potentially [https://www.google.com/url?q=https://github.com/projectestac/moodle-local_oauth&sa=D&ust=1536228177989000 turn Moodle into an OAuth server] so that users can sign into MoodleNet with their existing Moodle accounts (especially useful for on-boarding, to avoid having to re-enter personal details). This would mean adding a plugin. 

=== 2. Search & import courses ===

The 'Community Finder' function allows searching for resources on Moodle.net and is currently available as a 'block' that needs to be added manually (not ideal).[[#cmnt5|[e]]][[#cmnt6|[f]]]

It can be used with simple keyword search, or with advanced filtering.

‘Visit Demo' function for resources currently is just an optional link to a public course that needs to be hosted somewhere (submitted as part of 'sharing', not ideal).

‘Install’ function has 8 steps/screens.

==== Next steps regarding search & import ====

* Create new Moodle plugin(s) to handle search of MoodleNet content, in these places:

* Global search
* Create course
* Add an activity or resource
* Rich text editors -> Insert media -> Browse repositories

* Unless MoodleNet provides ‘preview’ functionality for Moodle content[[#cmnt7|[g]]][[#cmnt8|[h]]][[#cmnt9|[i]]], decide if instead of the user selecting which sections/resources to import before seeing them, they all get imported into a new course so the user can afterwards delete those they don’t need (or copy/move only those they need into an existing course).
* In any case, create new import plugin with simplified UX (1 or 2 steps max) and make it explicitly about ‘importing’ rather than ‘restoring’.
* If the import plugin doesn’t already, make it check upfront for compatibility with the Moodle version and list of plugins, and if necessary tell the user what they need to ask their admin before they can import that content. (Only admins can install plugins, and MoodleCloud doesn't allow extra plugins, but fortunately only a minority of content seems to depend on 3rd party activity plugins).

=== 3. Share ===

Step 1 is for choosing if you want to export or just open up your course to the public.

Step 2 is pre-filled with metadata from the course and includes list of subjects from Australian standard (used to be hierarchical, only allows selecting on subject), and some other fields which contain the same options as seen in the search filters above.

Step 3 has the following toggles:

* Anonymize user information
* Include user role assignments
* Include activities and resources
* Include blocks
* Include filters
* Include comments
* Include badges
* Include calendar events
* Include user completion details
* Include course logs
* Include grade history
* Include question bank
* Include groups and groupings
* Include competencies



Step 4 allows selecting/deselecting which activities to share (this should be moved to before step 2).



Step 5 is a review of previous options (backup options, not incl. course metadata weirdly). The main button here says ‘Perform backup’ rather than ‘Share to MoodleNet’.[[#cmnt10|[j]]]



Step 6 contents are packaged as an mbz file and uploaded to moodle.net

The mbz is a zip with xml files and other content (including subfolders for plugin content). The format doesn't seem to be documented but should contain all the info we need (eg. what Moodle version it came from, and the list of required plugins).



Step 7 - the upload then goes in moderation queue (Mary) before being published.



After sharing, there’s a status screen available

==== Next steps regarding sharing ====

* Add sharing function at section & activity level (currently only available at course level).
* Simplify UX (1 or 2 steps max) and make it explicitly about ‘sharing’ rather than ‘backup’.
* Possibly move all metadata input to a screen on MoodleNet (where it can also be edited later) rather than it being part of Moodle.
* Review all metadata fields.
* ‘Publisher’ will be the MoodleNet user who is doing the sharing.
* ‘Creator’ could be prefilled with the MoodleNet accounts of the Moodle users who created the course (or activities therein), if known.
* Decide on list of licensing options, and what should be the default.



== References ==

=== Relevant Documentation ===

* General docs: [https://www.google.com/url?q=https://docs.moodle.org/dev/Main_Page&sa=D&ust=1536228178000000 https://docs.moodle.org/dev/Main_Page] 
* Plugin diff. types: [https://www.google.com/url?q=https://docs.moodle.org/dev/Plugin_types&sa=D&ust=1536228178001000 https://docs.moodle.org/dev/Plugin_types]
* Existing plugins: [https://www.google.com/url?q=https://moodle.org/plugins/&sa=D&ust=1536228178001000 https://moodle.org/plugins/]
* Tutorial: [https://www.google.com/url?q=https://docs.moodle.org/dev/Tutorial&sa=D&ust=1536228178002000 https://docs.moodle.org/dev/Tutorial]
* API: [https://www.google.com/url?q=https://docs.moodle.org/dev/Web_services&sa=D&ust=1536228178002000 https://docs.moodle.org/dev/Web_services]
* This tool might be useful for command-line ops: [https://www.google.com/url?q=http://moosh-online.com&sa=D&ust=1536228178003000 http://moosh-online.com]

=== Relevant Moodle plugin types ===

Other than modifying Moodle Core (which would make our integration not be backwards compatible with older Moodle versions), this is the plugin architecture that is available for us to plug into Moodle:

* Simple HTML/PHP block: [https://www.google.com/url?q=https://docs.moodle.org/dev/Blocks&sa=D&ust=1536228178003000 https://docs.moodle.org/dev/Blocks]
* Repository (allow Moodle to bring contents in from external repositories): [https://www.google.com/url?q=https://docs.moodle.org/dev/Repository_plugins&sa=D&ust=1536228178004000 https://docs.moodle.org/dev/Repository_plugins]
* Portfolio (allow to publish files to all kinds of external document repository systems) [https://www.google.com/url?q=https://docs.moodle.org/dev/Portfolio_plugins&sa=D&ust=1536228178004000 https://docs.moodle.org/dev/Portfolio_plugins]
* Global search: [https://www.google.com/url?q=https://docs.moodle.org/dev/Search_engines&sa=D&ust=1536228178005000 https://docs.moodle.org/dev/Search_engines]
* Authentication / OAuth: [https://www.google.com/url?q=https://docs.moodle.org/dev/Authentication_plugins&sa=D&ust=1536228178005000 https://docs.moodle.org/dev/Authentication_plugins][https://www.google.com/url?q=https://docs.moodle.org/35/en/OAuth_2_authentication&sa=D&ust=1536228178006000 https://docs.moodle.org/35/en/OAuth_2_authentication]
* External tool source / LTI [https://www.google.com/url?q=https://docs.moodle.org/dev/External_tool_source&sa=D&ust=1536228178006000 https://docs.moodle.org/dev/External_tool_source][https://www.google.com/url?q=https://en.wikipedia.org/wiki/Learning_Tools_Interoperability&sa=D&ust=1536228178006000 https://en.wikipedia.org/wiki/Learning_Tools_Interoperability]
* Adding protocols to the API: [https://www.google.com/url?q=https://docs.moodle.org/dev/Webservice_protocols&sa=D&ust=1536228178007000 https://docs.moodle.org/dev/Webservice_protocols]

MoodleNet/tech/Moodle integration

2018-09-06T09:12:43Z

Mayel: /* MoodleNet integration with Moodle core */

MoodleNet/tech/Moodle integration

2018-09-06T09:11:53Z

Mayel: create

= MoodleNet integration with Moodle core =

Document about issue [https://www.google.com/url?q=https://tracker.moodle.org/browse/MDLNET-10&sa=D&ust=1536228177968000 MDLNET-10].

Short URL: [https://www.google.com/url?q=http://bit.ly/2mBAZgq&sa=D&ust=1536228177969000 http://bit.ly/2mBAZgq] 

== What we're trying to achieve ==

Users need to be able to easily: 

# Share content from their Moodle (entire courses or specific activities) to MoodleNet
# Search and import any type of MoodleNet resources from within their Moodle
# Import any type of resources[[#cmnt1|[a]]][[#cmnt2|[b]]] they come across when browsing MoodleNet into their Moodle



It would be nice if users could:

# Preview Moodle-specific resources on MoodleNet, without/before having to import them into their Moodle
# Sign into MoodleNet with their existing Moodle account
# Sign into their Moodle with their MoodleNet account

=== Where in Moodle could MoodleNet be integrated? ===

* Login / Registration (sign in to your Moodle with your MoodleNet account, and vice versa)
* Global search
* Create new course
* Add an activity or resource
* Rich text editors -> Insert media -> Browse repositories
* Share course
* Share activity

== Options for previewing Moodle-specific content[[#cmnt3|[c]]] ==

The most challenging functionality to implement is allowing users to preview Moodle-specific content (resources/activities) from MoodleNet before importing content into their Moodle course 



Because of all the different types of data possible, it seems obvious that we should leverage Moodle Core for this, with dedicated plugin(s). Here are options we’ve identified:

# Temporary course on user’s Moodle site - Add a "preview" UX flow to Moodle's import functionality, so that when a user clicks “preview” the content is seamlessly (1 step only) imported as a new course into their Moodle site, so the user can browse the content and if they’re satisfied they can then actually “import” (copy) the sections/activities they want into their existing course, or "delete the preview".

* Pro: Mostly involves tweaking some Moodle UX and plugins.
* Con: Users (or admins) might not feel comfortable importing random content from the web into their production Moodle instance.
* Con: Slower, more friction.

 Option 1 is most likely what we’re implementing for the MoodleNet MVP.

<ol start="2">
<li>Moodle HQ-run preview site - Auto-import the content to one big dedicated preview site (powered by Moodle).</li></ol>

* Pro: The content could be imported in the background as soon as it’s shared, and always be instantly accessible for previewing.
* Con: Educators would have read-only access.
* Con: The preview site would get massive and probably slow over time (solution could be to split the content between several sites).
* Con: Requires adding an automatic mode (controllable by command line) to the import plugin.

<ol start="3">
<li>Temporary Moodle site at subdomain of moodle.net - Auto-import the content on a temporary Moodle site (similar to [https://www.google.com/url?q=https://demo.moodle.net&sa=D&ust=1536228177979000 https://demo.moodle.net]) which gets deleted after X hours/days.</li></ol>

* Pro: Educators can get read-write access.
* Pro: There’s already a system in place to do this.
* Con: Slower, more friction.
* Con: Requires adding an automatic mode (controllable by command line) to the import plugin.

<ol start="4">
<li>Import to user’s MoodleCloud site[[#cmnt4|[d]]] - Import the content to the user's personal MoodleCloud site (or a separate personal test site?)</li></ol>

* Pro: User is in full control.
* Pro: Could make this a premium feature.
* Con: Requires the user to sign up for a MoodleCould site (solution could be to add an opt-in option that automatically does that when they join MoodleNet).
* Con: Slower, more friction.

== Options for importing content from around the web ==

TBD depending on the type content and where it’s coming from. Some examples:

* YouTube or Vimeo video: embedded in Page module
* Video file: linked (URL module) from original source?
* PDF: linked (URL module) from original source, or copied (File module)?
* Word document: linked (URL module) from original source, or copied (File module), or converted to HTML (Page module)?
* etc...

== Where the current Moodle.net is integrated with Moodle ==

=== Context ===

The existing Moodle.net allows users to share Moodle courses with the community. These courses are shared and, after moderation, appear via a searchable interface at [https://www.google.com/url?q=https://moodle.net&sa=D&ust=1536228177983000 https://moodle.net] and in Moodle Core’s ‘Community Finder’ functionality.

=== 1. Moodle.net registration ===

To submit a course to Moodle.net, the user’s Moodle site must be registered. An admin of the Moodle instance first needs to fill in Moodle.net registration form, which is main source of [https://www.google.com/url?q=https://moodle.net/stats/&sa=D&ust=1536228177983000 Moodle usage stats]. Users are blocked from sharing content to Moodle.net before this is done (but they can search & import content). Note that sites that are not publicly-accessible on the internet, or using a non-standard port are [https://www.google.com/url?q=https://docs.moodle.org/35/en/error/local_hub/cannotregisterbadport&sa=D&ust=1536228177984000 not able to register].

Admins are told that by registering:

* You'll be one of the first to find out about important notifications such as security alerts and new Moodle releases.
* You can access and activate mobile push notifications from your Moodle site through our free Moodle Mobile app.
* You are contributing to our Moodle statistics of the worldwide community, which help us improve Moodle and our community sites.
* If you wish, your site can be included in the list of registered Moodle sites in your country. [Unlisted / Name only / Name + URL]

Required fields: 

* Country
* Admin email address



Optional fields:

* Name
* Site listing in directory?
* Description
* Language
* Notifications about important security and technical issues?
* Updates about Moodle news and features?



The following information will be sent to contribute to overall statistics only. It will not be made public on any site listing.

* Moodle release (3.5)
* Number of courses (3)
* Number of users (3)
* Number of role assignments (3)
* Number of posts (0)
* Number of questions (0)
* Number of resources (0)
* Number of badges (0)
* Number of issued badges (0)
* Average number of participants (1.00)
* Average number of course modules (5.00)
* Mobile services enabled (Yes)
* Mobile notifications enabled (No)
* Number of users with registered mobile devices (1)
* Number of active users with registered mobile devices which are receiving notifications (0)

==== Next steps regarding registration ====

* Check structure of API and code that handles registration between Moodle & Moodle.net (both sides)
* Check if we can override this functionality with a plugin (for backward compatibility with old Moodle versions)
* Decide what changes (if any) need to be made to the data collected
* Decide if registration could be done by any teacher-level account instead of just admins (i.e. registering with the MoodleNet core API service, to collect stats & enable MoodleNet search)
* Add new sign-in functionality ([https://www.google.com/url?q=https://docs.moodle.org/35/en/OAuth_2_services&sa=D&ust=1536228177989000 OAuth] client) for users to connect their Moodle account to their MoodleNet account (i.e. authenticating with their MoodleNet instance's API, to enable personalised MoodleNet search, and sharing & importing of resources). An OAuth client is available as a core part of Moodle.
* Potentially [https://www.google.com/url?q=https://github.com/projectestac/moodle-local_oauth&sa=D&ust=1536228177989000 turn Moodle into an OAuth server] so that users can sign into MoodleNet with their existing Moodle accounts (especially useful for on-boarding, to avoid having to re-enter personal details). This would mean adding a plugin. 

=== 2. Search & import courses ===

The 'Community Finder' function allows searching for resources on Moodle.net and is currently available as a 'block' that needs to be added manually (not ideal).[[#cmnt5|[e]]][[#cmnt6|[f]]]

It can be used with simple keyword search, or with advanced filtering.

‘Visit Demo' function for resources currently is just an optional link to a public course that needs to be hosted somewhere (submitted as part of 'sharing', not ideal).

‘Install’ function has 8 steps/screens.

==== Next steps regarding search & import ====

* Create new Moodle plugin(s) to handle search of MoodleNet content, in these places:

* Global search
* Create course
* Add an activity or resource
* Rich text editors -> Insert media -> Browse repositories

* Unless MoodleNet provides ‘preview’ functionality for Moodle content[[#cmnt7|[g]]][[#cmnt8|[h]]][[#cmnt9|[i]]], decide if instead of the user selecting which sections/resources to import before seeing them, they all get imported into a new course so the user can afterwards delete those they don’t need (or copy/move only those they need into an existing course).
* In any case, create new import plugin with simplified UX (1 or 2 steps max) and make it explicitly about ‘importing’ rather than ‘restoring’.
* If the import plugin doesn’t already, make it check upfront for compatibility with the Moodle version and list of plugins, and if necessary tell the user what they need to ask their admin before they can import that content. (Only admins can install plugins, and MoodleCloud doesn't allow extra plugins, but fortunately only a minority of content seems to depend on 3rd party activity plugins).

=== 3. Share ===

Step 1 is for choosing if you want to export or just open up your course to the public.

Step 2 is pre-filled with metadata from the course and includes list of subjects from Australian standard (used to be hierarchical, only allows selecting on subject), and some other fields which contain the same options as seen in the search filters above.

Step 3 has the following toggles:

* Anonymize user information
* Include user role assignments
* Include activities and resources
* Include blocks
* Include filters
* Include comments
* Include badges
* Include calendar events
* Include user completion details
* Include course logs
* Include grade history
* Include question bank
* Include groups and groupings
* Include competencies



Step 4 allows selecting/deselecting which activities to share (this should be moved to before step 2).



Step 5 is a review of previous options (backup options, not incl. course metadata weirdly). The main button here says ‘Perform backup’ rather than ‘Share to MoodleNet’.[[#cmnt10|[j]]]



Step 6 contents are packaged as an mbz file and uploaded to moodle.net

The mbz is a zip with xml files and other content (including subfolders for plugin content). The format doesn't seem to be documented but should contain all the info we need (eg. what Moodle version it came from, and the list of required plugins).



Step 7 - the upload then goes in moderation queue (Mary) before being published.



After sharing, there’s a status screen available

==== Next steps regarding sharing ====

* Add sharing function at section & activity level (currently only available at course level).
* Simplify UX (1 or 2 steps max) and make it explicitly about ‘sharing’ rather than ‘backup’.
* Possibly move all metadata input to a screen on MoodleNet (where it can also be edited later) rather than it being part of Moodle.
* Review all metadata fields.
* ‘Publisher’ will be the MoodleNet user who is doing the sharing.
* ‘Creator’ could be prefilled with the MoodleNet accounts of the Moodle users who created the course (or activities therein), if known.
* Decide on list of licensing options, and what should be the default.



== References ==

=== Relevant Documentation ===

* General docs: [https://www.google.com/url?q=https://docs.moodle.org/dev/Main_Page&sa=D&ust=1536228178000000 https://docs.moodle.org/dev/Main_Page] 
* Plugin diff. types: [https://www.google.com/url?q=https://docs.moodle.org/dev/Plugin_types&sa=D&ust=1536228178001000 https://docs.moodle.org/dev/Plugin_types]
* Existing plugins: [https://www.google.com/url?q=https://moodle.org/plugins/&sa=D&ust=1536228178001000 https://moodle.org/plugins/]
* Tutorial: [https://www.google.com/url?q=https://docs.moodle.org/dev/Tutorial&sa=D&ust=1536228178002000 https://docs.moodle.org/dev/Tutorial]
* API: [https://www.google.com/url?q=https://docs.moodle.org/dev/Web_services&sa=D&ust=1536228178002000 https://docs.moodle.org/dev/Web_services]
* This tool might be useful for command-line ops: [https://www.google.com/url?q=http://moosh-online.com&sa=D&ust=1536228178003000 http://moosh-online.com]

=== Relevant Moodle plugin types ===

Other than modifying Moodle Core (which would make our integration not be backwards compatible with older Moodle versions), this is the plugin architecture that is available for us to plug into Moodle:

* Simple HTML/PHP block: [https://www.google.com/url?q=https://docs.moodle.org/dev/Blocks&sa=D&ust=1536228178003000 https://docs.moodle.org/dev/Blocks]
* Repository (allow Moodle to bring contents in from external repositories): [https://www.google.com/url?q=https://docs.moodle.org/dev/Repository_plugins&sa=D&ust=1536228178004000 https://docs.moodle.org/dev/Repository_plugins]
* Portfolio (allow to publish files to all kinds of external document repository systems) [https://www.google.com/url?q=https://docs.moodle.org/dev/Portfolio_plugins&sa=D&ust=1536228178004000 https://docs.moodle.org/dev/Portfolio_plugins]
* Global search: [https://www.google.com/url?q=https://docs.moodle.org/dev/Search_engines&sa=D&ust=1536228178005000 https://docs.moodle.org/dev/Search_engines]
* Authentication / OAuth: [https://www.google.com/url?q=https://docs.moodle.org/dev/Authentication_plugins&sa=D&ust=1536228178005000 https://docs.moodle.org/dev/Authentication_plugins][https://www.google.com/url?q=https://docs.moodle.org/35/en/OAuth_2_authentication&sa=D&ust=1536228178006000 https://docs.moodle.org/35/en/OAuth_2_authentication]
* External tool source / LTI [https://www.google.com/url?q=https://docs.moodle.org/dev/External_tool_source&sa=D&ust=1536228178006000 https://docs.moodle.org/dev/External_tool_source][https://www.google.com/url?q=https://en.wikipedia.org/wiki/Learning_Tools_Interoperability&sa=D&ust=1536228178006000 https://en.wikipedia.org/wiki/Learning_Tools_Interoperability]
* Adding protocols to the API: [https://www.google.com/url?q=https://docs.moodle.org/dev/Webservice_protocols&sa=D&ust=1536228178007000 https://docs.moodle.org/dev/Webservice_protocols]

MoodleNet/tech/architecture

2018-09-05T11:08:21Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet Tech index]

''Note: terms in bold are defined in the glossary at the end of the document.
''
----

There are broadly three approaches we can take to building out MoodleNet’s platform architecture. These are:

# Fully federated
# Federated with HQ API-as-a-service [Note: this is the architecture approach that was selected]
# Centralised SaaS

This document outlines each of these three potential architectural approaches, and explains why we have chosen to focus on the second option. We believe that creating MoodleNet with a federated architecture combined with a HQ API-as-a-service will balance an open approach with a sustainable way of managing the project.

Irrespective of architectural decision, we plan for MoodleNet to be consistent with Moodle’s philosophy of libre software. Moodle Core is licensed under the GNU General Public License (GNU GPL), which is compatible with the GNU Affero General Public License (GNU AGPL) that we intend to use for MoodleNet. The latter is recommended for software being run over a network. Like Moodle Core, MoodleNet is an open source platform, meaning that anyone can adapt, extend or modify the software for both commercial and non-commercial projects without any licensing fees.

----

== Federated with HQ API service ==
Moodle HQ will run a MoodleNet HQ '''API-as-a-service''' serving as a central index of information across the network. This enables consistent discovery and search experiences across all MoodleNet '''instances''' (including the one provided by Moodle HQ).

Each '''MoodleNet instance''' stores the full data of local users, communities, and collections (including personal information, private messages, and public comments/discussions).

The database of the MoodleNet HQ API service contains lists of all public communities, collections, resources, and users across the network, along with a copy of some metadata. A search index also sits behind the API to enable fast and accurate search results. Each item always refers back to the originating MoodleNet instance for the full data (e.g. membership, permissions, comments/discussions).

In practice, this means that the MoodleNet network, while '''federated''', is reliant upon the MoodleNet HQ API service for search and discovery. This provides users with a better and more consistent experience, reducing fragmentation and spreading the shared content more widely, and also gives Moodle HQ more control over the overall network.

Another HQ API service, the Moodle resources repository, could also provides hosting for Moodle course content that users share on MoodleNet. This could later be facilitated with P2P file sharing protocols like '''IPFS'''.

This network can also be based on existing '''protocols''' and '''standards''' to form a '''decentralised''' collection of nodes that send, receive, and store data. The data handling module can be based on an extended ActivityStreams data format and at least some of the APIs on the ActivityPub protocol to ensure compatibility between systems.

[[File:MoodleNet-technical-diagram.png|thumb|link=https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL]]

Interactive diagram: https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL

Advantages of a federated network:
* Robust and resilient
* Scales horizontally
* Private data stays on each user’s home instance
* Each instance is responsible for its content (moderation of discussions, etc)
* Standards-based but also extensible
* Open

Advantages of HQ API service:
* Some Moodle HQ influence over the network
* Consistent network-wide search and discovery experiences
* No duplication of resources for core functions like the indexing of resources from OER APIs, global search indexing, and Moodle resource hosting
* Each instance is still responsible for its content (moderation of discussions, etc)
* Moodle HQ controls the evolution/standardisation of content/metadata types and formats

Disadvantages of HQ API service:
* Single point of failure (HQ API service operated by Moodle HQ).
* Moodle HQ may be responsible for the content that shows up in search / discovery
* Some infrastructure costs for Moodle HQ
* Slightly higher number of components

----

== Glossary ==

ActivityPub - a standard decentralised social networking protocol based on ActivityStreams.

ActivityStreams - a standard format for syndicating social activities.

API - Application Programming Interface. A set of definitions, protocols, and tools for building application software, to enable communication between various components.

API-as-a-service - Software as a Service (SaaS) primarily exposed as an API.

Canonical - the main or reference location for something (eg. canonical URL)

Data handling module - a database abstraction library, using an ORM approach, which would have added support for caching and federation (when applicable).

Decentralisation - the process by which the activities of a network are distributed or delegated away from a central, authoritative location or group.

Federation - the ability for decentralised systems to send data to one another in a standardised way, to prevent fragmentation of the network. Email is a great example of a federated system.

GNU AGPL - a free, copyleft license published by the Free Software Foundation, and based on version 3 of the GNU General Public License (GPL) and the Affero General Public License. This license is compatible with the GPL and is recommended for any software that will commonly be run over a network.

GNU GPL - a widely used free software license guaranteeing end users the freedom to run, study, share and modify the libre software.

Instance - See also node. Can refer to an independently-hosted version of a software package.

IPFS - the InterPlanetary File System is a new hypermedia distribution protocol, addressed by content and identities. IPFS enables the creation of completely distributed applications. It aims to make the web faster, safer, and more open.

Libre software - software that is distributed under terms that allow users to run the software for any purpose as well as to study, change, and distribute it (and any adapted versions).

Metadata - data that provides information about other data. For educational resources, it could describe various aspects of the material, including grade level, subject area, and content type or format.

MoodleNet instance - an independently-hosted version of MoodleNet.

Moodle instance - an independently-hosted version of Moodle Core.

Node - a member of a decentralised network, which can sometimes serve as client, sometimes as server. See also instance.

Open Source - a decentralized software-development model that encourages open collaboration, with products such as source code, blueprints, and documentation freely available to the public.

ORM - Object-relational mapping, used to create a ‘virtual object database’ which can then be referenced programmatically (with less code and more flexibility as to the underlying data storage).

Protocol - a defined set of rules and formats that determine how data is transmitted.

SaaS - Software as a Service. Web-based software that’s centrally hosted and made available to use (free or by subscription).

Scaling horizontally - implies adding more nodes to a system to support its growth, for example installing copies of the same software on three web servers instead of just one.

Scaling vertically - implies adding resources (like CPUs or memory) to a single server in a system to support its growth.

Search index - a component of search engines which collects, parses, and stores data to facilitate fast and accurate search and information retrieval. Index design incorporates interdisciplinary concepts from linguistics, cognitive psychology, mathematics, informatics, and computer science.

Standard - a collection of agreed specifications, usually organised by a standards body such as the W3C.

MoodleNet/tech

2018-09-05T11:07:39Z

Mayel:

MoodleNet/tech/architecture

2018-08-27T10:54:21Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet Tech index]

''Note: terms in bold are defined in the glossary at the end of the document.
''
----

There are broadly three approaches we can take to building out MoodleNet’s platform architecture. These are:

# Fully federated
# Federated with HQ API-as-a-service [Note: this is the architecture approach that was selected]
# Centralised SaaS

This document outlines each of these three potential architectural approaches, and explains why we have chosen to focus on the second option. We believe that creating MoodleNet with a federated architecture combined with a HQ API-as-a-service will balance an open approach with a sustainable way of managing the project.

Irrespective of architectural decision, we plan for MoodleNet to be consistent with Moodle’s philosophy of libre software. Moodle Core is licensed under the GNU General Public License (GNU GPL), which is compatible with the GNU Affero General Public License (GNU AGPL) that we intend to use for MoodleNet. The latter is recommended for software being run over a network. Like Moodle Core, MoodleNet is an open source platform, meaning that anyone can adapt, extend or modify the software for both commercial and non-commercial projects without any licensing fees.

----

== Federated with HQ API service ==
Moodle HQ will run a MoodleNet HQ '''API-as-a-service''' serving as a central index of information across the network. This enables consistent discovery and search experiences across all MoodleNet '''instances''' (including the one provided by Moodle HQ).

Each '''MoodleNet instance''' stores the full data of local users, communities, and collections (including personal information, private messages, and public comments/discussions).

The database of the MoodleNet HQ API service contains lists of all public communities, collections, resources, and users across the network, along with a copy of some metadata. A search index also sits behind the API to enable fast and accurate search results. Each item always refers back to the originating MoodleNet instance for the full data (e.g. membership, permissions, comments/discussions).

In practice, this means that the MoodleNet network, while '''federated''', is reliant upon the MoodleNet HQ API service for search and discovery. This provides users with a better and more consistent experience, reducing fragmentation and spreading the shared content more widely, and also gives Moodle HQ more control over the overall network.

Another HQ API service, the Moodle resources repository, could also provides hosting for Moodle course content that users share on MoodleNet. This could later be facilitated with P2P file sharing protocols like '''IPFS'''.

This network can also be based on existing '''protocols''' and '''standards''' to form a '''decentralised''' collection of nodes that send, receive, and store data. The data handling module can be based on an extended ActivityStreams data format and at least some of the APIs on the ActivityPub protocol to ensure compatibility between systems.

[[File:MoodleNet-technical-diagram.png|thumb]]

Interactive diagram: https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL

Advantages of a federated network:
* Robust and resilient
* Scales horizontally
* Private data stays on each user’s home instance
* Each instance is responsible for its content (moderation of discussions, etc)
* Standards-based but also extensible
* Open

Advantages of HQ API service:
* Some Moodle HQ influence over the network
* Consistent network-wide search and discovery experiences
* No duplication of resources for core functions like the indexing of resources from OER APIs, global search indexing, and Moodle resource hosting
* Each instance is still responsible for its content (moderation of discussions, etc)
* Moodle HQ controls the evolution/standardisation of content/metadata types and formats

Disadvantages of HQ API service:
* Single point of failure (HQ API service operated by Moodle HQ).
* Moodle HQ may be responsible for the content that shows up in search / discovery
* Some infrastructure costs for Moodle HQ
* Slightly higher number of components

----

== Glossary ==

ActivityPub - a standard decentralised social networking protocol based on ActivityStreams.

ActivityStreams - a standard format for syndicating social activities.

API - Application Programming Interface. A set of definitions, protocols, and tools for building application software, to enable communication between various components.

API-as-a-service - Software as a Service (SaaS) primarily exposed as an API.

Canonical - the main or reference location for something (eg. canonical URL)

Data handling module - a database abstraction library, using an ORM approach, which would have added support for caching and federation (when applicable).

Decentralisation - the process by which the activities of a network are distributed or delegated away from a central, authoritative location or group.

Federation - the ability for decentralised systems to send data to one another in a standardised way, to prevent fragmentation of the network. Email is a great example of a federated system.

GNU AGPL - a free, copyleft license published by the Free Software Foundation, and based on version 3 of the GNU General Public License (GPL) and the Affero General Public License. This license is compatible with the GPL and is recommended for any software that will commonly be run over a network.

GNU GPL - a widely used free software license guaranteeing end users the freedom to run, study, share and modify the libre software.

Instance - See also node. Can refer to an independently-hosted version of a software package.

IPFS - the InterPlanetary File System is a new hypermedia distribution protocol, addressed by content and identities. IPFS enables the creation of completely distributed applications. It aims to make the web faster, safer, and more open.

Libre software - software that is distributed under terms that allow users to run the software for any purpose as well as to study, change, and distribute it (and any adapted versions).

Metadata - data that provides information about other data. For educational resources, it could describe various aspects of the material, including grade level, subject area, and content type or format.

MoodleNet instance - an independently-hosted version of MoodleNet.

Moodle instance - an independently-hosted version of Moodle Core.

Node - a member of a decentralised network, which can sometimes serve as client, sometimes as server. See also instance.

Open Source - a decentralized software-development model that encourages open collaboration, with products such as source code, blueprints, and documentation freely available to the public.

ORM - Object-relational mapping, used to create a ‘virtual object database’ which can then be referenced programmatically (with less code and more flexibility as to the underlying data storage).

Protocol - a defined set of rules and formats that determine how data is transmitted.

SaaS - Software as a Service. Web-based software that’s centrally hosted and made available to use (free or by subscription).

Scaling horizontally - implies adding more nodes to a system to support its growth, for example installing copies of the same software on three web servers instead of just one.

Scaling vertically - implies adding resources (like CPUs or memory) to a single server in a system to support its growth.

Search index - a component of search engines which collects, parses, and stores data to facilitate fast and accurate search and information retrieval. Index design incorporates interdisciplinary concepts from linguistics, cognitive psychology, mathematics, informatics, and computer science.

Standard - a collection of agreed specifications, usually organised by a standards body such as the W3C.

MoodleNet/tech/architecture

2018-08-27T10:53:47Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet Tech index]

''Note: terms in bold are defined in the glossary at the end of the document.
''
----

There are broadly three approaches we can take to building out MoodleNet’s platform architecture. These are:

# Fully federated
# Federated with HQ API-as-a-service [Note: this is the architecture approach that was selected]
# Centralised SaaS

This document outlines each of these three potential architectural approaches, and explains why we have chosen to focus on the second option. We believe that creating MoodleNet with a federated architecture combined with a HQ API-as-a-service will balance an open approach with a sustainable way of managing the project.

Irrespective of architectural decision, we plan for MoodleNet to be consistent with Moodle’s philosophy of libre software. Moodle Core is licensed under the GNU General Public License (GNU GPL), which is compatible with the GNU Affero General Public License (GNU AGPL) that we intend to use for MoodleNet. The latter is recommended for software being run over a network. Like Moodle Core, MoodleNet is an open source platform, meaning that anyone can adapt, extend or modify the software for both commercial and non-commercial projects without any licensing fees.

----

== Federated with HQ API service ==
Moodle HQ will run a MoodleNet HQ '''API-as-a-service''' serving as a central index of information across the network. This enables consistent discovery and search experiences across all MoodleNet '''instances''' (including the one provided by Moodle HQ).

Each '''MoodleNet instance''' stores the full data of local users, communities, and collections (including personal information, private messages, and public comments/discussions).

The database of the MoodleNet HQ API service contains lists of all public communities, collections, resources, and users across the network, along with a copy of some metadata. A search index also sits behind the API to enable fast and accurate search results. Each item always refers back to the originating MoodleNet instance for the full data (e.g. membership, permissions, comments/discussions).

In practice, this means that the MoodleNet network, while '''federated''', is reliant upon the MoodleNet HQ API service for search and discovery. This provides users with a better and more consistent experience, reducing fragmentation and spreading the shared content more widely, and also gives Moodle HQ more control over the overall network.

Another HQ API service, the Moodle resources repository, could also provides hosting for Moodle course content that users share on MoodleNet. This could later be facilitated with P2P file sharing protocols like '''IPFS'''.

This network can also be based on existing '''protocols''' and '''standards''' to form a '''decentralised''' collection of nodes that send, receive, and store data. The data handling module can be based on an extended ActivityStreams data format and at least some of the APIs on the ActivityPub protocol to ensure compatibility between systems.

[[File:MoodleNet-technical-diagram.png|thumb]]

Interactive diagram: https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL

Advantages of a federated network:
* Robust and resilient
* Scales horizontally
* Private data stays on each user’s home instance
* Each instance is responsible for its content (moderation of discussions, etc)
* Standards-based but also extensible
* Open

Advantages of HQ API service:
* Some Moodle HQ influence over the network
* Consistent network-wide search and discovery experiences
* No duplication of resources for core functions like the indexing of resources from OER APIs, global search indexing, and Moodle resource hosting
* Each instance is still responsible for its content (moderation of discussions, etc)
* Moodle HQ controls the evolution/standardisation of content/metadata types and formats

Disadvantages:
* Single point of failure (HQ API service operated by Moodle HQ).
* Moodle HQ may be responsible for the content that shows up in search / discovery
* Some infrastructure costs for Moodle HQ
* Slightly higher number of components

----

== Glossary ==

ActivityPub - a standard decentralised social networking protocol based on ActivityStreams.

ActivityStreams - a standard format for syndicating social activities.

API - Application Programming Interface. A set of definitions, protocols, and tools for building application software, to enable communication between various components.

API-as-a-service - Software as a Service (SaaS) primarily exposed as an API.

Canonical - the main or reference location for something (eg. canonical URL)

Data handling module - a database abstraction library, using an ORM approach, which would have added support for caching and federation (when applicable).

Decentralisation - the process by which the activities of a network are distributed or delegated away from a central, authoritative location or group.

Federation - the ability for decentralised systems to send data to one another in a standardised way, to prevent fragmentation of the network. Email is a great example of a federated system.

GNU AGPL - a free, copyleft license published by the Free Software Foundation, and based on version 3 of the GNU General Public License (GPL) and the Affero General Public License. This license is compatible with the GPL and is recommended for any software that will commonly be run over a network.

GNU GPL - a widely used free software license guaranteeing end users the freedom to run, study, share and modify the libre software.

Instance - See also node. Can refer to an independently-hosted version of a software package.

IPFS - the InterPlanetary File System is a new hypermedia distribution protocol, addressed by content and identities. IPFS enables the creation of completely distributed applications. It aims to make the web faster, safer, and more open.

Libre software - software that is distributed under terms that allow users to run the software for any purpose as well as to study, change, and distribute it (and any adapted versions).

Metadata - data that provides information about other data. For educational resources, it could describe various aspects of the material, including grade level, subject area, and content type or format.

MoodleNet instance - an independently-hosted version of MoodleNet.

Moodle instance - an independently-hosted version of Moodle Core.

Node - a member of a decentralised network, which can sometimes serve as client, sometimes as server. See also instance.

Open Source - a decentralized software-development model that encourages open collaboration, with products such as source code, blueprints, and documentation freely available to the public.

ORM - Object-relational mapping, used to create a ‘virtual object database’ which can then be referenced programmatically (with less code and more flexibility as to the underlying data storage).

Protocol - a defined set of rules and formats that determine how data is transmitted.

SaaS - Software as a Service. Web-based software that’s centrally hosted and made available to use (free or by subscription).

Scaling horizontally - implies adding more nodes to a system to support its growth, for example installing copies of the same software on three web servers instead of just one.

Scaling vertically - implies adding resources (like CPUs or memory) to a single server in a system to support its growth.

Search index - a component of search engines which collects, parses, and stores data to facilitate fast and accurate search and information retrieval. Index design incorporates interdisciplinary concepts from linguistics, cognitive psychology, mathematics, informatics, and computer science.

Standard - a collection of agreed specifications, usually organised by a standards body such as the W3C.

MoodleNet/tech

2018-08-27T10:51:54Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

An area to document the tech choices and decisions we've made.

[[File:MoodleNet-technical-diagram.png|thumb]]

* [https://docs.moodle.org/dev/MoodleNet/tech/architecture Technical architecture] - how is the platform going to be set up?
* [https://docs.moodle.org/dev/MoodleNet/tech/stack Tech stack] - why did we choose Elixir?

MoodleNet/tech/stack

2018-08-27T10:51:39Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet Tech index]

= Rationale for choosing Elixir for the MoodleNet back-end =

'''Author:''' Mayel de Borniol (Technical Architect)

'''Date:''' 6 August 2018

-----

== Introduction ==

MoodleNet is a new open social media platform for educators, focused on professional development and open content. It will be an integral part of the Moodle ecosystem.

Just like the ~7,000 languages that are spoken in the world today, there are many different types of programming languages that allow humans to communicate with computers (and tell them nicely what to do). An important decision for our team was what technical language(s) Moodlenet should speak, and this document highlights the decision-making process which ended up with choosing the ‘Elixir’ language.

== Research process ==

The process began with an extensive review of web application programming languages. More specifically, the technologies used for apps based on [https://en.wikipedia.org/wiki/ActivityPub ActivityPub federation standard] - which will enable MoodleNet to be a '''decentralised platform, you will be able self-host an instance''' (just like you can install Moodle on a server, and customise it) but all the instances will be '''interconnected'''.

A '''[https://ethercalc.org/fediverse-stacks spreadsheet of fediverse apps and their stacks]''' (and [https://social.coop/@mayel/100469319126679591 crowdsourced extra information via the fediverse]) was compiled. This showed that besides Ruby on Rails, there were a few ActivityPub projects using Python (and a couple intending to use PHP) and some other languages, however, most projects are still in early development and many are not yet federated. Considering that '''ActivityPub is still relatively new it is understandable that there are limited examples of full implementations''', let alone ones that are proven to work and be interoperable.

One of the first languages that stood out was Go, one of the only a few to actually have an [https://github.com/go-fed/activity ActivityPub library]. The developer was contacted and offered his assistance for future collaboration (although in full-time employment and developing the Go library in his spare time). What this meant was that the MoodleNet team would have to modify the library in order to tailor it to the project’s needs. The main obstacle to this, however, is that Go is a ‘statically typed’ language which means every ActivityStreams extension would have to be hard coded pre-compilation. This would make things less flexible, so this option was set aside.

Alongside researching the documentations, codebases, issue trackers and communicating with developers of the apps in the spreadsheet, many of them were installed and tested (including Mastodon, Pleroma, and Prismo). The latter, while having some functionality that MoodleNet will need, confirmed an earlier impression from running a Mastodon instance: '''Rails apps tend to not be lightweight and often rely on many external dependencies'''.

After comparing the possible language candidates, the focus shifted on detailing the pros and cons for each, finally focusing on the following:

* The '''[https://en.wikipedia.org/wiki/BEAM_(Erlang_virtual_machine) Erlang VM]''' is time tested (more than 20 years old), very fast and has good concurrency and inter-process communication (called OTP).
* '''[https://elixir-lang.org Elixir]''' is a new (7+ years) functional language designed for productivity and maintainability that runs on the Erlang VM.
* '''[https://phoenixframework.org Phoenix]''' is a modern web framework that makes building APIs and web applications easy. Since it’s built with Elixir and runs on Erlang VM, it is very fast and has excellent support for handling very large numbers of simultaneous users.

= Benefits of Elixir =

A list of reasons to use Elixir in our context:

== Performance ==

The Phoenix web framework has been found to perform better than Rails, PHP, and Python. [https://github.com/mroth/phoenix-showdown/blob/master/README.md#benchmarking One benchmark] showed Phoenix handling over 10x more requests than Rails in a given period. Phoenix was also much more consistent under load - Rails was more prone to have some requests bog down. This can cause a “chain reaction”, because Rails apps are configured with a fixed number of application processes, so if some of them are slow, it can mean that others have to wait in line, which dramatically increases the app’s response time.

Furthermore, Phoenix apps '''without caching''' drastically outperform Rails apps '''with caching'''. This is important because caching is notorious for being a source of complexity and bugs, and because caching can’t be used for moment-by-moment, personalised content. The [https://youtu.be/AdY5AfXs7aw?t=3m14s Bleacher Report] for example went from over 100 AWS servers to 5, with CPU usage rarely going above 10%, and saw a 10x performance improvement over their Rails app.

There are a growing number of software projects using Elixir - e.g. Pinterest [https://github.com/bignerdranch/why_elixir who say]:

<blockquote>“We like Elixir and have seen some pretty big wins with it. The system that manages rate limits for both the Pinterest API and Ads API is built in Elixir. Its 50 percent response time is around 500 microseconds with a 90 percent response time of 800 microseconds. Yes, microseconds.”
</blockquote>

And an [https://blog.carbonfive.com/2016/04/19/elixir-and-phoenix-the-future-of-web-apis-and-apps/ adopter of the Phoenix framework] says:

<blockquote>“A rather large JSON request was taking about 1.5-2.0s against our Rails backend (no caching). That same request (same h/w, database queries and data) takes about 400ms with Phoenix. Our entire application went from using just shy of 1 GB across 2 dynos to a single dyno using less than 100 MB. That single dyno is notably faster and can handle higher concurrency (about 10x). Importantly, Phoenix (without caching) performs better than Rails (with caching).”</blockquote>

One thing that makes Erlang/Elixir so efficient is [https://www.brianstorti.com/the-actor-model/ the actor model], which ActivityPub seems to have taken inspiration from.

== Scalability ==

The Erlang VM’s model of concurrency is great for multi-core CPUs, but it was created before they existed. Its original purpose was to support concurrency and fault-tolerance via the use of many different machines. This makes it an excellent tool for building systems that can handle more load by simply adding more servers.

As the [http://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/ docs for an Erlang web server] put it:

<blockquote>“At the time of writing there are application servers written in Erlang that can handle more than two million connections on a single server in a real production application, with spare memory and CPU! The Web is concurrent, and Erlang is a language designed for concurrency, so it is a perfect match. Of course, various platforms need to scale beyond a few million connections. This is where Erlang’s built-in distribution mechanisms come in. If one server isn’t enough, add more! Erlang allows you to use the same code for talking to local processes or to processes in other parts of your cluster, which means you can scale very quickly if the need arises.”
</blockquote>

== Developer Productivity & Happiness ==

When people argue about programming languages, often the performance card is pulled (“this language is so much faster in these benchmarks”). But performance isn’t the only consideration: while it’s possible to just add more servers, developer time often costs more than servers.

More important then is which framework helps write software faster, of a better quality, and which benefits the programmer’s wellbeing.

As Pinterest concluded from using Elixir:

<blockquote>“We’ve also seen an improvement in code clarity. We’re converting our notifications system from Java to Elixir. The Java version used an Actor system and weighed in at around 10,000 lines of code. The new Elixir system has shrunk this to around 1000 lines. The Elixir based system is also faster and more consistent than the Java one and runs on half the number of servers.”</blockquote>

And [http://www.techworld.com/apps-wearables/how-elixir-helped-bleacher-report-handle-8x-more-traffic-3653957/ Bleacher Report], who went from 150 servers to 5 using Elixir: > "The new language has led to cleaner code base and much less technical debt. It has also increased the speed of development.

Some [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ advantages of Elixir for programmers] include:

* No extra engineering spent on “making it faster” (if the runtime is already fast enough they don’t need to bother with caching for example).
* All the goodies of modern day programming, like a package manager.
* Pattern Matching: you can make assertions on the structure and can get values directly out of a deeply nested map (or list) and put their value into a variable. You also have method overloading and Elixir will try to match the functions from top to bottom which means you can have different function definitions based on the structure of your input data.
* Immutable data structures & pure functions: Everything that the function depends on is a parameter, and the only thing that “happens” is the return value of the function. There are no instance variables that are difficult to debug.
* Explicit code: For example, you explicitly specify a template by name, and pass the values you’ll need from the controller. Ecto also gives you more control over what data will be loaded from the DB.
* [https://hexdocs.pm/ecto/Ecto.Changeset.html Ecto Changesets]: filtering, casting, validation and definition of constraints when manipulating DB data.
* Optional type-checking: use [https://github.com/jeremyjh/dialyxir typing only when you want to].
* Parallelism: it’s not just about performance! Parallelism in the Erlang VM low cost and seamless. Spawning a new process (not like an OS process, they are more like actors) is easy and has a very low overhead, unlike starting a new thread. You can have millions of them on one machine. And thanks to immutability guarantees and every process being isolated you don’t have to worry about processes messing with each other.
* Doc tests: It is possible to write code examples directly in the documentation of a method. These will be executed during test runs and check if they still return the same values/still pass. They are also included in the generated documentation.

== Reliability ==

While Elixir is a fairly new language, it is mostly a friendly interface to the Erlang virtual machine, which has been used since the 80s to build some of the most reliable systems in the world: telephone systems.

It is made for running a complex system with almost no downtime, like having multiple levels of “supervising” processes in a system to reboot parts that have errors. Basically, microservices before microservices were cool.

== Concurrency ==

CPUs are no longer getting dramatically faster each year. Instead, we get machines with more cores. Our code can run faster, but only if it can run concurrently - meaning, different bits of code run simultaneously on different cores.

The main problem with concurrent code is having two pieces of code mess with the same data at the same time, creating unexpected results. Object-oriented languages like Ruby don’t provide great tools for avoiding such problems. But functional languages, like Elixir, do.

Writing concurrent code in Elixir is extremely easy, and it’s nearly impossible to accidentally interfere with other code that is running at the time.

== Simplicity ==

For modern web applications (written in languages like PHP or Ruby on Rails) to do everything we require of them, they depend on a lot of other pieces running on the server, for example:

* Only one web request can be handled at a time, and it is not possible to spin up new processes as needed, so tools are needed to spawn multiple application servers up front and put a web server like Nginx in front of them to hand off requests.
* It is not possible to do slow background tasks without blocking web requests, so something like [http://resque.github.io Resque] needs to be added to take care of running background jobs.
* It is not advisable to use a precious process to maintain a websocket connection with a user, so something like Pusher needs to be added to get realtime functionality (meaning extra costs).
* It is not possible to keep a big process running all the time to do scheduled tasks, so a dependency on cron needs to be added.
* No built-in tool for managing multiple parts of a running system currently exists, so tools like [https://www.theforeman.org foreman] are used to start and monitor them.

In Elixir on the other hand, it is possible to spin up a nearly limitless number of processes as needed, so it is possible (in theory) to forego all those tools above.

Elixir code is also simpler to understand than object-oriented code because it has explicitness as a value.

<blockquote>“Functional programming is associated with concurrency but it was not by design. It just happens that, by making the complex parts of our system explicit, solving more complicated issues like concurrency becomes much simpler.” - [http://www.sitepoint.com/an-interview-with-elixir-creator-jose-valim/ Jose Valim]
</blockquote>

== Flexibility ==

Using Phoenix and Elixir opens the door to building applications that are not possible with other web frameworks.

The Phoenix framework has first-class support for realtime communication via websockets (with polling as a fallback). In benchmarks, the creators have been able to[http://www.phoenixframework.org/blog/the-road-to-2-million-websocket-connections serve 2 million simultaneously-connected clients]. Additionally, they already have native channel clients for iOS, Android, and Windows devices. With that kind of support, you can confidently build servers to support chat, networked games, and more.

== Correctness ==

In Rails, ActiveRecord encourages developers to do all data validation in application code. However, validations that depend on the state of the database can only be reliably done by the database, using constraints or locks. This includes things like:

* Does any user have this username right now? (uniqueness constraint)
* Does post 5 exist still right now, before I comment on it? (foreign key constraint)
* Does this user’s account have enough money to cover this purchase right now? (CHECK constraint)
* Is this rental property reserved for June 8 right now? (EXCLUDE constraint on date ranges)

It is possible to use such constraints with a Rails application, but it is not typical to do so, and the tools do not encourage it.

Elixir’s [https://hexdocs.pm/ecto/Ecto.html Ecto] database library embraces database constraints, with built-in support for adding them, catching constraint violations, and turning them back into friendly user-facing error messages.

== Where Elixir is especially suited ==

Any project that is a good fit for Rails or Python is something that could be done in Phoenix, especially if the project involves any or multiple of the following:

* System expecting high traffic or requiring very fast / consistent response times
* Minimal downtime being crucial
* Realtime updates (eg, stock ticker, social media)
* Bidirectional realtime communication with websockets (eg, chat, games)

= Drawbacks of Elixir =

Some potential downsides of using Elixir, along with mitigating actions:

* Fewer Elixir developers available. However:
** There are also significantly fewer projects competing for those people.
** There is a trend in Ruby developers wanting to cross over to Elixir.
** Developers with Erlang experience are also well suited.
** Elixir is a shiny new thing with real promise, which helps attract very enthusiastic developers.
* While Phoenix is productive, it is not as productive as older frameworks like Rails… yet. Reasons include:
** Lack of developer experience with Elixir.
** The relative newness of its open source ecosystem (documentation, forums, example code available).
** There are fewer libraries in Elixir than in older languages, so there are more times when you’d have to write something yourself. However:
*** You can use the many existing Erlang libraries.
*** New Elixir libraries are being added quickly.
*** Any remaining gaps are a chance to contribute to the community by creating a great open source tool.
* It may be harder to convince people to use Elixir, given that it’s currently obscure - not in the top [https://www.tiobe.com/tiobe-index/ 50 TIOBE index]. However:
** Erlang is better-known. Elixir compiles to Erlang bytecode, runs on the Erlang VM and can use or be used by Erlang code. It’s basically “Erlang made friendlier”.
** Joe Armstrong, co-creator of Erlang, said of pre-1.0 Elixir in 2013 that it was "good s**t".
** Therefore, if we can convince someone on Erlang, Elixir is a no-brainer.

= What’s next for MoodleNet’s development =

== A generic agent-centric approach to federation? ==

Another fediverse app being developed in Elixir ([https://github.com/beta-phenylethylamine/fontina Fontina], for photo sharing - although it has been put on hiatus) is now working on a [https://github.com/fontina-project/pubstomp generic ActivityPub server] to serve as back-end (there may be a good opportunity to join efforts…) Here is how the developer describes it:

<blockquote>“I’m working on pubstomp, a generic AP server that is intended for services like mastodon/pixelfed/peertube to work as frontends to it and would indeed support single account [per person, versus having an account on an instance of each of those apps]. > That said, one of my goals down the road is to build”api adaptors" that would basically plug into pubstomp and adapt to, say, the mastoAPI, pleromaAPI, etc.”</blockquote>

This is a good example of an '''agent-centric approach''', where instead of having one '''monolithic app per use-case''' it is possible instead to separate out federation logic and custom app logic (both back-ends could still share a database on the same server, and share a JavaScript-based front-end app that talks to both APIs).

I started a [https://social.coop/@mayel/100469525067581562 thread about this on the fediverse] (please join the conversation!):

<blockquote>There’s need for a generic agent-centric #ActivityPub server, so that instead of signing up to a bunch of different servers, a user could have their identity and data all in one place, and all the apps they use (clients, but if necessary server-side “plugins” as well) would interact with the activity/objects types that they support.</blockquote>

== The plan for Moodlenet (so far) ==

# Fork the Pleroma back-end to create a set of ActivityPub libraries (or a generic ActivityPub server)
# Add suport for authenticating as OAuth client
# Add support for group accounts (agents that represent a several users)
# Create ActivityStreams extensions
# Test federation
# Possibly add [https://graphql.org GraphQL] client-server API
# Create front-end app with React.js (web and mobile)

We are planning to fork the [https://git.pleroma.social/pleroma/pleroma Pleroma back-end] to '''create a set of ActivityPub/ActivityStreams libraries'''. If that proves to not be feasible, we will turn it into a generic ActivityPub server back-end that can support any type of activity and object (including extensions to ActivityStreams) and is easily extensible which doesn’t ship with any frontend (possible name: ''Pub of the Commons''). Pleroma is written with [https://elixir-lang.org Elixir]’s [https://phoenixframework.org Phoenix Framework], and licensed as AGPL (which is also being used for MoodleNet) so the upstream project will be able to use any improvements we make.

Firstly, any parts of the code coming from Pleroma that we don’t needed will be removed (like support for the deprecated OStatus protocol, and the two front-ends which ship with Pleroma - its own Vue.js interface and Mastodon’s React.js interface), and we’ll add some things that can be '''universally useful''' like '''support for groups''' (actors made of several users), a basic HTML registration/authentication interface (and '''OAuth client''' functionality, so users can sign in using their existing accounts elsewhere) so that at least those things can be done without relying on a front-end app.

While we work on creating models/vocabulary for MoodleNet, we can use this generic ActivityPub server to test our ActivityStreams extensions and make sure federation works well in real time (using the API only). Only once that is ready, will we start plugging in custom MoodleNet logic and developing the front-end app (which is the reverse from many fediverse app projects, who have first implemented MVPs of their use case, and then often find it challenging to add federation on top).

Regarding the connection between the back-end and front-end app, the ActivityPub standard comes with a suggested [https://www.w3.org/TR/activitypub/#client-to-server-interactions client-server REST API specification], but for some reason Mastodon and many other fediverse apps have created their own custom REST APIs (and Pleroma implemented Mastodon’s so that it can share front-end apps). So an interesting option at this point for MoodleNet (and ''Pub of the Commons''), may be to still support Mastodon’s client REST API (for compatibility with existing front-ends like [https://github.com/nolanlawson/pinafore Pinafore]) and additionally to '''implement a new GraphQL-based API that would allow more flexibility and extensibility between the server and front-end apps''' (any functionality/activities/objects not supported by Mastodon would only have to be implemented in the server-to-server REST API and the [https://graphql.org GraphQL] API).

= References =

* [https://ethercalc.org/fediverse-stacks Spreadsheet of fediverse apps and their stacks]
* [https://www.w3.org/TR/activitypub/ ActivityPub] standard (for federation)
* [https://www.w3.org/TR/activitystreams-core/ ActivityStreams] & its [https://www.w3.org/TR/activitystreams-vocabulary/ vocabulary] (which ActivityPub uses as a data format)
* [https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/ How to implement a basic Mastodon-compatible server]
* [https://github.com/bignerdranch/why_elixir Why elixir] (big tanks to Big Nerd Ranch for some of the great material used in this doc!)
* [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ Choosing Elixir for the Code, not the Performance]
* [https://git.pleroma.social/pleroma/pleroma/wikis/Hacking-Pleroma:-Elixir,-Phoenix-and-a-bit-of-ActivityPub Pleroma’s architecture]

MoodleNet/tech/

2018-08-27T10:50:38Z

Mayel: redir

#REDIRECT [[MoodleNet/tech]]

MoodleNet/tech

2018-08-27T10:49:45Z

Mayel: Created page with "<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet index] ---- An area to document the tech choices and decisions we've made. File:MoodleNet-technical-diagr..."

<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet index]

----

An area to document the tech choices and decisions we've made.

[[File:MoodleNet-technical-diagram.png|thumb]]

* [https://docs.moodle.org/dev/MoodleNet/tech/architecture Technical architecture] - how is the platform going to be set up?
* [https://docs.moodle.org/dev/MoodleNet/tech/stack Tech stack] - why did we choose Elixir?

MoodleNet/tech/architecture

2018-08-27T10:48:03Z

Mayel: copied from Google doc

<< [https://docs.moodle.org/dev/MoodleNet/tech Back to MoodleNet Tech index]

''Note: terms in bold are defined in the glossary at the end of the document.
''
----

There are broadly three approaches we can take to building out MoodleNet’s platform architecture. These are:

# Fully federated
# Federated with HQ API-as-a-service [Note: this is the architecture approach that was selected]
# Centralised SaaS

This document outlines each of these three potential architectural approaches, and explains why we have chosen to focus on the second option. We believe that creating MoodleNet with a federated architecture combined with a HQ API-as-a-service will balance an open approach with a sustainable way of managing the project.

Irrespective of architectural decision, we plan for MoodleNet to be consistent with Moodle’s philosophy of libre software. Moodle Core is licensed under the GNU General Public License (GNU GPL), which is compatible with the GNU Affero General Public License (GNU AGPL) that we intend to use for MoodleNet. The latter is recommended for software being run over a network. Like Moodle Core, MoodleNet is an open source platform, meaning that anyone can adapt, extend or modify the software for both commercial and non-commercial projects without any licensing fees.

----

== Federated with HQ API service ==
Moodle HQ will run a MoodleNet HQ '''API-as-a-service''' serving as a central index of information across the network. This enables consistent discovery and search experiences across all MoodleNet '''instances''' (including the one provided by Moodle HQ).

Each '''MoodleNet instance''' stores the full data of local users, communities, and collections (including personal information, private messages, and public comments/discussions).

The database of the MoodleNet HQ API service contains lists of all public communities, collections, resources, and users across the network, along with a copy of some metadata. A search index also sits behind the API to enable fast and accurate search results. Each item always refers back to the originating MoodleNet instance for the full data (e.g. membership, permissions, comments/discussions).

In practice, this means that the MoodleNet network, while '''federated''', is reliant upon the MoodleNet HQ API service for search and discovery. This provides users with a better and more consistent experience, reducing fragmentation and spreading the shared content more widely, and also gives Moodle HQ more control over the overall network.

Another HQ API service, the Moodle resources repository, could also provides hosting for Moodle course content that users share on MoodleNet. This could later be facilitated with P2P file sharing protocols like '''IPFS'''.

This network can also be based on existing '''protocols''' and '''standards''' to form a '''decentralised''' collection of nodes that send, receive, and store data. The data handling module can be based on an extended ActivityStreams data format and at least some of the APIs on the ActivityPub protocol to ensure compatibility between systems.

[[File:MoodleNet-technical-diagram.png|thumb]]

Interactive diagram: https://whimsical.co/Xh45SHnfdAuNAJgGqQu8hL

Advantages:
* Robust and resilient
* Scales horizontally
* Private data stays on each user’s home instance
* Each instance is responsible for its content (moderation of discussions, etc)
* Standards-based but also extensible
* Open
* Some Moodle HQ influence over the network
* Consistent network-wide search and discovery experiences
* No duplication of resources for core functions like the indexing of resources from OER APIs, global search indexing, and Moodle resource hosting
* Each instance is still responsible for its content (moderation of discussions, etc)
* Moodle HQ controls the evolution/standardisation of content/metadata types and formats

Disadvantages:
* Single point of failure (HQ API service operated by Moodle HQ).
* Moodle HQ may be responsible for the content that shows up in search / discovery
* Some infrastructure costs for Moodle HQ
* Slightly higher number of components

----

== Glossary ==

ActivityPub - a standard decentralised social networking protocol based on ActivityStreams.

ActivityStreams - a standard format for syndicating social activities.

API - Application Programming Interface. A set of definitions, protocols, and tools for building application software, to enable communication between various components.

API-as-a-service - Software as a Service (SaaS) primarily exposed as an API.

Canonical - the main or reference location for something (eg. canonical URL)

Data handling module - a database abstraction library, using an ORM approach, which would have added support for caching and federation (when applicable).

Decentralisation - the process by which the activities of a network are distributed or delegated away from a central, authoritative location or group.

Federation - the ability for decentralised systems to send data to one another in a standardised way, to prevent fragmentation of the network. Email is a great example of a federated system.

GNU AGPL - a free, copyleft license published by the Free Software Foundation, and based on version 3 of the GNU General Public License (GPL) and the Affero General Public License. This license is compatible with the GPL and is recommended for any software that will commonly be run over a network.

GNU GPL - a widely used free software license guaranteeing end users the freedom to run, study, share and modify the libre software.

Instance - See also node. Can refer to an independently-hosted version of a software package.

IPFS - the InterPlanetary File System is a new hypermedia distribution protocol, addressed by content and identities. IPFS enables the creation of completely distributed applications. It aims to make the web faster, safer, and more open.

Libre software - software that is distributed under terms that allow users to run the software for any purpose as well as to study, change, and distribute it (and any adapted versions).

Metadata - data that provides information about other data. For educational resources, it could describe various aspects of the material, including grade level, subject area, and content type or format.

MoodleNet instance - an independently-hosted version of MoodleNet.

Moodle instance - an independently-hosted version of Moodle Core.

Node - a member of a decentralised network, which can sometimes serve as client, sometimes as server. See also instance.

Open Source - a decentralized software-development model that encourages open collaboration, with products such as source code, blueprints, and documentation freely available to the public.

ORM - Object-relational mapping, used to create a ‘virtual object database’ which can then be referenced programmatically (with less code and more flexibility as to the underlying data storage).

Protocol - a defined set of rules and formats that determine how data is transmitted.

SaaS - Software as a Service. Web-based software that’s centrally hosted and made available to use (free or by subscription).

Scaling horizontally - implies adding more nodes to a system to support its growth, for example installing copies of the same software on three web servers instead of just one.

Scaling vertically - implies adding resources (like CPUs or memory) to a single server in a system to support its growth.

Search index - a component of search engines which collects, parses, and stores data to facilitate fast and accurate search and information retrieval. Index design incorporates interdisciplinary concepts from linguistics, cognitive psychology, mathematics, informatics, and computer science.

Standard - a collection of agreed specifications, usually organised by a standards body such as the W3C.

MoodleNet/tech/stack

2018-08-06T16:01:59Z

Mayel: /* Research process */

= Rationale for choosing Elixir for the MoodleNet back-end =

'''Author:''' Mayel de Borniol (Technical Architect)

'''Date:''' 6 August 2018

-----

== Introduction ==

MoodleNet is a new open social media platform for educators, focused on professional development and open content. It will be an integral part of the Moodle ecosystem.

Just like the ~7,000 languages that are spoken in the world today, there are many different types of programming languages that allow humans to communicate with computers (and tell them nicely what to do). An important decision for our team was what technical language(s) Moodlenet should speak, and this document highlights the decision-making process which ended up with choosing the ‘Elixir’ language.

== Research process ==

The process began with an extensive review of web application programming languages. More specifically, the technologies used for apps based on [https://en.wikipedia.org/wiki/ActivityPub ActivityPub federation standard] - which will enable MoodleNet to be a '''decentralised platform, you will be able self-host an instance''' (just like you can install Moodle on a server, and customise it) but all the instances will be '''interconnected'''.

A '''[https://ethercalc.org/fediverse-stacks spreadsheet of fediverse apps and their stacks]''' (and [https://social.coop/@mayel/100469319126679591 crowdsourced extra information via the fediverse]) was compiled. This showed that besides Ruby on Rails, there were a few ActivityPub projects using Python (and a couple intending to use PHP) and some other languages, however, most projects are still in early development and many are not yet federated. Considering that '''ActivityPub is still relatively new it is understandable that there are limited examples of full implementations''', let alone ones that are proven to work and be interoperable.

One of the first languages that stood out was Go, one of the only a few to actually have an [https://github.com/go-fed/activity ActivityPub library]. The developer was contacted and offered his assistance for future collaboration (although in full-time employment and developing the Go library in his spare time). What this meant was that the MoodleNet team would have to modify the library in order to tailor it to the project’s needs. The main obstacle to this, however, is that Go is a ‘statically typed’ language which means every ActivityStreams extension would have to be hard coded pre-compilation. This would make things less flexible, so this option was set aside.

Alongside researching the documentations, codebases, issue trackers and communicating with developers of the apps in the spreadsheet, many of them were installed and tested (including Mastodon, Pleroma, and Prismo). The latter, while having some functionality that MoodleNet will need, confirmed an earlier impression from running a Mastodon instance: '''Rails apps tend to not be lightweight and often rely on many external dependencies'''.

After comparing the possible language candidates, the focus shifted on detailing the pros and cons for each, finally focusing on the following:

* The '''[https://en.wikipedia.org/wiki/BEAM_(Erlang_virtual_machine) Erlang VM]''' is time tested (more than 20 years old), very fast and has good concurrency and inter-process communication (called OTP).
* '''[https://elixir-lang.org Elixir]''' is a new (7+ years) functional language designed for productivity and maintainability that runs on the Erlang VM.
* '''[https://phoenixframework.org Phoenix]''' is a modern web framework that makes building APIs and web applications easy. Since it’s built with Elixir and runs on Erlang VM, it is very fast and has excellent support for handling very large numbers of simultaneous users.

= Benefits of Elixir =

A list of reasons to use Elixir in our context:

== Performance ==

The Phoenix web framework has been found to perform better than Rails, PHP, and Python. [https://github.com/mroth/phoenix-showdown/blob/master/README.md#benchmarking One benchmark] showed Phoenix handling over 10x more requests than Rails in a given period. Phoenix was also much more consistent under load - Rails was more prone to have some requests bog down. This can cause a “chain reaction”, because Rails apps are configured with a fixed number of application processes, so if some of them are slow, it can mean that others have to wait in line, which dramatically increases the app’s response time.

Furthermore, Phoenix apps '''without caching''' drastically outperform Rails apps '''with caching'''. This is important because caching is notorious for being a source of complexity and bugs, and because caching can’t be used for moment-by-moment, personalised content. The [https://youtu.be/AdY5AfXs7aw?t=3m14s Bleacher Report] for example went from over 100 AWS servers to 5, with CPU usage rarely going above 10%, and saw a 10x performance improvement over their Rails app.

There are a growing number of software projects using Elixir - e.g. Pinterest [https://github.com/bignerdranch/why_elixir who say]:

<blockquote>“We like Elixir and have seen some pretty big wins with it. The system that manages rate limits for both the Pinterest API and Ads API is built in Elixir. Its 50 percent response time is around 500 microseconds with a 90 percent response time of 800 microseconds. Yes, microseconds.”
</blockquote>

And an [https://blog.carbonfive.com/2016/04/19/elixir-and-phoenix-the-future-of-web-apis-and-apps/ adopter of the Phoenix framework] says:

<blockquote>“A rather large JSON request was taking about 1.5-2.0s against our Rails backend (no caching). That same request (same h/w, database queries and data) takes about 400ms with Phoenix. Our entire application went from using just shy of 1 GB across 2 dynos to a single dyno using less than 100 MB. That single dyno is notably faster and can handle higher concurrency (about 10x). Importantly, Phoenix (without caching) performs better than Rails (with caching).”</blockquote>

One thing that makes Erlang/Elixir so efficient is [https://www.brianstorti.com/the-actor-model/ the actor model], which ActivityPub seems to have taken inspiration from.

== Scalability ==

The Erlang VM’s model of concurrency is great for multi-core CPUs, but it was created before they existed. Its original purpose was to support concurrency and fault-tolerance via the use of many different machines. This makes it an excellent tool for building systems that can handle more load by simply adding more servers.

As the [http://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/ docs for an Erlang web server] put it:

<blockquote>“At the time of writing there are application servers written in Erlang that can handle more than two million connections on a single server in a real production application, with spare memory and CPU! The Web is concurrent, and Erlang is a language designed for concurrency, so it is a perfect match. Of course, various platforms need to scale beyond a few million connections. This is where Erlang’s built-in distribution mechanisms come in. If one server isn’t enough, add more! Erlang allows you to use the same code for talking to local processes or to processes in other parts of your cluster, which means you can scale very quickly if the need arises.”
</blockquote>

== Developer Productivity & Happiness ==

When people argue about programming languages, often the performance card is pulled (“this language is so much faster in these benchmarks”). But performance isn’t the only consideration: while it’s possible to just add more servers, developer time often costs more than servers.

More important then is which framework helps write software faster, of a better quality, and which benefits the programmer’s wellbeing.

As Pinterest concluded from using Elixir:

<blockquote>“We’ve also seen an improvement in code clarity. We’re converting our notifications system from Java to Elixir. The Java version used an Actor system and weighed in at around 10,000 lines of code. The new Elixir system has shrunk this to around 1000 lines. The Elixir based system is also faster and more consistent than the Java one and runs on half the number of servers.”</blockquote>

And [http://www.techworld.com/apps-wearables/how-elixir-helped-bleacher-report-handle-8x-more-traffic-3653957/ Bleacher Report], who went from 150 servers to 5 using Elixir: > "The new language has led to cleaner code base and much less technical debt. It has also increased the speed of development.

Some [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ advantages of Elixir for programmers] include:

* No extra engineering spent on “making it faster” (if the runtime is already fast enough they don’t need to bother with caching for example).
* All the goodies of modern day programming, like a package manager.
* Pattern Matching: you can make assertions on the structure and can get values directly out of a deeply nested map (or list) and put their value into a variable. You also have method overloading and Elixir will try to match the functions from top to bottom which means you can have different function definitions based on the structure of your input data.
* Immutable data structures & pure functions: Everything that the function depends on is a parameter, and the only thing that “happens” is the return value of the function. There are no instance variables that are difficult to debug.
* Explicit code: For example, you explicitly specify a template by name, and pass the values you’ll need from the controller. Ecto also gives you more control over what data will be loaded from the DB.
* [https://hexdocs.pm/ecto/Ecto.Changeset.html Ecto Changesets]: filtering, casting, validation and definition of constraints when manipulating DB data.
* Optional type-checking: use [https://github.com/jeremyjh/dialyxir typing only when you want to].
* Parallelism: it’s not just about performance! Parallelism in the Erlang VM low cost and seamless. Spawning a new process (not like an OS process, they are more like actors) is easy and has a very low overhead, unlike starting a new thread. You can have millions of them on one machine. And thanks to immutability guarantees and every process being isolated you don’t have to worry about processes messing with each other.
* Doc tests: It is possible to write code examples directly in the documentation of a method. These will be executed during test runs and check if they still return the same values/still pass. They are also included in the generated documentation.

== Reliability ==

While Elixir is a fairly new language, it is mostly a friendly interface to the Erlang virtual machine, which has been used since the 80s to build some of the most reliable systems in the world: telephone systems.

It is made for running a complex system with almost no downtime, like having multiple levels of “supervising” processes in a system to reboot parts that have errors. Basically, microservices before microservices were cool.

== Concurrency ==

CPUs are no longer getting dramatically faster each year. Instead, we get machines with more cores. Our code can run faster, but only if it can run concurrently - meaning, different bits of code run simultaneously on different cores.

The main problem with concurrent code is having two pieces of code mess with the same data at the same time, creating unexpected results. Object-oriented languages like Ruby don’t provide great tools for avoiding such problems. But functional languages, like Elixir, do.

Writing concurrent code in Elixir is extremely easy, and it’s nearly impossible to accidentally interfere with other code that is running at the time.

== Simplicity ==

For modern web applications (written in languages like PHP or Ruby on Rails) to do everything we require of them, they depend on a lot of other pieces running on the server, for example:

* Only one web request can be handled at a time, and it is not possible to spin up new processes as needed, so tools are needed to spawn multiple application servers up front and put a web server like Nginx in front of them to hand off requests.
* It is not possible to do slow background tasks without blocking web requests, so something like [http://resque.github.io Resque] needs to be added to take care of running background jobs.
* It is not advisable to use a precious process to maintain a websocket connection with a user, so something like Pusher needs to be added to get realtime functionality (meaning extra costs).
* It is not possible to keep a big process running all the time to do scheduled tasks, so a dependency on cron needs to be added.
* No built-in tool for managing multiple parts of a running system currently exists, so tools like [https://www.theforeman.org foreman] are used to start and monitor them.

In Elixir on the other hand, it is possible to spin up a nearly limitless number of processes as needed, so it is possible (in theory) to forego all those tools above.

Elixir code is also simpler to understand than object-oriented code because it has explicitness as a value.

<blockquote>“Functional programming is associated with concurrency but it was not by design. It just happens that, by making the complex parts of our system explicit, solving more complicated issues like concurrency becomes much simpler.” - [http://www.sitepoint.com/an-interview-with-elixir-creator-jose-valim/ Jose Valim]
</blockquote>

== Flexibility ==

Using Phoenix and Elixir opens the door to building applications that are not possible with other web frameworks.

The Phoenix framework has first-class support for realtime communication via websockets (with polling as a fallback). In benchmarks, the creators have been able to[http://www.phoenixframework.org/blog/the-road-to-2-million-websocket-connections serve 2 million simultaneously-connected clients]. Additionally, they already have native channel clients for iOS, Android, and Windows devices. With that kind of support, you can confidently build servers to support chat, networked games, and more.

== Correctness ==

In Rails, ActiveRecord encourages developers to do all data validation in application code. However, validations that depend on the state of the database can only be reliably done by the database, using constraints or locks. This includes things like:

* Does any user have this username right now? (uniqueness constraint)
* Does post 5 exist still right now, before I comment on it? (foreign key constraint)
* Does this user’s account have enough money to cover this purchase right now? (CHECK constraint)
* Is this rental property reserved for June 8 right now? (EXCLUDE constraint on date ranges)

It is possible to use such constraints with a Rails application, but it is not typical to do so, and the tools do not encourage it.

Elixir’s [https://hexdocs.pm/ecto/Ecto.html Ecto] database library embraces database constraints, with built-in support for adding them, catching constraint violations, and turning them back into friendly user-facing error messages.

== Where Elixir is especially suited ==

Any project that is a good fit for Rails or Python is something that could be done in Phoenix, especially if the project involves any or multiple of the following:

* System expecting high traffic or requiring very fast / consistent response times
* Minimal downtime being crucial
* Realtime updates (eg, stock ticker, social media)
* Bidirectional realtime communication with websockets (eg, chat, games)

= Drawbacks of Elixir =

Some potential downsides of using Elixir, along with mitigating actions:

* Fewer Elixir developers available. However:
** There are also significantly fewer projects competing for those people.
** There is a trend in Ruby developers wanting to cross over to Elixir.
** Developers with Erlang experience are also well suited.
** Elixir is a shiny new thing with real promise, which helps attract very enthusiastic developers.
* While Phoenix is productive, it is not as productive as older frameworks like Rails… yet. Reasons include:
** Lack of developer experience with Elixir.
** The relative newness of its open source ecosystem (documentation, forums, example code available).
** There are fewer libraries in Elixir than in older languages, so there are more times when you’d have to write something yourself. However:
*** You can use the many existing Erlang libraries.
*** New Elixir libraries are being added quickly.
*** Any remaining gaps are a chance to contribute to the community by creating a great open source tool.
* It may be harder to convince people to use Elixir, given that it’s currently obscure - not in the top [https://www.tiobe.com/tiobe-index/ 50 TIOBE index]. However:
** Erlang is better-known. Elixir compiles to Erlang bytecode, runs on the Erlang VM and can use or be used by Erlang code. It’s basically “Erlang made friendlier”.
** Joe Armstrong, co-creator of Erlang, said of pre-1.0 Elixir in 2013 that it was "good s**t".
** Therefore, if we can convince someone on Erlang, Elixir is a no-brainer.

= What’s next for MoodleNet’s development =

== A generic agent-centric approach to federation? ==

Another fediverse app being developed in Elixir ([https://github.com/beta-phenylethylamine/fontina Fontina], for photo sharing - although it has been put on hiatus) is now working on a [https://github.com/fontina-project/pubstomp generic ActivityPub server] to serve as back-end (there may be a good opportunity to join efforts…) Here is how the developer describes it:

<blockquote>“I’m working on pubstomp, a generic AP server that is intended for services like mastodon/pixelfed/peertube to work as frontends to it and would indeed support single account [per person, versus having an account on an instance of each of those apps]. > That said, one of my goals down the road is to build”api adaptors" that would basically plug into pubstomp and adapt to, say, the mastoAPI, pleromaAPI, etc.”</blockquote>

This is a good example of an '''agent-centric approach''', where instead of having one '''monolithic app per use-case''' it is possible instead to separate out federation logic and custom app logic (both back-ends could still share a database on the same server, and share a JavaScript-based front-end app that talks to both APIs).

I started a [https://social.coop/@mayel/100469525067581562 thread about this on the fediverse] (please join the conversation!):

<blockquote>There’s need for a generic agent-centric #ActivityPub server, so that instead of signing up to a bunch of different servers, a user could have their identity and data all in one place, and all the apps they use (clients, but if necessary server-side “plugins” as well) would interact with the activity/objects types that they support.</blockquote>

== The plan for Moodlenet (so far) ==

# Fork the Pleroma back-end to create a set of ActivityPub libraries (or a generic ActivityPub server)
# Add suport for authenticating as OAuth client
# Add support for group accounts (agents that represent a several users)
# Create ActivityStreams extensions
# Test federation
# Possibly add [https://graphql.org GraphQL] client-server API
# Create front-end app with React.js (web and mobile)

We are planning to fork the [https://git.pleroma.social/pleroma/pleroma Pleroma back-end] to '''create a set of ActivityPub/ActivityStreams libraries'''. If that proves to not be feasible, we will turn it into a generic ActivityPub server back-end that can support any type of activity and object (including extensions to ActivityStreams) and is easily extensible which doesn’t ship with any frontend (possible name: ''Pub of the Commons''). Pleroma is written with [https://elixir-lang.org Elixir]’s [https://phoenixframework.org Phoenix Framework], and licensed as AGPL (which is also being used for MoodleNet) so the upstream project will be able to use any improvements we make.

Firstly, any parts of the code coming from Pleroma that we don’t needed will be removed (like support for the deprecated OStatus protocol, and the two front-ends which ship with Pleroma - its own Vue.js interface and Mastodon’s React.js interface), and we’ll add some things that can be '''universally useful''' like '''support for groups''' (actors made of several users), a basic HTML registration/authentication interface (and '''OAuth client''' functionality, so users can sign in using their existing accounts elsewhere) so that at least those things can be done without relying on a front-end app.

While we work on creating models/vocabulary for MoodleNet, we can use this generic ActivityPub server to test our ActivityStreams extensions and make sure federation works well in real time (using the API only). Only once that is ready, will we start plugging in custom MoodleNet logic and developing the front-end app (which is the reverse from many fediverse app projects, who have first implemented MVPs of their use case, and then often find it challenging to add federation on top).

Regarding the connection between the back-end and front-end app, the ActivityPub standard comes with a suggested [https://www.w3.org/TR/activitypub/#client-to-server-interactions client-server REST API specification], but for some reason Mastodon and many other fediverse apps have created their own custom REST APIs (and Pleroma implemented Mastodon’s so that it can share front-end apps). So an interesting option at this point for MoodleNet (and ''Pub of the Commons''), may be to still support Mastodon’s client REST API (for compatibility with existing front-ends like [https://github.com/nolanlawson/pinafore Pinafore]) and additionally to '''implement a new GraphQL-based API that would allow more flexibility and extensibility between the server and front-end apps''' (any functionality/activities/objects not supported by Mastodon would only have to be implemented in the server-to-server REST API and the [https://graphql.org GraphQL] API).

= References =

* [https://ethercalc.org/fediverse-stacks Spreadsheet of fediverse apps and their stacks]
* [https://www.w3.org/TR/activitypub/ ActivityPub] standard (for federation)
* [https://www.w3.org/TR/activitystreams-core/ ActivityStreams] & its [https://www.w3.org/TR/activitystreams-vocabulary/ vocabulary] (which ActivityPub uses as a data format)
* [https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/ How to implement a basic Mastodon-compatible server]
* [https://github.com/bignerdranch/why_elixir Why elixir] (big tanks to Big Nerd Ranch for some of the great material used in this doc!)
* [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ Choosing Elixir for the Code, not the Performance]
* [https://git.pleroma.social/pleroma/pleroma/wikis/Hacking-Pleroma:-Elixir,-Phoenix-and-a-bit-of-ActivityPub Pleroma’s architecture]

MoodleNet/1.0/Decision Log

2018-08-06T15:41:04Z

Mayel:

<< [https://docs.moodle.org/dev/MoodleNet Back to MoodleNet index]

----

This page serves as a log of decisions made during the development of Project MoodleNet, along with a brief justification.

* 6 Aug 18 - [https://docs.moodle.org/dev/MoodleNet/tech/stack Elixir will be the main programming language] used by MoodleNet's back-end
* 13th June 18 - Initial integration will be with MoodleCloud, as that makes it easier in terms of versioning and tightly controlling data flows.
* 6th June 18 - We're going to use GitLab now that Microsoft has acquired GitHub.
* 23rd Apr 18 - Martin has decided we are going with the name 'MoodleNet'.
* Feb 18 - the MVP should be focused on resource curation so that we're not just dropping people into a social network that doesn't have a particular purpose
* 9th Jan 18 - Renaming 'News feed' component of project to 'Activity feed' to more accurately describe what we're developing.
* 3rd Jan 18 - Social sign-in shouldn't be the ''only'' way to log in to Project MoodleNet ([http://dougbelshaw.com/blog/2018/01/03/identity-on-the-web/ rationale])

MoodleNet/tech/stack

2018-08-06T15:38:58Z

Mayel:

= Rationale for choosing Elixir for the MoodleNet back-end =

'''Author:''' Mayel de Borniol (Technical Architect)

'''Date:''' 6 August 2018

-----

== Introduction ==

MoodleNet is a new open social media platform for educators, focused on professional development and open content. It will be an integral part of the Moodle ecosystem.

Just like the ~7,000 languages that are spoken in the world today, there are many different types of programming languages that allow humans to communicate with computers (and tell them nicely what to do). An important decision for our team was what technical language(s) Moodlenet should speak, and this document highlights the decision-making process which ended up with choosing the ‘Elixir’ language.

== Research process ==

The process began with an extensive review of web application programming languages. More specifically, the technologies used for apps based on [https://en.wikipedia.org/wiki/ActivityPub ActivityPub federation standard] - which will enable MoodleNet to be a '''decentralised platform, you will be able self-host an instance''' (just like you can install Moodle on a server, and customise it) but all the instances will be '''interconnected'''.

A [https://ethercalc.org/fediverse-stacks spreadsheet of fediverse apps and their stacks] (and [https://social.coop/@mayel/100469319126679591 crowdsourced extra information via the fediverse]) was compiled. This showed that besides Ruby on Rails, there were a few ActivityPub projects using Python (and a couple intending to use PHP) and some other languages, however, most projects are still in early development and many are not yet federated. Considering that '''ActivityPub is still relatively new it is understandable that there are limited examples of full implementations''', let alone ones that are proven to work and be interoperable.

One of the first languages that stood out was Go, one of the only a few to actually have an [https://github.com/go-fed/activity ActivityPub library]. The developer was contacted and offered his assistance for future collaboration (although in full-time employment and developing the Go library in his spare time). What this meant was that the MoodleNet team would have to modify the library in order to tailor it to the project’s needs. The main obstacle to this, however, is that Go is a ‘statically typed’ language which means every ActivityStreams extension would have to be hard coded pre-compilation. This would make things less flexible, so this option was set aside.

Alongside researching the documentations, codebases, issue trackers and communicating with developers of the apps in the spreadsheet, many of them were installed and tested (including Mastodon, Pleroma, and Prismo). The latter, while having some functionality that MoodleNet will need, confirmed an earlier impression from running a Mastodon instance: '''Rails apps tend to not be lightweight and often rely on many external dependencies'''.

After comparing the possible language candidates, the focus shifted on detailing the pros and cons for each, finally focusing on the following:

* The '''[https://en.wikipedia.org/wiki/BEAM_(Erlang_virtual_machine) Erlang VM]''' is time tested (more than 20 years old), very fast and has good concurrency and inter-process communication (called OTP).
* '''[https://elixir-lang.org Elixir]''' is a new (7+ years) functional language designed for productivity and maintainability that runs on the Erlang VM.
* '''[https://phoenixframework.org Phoenix]''' is a modern web framework that makes building APIs and web applications easy. Since it’s built with Elixir and runs on Erlang VM, it is very fast and has excellent support for handling very large numbers of simultaneous users.

= Benefits of Elixir =

A list of reasons to use Elixir in our context:

== Performance ==

The Phoenix web framework has been found to perform better than Rails, PHP, and Python. [https://github.com/mroth/phoenix-showdown/blob/master/README.md#benchmarking One benchmark] showed Phoenix handling over 10x more requests than Rails in a given period. Phoenix was also much more consistent under load - Rails was more prone to have some requests bog down. This can cause a “chain reaction”, because Rails apps are configured with a fixed number of application processes, so if some of them are slow, it can mean that others have to wait in line, which dramatically increases the app’s response time.

Furthermore, Phoenix apps '''without caching''' drastically outperform Rails apps '''with caching'''. This is important because caching is notorious for being a source of complexity and bugs, and because caching can’t be used for moment-by-moment, personalised content. The [https://youtu.be/AdY5AfXs7aw?t=3m14s Bleacher Report] for example went from over 100 AWS servers to 5, with CPU usage rarely going above 10%, and saw a 10x performance improvement over their Rails app.

There are a growing number of software projects using Elixir - e.g. Pinterest [https://github.com/bignerdranch/why_elixir who say]:

<blockquote>“We like Elixir and have seen some pretty big wins with it. The system that manages rate limits for both the Pinterest API and Ads API is built in Elixir. Its 50 percent response time is around 500 microseconds with a 90 percent response time of 800 microseconds. Yes, microseconds.”
</blockquote>

And an [https://blog.carbonfive.com/2016/04/19/elixir-and-phoenix-the-future-of-web-apis-and-apps/ adopter of the Phoenix framework] says:

<blockquote>“A rather large JSON request was taking about 1.5-2.0s against our Rails backend (no caching). That same request (same h/w, database queries and data) takes about 400ms with Phoenix. Our entire application went from using just shy of 1 GB across 2 dynos to a single dyno using less than 100 MB. That single dyno is notably faster and can handle higher concurrency (about 10x). Importantly, Phoenix (without caching) performs better than Rails (with caching).”</blockquote>

One thing that makes Erlang/Elixir so efficient is [https://www.brianstorti.com/the-actor-model/ the actor model], which ActivityPub seems to have taken inspiration from.

== Scalability ==

The Erlang VM’s model of concurrency is great for multi-core CPUs, but it was created before they existed. Its original purpose was to support concurrency and fault-tolerance via the use of many different machines. This makes it an excellent tool for building systems that can handle more load by simply adding more servers.

As the [http://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/ docs for an Erlang web server] put it:

<blockquote>“At the time of writing there are application servers written in Erlang that can handle more than two million connections on a single server in a real production application, with spare memory and CPU! The Web is concurrent, and Erlang is a language designed for concurrency, so it is a perfect match. Of course, various platforms need to scale beyond a few million connections. This is where Erlang’s built-in distribution mechanisms come in. If one server isn’t enough, add more! Erlang allows you to use the same code for talking to local processes or to processes in other parts of your cluster, which means you can scale very quickly if the need arises.”
</blockquote>

== Developer Productivity & Happiness ==

When people argue about programming languages, often the performance card is pulled (“this language is so much faster in these benchmarks”). But performance isn’t the only consideration: while it’s possible to just add more servers, developer time often costs more than servers.

More important then is which framework helps write software faster, of a better quality, and which benefits the programmer’s wellbeing.

As Pinterest concluded from using Elixir:

<blockquote>“We’ve also seen an improvement in code clarity. We’re converting our notifications system from Java to Elixir. The Java version used an Actor system and weighed in at around 10,000 lines of code. The new Elixir system has shrunk this to around 1000 lines. The Elixir based system is also faster and more consistent than the Java one and runs on half the number of servers.”</blockquote>

And [http://www.techworld.com/apps-wearables/how-elixir-helped-bleacher-report-handle-8x-more-traffic-3653957/ Bleacher Report], who went from 150 servers to 5 using Elixir: > "The new language has led to cleaner code base and much less technical debt. It has also increased the speed of development.

Some [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ advantages of Elixir for programmers] include:

* No extra engineering spent on “making it faster” (if the runtime is already fast enough they don’t need to bother with caching for example).
* All the goodies of modern day programming, like a package manager.
* Pattern Matching: you can make assertions on the structure and can get values directly out of a deeply nested map (or list) and put their value into a variable. You also have method overloading and Elixir will try to match the functions from top to bottom which means you can have different function definitions based on the structure of your input data.
* Immutable data structures & pure functions: Everything that the function depends on is a parameter, and the only thing that “happens” is the return value of the function. There are no instance variables that are difficult to debug.
* Explicit code: For example, you explicitly specify a template by name, and pass the values you’ll need from the controller. Ecto also gives you more control over what data will be loaded from the DB.
* [https://hexdocs.pm/ecto/Ecto.Changeset.html Ecto Changesets]: filtering, casting, validation and definition of constraints when manipulating DB data.
* Optional type-checking: use [https://github.com/jeremyjh/dialyxir typing only when you want to].
* Parallelism: it’s not just about performance! Parallelism in the Erlang VM low cost and seamless. Spawning a new process (not like an OS process, they are more like actors) is easy and has a very low overhead, unlike starting a new thread. You can have millions of them on one machine. And thanks to immutability guarantees and every process being isolated you don’t have to worry about processes messing with each other.
* Doc tests: It is possible to write code examples directly in the documentation of a method. These will be executed during test runs and check if they still return the same values/still pass. They are also included in the generated documentation.

== Reliability ==

While Elixir is a fairly new language, it is mostly a friendly interface to the Erlang virtual machine, which has been used since the 80s to build some of the most reliable systems in the world: telephone systems.

It is made for running a complex system with almost no downtime, like having multiple levels of “supervising” processes in a system to reboot parts that have errors. Basically, microservices before microservices were cool.

== Concurrency ==

CPUs are no longer getting dramatically faster each year. Instead, we get machines with more cores. Our code can run faster, but only if it can run concurrently - meaning, different bits of code run simultaneously on different cores.

The main problem with concurrent code is having two pieces of code mess with the same data at the same time, creating unexpected results. Object-oriented languages like Ruby don’t provide great tools for avoiding such problems. But functional languages, like Elixir, do.

Writing concurrent code in Elixir is extremely easy, and it’s nearly impossible to accidentally interfere with other code that is running at the time.

== Simplicity ==

For modern web applications (written in languages like PHP or Ruby on Rails) to do everything we require of them, they depend on a lot of other pieces running on the server, for example:

* Only one web request can be handled at a time, and it is not possible to spin up new processes as needed, so tools are needed to spawn multiple application servers up front and put a web server like Nginx in front of them to hand off requests.
* It is not possible to do slow background tasks without blocking web requests, so something like [http://resque.github.io Resque] needs to be added to take care of running background jobs.
* It is not advisable to use a precious process to maintain a websocket connection with a user, so something like Pusher needs to be added to get realtime functionality (meaning extra costs).
* It is not possible to keep a big process running all the time to do scheduled tasks, so a dependency on cron needs to be added.
* No built-in tool for managing multiple parts of a running system currently exists, so tools like [https://www.theforeman.org foreman] are used to start and monitor them.

In Elixir on the other hand, it is possible to spin up a nearly limitless number of processes as needed, so it is possible (in theory) to forego all those tools above.

Elixir code is also simpler to understand than object-oriented code because it has explicitness as a value.

<blockquote>“Functional programming is associated with concurrency but it was not by design. It just happens that, by making the complex parts of our system explicit, solving more complicated issues like concurrency becomes much simpler.” - [http://www.sitepoint.com/an-interview-with-elixir-creator-jose-valim/ Jose Valim]
</blockquote>

== Flexibility ==

Using Phoenix and Elixir opens the door to building applications that are not possible with other web frameworks.

The Phoenix framework has first-class support for realtime communication via websockets (with polling as a fallback). In benchmarks, the creators have been able to[http://www.phoenixframework.org/blog/the-road-to-2-million-websocket-connections serve 2 million simultaneously-connected clients]. Additionally, they already have native channel clients for iOS, Android, and Windows devices. With that kind of support, you can confidently build servers to support chat, networked games, and more.

== Correctness ==

In Rails, ActiveRecord encourages developers to do all data validation in application code. However, validations that depend on the state of the database can only be reliably done by the database, using constraints or locks. This includes things like:

* Does any user have this username right now? (uniqueness constraint)
* Does post 5 exist still right now, before I comment on it? (foreign key constraint)
* Does this user’s account have enough money to cover this purchase right now? (CHECK constraint)
* Is this rental property reserved for June 8 right now? (EXCLUDE constraint on date ranges)

It is possible to use such constraints with a Rails application, but it is not typical to do so, and the tools do not encourage it.

Elixir’s [https://hexdocs.pm/ecto/Ecto.html Ecto] database library embraces database constraints, with built-in support for adding them, catching constraint violations, and turning them back into friendly user-facing error messages.

== Where Elixir is especially suited ==

Any project that is a good fit for Rails or Python is something that could be done in Phoenix, especially if the project involves any or multiple of the following:

* System expecting high traffic or requiring very fast / consistent response times
* Minimal downtime being crucial
* Realtime updates (eg, stock ticker, social media)
* Bidirectional realtime communication with websockets (eg, chat, games)

= Drawbacks of Elixir =

Some potential downsides of using Elixir, along with mitigating actions:

* Fewer Elixir developers available. However:
** There are also significantly fewer projects competing for those people.
** There is a trend in Ruby developers wanting to cross over to Elixir.
** Developers with Erlang experience are also well suited.
** Elixir is a shiny new thing with real promise, which helps attract very enthusiastic developers.
* While Phoenix is productive, it is not as productive as older frameworks like Rails… yet. Reasons include:
** Lack of developer experience with Elixir.
** The relative newness of its open source ecosystem (documentation, forums, example code available).
** There are fewer libraries in Elixir than in older languages, so there are more times when you’d have to write something yourself. However:
*** You can use the many existing Erlang libraries.
*** New Elixir libraries are being added quickly.
*** Any remaining gaps are a chance to contribute to the community by creating a great open source tool.
* It may be harder to convince people to use Elixir, given that it’s currently obscure - not in the top [https://www.tiobe.com/tiobe-index/ 50 TIOBE index]. However:
** Erlang is better-known. Elixir compiles to Erlang bytecode, runs on the Erlang VM and can use or be used by Erlang code. It’s basically “Erlang made friendlier”.
** Joe Armstrong, co-creator of Erlang, said of pre-1.0 Elixir in 2013 that it was "good s**t".
** Therefore, if we can convince someone on Erlang, Elixir is a no-brainer.

= What’s next for MoodleNet’s development =

== A generic agent-centric approach to federation? ==

Another fediverse app being developed in Elixir ([https://github.com/beta-phenylethylamine/fontina Fontina], for photo sharing - although it has been put on hiatus) is now working on a [https://github.com/fontina-project/pubstomp generic ActivityPub server] to serve as back-end (there may be a good opportunity to join efforts…) Here is how the developer describes it:

<blockquote>“I’m working on pubstomp, a generic AP server that is intended for services like mastodon/pixelfed/peertube to work as frontends to it and would indeed support single account [per person, versus having an account on an instance of each of those apps]. > That said, one of my goals down the road is to build”api adaptors" that would basically plug into pubstomp and adapt to, say, the mastoAPI, pleromaAPI, etc.”</blockquote>

This is a good example of an '''agent-centric approach''', where instead of having one '''monolithic app per use-case''' it is possible instead to separate out federation logic and custom app logic (both back-ends could still share a database on the same server, and share a JavaScript-based front-end app that talks to both APIs).

I started a [https://social.coop/@mayel/100469525067581562 thread about this on the fediverse] (please join the conversation!):

<blockquote>There’s need for a generic agent-centric #ActivityPub server, so that instead of signing up to a bunch of different servers, a user could have their identity and data all in one place, and all the apps they use (clients, but if necessary server-side “plugins” as well) would interact with the activity/objects types that they support.</blockquote>

== The plan for Moodlenet (so far) ==

# Fork the Pleroma back-end to create a set of ActivityPub libraries (or a generic ActivityPub server)
# Add suport for authenticating as OAuth client
# Add support for group accounts (agents that represent a several users)
# Create ActivityStreams extensions
# Test federation
# Possibly add [https://graphql.org GraphQL] client-server API
# Create front-end app with React.js (web and mobile)

We are planning to fork the [https://git.pleroma.social/pleroma/pleroma Pleroma back-end] to '''create a set of ActivityPub/ActivityStreams libraries'''. If that proves to not be feasible, we will turn it into a generic ActivityPub server back-end that can support any type of activity and object (including extensions to ActivityStreams) and is easily extensible which doesn’t ship with any frontend (possible name: ''Pub of the Commons''). Pleroma is written with [https://elixir-lang.org Elixir]’s [https://phoenixframework.org Phoenix Framework], and licensed as AGPL (which is also being used for MoodleNet) so the upstream project will be able to use any improvements we make.

Firstly, any parts of the code coming from Pleroma that we don’t needed will be removed (like support for the deprecated OStatus protocol, and the two front-ends which ship with Pleroma - its own Vue.js interface and Mastodon’s React.js interface), and we’ll add some things that can be '''universally useful''' like '''support for groups''' (actors made of several users), a basic HTML registration/authentication interface (and '''OAuth client''' functionality, so users can sign in using their existing accounts elsewhere) so that at least those things can be done without relying on a front-end app.

While we work on creating models/vocabulary for MoodleNet, we can use this generic ActivityPub server to test our ActivityStreams extensions and make sure federation works well in real time (using the API only). Only once that is ready, will we start plugging in custom MoodleNet logic and developing the front-end app (which is the reverse from many fediverse app projects, who have first implemented MVPs of their use case, and then often find it challenging to add federation on top).

Regarding the connection between the back-end and front-end app, the ActivityPub standard comes with a suggested [https://www.w3.org/TR/activitypub/#client-to-server-interactions client-server REST API specification], but for some reason Mastodon and many other fediverse apps have created their own custom REST APIs (and Pleroma implemented Mastodon’s so that it can share front-end apps). So an interesting option at this point for MoodleNet (and ''Pub of the Commons''), may be to still support Mastodon’s client REST API (for compatibility with existing front-ends like [https://github.com/nolanlawson/pinafore Pinafore]) and additionally to '''implement a new GraphQL-based API that would allow more flexibility and extensibility between the server and front-end apps''' (any functionality/activities/objects not supported by Mastodon would only have to be implemented in the server-to-server REST API and the [https://graphql.org GraphQL] API).

= References =

* [https://ethercalc.org/fediverse-stacks Spreadsheet of fediverse apps and their stacks]
* [https://www.w3.org/TR/activitypub/ ActivityPub] standard (for federation)
* [https://www.w3.org/TR/activitystreams-core/ ActivityStreams] & its [https://www.w3.org/TR/activitystreams-vocabulary/ vocabulary] (which ActivityPub uses as a data format)
* [https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/ How to implement a basic Mastodon-compatible server]
* [https://github.com/bignerdranch/why_elixir Why elixir] (big tanks to Big Nerd Ranch for some of the great material used in this doc!)
* [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ Choosing Elixir for the Code, not the Performance]
* [https://git.pleroma.social/pleroma/pleroma/wikis/Hacking-Pleroma:-Elixir,-Phoenix-and-a-bit-of-ActivityPub Pleroma’s architecture]

MoodleNet/tech/stack

2018-08-06T14:42:07Z

Mayel: Created page with "= Rationale for choosing Elixir for the MoodleNet back-end = '''Author:''' Mayel de Borniol (Technical Architect) '''Date:''' 6 August 2018 ----- == Introduction == Mood..."

= Rationale for choosing Elixir for the MoodleNet back-end =

'''Author:''' Mayel de Borniol (Technical Architect)

'''Date:''' 6 August 2018

-----

== Introduction ==

MoodleNet is a new open social media platform for educators, focussed on professional development and open content. It will be an integral part of the Moodle ecosystem.

Just like the ~7,000 languages that are spoken in the world today, there many different types of programming languages that allow humans to communicate with computers (and tell them nicely what to do). An important decision for our team was what technical language(s) Moodlenet should speak, and this document highlights the decision-making process which ended up with choosing the ‘Elixir’ language.

== Research process ==

The process began with an extensive review of web application appprogramming languages. More specifically, the technologies used for apps based on [https://en.wikipedia.org/wiki/ActivityPub ActivityPub federation standard] - which will enable MoodleNet to be a '''decentralised platform, you will be able self-host an instance''' (just like you can install Moodle on a server, and customise it) but all the instances will be '''interconnected'''.

A [https://ethercalc.org/fediverse-stacks spreadsheet of fediverse apps and their stacks] (and [https://social.coop/@mayel/100469319126679591 crowdsourced extra information via the fediverse]) was compiled. This showed that besides Ruby on Rails, there were a few ActivityPub projects using Python (and a couple intending to use PHP) and some other languages, however, most projects are still in early development and many are not yet federated. Considering that '''ActivityPub is still relatively new it is understandable that there are limited examples of full implementations''', let alone ones that are proven to work and be interoperable.

One of the first languages that stood out was Go, one of the only a few to actually have an [https://github.com/go-fed/activity ActivityPub library]. The developer was contacted and offered his assistance for future collaboration (although in full-time employment and developing the Go library in his spare time). What this meant was that the MoodleNet team would have to modify the library in order to tailor it to the project’s needs. The main obstacle to this, however, is that Go is a ‘statically typed’ language which means every ActivityStreams extension would have to be hard coded pre-compilation. This would make things less flexible, so this option was set aside.

Alongside researching the documentations, codebases, issue trackers and communicating with developers of the apps in the spreadsheet, many of them were installed and tested (including Mastodon, Pleroma, and Prismo). The latter, while having some functionality that MoodleNet will need, confirmed an earlier impression from running a Mastodon instance: '''Rails apps tend to not be lightweight and often rely on many external dependencies'''.

After comparing the possible language candidates, the focus shifted on detailing the pros and cons for each, finaly focusing on the following:

* The '''[https://en.wikipedia.org/wiki/BEAM_(Erlang_virtual_machine) Erlang VM]''' is time tested (more than 20 years old), very fast and has good concurrency and inter-process communication (called OTP).
* '''[https://elixir-lang.org Elixir]''' is a new (7+ years) functional language designed for productivity and maintainability that runs on the Erlang VM.
* '''[https://phoenixframework.org Phoenix]''' is a modern web framework that makes building APIs and web applications easy. Since it’s built with Elixir and runs on Erlang VM, it is very fast and has excellent support for handling very large numbers of simultaneous users.

= Benefits of Elixir =

A list of reasons to use Elixir in our context:

== Performance ==

The Phoenix web framework has been found to perform better than Rails, PHP, and Python. [https://github.com/mroth/phoenix-showdown/blob/master/README.md#benchmarking One benchmark] showed Phoenix handling over 10x more requests than Rails in a given period. Phoenix was also much more consistent under load - Rails was more prone to have some requests bog down. This can cause a “chain reaction”, because Rails apps are configured with a fixed number of application processes, so if some of them are slow, it can mean that others have to wait in line, which dramatically increases the app’s response time.

Furthermore, Phoenix apps '''without caching''' drastically outperform Rails apps '''with caching'''. This is important because caching is notorious for being a source of complexity and bugs, and because caching can’t be used for moment-by-moment, personalized content. The [https://youtu.be/AdY5AfXs7aw?t=3m14s Bleacher Report] for example went from over 100 AWS servers to 5, with CPU usage rarely going above 10%, and saw a 10x performance improvement over their Rails app.

There are a growing number of software projects using Elixir - e.g. Pinterest [https://github.com/bignerdranch/why_elixir who say]:

<blockquote>“We like Elixir and have seen some pretty big wins with it. The system that manages rate limits for both the Pinterest API and Ads API is built in Elixir. Its 50 percent response time is around 500 microseconds with a 90 percent response time of 800 microseconds. Yes, microseconds.”
</blockquote>
And an [https://blog.carbonfive.com/2016/04/19/elixir-and-phoenix-the-future-of-web-apis-and-apps/ adopter of the Phoenix framework] says: > “A rather large JSON request was taking about 1.5-2.0s against our Rails backend (no caching). That same request (same h/w, database queries and data) takes about 400ms with Phoenix. Our entire application went from using just shy of 1 GB across 2 dynos to a single dyno using less than 100 MB. That single dyno is notably faster and can handle higher concurrency (about 10x). Importantly, Phoenix (without caching) performs better than Rails (with caching).”

One thing that makes Erlang/Elixir so efficient is [https://www.brianstorti.com/the-actor-model/ the actor model], which ActivityPub seems to have taken inspiration from.

== Scalability ==

The Erlang VM’s model of concurrency is great for multi-core CPUs, but it was created before they existed. Its original purpose was to support concurrency and fault-tolerance via the use of many different machines. This makes it an excellent tool for building systems that can handle more load by simply adding more servers.

As the [http://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/ docs for an Erlang web server] put it:

<blockquote>“At the time of writing there are application servers written in Erlang that can handle more than two million connections on a single server in a real production application, with spare memory and CPU! The Web is concurrent, and Erlang is a language designed for concurrency, so it is a perfect match. Of course, various platforms need to scale beyond a few million connections. This is where Erlang’s built-in distribution mechanisms come in. If one server isn’t enough, add more! Erlang allows you to use the same code for talking to local processes or to processes in other parts of your cluster, which means you can scale very quickly if the need arises.”
</blockquote>
== Developer Productivity & Happiness ==

When people argue about programming languages, often the performance card is pulled (“this language is so much faster in these benchmarks”). But performance isn’t the only consideration: while it’s possible to just add more servers, developer time often costs more than servers.

More important then is which framework helps write software faster, of a better quality, and which benefits the programmer’s wellbeing.

As Pinterest concluded from using Elixir: > “We’ve also seen an improvement in code clarity. We’re converting our notifications system from Java to Elixir. The Java version used an Actor system and weighed in at around 10,000 lines of code. The new Elixir system has shrunk this to around 1000 lines. The Elixir based system is also faster and more consistent than the Java one and runs on half the number of servers.”

And [http://www.techworld.com/apps-wearables/how-elixir-helped-bleacher-report-handle-8x-more-traffic-3653957/ Bleacher Report], who went from 150 servers to 5 using Elixir: > "The new language has led to cleaner code base and much less technical debt. It has also increased the speed of development.

Some [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ advantages of Elixir for programmers] include:

* No extra engineering spent on “making it faster” (if the runtime is already fast enough they don’t need to bother with caching for example).
* All the goodies of modern day programming, like a package manager.
* Pattern Matching: you can make assertions on the structure and can get values directly out of a deeply nested map (or list) and put their value into a variable. You also have method overloading and Elixir will try to match the functions from top to bottom which means you can have different function definitions based on the structure of your input data.
* Immutable data structures & pure functions: Everything that the function depends on is a parameter, and the only thing that “happens” is the return value of the function. There are no instance variables that are difficult to debug.
* Explicit code: For example, you explicitly specify a template by name, and pass the values you’ll need from the controller. Ecto also gives you more control over what data will be loaded from the DB.
* [https://hexdocs.pm/ecto/Ecto.Changeset.html Ecto Changesets]: filtering, casting, validation and definition of constraints when manipulating DB data.
* Optional type-checking: use [https://github.com/jeremyjh/dialyxir typing only when you want to].
* Parallelism: it’s not just about performance! Parallelism in the Erlang VM low cost and seamless. Spawning a new process (not like an OS process, they are more like actors) is easy and has a very low overhead, unlike starting a new thread. You can have millions of them on one machine. And thanks to immutability guarantees and every process being isolated you don’t have to worry about processes messing with each other.
* Doc tests: It is possible to write code examples directly in the documentation of a method. These will be executed during test runs and check if they still return the same values/still pass. They are also included in the generated documentation.

== Reliability ==

While Elixir is a fairly new language, it is mostly a friendly interface to the Erlang virtual machine, which has been used since the 80s to build some of the most reliable systems in the world: telephone systems.

It is made for running a complex system with almost no downtime, like having multiple levels of “supervising” processes in a system to reboot parts that have errors. Basically, microservices before microservices were cool.

== Concurrency ==

CPUs are no longer getting dramatically faster each year. Instead, we get machines with more cores. Our code can run faster, but only if it can run concurrently - meaning, different bits of code run simultaneously on different cores.

The main problem with concurrent code is having two pieces of code mess with the same data at the same time, creating unexpected results. Object-oriented languages like Ruby don’t provide great tools for avoiding such problems. But functional languages, like Elixir, do.

Writing concurrent code in Elixir is extremely easy, and it’s nearly impossible to accidentally interfere with other code that is running at the time.

== Simplicity ==

For modern web applications (written in languages like PHP or Ruby on Rails) to do everything we require of them, they depend on a lot of other pieces running on the server, for example: * Only one web request can be handled at a time, and it is not possible to spin up new processes as needed, so tools are needed to spawn multiple application servers up front and put a web server like Nginx in front of them to hand off requests. * It is not possible to do slow background tasks without blocking web requests, so something like [http://resque.github.io Resque] needs to be added to take care of running background jobs. * It is not advisable to use a precious process to maintain a websocket connection with a user, so something like Pusher needs to be added to get realtime functionality (meaning extra costs). * It is not possible to keep a big process running all the time to do scheduled tasks, so a dependency on cron needs to be added. * No built-in tool for managing multiple parts of a running system currently exists, so tools like [https://www.theforeman.org foreman] are used to start and monitor them.

In Elixir on the other hand, it is possible to spin up a nearly limitless number of processes as needed, so it is possible (in theory) to forego all those tools above.

Elixir code is also simpler to understand than object-oriented code because it has explicitness as a value.

<blockquote>“Functional programming is associated with concurrency but it was not by design. It just happens that, by making the complex parts of our system explicit, solving more complicated issues like concurrency becomes much simpler.” - [http://www.sitepoint.com/an-interview-with-elixir-creator-jose-valim/ Jose Valim]
</blockquote>
== Flexibility ==

Using Phoenix and Elixir opens the door to building applications that are not possible with other web frameworks.

The Phoenix framework has first-class support for realtime communication via websockets (with polling as a fallback). In benchmarks, the creators have been able to[http://www.phoenixframework.org/blog/the-road-to-2-million-websocket-connections serve 2 million simultaneously-connected clients]. Additionally, they already have native channel clients for iOS, Android, and Windows devices. With that kind of support, you can confidently build servers to support chat, networked games, and more.

== Correctness ==

In Rails, ActiveRecord encourages developers to do all data validation in application code. However, validations that depend on the state of the database can only be reliably done by the database, using constraints or locks. This includes things like:

* Does any user have this username right now? (uniqueness constraint)
* Does post 5 exist still right now, before I comment on it? (foreign key constraint)
* Does this user’s account have enough money to cover this purchase right now? (CHECK constraint)
* Is this rental property reserved for June 8 right now? (EXCLUDE constraint on date ranges)

It is possible to use such constraints with a Rails application, but it is not typical to do so, and the tools do not encourage it.

Elixir’s [https://hexdocs.pm/ecto/Ecto.html Ecto] database library embraces database constraints, with built-in support for adding them, catching constraint violations, and turning them back into friendly user-facing error messages.

== Where Elixir is especially suited ==

Any project that is a good fit for Rails or Python is something that could be done in Phoenix, especially if the project involves any or multiple of the following:

* System expecting high traffic or requiring very fast / consistent response times
* Minimal downtime being crucial
* Realtime updates (eg, stock ticker, social media)
* Bidirectional realtime communication with websockets (eg, chat, games)

= Drawbacks of Elixir =

Some potential downsides of using Elixir, along with mitigating actions:

* Fewer Elixir developers available. However:
** There are also significantly fewer projects competing for those people.
** There is a trend in Ruby developers wanting to cross over to Elixir.
** Developers with Erlang experience are also well suited.
** Elixir is a shiny new thing with real promise, which helps attract very enthusiastic developers.
* While Phoenix is productive, it is not as productive as older frameworks like Rails… yet. Reasons include:
** Lack of developer experience with Elixir.
** The relative newness of its open source ecosystem (documentation, forums, example code available).
** There are fewer libraries in Elixir than in older languages, so there are more times when you’d have to write something yourself. However:
*** You can use the many existing Erlang libraries.
*** New Elixir libraries are being added quickly.
*** Any remaining gaps are a chance to contribute to the community by creating a great open source tool.
* It may be harder to convince people to use Elixir, given that it’s currently obscure - not in the top [https://www.tiobe.com/tiobe-index/ 50 TIOBE index]. However:
** Erlang is better-known. Elixir compiles to Erlang bytecode, runs on the Erlang VM and can use or be used by Erlang code. It’s basically “Erlang made friendlier”.
** Joe Armstrong, co-creator of Erlang, said of pre-1.0 Elixir in 2013 that it was "good s**t".
** Therefore, if we can convince someone on Erlang, Elixir is a no-brainer.

= What’s next for MoodleNet’s development =

== A generic agent-centric approach to federation? ==

Another fediverse app being developed in Elixir ([https://github.com/beta-phenylethylamine/fontina Fontina], for photo sharing - although it has been put on hiatus) is now working on a [https://github.com/fontina-project/pubstomp generic ActivityPub server] to serve as back-end (there may be a good opportunity to join efforts…) Here is how the developer describes it: > “I’m working on pubstomp, a generic AP server that is intended for services like mastodon/pixelfed/peertube to work as frontends to it and would indeed support single account [per person, versus having an account on an instance of each of those apps]. > That said, one of my goals down the road is to build”api adaptors" that would basically plug into pubstomp and adapt to, say, the mastoAPI, pleromaAPI, etc.”

This is a good example of an '''agent-centric approach''', where instead of having one '''monolithic app per use-case''' it is possible instead to seperate out federation logic and custom app logic (both back-ends could still share a database on the same server, and share a JavaScript-based front-end app that talks to both APIs).

I started a [https://social.coop/@mayel/100469525067581562 thread about this on the fediverse] (please join the conversation!): > There’s need for a generic agent-centric #ActivityPub server, so that instead of signing up to a bunch of different servers, a user could have their indentity and data all in one place, and all the apps they use (clients, but if necessary server-side “plugins” as well) would interact with the activity/objects types that they support.

== The plan for Moodlenet (so far) ==

# Fork the Pleroma back-end to create a set of ActivityPub libraries (or a generic ActivityPub server)
# Add suport for authenticating as OAuth client
# Add support for group accounts (agents that represent a severa users)
# Create ActivityStreams extensions
# Test federation
# Possibly add [https://graphql.org GraphQL] client-server API
# Create front-end app with React.js (web and mobile)

We are planning to fork the [https://git.pleroma.social/pleroma/pleroma Pleroma back-end] to '''create a set of ActivityPub/ActivityStreams libraries'''. If that proves to not be feasible, we will turn it into a generic ActivityPub server back-end that can support any type of activity and object (including extensions to ActivityStreams) and is easily extensible which doesn’t ship with any frontend (possible name: ''Pub of the Commons''). Pleroma is written with [https://elixir-lang.org Elixir]’s [https://phoenixframework.org Phoenix Framework], and licenced as AGPL (which is also being used for MoodleNet) so the upstream project will be able to use any improvements we make.

Firstly, any parts of the code coming from Pleroma that we don’t needed will be removed (like support for the deprecated OStatus protocol, and the two front-ends which ship with Pleroma - its own Vue.js interface and Mastodon’s React.js interface), and we’ll add some things that can be '''universally useful''' like '''support for groups''' (actors made of several users), a basic HTML registration/authentication interface (and '''OAuth client''' functionality, so users can sign in using their existing accounts elsewhere) so that at least those things can be done without relying on a front-end app.

While we work on creating models/vocabulary for MoodleNet, we can use this generic ActivityPub server to test our ActivityStreams extensions and make sure federation works well in real time (using the API only). Only once that is ready, will we start plugging in custom MoodleNet logic and developing the front-end app (which is the reverse from many fediverse app projects, who have first implemented MVPs of their use case, and then often find it challenging to add federation on top).

Regarding the connection between the back-end and front-end app, the ActivityPub standard comes with a suggested [https://www.w3.org/TR/activitypub/#client-to-server-interactions client-server REST API specification], but for some reason Mastodon and many other fediverse apps have created their own custom REST APIs (and Pleroma implemented Mastodon’s so that it can share front-end apps). So an interesting option at this point for MoodleNet (and ''Pub of the Commons''), may be to still support Mastodon’s client REST API (for compatibillity with existing front-ends like [https://github.com/nolanlawson/pinafore Pinafore]) and additionally to '''implement a new GraphQL-based API that would allow more flexibility and extensiblity between the server and front-end apps''' (any functionality/activities/objects not supported by Mastodon would only have to be implemented in the server-to-server REST API and the [https://graphql.org GraphQL] API).

'''References'''

* [https://ethercalc.org/fediverse-stacks Spreadsheet of fediverse apps and their stacks]
* [https://www.w3.org/TR/activitypub/ ActivityPub] standard (for federation)
* [https://www.w3.org/TR/activitystreams-core/ ActivityStreams] & its [https://www.w3.org/TR/activitystreams-vocabulary/ vocabulary] (which ActivityPub uses as a data format)
* [https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/ How to implement a basic Mastodon-compatible server]
* [https://github.com/bignerdranch/why_elixir Why elixir] (big tanks to Big Nerd Ranch for some of the great material used in this doc!)
* [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ Choosing Elixir for the Code, not the Performance]
* [https://git.pleroma.social/pleroma/pleroma/wikis/Hacking-Pleroma:-Elixir,-Phoenix-and-a-bit-of-ActivityPub Pleroma’s architecture]

MoodleNet stack choice

2018-08-06T14:32:45Z

Mayel: page created

= Rationale for choosing Elixir for the MoodleNet back-end =

'''Author:''' Mayel de Borniol (Technical Architect)

'''Date:''' 6 August 2018

-----

== Introduction ==

MoodleNet is a new open social media platform for educators, focussed on professional development and open content. It will be an integral part of the Moodle ecosystem.

Just like the ~7,000 languages that are spoken in the world today, there many different types of programming languages that allow humans to communicate with computers (and tell them nicely what to do). An important decision for our team was what technical language(s) Moodlenet should speak, and this document highlights the decision-making process which ended up with choosing the ‘Elixir’ language.

== Research process ==

The process began with an extensive review of web application appprogramming languages. More specifically, the technologies used for apps based on [https://en.wikipedia.org/wiki/ActivityPub ActivityPub federation standard] - which will enable MoodleNet to be a '''decentralised platform, you will be able self-host an instance''' (just like you can install Moodle on a server, and customise it) but all the instances will be '''interconnected'''.

A [https://ethercalc.org/fediverse-stacks spreadsheet of fediverse apps and their stacks] (and [https://social.coop/@mayel/100469319126679591 crowdsourced extra information via the fediverse]) was compiled. This showed that besides Ruby on Rails, there were a few ActivityPub projects using Python (and a couple intending to use PHP) and some other languages, however, most projects are still in early development and many are not yet federated. Considering that '''ActivityPub is still relatively new it is understandable that there are limited examples of full implementations''', let alone ones that are proven to work and be interoperable.

One of the first languages that stood out was Go, one of the only a few to actually have an [https://github.com/go-fed/activity ActivityPub library]. The developer was contacted and offered his assistance for future collaboration (although in full-time employment and developing the Go library in his spare time). What this meant was that the MoodleNet team would have to modify the library in order to tailor it to the project’s needs. The main obstacle to this, however, is that Go is a ‘statically typed’ language which means every ActivityStreams extension would have to be hard coded pre-compilation. This would make things less flexible, so this option was set aside.

Alongside researching the documentations, codebases, issue trackers and communicating with developers of the apps in the spreadsheet, many of them were installed and tested (including Mastodon, Pleroma, and Prismo). The latter, while having some functionality that MoodleNet will need, confirmed an earlier impression from running a Mastodon instance: '''Rails apps tend to not be lightweight and often rely on many external dependencies'''.

After comparing the possible language candidates, the focus shifted on detailing the pros and cons for each, finaly focusing on the following:

* The '''[https://en.wikipedia.org/wiki/BEAM_(Erlang_virtual_machine) Erlang VM]''' is time tested (more than 20 years old), very fast and has good concurrency and inter-process communication (called OTP).
* '''[https://elixir-lang.org Elixir]''' is a new (7+ years) functional language designed for productivity and maintainability that runs on the Erlang VM.
* '''[https://phoenixframework.org Phoenix]''' is a modern web framework that makes building APIs and web applications easy. Since it’s built with Elixir and runs on Erlang VM, it is very fast and has excellent support for handling very large numbers of simultaneous users.

= Benefits of Elixir =

A list of reasons to use Elixir in our context:

== Performance ==

The Phoenix web framework has been found to perform better than Rails, PHP, and Python. [https://github.com/mroth/phoenix-showdown/blob/master/README.md#benchmarking One benchmark] showed Phoenix handling over 10x more requests than Rails in a given period. Phoenix was also much more consistent under load - Rails was more prone to have some requests bog down. This can cause a “chain reaction”, because Rails apps are configured with a fixed number of application processes, so if some of them are slow, it can mean that others have to wait in line, which dramatically increases the app’s response time.

Furthermore, Phoenix apps '''without caching''' drastically outperform Rails apps '''with caching'''. This is important because caching is notorious for being a source of complexity and bugs, and because caching can’t be used for moment-by-moment, personalized content. The [https://youtu.be/AdY5AfXs7aw?t=3m14s Bleacher Report] for example went from over 100 AWS servers to 5, with CPU usage rarely going above 10%, and saw a 10x performance improvement over their Rails app.

There are a growing number of software projects using Elixir - e.g. Pinterest [https://github.com/bignerdranch/why_elixir who say]:

<blockquote>“We like Elixir and have seen some pretty big wins with it. The system that manages rate limits for both the Pinterest API and Ads API is built in Elixir. Its 50 percent response time is around 500 microseconds with a 90 percent response time of 800 microseconds. Yes, microseconds.”
</blockquote>
And an [https://blog.carbonfive.com/2016/04/19/elixir-and-phoenix-the-future-of-web-apis-and-apps/ adopter of the Phoenix framework] says: > “A rather large JSON request was taking about 1.5-2.0s against our Rails backend (no caching). That same request (same h/w, database queries and data) takes about 400ms with Phoenix. Our entire application went from using just shy of 1 GB across 2 dynos to a single dyno using less than 100 MB. That single dyno is notably faster and can handle higher concurrency (about 10x). Importantly, Phoenix (without caching) performs better than Rails (with caching).”

One thing that makes Erlang/Elixir so efficient is [https://www.brianstorti.com/the-actor-model/ the actor model], which ActivityPub seems to have taken inspiration from.

== Scalability ==

The Erlang VM’s model of concurrency is great for multi-core CPUs, but it was created before they existed. Its original purpose was to support concurrency and fault-tolerance via the use of many different machines. This makes it an excellent tool for building systems that can handle more load by simply adding more servers.

As the [http://ninenines.eu/docs/en/cowboy/2.0/guide/erlang_web/ docs for an Erlang web server] put it:

<blockquote>“At the time of writing there are application servers written in Erlang that can handle more than two million connections on a single server in a real production application, with spare memory and CPU! The Web is concurrent, and Erlang is a language designed for concurrency, so it is a perfect match. Of course, various platforms need to scale beyond a few million connections. This is where Erlang’s built-in distribution mechanisms come in. If one server isn’t enough, add more! Erlang allows you to use the same code for talking to local processes or to processes in other parts of your cluster, which means you can scale very quickly if the need arises.”
</blockquote>
== Developer Productivity & Happiness ==

When people argue about programming languages, often the performance card is pulled (“this language is so much faster in these benchmarks”). But performance isn’t the only consideration: while it’s possible to just add more servers, developer time often costs more than servers.

More important then is which framework helps write software faster, of a better quality, and which benefits the programmer’s wellbeing.

As Pinterest concluded from using Elixir: > “We’ve also seen an improvement in code clarity. We’re converting our notifications system from Java to Elixir. The Java version used an Actor system and weighed in at around 10,000 lines of code. The new Elixir system has shrunk this to around 1000 lines. The Elixir based system is also faster and more consistent than the Java one and runs on half the number of servers.”

And [http://www.techworld.com/apps-wearables/how-elixir-helped-bleacher-report-handle-8x-more-traffic-3653957/ Bleacher Report], who went from 150 servers to 5 using Elixir: > "The new language has led to cleaner code base and much less technical debt. It has also increased the speed of development.

Some [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ advantages of Elixir for programmers] include:

* No extra engineering spent on “making it faster” (if the runtime is already fast enough they don’t need to bother with caching for example).
* All the goodies of modern day programming, like a package manager.
* Pattern Matching: you can make assertions on the structure and can get values directly out of a deeply nested map (or list) and put their value into a variable. You also have method overloading and Elixir will try to match the functions from top to bottom which means you can have different function definitions based on the structure of your input data.
* Immutable data structures & pure functions: Everything that the function depends on is a parameter, and the only thing that “happens” is the return value of the function. There are no instance variables that are difficult to debug.
* Explicit code: For example, you explicitly specify a template by name, and pass the values you’ll need from the controller. Ecto also gives you more control over what data will be loaded from the DB.
* [https://hexdocs.pm/ecto/Ecto.Changeset.html Ecto Changesets]: filtering, casting, validation and definition of constraints when manipulating DB data.
* Optional type-checking: use [https://github.com/jeremyjh/dialyxir typing only when you want to].
* Parallelism: it’s not just about performance! Parallelism in the Erlang VM low cost and seamless. Spawning a new process (not like an OS process, they are more like actors) is easy and has a very low overhead, unlike starting a new thread. You can have millions of them on one machine. And thanks to immutability guarantees and every process being isolated you don’t have to worry about processes messing with each other.
* Doc tests: It is possible to write code examples directly in the documentation of a method. These will be executed during test runs and check if they still return the same values/still pass. They are also included in the generated documentation.

== Reliability ==

While Elixir is a fairly new language, it is mostly a friendly interface to the Erlang virtual machine, which has been used since the 80s to build some of the most reliable systems in the world: telephone systems.

It is made for running a complex system with almost no downtime, like having multiple levels of “supervising” processes in a system to reboot parts that have errors. Basically, microservices before microservices were cool.

== Concurrency ==

CPUs are no longer getting dramatically faster each year. Instead, we get machines with more cores. Our code can run faster, but only if it can run concurrently - meaning, different bits of code run simultaneously on different cores.

The main problem with concurrent code is having two pieces of code mess with the same data at the same time, creating unexpected results. Object-oriented languages like Ruby don’t provide great tools for avoiding such problems. But functional languages, like Elixir, do.

Writing concurrent code in Elixir is extremely easy, and it’s nearly impossible to accidentally interfere with other code that is running at the time.

== Simplicity ==

For modern web applications (written in languages like PHP or Ruby on Rails) to do everything we require of them, they depend on a lot of other pieces running on the server, for example: * Only one web request can be handled at a time, and it is not possible to spin up new processes as needed, so tools are needed to spawn multiple application servers up front and put a web server like Nginx in front of them to hand off requests. * It is not possible to do slow background tasks without blocking web requests, so something like [http://resque.github.io Resque] needs to be added to take care of running background jobs. * It is not advisable to use a precious process to maintain a websocket connection with a user, so something like Pusher needs to be added to get realtime functionality (meaning extra costs). * It is not possible to keep a big process running all the time to do scheduled tasks, so a dependency on cron needs to be added. * No built-in tool for managing multiple parts of a running system currently exists, so tools like [https://www.theforeman.org foreman] are used to start and monitor them.

In Elixir on the other hand, it is possible to spin up a nearly limitless number of processes as needed, so it is possible (in theory) to forego all those tools above.

Elixir code is also simpler to understand than object-oriented code because it has explicitness as a value.

<blockquote>“Functional programming is associated with concurrency but it was not by design. It just happens that, by making the complex parts of our system explicit, solving more complicated issues like concurrency becomes much simpler.” - [http://www.sitepoint.com/an-interview-with-elixir-creator-jose-valim/ Jose Valim]
</blockquote>
== Flexibility ==

Using Phoenix and Elixir opens the door to building applications that are not possible with other web frameworks.

The Phoenix framework has first-class support for realtime communication via websockets (with polling as a fallback). In benchmarks, the creators have been able to[http://www.phoenixframework.org/blog/the-road-to-2-million-websocket-connections serve 2 million simultaneously-connected clients]. Additionally, they already have native channel clients for iOS, Android, and Windows devices. With that kind of support, you can confidently build servers to support chat, networked games, and more.

== Correctness ==

In Rails, ActiveRecord encourages developers to do all data validation in application code. However, validations that depend on the state of the database can only be reliably done by the database, using constraints or locks. This includes things like:

* Does any user have this username right now? (uniqueness constraint)
* Does post 5 exist still right now, before I comment on it? (foreign key constraint)
* Does this user’s account have enough money to cover this purchase right now? (CHECK constraint)
* Is this rental property reserved for June 8 right now? (EXCLUDE constraint on date ranges)

It is possible to use such constraints with a Rails application, but it is not typical to do so, and the tools do not encourage it.

Elixir’s [https://hexdocs.pm/ecto/Ecto.html Ecto] database library embraces database constraints, with built-in support for adding them, catching constraint violations, and turning them back into friendly user-facing error messages.

== Where Elixir is especially suited ==

Any project that is a good fit for Rails or Python is something that could be done in Phoenix, especially if the project involves any or multiple of the following:

* System expecting high traffic or requiring very fast / consistent response times
* Minimal downtime being crucial
* Realtime updates (eg, stock ticker, social media)
* Bidirectional realtime communication with websockets (eg, chat, games)

= Drawbacks of Elixir =

Some potential downsides of using Elixir, along with mitigating actions:

* Fewer Elixir developers available. However:
** There are also significantly fewer projects competing for those people.
** There is a trend in Ruby developers wanting to cross over to Elixir.
** Developers with Erlang experience are also well suited.
** Elixir is a shiny new thing with real promise, which helps attract very enthusiastic developers.
* While Phoenix is productive, it is not as productive as older frameworks like Rails… yet. Reasons include:
** Lack of developer experience with Elixir.
** The relative newness of its open source ecosystem (documentation, forums, example code available).
** There are fewer libraries in Elixir than in older languages, so there are more times when you’d have to write something yourself. However:
*** You can use the many existing Erlang libraries.
*** New Elixir libraries are being added quickly.
*** Any remaining gaps are a chance to contribute to the community by creating a great open source tool.
* It may be harder to convince people to use Elixir, given that it’s currently obscure - not in the top [https://www.tiobe.com/tiobe-index/ 50 TIOBE index]. However:
** Erlang is better-known. Elixir compiles to Erlang bytecode, runs on the Erlang VM and can use or be used by Erlang code. It’s basically “Erlang made friendlier”.
** Joe Armstrong, co-creator of Erlang, said of pre-1.0 Elixir in 2013 that it was "good s**t".
** Therefore, if we can convince someone on Erlang, Elixir is a no-brainer.

= What’s next for MoodleNet’s development =

== A generic agent-centric approach to federation? ==

Another fediverse app being developed in Elixir ([https://github.com/beta-phenylethylamine/fontina Fontina], for photo sharing - although it has been put on hiatus) is now working on a [https://github.com/fontina-project/pubstomp generic ActivityPub server] to serve as back-end (there may be a good opportunity to join efforts…) Here is how the developer describes it: > “I’m working on pubstomp, a generic AP server that is intended for services like mastodon/pixelfed/peertube to work as frontends to it and would indeed support single account [per person, versus having an account on an instance of each of those apps]. > That said, one of my goals down the road is to build”api adaptors" that would basically plug into pubstomp and adapt to, say, the mastoAPI, pleromaAPI, etc.”

This is a good example of an '''agent-centric approach''', where instead of having one '''monolithic app per use-case''' it is possible instead to seperate out federation logic and custom app logic (both back-ends could still share a database on the same server, and share a JavaScript-based front-end app that talks to both APIs).

I started a [https://social.coop/@mayel/100469525067581562 thread about this on the fediverse] (please join the conversation!): > There’s need for a generic agent-centric #ActivityPub server, so that instead of signing up to a bunch of different servers, a user could have their indentity and data all in one place, and all the apps they use (clients, but if necessary server-side “plugins” as well) would interact with the activity/objects types that they support.

== The plan for Moodlenet (so far) ==

# Fork the Pleroma back-end to create a set of ActivityPub libraries (or a generic ActivityPub server)
# Add suport for authenticating as OAuth client
# Add support for group accounts (agents that represent a severa users)
# Create ActivityStreams extensions
# Test federation
# Possibly add [https://graphql.org GraphQL] client-server API
# Create front-end app with React.js (web and mobile)

We are planning to fork the [https://git.pleroma.social/pleroma/pleroma Pleroma back-end] to '''create a set of ActivityPub/ActivityStreams libraries'''. If that proves to not be feasible, we will turn it into a generic ActivityPub server back-end that can support any type of activity and object (including extensions to ActivityStreams) and is easily extensible which doesn’t ship with any frontend (possible name: ''Pub of the Commons''). Pleroma is written with [https://elixir-lang.org Elixir]’s [https://phoenixframework.org Phoenix Framework], and licenced as AGPL (which is also being used for MoodleNet) so the upstream project will be able to use any improvements we make.

Firstly, any parts of the code coming from Pleroma that we don’t needed will be removed (like support for the deprecated OStatus protocol, and the two front-ends which ship with Pleroma - its own Vue.js interface and Mastodon’s React.js interface), and we’ll add some things that can be '''universally useful''' like '''support for groups''' (actors made of several users), a basic HTML registration/authentication interface (and '''OAuth client''' functionality, so users can sign in using their existing accounts elsewhere) so that at least those things can be done without relying on a front-end app.

While we work on creating models/vocabulary for MoodleNet, we can use this generic ActivityPub server to test our ActivityStreams extensions and make sure federation works well in real time (using the API only). Only once that is ready, will we start plugging in custom MoodleNet logic and developing the front-end app (which is the reverse from many fediverse app projects, who have first implemented MVPs of their use case, and then often find it challenging to add federation on top).

Regarding the connection between the back-end and front-end app, the ActivityPub standard comes with a suggested [https://www.w3.org/TR/activitypub/#client-to-server-interactions client-server REST API specification], but for some reason Mastodon and many other fediverse apps have created their own custom REST APIs (and Pleroma implemented Mastodon’s so that it can share front-end apps). So an interesting option at this point for MoodleNet (and ''Pub of the Commons''), may be to still support Mastodon’s client REST API (for compatibillity with existing front-ends like [https://github.com/nolanlawson/pinafore Pinafore]) and additionally to '''implement a new GraphQL-based API that would allow more flexibility and extensiblity between the server and front-end apps''' (any functionality/activities/objects not supported by Mastodon would only have to be implemented in the server-to-server REST API and the [https://graphql.org GraphQL] API).

'''References'''

* [https://ethercalc.org/fediverse-stacks Spreadsheet of fediverse apps and their stacks]
* [https://www.w3.org/TR/activitypub/ ActivityPub] standard (for federation)
* [https://www.w3.org/TR/activitystreams-core/ ActivityStreams] & its [https://www.w3.org/TR/activitystreams-vocabulary/ vocabulary] (which ActivityPub uses as a data format)
* [https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/ How to implement a basic Mastodon-compatible server]
* [https://github.com/bignerdranch/why_elixir Why elixir] (big tanks to Big Nerd Ranch for some of the great material used in this doc!)
* [https://pragtob.wordpress.com/2017/07/26/choosing-elixir-for-the-code-not-the-performance/ Choosing Elixir for the Code, not the Performance]
* [https://git.pleroma.social/pleroma/pleroma/wikis/Hacking-Pleroma:-Elixir,-Phoenix-and-a-bit-of-ActivityPub Pleroma’s architecture]

Moodle App Plugins Development Guide

2018-06-25T15:39:43Z

Mayel: purge cache

{{Moodle Mobile}}

==Context==
Since Moodle 3.1 it is possible to support different types of Moodle plugins in the Mobile app via the [[Moodle Mobile Remote add-ons|Remote add-ons]] functionality.

Remote add-ons allow a developer to add complete support to their plugins in the Mobile app, but they have some disadvantages:
* Remote add-ons are not easy to develop and test since they are required to be developed as an Angular JS/Ionic module.
* A zip file containing the plugin must be downloaded from the server to be lazy-loaded.
* It is not easy to maintain or upgrade them.
* Developers had to set up a local Mobile development environment

In order to allow plugin developers to make their plugins compatible with the app, the Mobile team has been thinking in a new way to extend the mobile app features following these premises:
* It has to be easy to develop
* It should work without developing Angular/Ionic code
* It has to be easy to maintain
* It has to be supported since Moodle 3.1 at least
* Should support all the different types of Moodle plugins supported by the app
* Should work in any type of device
* Should not require JavaScript at all, although in some cases it will be needed. In the latter case, we’ll try to simplify the required JavaScript

==New approach==

We published an initial draft specification, and last month we started its implementation. During the implementation process we decided to make the following changes to the initial plans in order to make developers life easier:

* There will be just one way to support plugins in the app.
* This new way will allow developers to support plugins using PHP code, templates and Ionic markup (html components).
* The use of JavaScript will be optional (but some type of advanced plugins may require it)
* Developers won’t need to set up a Mobile development environment, they will be able to test using the latest version of the official app (although setting up a local Mobile environment is recommended for complex plugins).

This means that remote add-ons won’t be necessary anymore, and developers won’t have to learn Ionic 3 / Angular and set up a new mobile development environment to migrate them.

Important notes:
* Moodle Mobile 3.5 (to be released June 2018) will be the first version of the Mobile app supporting this new type of plugins.
* Remote add-ons will have to be migrated to the new simpler way (following this documentation)
* These features are natively supported in Moodle 3.5, but for previous versions you will need to install the Moodle Mobile Additional Features plugin.

==How it works==

The overall idea is to allow Moodle plugins to extend different areas in the app with ''just PHP server side'' code and Ionic 3 markup (custom html elements that are called components) using a set of custom Ionic directives and components.

Developers will have to:
# Create a db/mobile.php file in their plugins. In this file developers will be able to indicate which areas of the app they want to extend, for example, adding a new option in the main menu, implementing an activity module not supported, including a new option in the course menu, including a new option in the user profile, etc. All the areas supported are described further in this document.
# Create new functions in a reserved namespace that will return the content of the new options. The content should be returned rendered (html). The template should use [https://ionicframework.com/docs/components/ Ionic components] so that it looks native (custom html elements) but it can be generated using mustache templates.

Let’s clarify some points:

* You don’t need to create new Web Service functions (although you will be able to use them for advanced features). You just need plain php functions that will be placed in a reserved namespace.
* Those functions will be exported via the Web Service function tool_mobile_get_content
* As arguments of your functions you will always receive the userid, some relevant details of the app (app version, current language in the app, etc…) and some specific data depending on the type of plugin (courseid, cmid, …).
* We provide a list of custom Ionic components and directives (html tags) that will provide dynamic behaviour, like indicating that you are linking a file that can be downloaded, or to allow a transition to new pages into the app calling a specific function in the server, submit form data to the server etc..

==Step by step example==

In this example, we are going to update an existing plugin ([https://github.com/markn86/moodle-mod_certificate Certificate activity module]) that currently uses a Remote add-on.
This is a simple activity module that displays the certificate issued for the current user along with the list of the dates of previously issued certificates. It also stores in the course log that the user viewed a certificate. This module also works offline: when the user downloads the course or activity, the data is pre-fetched and can be viewed offline.

The example code can be downloaded from here (see last commit) https://github.com/jleyva/moodle-mod_certificate/commits/MOBILE-2363

TIP: Make sure to ([https://docs.moodle.org/35/en/Developer_tools#Purge_all_caches purge all cache]) after making an edit to one of the following files for your changes to be taken into account.

===Step 1. Update the db/mobile.php file===
In this case, we are updating an existing file but for new plugins, you should create this new file.

<code php>
$addons = array(
"mod_certificate" => array( // Plugin identifier
'handlers' => array( // Different places where the plugin will display content.
'coursecertificate' => array( // Handler unique name (alphanumeric).
'displaydata' => array(
'icon' => $CFG->wwwroot . '/mod/certificate/pix/icon.gif',
'class' => '',
),

'delegate' => 'CoreCourseModuleDelegate', // Delegate (where to display the link to the plugin)
'method' => 'mobile_course_view', // Main function in \mod_certificate\output\mobile
'offlinefunctions' => array(
'mobile_course_view' => array(),
'mobile_issues_view' => array()
) // Function that needs to be downloaded for offline.
)
),
'lang' => array( // Language strings that are used in all the handlers.
array('pluginname', 'certificate'),
array('summaryofattempts', 'certificate'),
array('getcertificate', 'certificate'),
array('requiredtimenotmet', 'certificate'),
array('viewcertificateviews', 'certificate')
),
)
);
</code>

;Plugin identifier:
: A unique name for the plugin, it can be anything (there’s no need to match the module name).

;Handlers (Different places where the plugin will display content):
: A plugin can be displayed in different views in the app. Each view should have a unique name inside the plugin scope (alphanumeric).

; Display data:
: This is only needed for certain types of plugins. Also, depending on the type of delegate it may require additional (or less fields), in this case we are indicating the module icon.

; Delegate
: Where to display the link to the plugin, see the Delegates chapter in this documentation for all the possible options.

; Method:
: This is the function in the Moodle component/lib.php file to be executed the first time the user clicks in the new option displayed in the app. The function should be a method of a Mobile class under the output/mobile namespace.

; Offlinefunctions
: These are the functions that need to be downloaded for offline usage. This is the list of functions that need to be called and stored when the user downloads a course for offline usage. Please note that you can add functions here that are not even listed in the mobile.php file.
: In our example, downloading for offline access will mean that we'll execute the functions for getting the certificate and issued certificates passing as parameters the current userid (and courseid when we are using the mod or course delegate). If we have the result of those functions stored in the app, we'll be able to display the certificate information even if the user is offline.
: Offline functions will be mostly used to display information for final users, any further interaction with the view won’t be supported offline (for example, trying to send information when the user is offline).
: You can indicate here other Web Services functions, indicating the parameters that they might need from a defined subset (currently userid and courseid)
: Prefetching the module will also download all the files returned by the methods in these offline functions (in the ''files'' array).

;Lang:
: The language pack string ids used in the plugin by all the handlers. Please note that you should avoid adding all the plugin string ids (including those unused) because the Web Service that returns the plugin information will include the translation of each string id for every language installed in the platform.

There are additional attributes supported by the mobile.php list, see “Mobile.php supported options” section below.

===Step 2. Creating the main function===

The main function displays the current issued certificate (or several warnings if it’s not possible to issue a certificate). It also displays a link to view the dates of previously issued certificates.

All the functions must be created in the plugin or subsystem classes/output directory, the name of the class must be mobile.

For this example (mod_certificate plugin) the namespace name will be mod_certificate\output.

'''File contents: mod/certificate/classes/output/mobile.php'''

<code php>
<?php
namespace mod_certificate\output;

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

use context_module;
use mod_certificate_external;

/**
* Mobile output class for certificate
*
* @package mod_certificate
* @copyright 2018 Juan Leyva
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class mobile {

/**
* Returns the certificate course view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_course_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

// Set timemodified for each certificate.
foreach ($issues as $issue) {
if (empty($issue->timemodified)) {
$issue->timemodified = $issue->timecreated;
}
}

$showget = true;
if ($certificate->requiredtime && !has_capability('mod/certificate:manage', $context)) {
if (certificate_get_course_time($certificate->course) < ($certificate->requiredtime * 60)) {
$showget = false;
}
}

$certificate->name = format_string($certificate->name);
list($certificate->intro, $certificate->introformat) =
external_format_text($certificate->intro, $certificate->introformat, $context->id,'mod_certificate', 'intro');
$data = array(
'certificate' => $certificate,
'showget' => $showget && count($issues) > 0,
'issues' => $issues,
'issue' => $issues[0],
'numissues' => count($issues),
'cmid' => $cm->id,
'courseid' => $args->courseid
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'javascript' => '',
'otherdata' => '',
'files' => $issues
);
}
}
</code>

Let’s go through the function code to analyse the different parts.

;Function declaration:
: The function name is the same as the one used in the mobile.php file (method field). There is only one argument “$args” which is an array containing all the information sent by the mobile app (the courseid, userid, appid, appversionname, appversioncode, applang, appcustomurlscheme…)

; Function implementation:
: In the first part of the function, we check permissions and capabilities (like a view.php script would do normally). Then we retrieve the certificate information that’s necessary to display the template.

Finally, we return:
* The rendered template (notice that we could return more than one template but we usually would only need one). By default the app will always render the first template received, the rest of the templates can be used if the plugin defines some Javascript code.
* JavaScript: Empty, because we don’t need any in this case
* Other data: Empty as well, because we don’t need any additional data to be used by directives or components in the template. This field will be published as an object supporting 2-way-data-bind to the template.
* Files: A list of files that the app should be able to download (for offline usage mostly)

===Step 3. Creating the template for the main function===

This is the most important part of your plugin because it contains the code that will be rendered on the mobile app.

In this template we’ll be using Ionic and custom directives and components available in the Mobile app.

All the HTML attributes starting with ion- are ionic components. Most of the time the component name is self-explanatory but you may refer to a detailed guide here: https://ionicframework.com/docs/components/

All the HTML attributes starting with ''core-'' are custom components of the Mobile app.

'''File contents: mod/certificate/templates/mobile_view_page.mustache'''

<code php>
{{=<% %>=}}
<div>
<core-course-module-description description="<% certificate.intro %>" component="mod_certificate" componentId="<% cmid %>"></core-course-module-description>

<ion-list>
<ion-list-header>
{{ 'plugin.mod_certificate.summaryofattempts' | translate }}
</ion-list-header>

<%#issues%>
<ion-item>
<button ion-button block color="light" core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewcertificateviews' | translate: {$a: <% numissues %>} }}
</button>
</ion-item>
<%/issues%>

<%#showget%>
<ion-item>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
<ion-icon name="cloud-download" item-start></ion-icon>
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</ion-item>
<%/showget%>

<%^showget%>
<ion-item>
{{ 'plugin.mod_certificate.requiredtimenotmet' | translate }}
</ion-item>
<%/showget%>


}" [preSets]="{getFromCache: 0, saveToCache: 0}">
</ion-list>
</div>
</code>

In the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Then we display the module description using <code><core-course-module-description</code> that is a component used to include the course module description.

For displaying the certificate information we create a list of elements, adding a header on top.
The following line <code>{{ 'plugin.mod_certificate.summaryofattempts' | translate }}</code> indicates that the Mobile app will translate the ''summaryofattempts'' string id (here we could’ve used mustache translation but it is usually better to delegate the strings translations to the app). The string id has this format:

“plugin” + plugin identifier (from mobile.php) + string id (the string must be indicated in the lang field in mobile.php).

Then we display a button to transition to another page if there are certificates issued. The attribute (directive) <code>core-site-plugins-new-content</code> indicates that if the user clicks the button, we need to call the function “mobile_issues_view” in the component “mod_certificate” passing as arguments the cmid and courseid. The content returned by this function will be displayed in a new page (see Step 4 for the code of this new page).

Just after this button we display another one but this time for downloading an issued certificate. The <code>core-course-download-module-main-file</code> directive indicates that clicking this button is for downloading the whole activity and opening the main file. This means that, when the user clicks this button, the whole certificate activity will be available in offline.

Finally, just before the ion-list is closed, we use the <code>core-site-plugins-call-ws-on-load</code> directive to indicate that once the page is loaded, we need to call to a Web Service function in the server, in this case we are calling the ''mod_certificate_view_certificate'' that will log that the user viewed this page.

As you can see, no JavaScript was necessary at all. We used plain HTML elements and attributes that did all the complex dynamic logic (like calling a Web Service) behind the scenes.

===Step 4. Adding an additional page===

'''Partial file contents: mod/certificate/classes/output/mobile.php'''

<code php>
/**
* Returns the certificate issues view for the mobile app.
* @param array $args Arguments from tool_mobile_get_content WS
*
* @return array HTML, javascript and otherdata
*/
public static function mobile_issues_view($args) {
global $OUTPUT, $USER, $DB;

$args = (object) $args;
$cm = get_coursemodule_from_id('certificate', $args->cmid);

// Capabilities check.
require_login($args->courseid , false , $cm, true, true);

$context = context_module::instance($cm->id);

require_capability ('mod/certificate:view', $context);
if ($args->userid != $USER->id) {
require_capability('mod/certificate:manage', $context);
}
$certificate = $DB->get_record('certificate', array('id' => $cm->instance));

// Get certificates from external (taking care of exceptions).
try {
$issued = mod_certificate_external::issue_certificate($cm->instance);
$certificates = mod_certificate_external::get_issued_certificates($cm->instance);
$issues = array_values($certificates['issues']); // Make it mustache compatible.
} catch (Exception $e) {
$issues = array();
}

$data = array(
'issues' => $issues
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_issues', $data),
),
),
'javascript' => '',
'otherdata' => ''
);
}
</code>

This function for the new page was added just after the mobile_course_view function, the code is quite similar: Capabilities checks, retrieves the information required for the template and returns the template rendered.

The code of the mustache template is also very simple:

'''File contents: mod/certificate/templates/mobile_view_issues.mustache'''

<code php>
{{=<% %>=}}
<div>
<ion-list>
<%#issues%>
<ion-item>
{{ <%timecreated%> | coreToLocaleString }}
<%grade%>
</ion-item>
<%/issues%>
</ion-list>
</div>
</code>

As we did in the previous template, in the first line of the template we switch delimiters to avoid conflicting with Ionic delimiters (that are curly brackets like mustache).

Here we are creating an ionic list that will display a new item in the list per each issued certificated.

For the issued certificated we’ll display the time when it was created (using the app filter ''coreToLocaleString''). We are also displaying the grade displayed in the certificate (if any).

===Step 5. Plugin webservices, if included===

If your plugin uses its own web services, they will also need to be enabled for mobile access in your db/services.php file.

The following line <code>'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'),</code> should be included in each webservice definition.

'''File contents: mod/certificate/db/services.php'''

<code php>
$functions = array(

'mod_certificate_get_certificates_by_courses' => array(
'classname' => 'mod_certificate_external',
'methodname' => 'get_certificates_by_courses',
'description' => 'Returns a list of certificate instances...',
'type' => 'read',
'capabilities' => 'mod/certificate:view',
'services' => array(MOODLE_OFFICIAL_MOBILE_SERVICE, 'local_mobile'),
),
</code>

This extra services definition is the reason why you will need to have the local_mobile plugin installed for Moodle versions 3.4 and lower, so that your Moodle site will have all the additional webservices included to deal with all these mobile access calls. This is explained further in the [https://docs.moodle.org/dev/Mobile_support_for_plugins#Moodle_version_requirements Moodle version requirements section] below.

==Getting started==

The first and most important thing to know is that you don’t need a local mobile environment, you can just use the Chrome or Chromium browser to add mobile support to your plugins!

Open this URL (with Chrome or Chromium browser): https://mobileapp.moodledemo.net/ and you will see a web version of the mobile app completely functional (except for some native features). This URL is updated with the latest integration version of the app.

Please test that your site works correctly in the web version before starting any development.

===Moodle version requirements===

If your Moodle version is lower than 3.5 (to be released in May) you will need to install the [https://docs.moodle.org/en/Moodle_Mobile_additional_features Moodle Mobile additional features plugin].

Please use this development version for now: https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE (if your Moodle version is 3.2, 3.3 or 3.4) you will have to use the specific branch for your version but applying manually the [https://github.com/moodlehq/moodle-local_mobile/commits/MOODLE_31_STABLE last commit from the 3.1 branch] (the one with number MOBILE-2362).

Also, when installing the Moodle Mobile Additional features plugin you must follow the installation instructions so the service is set up properly.

Remember to update your plugin documentation to reflect that this plugin is mandatory for Mobile support. We don’t recommend to indicate in your plugin version.php a dependency to local_mobile though.

===Development workflow===

First of all, we recommend creating a simple ''mobile.php'' for displaying a new main menu option (even if your plugin won’t be in the main menu, just to verify that you are able to extend the app plugins). Then open the webapp (https://mobileapp.moodledemo.net/) or refresh the browser if it was already open. Check that you can correctly see the new menu option you included.

Then, develop the main function of the app returning a “Hello world” or basic code (without using templates) to see that everything works together. After adding the classes/output/mobile.php file it is very important to “Purge all caches” to avoid problems with the auto-loading cache.

It is important to remember that:
* Any change in the mobile.php file will require you to refresh the web app page in the browser (remember to disable the cache in the Chrome developer options).
* Any change in an existing template or function won’t require to refresh the browser page. In most cases you should just do a PTR (Pull down To Refresh) in the page that displays the view returned by the function. Be aware that PTR will work only when using the “device” emulation in the browser (see following section).

===Testing and debugging===

To learn how to debug with the web version of the app, please read the following documents:
* [[Moodle Mobile debugging WS requests]] AND
* [[Moodle Mobile development using Chrome or Chromium]] (please, omit the installation section)

For plugins using the Javascript API you may develop making use of the console.log function to add trace messages in your code that will be displayed in the browser console.

==Mobile.php supported options==

In the Step by Step section we learned about some of the existing options for handlers configuration. This is the full list of supported options:

===Common options===

* '''displaydata''' (mandatory for certain types): Data used to display the handler. It will vary depending on the delegate, and some delegates won’t need it at all (like course format). Attributes usually required in the ''displaydata'': title, icon, class.
* '''delegate''' (mandatory): Name of the delegate to register the handler in.
* '''method''' (mandatory): The function to call to retrieve the main page content.
* '''priority''' (optional): Priority of the handler. Only for certain delegates. Higher priority is displayed first.
* '''lang''' (optional): List of language strings.
* '''init''' (optional): A function to call to retrieve the initialization JS and the "restrict" to apply to the whole handler. It can also return templates that can be used from the Javascript of the init method or the Javascript of the handler’s method.
* '''restricttocurrentuser''' (optional) Only used if the delegate has a isEnabledForUser function. If true, the handler will only be shown for current user. For more info about displaying the plugin only for certain users, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''restricttoenrolledcourses''' (optional): Only used if the delegate has a isEnabledForCourse function. If true or not defined, the handler will only be shown for courses the user is enrolled in. For more info about displaying the plugin only for certain courses, please see [[Mobile_support_for_plugins#Display_the_plugin_only_if_certain_conditions_are_met|Display the plugin only if certain conditions are met]].
* '''styles''' (optional): An array with two properties: ''url'' and ''version''. The URL should point to a CSS file, either using an absolute URL or a relative URL. This file will be downloaded and applied by the app. It's recommended to include styles that will only affect your plugin templates. The version number is used to determine if the file needs to be downloaded again, you should change the version number everytime you change the CSS file.

===Options only for CoreCourseModuleDelegate===

* '''offlinefunctions''': (optional) List of functions to call when prefetching the module. It can be a get_content method or a WS. You can filter the params received by the WS. By default, WS will receive these params: courseid, cmid, userid. Other valid values that will be added if they are present in the list of params: courseids (it will receive a list with the courses the user is enrolled in), component + 'id' (e.g. certificateid).
* '''downloadbutton''': (optional) Whether to display download button in the module. If not defined, the button will be shown if there is any offlinefunction.
* '''isresource''': (optional) Whether the module is a resource or an activity. Only used if there is any offlinefunction. If your module relies on the "contents" field, then it should be true.
* '''updatesnames''': (optional) Only used if there is any offlinefunction. A Regular Expression to check if there's any update in the module. It will be compared to the result of ''core_course_check_updates''.

===Options only for CoreCourseFormatDelegate===

* '''canviewallsections''': (optional) Whether the course format allows seeing all sections in a single page. Defaults to true.
* '''displayenabledownload''': (optional) Whether the option to enable section/module download should be displayed. Defaults to true.
* '''displaysectionselector''': (optional) Whether the default section selector should be displayed. Defaults to true.

===Options only for CoreUserDelegate===

* '''type''': The type of the addon. Values accepted: 'newpage' (default) or 'communication'.

==Delegates==

===CoreMainMenuDelegate===

You must use this delegate when you want to add new items to the main menu (currently displayed at the bottom of the app).

===CoreCourseOptionsDelegate===

You must use this delegate when you want to add new options in a course (Participants or Grades are examples of this type of delegate).

===CoreCourseModuleDelegate===

You must use this delegate for supporting activity modules or resources, please review the specific options for this delegate in the “Options only for CoreCourseModuleDelegate” section.

===CoreUserDelegate===

You must use this delegate when you want to add additional options in the user profile page in the app. Options can be of different types (newpage, communication or action).

===CoreCourseFormatDelegate===

You must use this delegate for supporting course formats, please review the specific options for this delegate in the “Options only for CoreCourseFormatDelegate” section.

===Other advanced delegates===

This delegates require JavaScript to be supported. See [[Mobile_support_for_plugins#Initialization|Initialization]] for more information.

* CoreContentLinksDelegate
* CoreUserProfileFieldDelegate
* CoreCourseModulePrefetchDelegate
* CoreFileUploaderDelegate
* CorePluginFileDelegate

==Available components and directives==

===Difference between component and directives===

A component (represented as an HTML tag) is used to add custom elements to the app.
Example of components are: ion-list, ion-item, core-search-box

A directive (represented as an HTML attribute) allows you to extend a piece of HTML with additional information or functionality.
Example of directives are: core-auto-focus, *ngIf, ng-repeat

The Mobile app uses Angular, Ionic and custom components and directives, for a full reference of:
* Angular directives, please check: https://angular.io/api?type=directive
* Ionic components, please check: https://ionicframework.com/docs/

===Custom core components and directives===

These are some useful custom components and directives (only available in the mobile app). Please notice that this isn’t the full list of components and directives of the app, it’s just an extract of the most common ones.

====core-format-text====

This directive formats the text and adds some directives needed for the app to work as it should. For example, it treats all links and all the embedded media so they work fine in the app. If some content in your template includes links or embedded media, please use this directive.

This directive automatically applies core-external-content and core-link to all the links and embedded media.

Data that can be passed to the directive:

* '''text''' (string): The text to format.
* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.
* '''adaptImg''' (boolean): Optional. Whether to adapt images to screen width. Defaults to true.
* '''clean''' (boolean): Optional. Whether all the HTML tags should be removed. Defaults to false.
* '''singleLine''' (boolean): Optional. Whether new lines should be removed (all text in single line). Only if clean=true. Defaults to false.
* '''maxHeight''' (number): Optional. Max height in pixels to render the content box. It should be 50 at least to make sense. Using this parameter will force display: block to calculate height better. If you want to avoid this use class="inline" at the same time to use display: inline-block.
* '''fullOnClick''' (boolean): Optional. Whether it should open a new page with the full contents on click. Only if maxHeight is set and the content has been collapsed. Defaults to false.
* '''fullTitle''' (string): Optional. Title to use in full view. Defaults to "Description".

Example usage:

<code php>
<core-format-text text="<% cm.description %>" component="mod_certificate" componentId="<% cm.id %>"></core-format-text>
</code>

====core-link====

Directive to handle a link. It performs several checks, like checking if the link needs to be opened in the app, and opens the link as it should (without overriding the app).

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''capture''' (boolean): Optional. Whether the link needs to be captured by the app (check if the link can be handled by the app instead of opening it in a browser).
* '''inApp''' (boolean): Optional. True to open in embedded browser, false to open in system browser.
* '''autoLogin''' (string): Optional. If the link should be open with auto-login. Accepts the following values:
** "yes" -> Always auto-login.
** "no" -> Never auto-login.
** "check" -> Auto-login only if it points to the current site. Default value.

Example usage:
<code php>
<a href="<% cm.url %>" core-link>
</code>

====core-external-content====

Directive to handle links to files and embedded files. This directive should be used in any link to a file or any embedded file that you want to have available when the app is offline.

If a file is downloaded, its URL will be replaced by the local file URL.

This directive is automatically applied to all the links and media inside core-format-text.

Data that can be passed to the directive:

* '''siteId''' (string): Optional. Site ID to use. If not defined, current site.
* '''component''' (string): Optional. Component to use when downloading embedded files.
* '''componentId''' (string|number): Optional. ID to use in conjunction with the component.

Example usage:
<code php>
<img src="<% event.iconurl %>" core-external-content component="mod_certificate" componentId="<% event.id %>">
</code>

====core-user-link====

Directive to go to user profile on click. When the user clicks the element where this directive is attached, the right user profile will be opened.

Data that can be passed to the directive:

* '''userId''' (number): User id to open the profile.
* '''courseId''' (number): Optional. Course id to show the user info related to that course.

Example usage:
<code php>
<a ion-item core-user-link userId="<% userid %>">
</code>

====core-file====

Component to handle a remote file. It shows the file name, icon (depending on mimetype) and a button to download/refresh it. The user can identify if the file is downloaded or not based on the button.

Data that can be passed to the directive:

* file (object): The file. Must have a property 'filename' and a 'fileurl' or 'url'
* component (string): Optional. Component the file belongs to.
* componentId (string|number): Optional. ID to use in conjunction with the component.
* canDelete (boolean): Optional. Whether file can be deleted.
* alwaysDownload (boolean): Optional. Whether it should always display the refresh button when the file is downloaded. Use it for files that you cannot determine if they're outdated or not.
* canDownload (boolean): Optional. Whether file can be downloaded. Defaults to true.

Example usage:
<code php>
<core-file [file]="{fileurl: <% issue.url %>, filename: <% issue.name %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>"></core-file>
</code>

====core-download-file====

Directive to allow downloading and open a file. When the item with this directive is clicked, the file will be downloaded (if needed) and opened.

It is usually recommended to use the core-file component since it also displays the state of the file.

Data that can be passed to the directive:

* '''core-download-file''' (object): The file to download.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component.

Example usage: a button to download a file.
<code php>
<button ion-button [core-download-file]="{fileurl: <% issue.url %>, timemodified: <% issue.timemodified %>, filesize: <% issue.size %>}" component="mod_certificate" componentId="<% cm.id %>">
{{ 'plugin.mod_certificate.download | translate }}
</button>
</code>

====core-course-download-module-main-file====

Directive to allow downloading and opening the main file of a module.

When the item with this directive is clicked, the whole module will be downloaded (if needed) and its main file opened. This is meant for modules like mod_resource.

This directive must receive either a module or a moduleId. If no files are provided, it will use module.contents.

Data that can be passed to the directive:

* '''module''' (object): Optional. The module object. Required if module is not supplied.
* '''moduleId''' (number): Optional. The module ID. Required if module is not supplied.
* '''courseId''' (number): The course ID the module belongs to.
* '''component''' (string): Optional. Component to link the file to.
* '''componentId''' (string|number): Optional. Component ID to use in conjunction with the component. If not defined, moduleId.
* '''files''' (object[]): Optional. List of files of the module. If not provided, use module.contents.

Example usage:
<code php>
<button ion-button block core-course-download-module-main-file moduleId="<% cmid %>" courseId="<% certificate.course %>" component="mod_certificate" [files]="[{fileurl: '<% issue.fileurl %>', filename: '<% issue.filename %>', timemodified: '<% issue.timemodified %>', mimetype: '<% issue.mimetype %>'}]">
{{ 'plugin.mod_certificate.getcertificate' | translate }}
</button>
</code>

====core-navbar-buttons====

Component to add buttons to the app's header without having to place them inside the header itself. Using this component in a site plugin will allow adding buttons to the header of the current page.

If this component indicates a position (start/end), the buttons will only be added if the header has some buttons in that position. If no start/end is specified, then the buttons will be added to the first <ion-buttons> found in the header.

You can use the [hidden] input to hide all the inner buttons if a certain condition is met.

Example usage:
<code php>
<core-navbar-buttons end>
<button ion-button icon-only (click)="action()">
<ion-icon name="funnel"></ion-icon>
</button>
</core-navbar-buttons>
</code>

===Specific component and directives for plugins===

These are component and directives created specifically for supporting Moodle plugins.

====core-site-plugins-new-content====

Directive to display a new content when clicked. This new content can be displayed in a new page or in the current page (only if the current page is already displaying a site plugin content).

Data that can be passed to the directive:

* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the new ''get_content'' WS call. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usages:

A button to go to a new content page:
<code php>
<button ion-button core-site-plugins-new-content title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

A button to load new content in current page using userid from otherdata:
<code php>
<button ion-button core-site-plugins-new-content component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.viewissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws====

Directive to call a WS when the element is clicked. The action to do when the WS call is successful depends on the provided data: display a message, go back or refresh current view.

If you want to load a new content when the WS call is done, please see core-site-plugins-call-ws-new-content.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* preSets (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''successMessage''' (string): Message to show on success. If not supplied, no message. If supplied but empty, default message (“Success”).
* '''goBackOnSuccess''' (boolean): Whether to go back if the WS call is successful.
* '''refreshOnSuccess''' (boolean): Whether to refresh the current view if the WS call is successful.

Example usages:

A button to send some data to the server without using cache, displaying default messages and refreshing on success:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage successMessage refreshOnSuccess="true">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

A button to send some data to the server using cache without confirming, going back on success and using userid from otherdata:
<code php>
<button ion-button core-site-plugins-call-ws name="mod_certificate_view_certificate" [params]="{certificateid: <% certificate.id %>}" goBackOnSuccess="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.senddata' | translate }}
</button>
</code>

====core-site-plugins-call-ws-new-content====

Directive to call a WS when the element is clicked and load a new content passing the WS result as args. This new content can be displayed in a new page or in the same page (only if current page is already displaying a site plugin content).

If you don't need to load some new content when done, please see core-site-plugins-call-ws.

Data that can be passed to the directive:

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].
* '''confirmMessage''' (string): Message to confirm the action when the user clicks the element. If not supplied, no confirmation. If supplied but empty, default message ("Are you sure?").
* '''component''' (string): The component of the new content.
* '''method''' (string): The method to get the new content.
* '''args''' (object): The params to get the new content.
* '''title''' (string): The title to display with the new content. Only if samePage=false.
* '''samePage''' (boolean): Whether to display the content in same page or open a new one. Defaults to new page.
* '''useOtherData''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the args for the new ''get_content'' call. The format is the same as in ''useOtherDataForWS''.

Example usages:

A button to get some data from the server without using cache, showing default confirm and displaying a new page:
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" [preSets]="{getFromCache: 0, saveToCache: 0}" confirmMessage title="<% certificate.name %>" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

A button to get some data from the server using cache, without confirm, displaying new content in same page and using ''userid'' from ''otherdata'':
<code php>
<button ion-button core-site-plugins-call-ws-new-content name="mod_certificate_get_issued_certificates" [params]="{certificateid: <% certificate.id %>}" component="mod_certificate" method="mobile_issues_view" [args]="{cmid: <% cmid %>, courseid: <% courseid %>}" samePage="true" [useOtherData]="['userid']">
{{ 'plugin.mod_certificate.getissued' | translate }}
</button>
</code>

====core-site-plugins-call-ws-on-load====

Directive to call a WS as soon as the template is loaded. This directive is meant for actions to do in the background, like calling logging Web Services.

If you want to call a WS when the user clicks on a certain element, please see core-site-plugins-call-ws.

* '''name''' (string): The name of the WS to call.
* '''params''' (object): The params for the WS call.
* '''preSets''' (object): Extra options for the WS call: whether to use cache or not, etc.
* '''useOtherDataForWS''' (any): Whether to include ''otherdata'' (from the ''get_content'' WS call) in the params for the WS call. If not supplied, no other data will be added. If supplied but empty (null, false or empty string) all the ''otherdata'' will be added. If it’s an array, it will only copy the properties whose names are in the array.
* '''form''' (string): ID or name to identify a form in the template. The form will be obtained from ''document.forms''. If supplied and form is found, the form data will be retrieved and sent to the WS. If your form contains an ion-radio, ion-checkbox or ion-select, please see [[Mobile_support_for_plugins#Values_of_ion-radio.2C_ion-checkbox_or_ion-select_aren.27t_sent_to_my_WS|Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS]].

Example usage:
<code php>
}" [preSets]="{getFromCache: 0, saveToCache: 0}">
</code>

==Advanced features==

===Display the plugin only if certain conditions are met===

You might want to display your plugin in the mobile app only if certain dynamic conditions are met, so the plugin would be displayed only for some users. This can be achieved using the "init" method (for more info, please see the [[Mobile_support_for_plugins#Initialization|Initialization]] section ahead).

All the init methods are called as soon as your plugin is retrieved. If you don't want your plugin to be displayed for the current user, then you should return an exception in this init method. It's recommended to include a message explaining why the plugin isn't available for the current user, this exception will be logged in the Javascript console.

On the other hand, you might want to display a plugin only for certain courses (''CoreCourseOptionsDelegate'') or only if the user is viewing certain users' profiles (''CoreUserDelegate''). This can be achieved with the init method too.

In the init method you can return a "restrict" property with two fields in it: ''courses'' and ''users''. If you return a list of courses IDs in this restrict property, then your plugin will only be displayed when the user views any of those courses. In the same way, if you return a list of user IDs then your plugin will only be displayed when the user views any of those users' profiles.

===Using “otherdata”===

The values returned by the functions in otherdata are added to a variable so they can be used both in Javascript and in templates. The otherdata returned by a init call is added to a variable named INIT_OTHERDATA, while the otherdata returned by a ''get_content'' WS call is added to a variable named CONTENT_OTHERDATA.

The otherdata returned by a init call will be passed to the JS and template of all the get_content calls in that handler. The otherdata returned by a get_content call will only be passed to the JS and template returned by that get_content call.

This means that, in your Javascript, you can access and use these data like this:
<code php>
this.CONTENT_OTHERDATA.myVar
</code>
And in the template you could use it like this:
<code php>
{{ CONTENT_OTHERDATA.myVar }}
</code>
''myVar'' is the name we put to one of our variables, it can be the name you want. In the example above, this is the otherdata returned by the PHP method:

array('myVar' => 'Initial value')

====Example====

In our plugin we want to display an input text with a certain initial value. When the user clicks a button, we want the value in the input to be sent to a certain WebService. This can be done using otherdata.

We will return the initial value of the input in the otherdata of our PHP method:
<code php>
'otherdata' => array('myVar' => 'My initial value'),
</code>
Then in the template we will use it like this:
<code php>
<ion-item text-wrap>
<ion-label stacked>{{ 'plugin.mod_certificate.textlabel | translate }}</ion-label>
<ion-input type="text" [(ngModel)]="CONTENT_OTHERDATA.myVar"></ion-input>
</ion-item>
<ion-item>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [useOtherDataForWS]="['myVar']">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</ion-item>
</code>

In the example above, we are creating an input text and we use ''[(ngModel)]'' to use the value in ''myVar'' as the initial value and to store the changes in the same ''myVar'' variable. This means that the initial value of the input will be “My initial value”, and if the user changes the value of the input these changes will be applied to the ''myVar'' variable. This is called 2-way data binding in Angular.

Then we add a button to send this data to a WS, and for that we use the directive core-site-plugins-call-ws. We use the ''useOtherDataForWS'' attribute to specify which variable from ''otherdata'' we want to send to our WebService. So if the user enters “A new value” in the input and then clicks the button, it will call the WebService ''mod_certificate_my_webservice'' and will send as a param: myVar -> “A new value”.

We can achieve the same result using the ''params'' attribute of the core-site-plugins-call-ws directive instead of using ''useOtherDataForWS'':
<code php>
<button ion-button block color="light" core-site-plugins-call-ws name="mod_certificate_my_webservice" [params]="{myVar: CONTENT_OTHERDATA.myVar}">
{{ 'plugin.mod_certificate.send | translate }}
</button>
</code>
The WebService call will be exactly the same with both buttons.

Please notice that this example could be done without using otherdata too, using the “''form''” input of the ''core-site-plugins-call-ws directive''.

===JS functions visible in the templates===

The app provides some Javascript functions that can be used from the templates to update, refresh or view content. These are the functions:

* '''openContent(title: string, args: any, component?: string, method?: string)''': Open a new page to display some new content. You need to specify the ''title'' of the new page and the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.
* '''refreshContent(showSpinner = true)''': Refresh the current content. By default it will display a spinner while refreshing, if you don't want it to be displayed you should pass false as a parameter.
* '''updateContent(args: any, component?: string, method?: string)''': Refresh the current content using different params. You need to specify the ''args'' to send to the method. If ''component'' and ''method'' aren't provided, it will use the same as in the current page.

====Examples====

=====Group selector=====

Imagine we have an activity that uses groups and we want to let the user select which group he wants to see. A possible solution would be to return all the groups in the same template (hidden), and then show the group user selects. However, we can make it more dynamic and return only the group the user is requesting.

To do so, we'll use a drop down to select the group. When the user selects a group using this drop down we'll update the page content to display the new group.

The main difficulty in this is to tell the view which group needs to be selected when the view is loaded. There are 2 ways to do it: using plain HTML or using Angular's ''ngModel''.

======Using plain HTML======

We need to add a "''selected''" attribute to the option that needs to be selected. To do so, we need to pre-caclulate the selected option in the PHP code:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);
// Detect which group is selected.
foreach ($groups as $gid=>$group) {
$group->selected = $gid === $groupid;
}

$data = array(
'cmid' => $cm->id,
'courseid' => $args->courseid,
'groups' => $groups
);

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
);
</code>

In the code above, we're retrieving the groups the user can see and then we're adding a "selected" bool to each one to determine which one needs to be selected in the drop down. Finally, we pass the list of groups to the template.

In the template, we display the drop down like this:

<code php>
<ion-select (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: $event})" interface="popover">
<%#groups%>
<ion-option value="<% id %>" <%#selected%>selected<%/selected%> ><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

The ''ionChange'' function will be called everytime the user selects a different group with the drop down. We're using the function ''updateContent'' to update the current view using the new group. ''$event'' is an Angular variable that will have the selected value (in our case, the group ID that was just selected). This is enough to make the group selector work.

======Using ngModel======

ngModel is an Angular directive that allows storing the value of a certain input/select in a Javascript variable, and also the opposite way: tell the input/select which value to set. The main problem is that we cannot initialize a Javascript variable from the template (Angular doesn't have ''ng-init'' like in AngularJS), so we'll use "otherdata".

In the PHP function we'll return the group that needs to be selected in the ''otherdata'' array:

<code php>
$groupid = empty($args->group) ? 0 : $args->group; // By default, group 0.
$groups = groups_get_activity_allowed_groups($cm, $user->id);

...

return array(
'templates' => array(
array(
'id' => 'main',
'html' => $OUTPUT->render_from_template('mod_certificate/mobile_view_page', $data),
),
),
'otherdata' => array(
'group' => $groupid
),
);
</code>

In the example above we don't need to iterate over the groups array like in the plain HTML example. However, now we're returning the groupid in the "otherdata" array. As it's explained in the [[Mobile_support_for_plugins#Using_.E2.80.9Cotherdata.E2.80.9D|Using "otherdata"]] section, this "otherdata" is visible in the templates inside a variable named ''CONTENT_OTHERDATA''. So in the template we'll use this variable like this:

<code php>
<ion-select [(ngModel)]="CONTENT_OTHERDATA.group" (ionChange)="updateContent({cmid: <% cmid %>, courseid: <% courseid %>, group: CONTENT_OTHERDATA.group})" interface="popover">
<%#groups%>
<ion-option value="<% id %>"><% name %></ion-option>
<%/groups%>
</ion-select>
</code>

===Initialization===

All handlers can specify a “''init''” method in the mobile.php file. This method is meant to return some JavaScript code that needs to be executed as soon as the plugin is retrieved.

When the app retrieves all the handlers, the first thing it will do is call the ''tool_mobile_get_content'' WebService with the init method. This WS call will only receive the default args.

The app will immediately execute the JavaScript code returned by this WS call. This JavaScript can be used to manually register your handlers in the delegates you want, without having to rely on the default handlers built based on the mobile.php data.

The templates returned by this init method will be added to a INIT_TEMPLATES variable that will be passed to all the Javascript code of that handler. This means that the Javascript returned by the init method or the “main” method can access any of the templates HTML like this:
<code javascript>
this.INIT_TEMPLATES[‘main’];
</code>
In this case, “main” is the ID of the template we want to use.

The same happens with the ''otherdata'' returned by this init method, it is added to a INIT_OTHERDATA variable.

The ''restrict'' field returned by this init call will be used to determine if your handler is enabled or not. For example, if your handler is for the delegate ''CoreCourseOptionsDelegate'' and you return a list of courseids in restrict->courses, then your handler will only be enabled in the courses you returned. This only applies to the “default” handlers, if you register your own handler using the Javascript code then you should check yourself if the handler is enabled.

Finally, if you return an object in this init Javascript code, all the properties of that object will be passed to all the Javascript code of that handler so you can use them when the code is run. For example, if your init Javascript code does something like this:
<code javascript>
var result = {
MyAddonClass: new MyAddonClass()
};
result:
</code>
Then, for the rest of Javascript code of your handler (e.g. for the “main” method) you can use this variable like this:
<code javascript>
this.MyAddonClass
</code>

====Examples====

=====Module link handler=====

A link handler allows you to decide what to do when a link with a certain URL is clicked. This is useful, for example, to open your module when a link to the module is clicked. In this example we’ll create a link handler to detect links to a certificate module using a init JavaScript:
<code javascript>
var that = this;

function AddonModCertificateModuleLinkHandler() {
that.CoreContentLinksModuleIndexHandler.call(this, that.CoreCourseHelperProvider, 'mmaModCertificate', 'certificate');

this.name = "AddonModCertificateLinkHandler";
}

AddonModCertificateModuleLinkHandler.prototype = Object.create(this.CoreContentLinksModuleIndexHandler.prototype);
AddonModCertificateModuleLinkHandler.prototype.constructor = AddonModCertificateModuleLinkHandler;

this.CoreContentLinksDelegate.registerHandler(new AddonModCertificateModuleLinkHandler());
</code>

=====Module prefetch handler=====

The ''CoreCourseModuleDelegate'' handler allows you to define a list of ''offlinefunctions'' to prefetch a module. However, you might want to create your own prefetch handler to determine what needs to be downloaded. For example, you might need to chain WS calls (pass the result of a WS call to the next one), and this cannot be done using ''offlinefunctions''.

Here’s an example on how to create a prefetch handler using init JS:
<code javascript>
var that = this;

function AddonModCertificateModulePrefetchHandler() {
that.CoreCourseModulePrefetchHandlerBase.call(this, that.injector);

this.name = "certificate";
this.component = "mmaModCertificate";
this.updatesNames = /^configuration$|^.*files$/;
}

AddonModCertificateModulePrefetchHandler.prototype = Object.create(this.CoreCourseModulePrefetchHandlerBase.prototype);
AddonModCertificateModulePrefetchHandler.prototype.constructor = AddonModCertificateModulePrefetchHandler;

AddonModCertificateModulePrefetchHandler.prototype.downloadOrPrefetch = function(module, courseId, prefetch, dirPath) {

var promises = [];

promises.push(that.CoreCourseModulePrefetchHandlerBase.prototype.downloadOrPrefetch.call(this, module, courseId, prefetch, dirPath));

promises.push(that.sitesProvider.getCurrentSite().read("mod_certificate_get_certificates_by_courses", {courseids: [courseId]}));

return Promise.all(promises);
};

this.CoreCourseModulePrefetchDelegate.registerHandler(new AddonModCertificateModulePrefetchHandler());
</code>

=====Single activity course format=====

In the following example, the value of INIT_TEMPLATES["main"] is:

<core-dynamic-component [component]="componentClass" [data]="data"></core-dynamic-component>

This template is returned by the init method. And this is the JavaScript code returned by the init method:
<code javascript>
var that = this;

function getAddonSingleActivityFormatComponent() {
function AddonSingleActivityFormatComponent() {
this.data = {};
};
AddonSingleActivityFormatComponent.prototype.constructor = AddonSingleActivityFormatComponent;
AddonSingleActivityFormatComponent.prototype.ngOnChanges = function(changes) {
var self = this;

if (this.course && this.sections && this.sections.length) {
var module = this.sections[0] && this.sections[0].modules && this.sections[0].modules[0];
if (module && !this.componentClass) {
that.CoreCourseModuleDelegate.getMainComponent(that.Injector, this.course, module).then((component) => {
self.componentClass = component || that.CoreCourseUnsupportedModuleComponent;
});
}

this.data.courseId = this.course.id;
this.data.module = module;
}
};
AddonSingleActivityFormatComponent.prototype.doRefresh = function(refresher, done) {
return Promise.resolve(this.dynamicComponent.callComponentFunction("doRefresh", [refresher, done]));
};

return AddonSingleActivityFormatComponent;
};

function AddonSingleActivityFormatHandler() {
this.name = "singleactivity";
};

AddonSingleActivityFormatHandler.prototype.constructor = AddonSingleActivityFormatHandler;

AddonSingleActivityFormatHandler.prototype.isEnabled = function() {
return true;
};

AddonSingleActivityFormatHandler.prototype.canViewAllSections = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseTitle = function(course, sections) {
if (sections && sections[0] && sections[0].modules && sections[0].modules[0]) {
return sections[0].modules[0].name;
}

return course.fullname || "";
};

AddonSingleActivityFormatHandler.prototype.displayEnableDownload = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.displaySectionSelector = function(course) {
return false;
};

AddonSingleActivityFormatHandler.prototype.getCourseFormatComponent = function(injector, course) {
that.Injector = injector || that.Injector;

return that.CoreCompileProvider.instantiateDynamicComponent(that.INIT_TEMPLATES["main"], getAddonSingleActivityFormatComponent(), injector);
};

this.CoreCourseFormatDelegate.registerHandler(new AddonSingleActivityFormatHandler());
</code>

===Using the JavaScript API===

The Javascript API is partly supported right now, only the ''CoreUserProfileFieldDelegate'' supports it now. This API allows you to override any of the functions of the default handler.

The “method” specified in a handler registered in the ''CoreUserProfileFieldDelegate'' will be called immediately after the init method, and the Javascript returned by this method will be run. If this Javascript code returns an object with certain functions, these function will override the ones in the default handler.

For example, if the Javascript returned by the method returns something like this:

<code javascript>
var result = {
getData: function(field, signup, registerAuth, formValues) {
}
};
result;
</code>

The the ''getData'' function of the default handler will be overridden by the returned getData function.

The default handler for ''CoreUserProfileFieldDelegate'' only has 2 functions: ''getComponent'' and ''getData''. In addition, the JavaScript code can return an extra function named ''componentInit'' that will be executed when the component returned by ''getComponent'' is initialized.

Here’s an example on how to support the text user profile field using this API:

<code javascript>
var that = this;

var result = {
componentInit: function() {
if (this.field && this.edit && this.form) {
this.field.modelName = "profile_field_" + this.field.shortname;

if (this.field.param2) {
this.field.maxlength = parseInt(this.field.param2, 10) || "";
}

this.field.inputType = that.CoreUtilsProvider.isTrueOrOne(this.field.param3) ? "password" : "text";

var formData = {
value: this.field.defaultdata,
disabled: this.disabled
};

this.form.addControl(this.field.modelName, that.FormBuilder.control(formData, this.field.required && !this.field.locked ? that.Validators.required : null));
}
},
getData: function(field, signup, registerAuth, formValues) {
var name = "profile_field_" + field.shortname;

return {
type: "text",
name: name,
value: that.CoreTextUtilsProvider.cleanTags(formValues[name])
};
}
};

result;
</code>

==Troubleshooting==

=== Invalid response received ===

You might receive this error when using the "core-site-plugins-call-ws" directive or similar. By default, the app expects all WebService calls to return an object, if your WebService returns another type (string, bool, ...) then you need to specify it using the preSets attribute of the directive. For example, if your WS returns a boolean value, then you should specify it like this:

[preSets]="{typeExpected: 'boolean'}"

In a similar way, if your WebService returns null you need to tell the app not to expect any result using the preSets:

[preSets]="{responseExpected: false}"

=== Values of ion-radio, ion-checkbox or ion-select aren't sent to my WS ===

Some directives allow you to specify a form id or name to send the data from the form to a certain WS. These directives look for HTML inputs to retrieve the data to send. However, ion-radio, ion-checkbox and ion-select don't use HTML inputs, they simulate them, so the directive isn't going to find their data and so it won't be sent to the WebService.

There are 2 workarounds to fix this problem. It seems that the next major release of Ionic framework does use HTML inputs, so these are temporary solutions.

==== Sending the data manually ====

The first solution is to send the missing params manually using the "''params''" property. We will use ''ngModel'' to store the input value in a variable, and this variable will be passed to the params. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a template like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>

<button ion-button block type="submit" core-site-plugins-call-ws name="myws" [params]="{id: <% id %>, responses: responses}" form="myform">
{{ 'plugin.mycomponent.save' | translate }}
</button>
</code>

Basically, you need to add ''ngModel'' to the affected element (in this case, the ''radio-group''). You can put whatever name you want as the value, we used "responses". With this, everytime the user selects a radio button the value will be stored in a variable named "responses". Then, in the button we are passing this variable to the params of the WebService.

Please notice that the "form" attribute has priority over "params", so if you have an input with name="responses" it will override what you're manually passing to params.

==== Using a hidden input ====

Since the directive is looking for HTML inputs, you need to add one with the value to send to the server. You can use ''ngModel'' to synchronize your ion-radio/ion-checkbox/ion-select with the new hidden input. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too.

For example, if you have a radio button like this:

<code javascript>
<div radio-group name="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>
</div>
</code>

Then you should modify it like this:

<code javascript>
<div radio-group name="responses" [(ngModel)]="responses">
<ion-item>
<ion-label>First value</ion-label>
<ion-radio value="1"></ion-radio>
</ion-item>

<ion-input type="hidden" [ngModel]="responses" name="responses"></ion-input>
</div>
</code>

In the example above, we're using a variable named "responses" to synchronize the data between the ''radio-group'' and the hidden input. You can use whatever name you want.

=== I can't return an object or array in otherdata ===

If you try to return an object or an array in any field inside ''otherdata'', the WebService call will fail with the following error:

''Scalar type expected, array or object received''

Each field in ''otherdata'' must be a string, number or boolean, it cannot be an object or array. To make it work, you need to encode your object or array into a JSON string:

<code php>
'otherdata' => array('data' => json_encode($data))</code>

The app will automatically parse this JSON and convert it back into an array or object.

==Examples==

===Accepting dynamic names in a WebService===

We want to display a form where the names of the fields are dynamic, like it happens in quiz. This data will be sent to a new WebService that we have created.

The first issue we find is that the WebService needs to define the names of the parameters received, but in this case they're dynamic. The solution is to accept an array of objects with name and value. So in the ''_parameters()'' function of our new WebService, we will add this parameter:

<code php>
'data' => new external_multiple_structure(
new external_single_structure(
array(
'name' => new external_value(PARAM_RAW, 'data name'),
'value' => new external_value(PARAM_RAW, 'data value'),
)
),
'The data to be saved', VALUE_DEFAULT, array()
)</code>

Now we need to adapt our form to send the data as the WebService requires it. In our template, we have a button with the directive ''core-site-plugins-call-ws'' that will send the form data to our WebService. To make this work we will have to pass the parameters manually, without using the "''form''" attribute, because we need to format the data before it is sent.

Since we will send the params manually and we want it all to be sent in the same array, we will use ''ngModel'' to store the input data into a variable that we'll call "data", but you can use the name you want. This "data" will be an object that will hold the input data with the format "name->value". For example, if I have an input with name "a1" and value "My answer", the data object will be:

{a1: "My answer"}

So we need to add ''ngModel'' to all the inputs whose values need to be sent to the "data" WS param. Please notice that ''ngModel'' '''requires''' the element to have a name, so if you add ''ngModel'' to a certain element you need to add a name too. For example:

<code javascript><ion-input name="<% name %>" [(ngModel)]="CONTENT_OTHERDATA.data['<% name %>']"></code>

As you can see, we're using ''CONTENT_OTHERDATA'' to store the data. We do it like this because we'll use ''otherdata'' to initialize the form, setting the values the user has already stored. If you don't need to initialize the form, then you can use the variable "dataObject", an empty object that the Mobile app creates for you: [(ngModel)]="dataObject['<% name %>']"

The Mobile app has a function that allows you to convert this data object into an array like the one the WS expects: ''objectToArrayOfObjects''. So in our button we'll use this function to format the data before it's sent:

<code javascript>
<button ion-button block type="submit" core-site-plugins-call-ws name="my_ws_name"
[params]="{id: <% id %>, data: CoreUtilsProvider.objectToArrayOfObjects(CONTENT_OTHERDATA.data, 'name', 'value')}"
successMessage
refreshOnSuccess="true">
</code>

As you can see in the example above, we're specifying that the keys of the "data" object need to be stored in a property named "name", and the values need to be stored in a property named "value". If your WebService expects different names you need to change the parameters of the function ''objectToArrayOfObjects''.

If you open your plugin now in the Mobile app it will display an error in the Javascript console. The reason is that the variable "data" doesn't exist inside ''CONTENT_OTHERDATA''. As it is explained in previous sections, ''CONTENT_OTHERDATA'' holds the data that you return in ''otherdata'' for your method. We'll use ''otherdata'' to initialize the values to be displayed in the form.

If the user hasn't answered the form yet, we can initialize the "data" object as an empty object. Please remember that we cannot return arrays or objects in ''otherdata'', so we'll return a JSON string.

<code php>
'otherdata' => array('data' => '{}')</code>

With the code above, the form will always be empty when the user opens it. But now we want to check if the user has already answered the form and fill the form with the previous values. We will do it like this:

<code php>
$userdata = get_user_responses(); // It will held the data in a format name->value. Example: array('a1' => 'My value').
...
'otherdata' => array('data' => json_encode($userdata))
</code>

Now the user will be able to see previous values when the form is opened, and clicking the button will send the data to our WebService in array format.

[[Category:Mobile]]