index.md

# Moodle-Plugin

This documentation part describes the source-code file-structure,
database layout
and functionality of our moodle-plugin.

## Repo/File-Structure

The plugin repo is located at the HFT Stuttgart transfer portal [here][plugin-repo].

It contains a license file,
a readme linking to this documentation
and the plugin code in a subfolder.

This plugin is a moodle [assign-submission-plugin][moodle-assign-submission-plugins].

### Version.php

This file set's a few plugin variables read from moodle.
The `plugin release` variable should contain a version number in the [semantic-version scheme][semver].
The `plugin version` needs to match the `plugin release`. Minor and patch part of the semantic-version have to be padded to three digits.

### Settings.php

This defines the plugin settings, configurable from the moodle plugin administration.

Defined options are the default enabled state for assignments
and the backend url.

### Locallib.php

This file holds the plugin class that extends the `assign_submission_plugin`.

On the top multiple requires are done for the additional files in the subfolders `models` and `utils`.
Next starts the class definition,
overriding the parent classes abstract methods getting called on various actions from the Moodle-UI.

### Models

| file            | content description                                                      |
| --------------- | ------------------------------------------------------------------------ |
| `DttResult.php` | classes `DttResult` and `DttResultSummary` for transferring from backend |

### Utils

| file           | content description                          |
| -------------- | -------------------------------------------- |
| `backend.php`  | logic to communicate with the backend server |
| `database.php` | logic talking to the database                |
| `view.php`     | logic to react to frontend actions           |

## Database

Results from tests are delivered in a summary object,
containing some meta data and an array of single result objects.

Both classes are persisted in their own database table.
Both are matched by the assignment and submission id to which they belong.
An additional redundant relationship between results and summaries was not implemented.

```plantuml

entity "assignsubmission_dtt_summary" as summary {
    id: int <<generated>>
    --
    assignment_id: int <<FK>>
    submission_id: int <<FK>>
    timestamp: int
    global_stacktrace: text
}

entity "assignsubmission_dtt_result" as results {
    id: int <<generated>>
    --
    assignment_id: int <<FK>>
    submission_id: int <<FK>>
    --
    name: char
    state: int
    failure_type: char
    failure_reason: char
    stacktrace: text
    column_number: int
    line_number: int
    position: int
}

entity assign {}
entity assign_submission {}

assign "id" ||--|{ "assignment_id" summary
assign_submission "id" ||-up-|{ "submission_id" summary

assign "id" ||--|{ "assignment_id" results
assign_submission "id" ||-up-|{ "submission_id" results

```

## Functionality

This plugin offers the possibility to create an assignment
that accepts an URL to a Git-repo or a zipped code base as a submission.

The lecturer who creates the assignment must provide a Git repo that contains the test code
and specify a Docker image available on DockerHub that will be used as a test runner.

When a submission is made, it is sent to the backend server.
There it is tested against the test code in the test runner defined by the lecturer.
The connection from the plugin remains open all the time. After completing the test,
the backend closes the connection with the results as a response.

The received results are persisted in the database.
In the view of a submission, a summary table is displayed at the top
and each individual result in a second table below.

[moodle-assign-submission-plugins]: https://docs.moodle.org/dev/Assign_submission_plugins
[plugin-repo]: https://transfer.hft-stuttgart.de/gitlab/dtt/moodle-plugin
[semver]: https://semver.org/