tutorial.md

Tutorial

This tutorial will outline how to create a straightforward notes app. The finished app is available on GitHub.

Setup

After the development tool has been installed the development environment needs to be set up <../general/devenv>. This can be done by either downloading the zip from the website or cloning it directly from GitHub. First, you want to enable debug mode to get proper error messages. To do that set debug to true in the owncloud/config/config.php file

<?php

$CONFIG = [
    'debug' => true,
    ... configuration goes here ...
];

PHP errors are logged to owncloud/data/owncloud.log

Now open another terminal window and start the development server

cd owncloud
php -S localhost:8080

Afterwards, the app can be created in the apps folder

cd apps
ocdev startapp OwnNotes

This creates a new folder called ownnotes. Now access and set up ownCloud through the web interface at http://localhost:8080 and enable the OwnNotes application on the apps page.

The first basic app is now available at http://localhost:8080/index.php/apps/ownnotes/

Routes & Controllers

A typical web application consists of server side and client side code. The glue between those two parts are the URLs. In case of the notes app the following URLs will be used:

• GET /: Returns the interface in HTML
• GET /notes: Returns a list of all notes in JSON
• GET /notes/1: Returns a note with the id 1 in JSON
• DELETE /notes/1: Deletes a note with the id 1
• POST /notes: Creates a new note by passing in JSON
• PUT /notes/1: Updates a note with the id 1 by passing in JSON

On the client side we can call these URLs with the following jQuery code:

// example for calling the PUT /notes/1 URL
var baseUrl = OC.generateUrl('/apps/ownnotes');
var note = {
    title: 'New note',
    content: 'This is the note text'
};
var id = 1;
$.ajax({
    url: baseUrl + '/notes/' + id,
    type: 'PUT',
    contentType: 'application/json',
    data: JSON.stringify(note)
}).done(function (response) {
    // handle success
}).fail(function (response, code) {
    // handle failure
});

On the server side, we need to register a callback that is executed once the request comes in. The callback itself will be a method on a controller <controllers> and the controller will be connected to the URL with a route <routes>. The controller and route for the page are already set up in ``ownno