[Pkg-owncloud-commits] [owncloud-doc] 29/270: WIP
David Prévot
taffit at moszumanska.debian.org
Thu Jul 31 03:52:57 UTC 2014
This is an automated email from the git hooks/post-receive script.
taffit pushed a commit to branch master
in repository owncloud-doc.
commit d9f7739a3a5ad88188066403e4efe1457a21fd52
Author: Bernhard Posselt <dev at bernhard-posselt.com>
Date: Wed May 7 00:17:01 2014 +0200
WIP
---
developer_manual/app/app/classloader.rst | 36 --
developer_manual/app/appframework/angular.rst | 464 ---------------------
developer_manual/app/appframework/angularsetup.rst | 335 ---------------
developer_manual/app/classloader.rst | 36 ++
.../app/{appframework => }/container.rst | 0
developer_manual/app/general/angular.rst | 118 ------
developer_manual/app/index.rst | 161 ++++---
developer_manual/app/intro/createapp.rst | 126 ------
developer_manual/app/main.rst | 5 +
developer_manual/app/tutorial.rst | 32 ++
developer_manual/contents.rst | 2 +-
developer_manual/devenv/index.rst | 105 -----
.../{app => }/general/codingguidelines.rst | 2 +-
developer_manual/{app => }/general/debugging.rst | 0
.../{app => }/general/dependencyinjection.rst | 2 +-
developer_manual/general/devenv.rst | 86 ++++
developer_manual/{app => }/general/index.rst | 2 +-
developer_manual/{app => }/general/security.rst | 8 +-
18 files changed, 239 insertions(+), 1281 deletions(-)
diff --git a/developer_manual/app/app/classloader.rst b/developer_manual/app/app/classloader.rst
deleted file mode 100644
index 6c12bf9..0000000
--- a/developer_manual/app/app/classloader.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-Classloader
-===========
-
-.. sectionauthor:: Bernhard Posselt <nukeawhale at gmail.com>
-
-The classloader is provided by ownCloud and loads all your classes automatically. The only thing left to include by yourself are 3rdparty libraries.
-Note that this means that the classes need to be named and organized in folders according to their full qualifier.
-
-The classloader works like this:
-
-* Take the full qualifier of a class::
-
- \OCA\AppTemplateAdvanced\Db\ItemMapper
-
-* If it starts with \\OCA include file from the apps directory
-* Cut off \\OCA::
-
- \AppTemplateAdvanced\Db\ItemMapper
-
-* Convert all charactes to lowercase::
-
- \apptemplateadvanced\db\itemmapper
-
-* Replace \\ with /::
-
- /apptemplateadvanced/db/itemmapper
-
-* Append .php::
-
- /apptemplateadvanced/db/itemmapper.php
-
-* Prepend /apps because of the OCA namespace and include the file::
-
- require '/apps/apptemplateadvanced/db/itemmapper.php';
-
-Remember: for it to be autoloaded, the :file:`itemmapper.php` needs to either be stored in the **/apps/apptemplateadvanced/db/** folder, or adjust its namespace according to the folder it's stored in.
\ No newline at end of file
diff --git a/developer_manual/app/appframework/angular.rst b/developer_manual/app/appframework/angular.rst
deleted file mode 100644
index 32bcf93..0000000
--- a/developer_manual/app/appframework/angular.rst
+++ /dev/null
@@ -1,464 +0,0 @@
-Angular App Framework Libraries
-===============================
-
-.. sectionauthor:: Bernhard Posselt <nukeawhale at gmail.com>
-
-.. versionadded:: 6.0
-
-The App Framework comes with additional libraries which help to interact with the ownCloud server.
-
-
-Include script files
---------------------
-To make use of the the tools include them in your templates.
-
-Using ownCloud Templates:
-
-:file:`templates/main.php`
-
-.. code-block:: php
-
- <?php \OCP\Util::addScript('appframework', 'public/app'); ?>
-
-
-Using Twig Templates:
-
-:file:`templates/main.php`
-
-.. code-block:: js
-
- {{ script('public/app', 'appframework') }}
-
-After the script has been included the modules can be used inside the angular module by injecting them:
-
-:file:`js/app/app.coffee`
-
-.. code-block:: python
-
- # create your application and inject OC
- angular.module('YourApp', ['OC'])
-
-
-General
--------
-Now that the library is loaded and set up they can be used inside the module container. The App Framework follows the convention of marking class names with a leading underscore and object instances without it.
-
-.. note:: The App Framework uses CoffeeScript so if JavaScript objects should extend the provided objects, you need to implement the inheritance like CoffeeScript does it.
-
-Services
---------
-
-The App Framework provides the following services:
-
-Router
-~~~~~~
-The **OC.Router** object
-
-Notification
-~~~~~~~~~~~~
-The **OC.Notification** object
-
-Utils
-~~~~~
-The **OC** object
-
-_Loading
-~~~~~~~~
-Simple object that can be used for displaying loading notifcations. It has an internal counter that starts at 0 and can be increased and decreased. If the counter is bigger than 0 isLoading is true.
-
-Example:
-
-.. code-block:: js
-
- loading = new Loading()
- loading.isLoading() # false
-
- loading.increase()
- loading.isLoading() # true
-
- loading.increase()
- loading.getCount() # 2
-
- loading.decrease()
- loading.decrease()
- loading.isLoading() # false
-
-_Request
-~~~~~~~~
-Used to perform AJAX requests.
-
-Example:
-
-.. code-block:: js
-
- // simple GET request
- req = new _Request($http, new _Publisher(), Router)
- req.get('mail_index')
-
-
-.. js:class:: _Request($http http, _Publisher publisher, Router router)
-
- .. js:function:: request(route[, data])
-
- :param object route: The name of the route that should be used
- :param object data: an object containing optional parameters
-
- Creates an AJAX request. The following data attributes can be set:
-
- * **routeParams**: object with parameters for the route
- * **data**: ajax data objec which is passed to PHP
- * **onSuccess**: callback for successful requests
- * **onFailure**: callback for failed requests
- * **config**: a config which should be passed to $http
-
- .. js:function:: get(route[, data])
-
- :param object route: The name of the route that should be used
- :param object data: an object containing optional parameters
-
- Shortcut for doing a GET request, for data attributes see :js:func:`_Request.request`
-
- .. js:function:: post(route[, data])
-
- :param object route: The name of the route that should be used
- :param object data: an object containing optional parameters
-
- Shortcut for doing a POST request, for data attributes see :js:func:`_Request.request`
-
- .. js:function:: put(route[, data])
-
- :param object route: The name of the route that should be used
- :param object data: an object containing optional parameters
-
- Shortcut for doing a PUT request, for data attributes see :js:func:`_Request.request`
-
- .. js:function:: delete(route[, data])
-
- :param object route: The name of the route that should be used
- :param object data: an object containing optional parameters
-
- Shortcut for doing a DELETE request, for data attributes see :js:func:`_Request.request`
-
-
-_Publisher
-~~~~~~~~~~
-Used to automatically distribute JSON from AJAX Requests to the models. This is especially effective when you need to query for data and dont want to provide a callback to pass the return value to your models.
-
-Example: Passing folders from the server to the client's FolderModel.
-
-.. code-block:: php
-
- <?php
-
- /**
- * @Ajax
- */
- public function getAllFolders(){
- // the keys on the first level can be used
- return $this->renderJSON(array(
- 'foldersKey' => array(
- array('id' => 1, 'name' => 'Books'),
- array('id' => 2, 'name' => 'Stuff')
- )
- ));
- }
-
-They key **foldersKey** can now be registered on the client side by subscribing to it with:
-
-.. code-block:: python
-
- angular.module('YourApp').factory 'Publisher',
- ['_Publisher', 'FolderModel', (_Publisher, FolderModel) ->
-
- publisher = new _Publisher()
- publisher.subscribeObjectTo(FolderModel, 'foldersKey')
-
- return publisher
- ]
-
-Now everytime you call the **getAllFolders** controller method the returned JSON will be passed directly to the FolderModel.
-
-Internally it works like this:
-
-* For each successful request the data JSON array is iterated over
-* If a key is found that a model subscribed to the data will be passed to its **handle()** method
-
-The default **handle()** method of the model only adds/updates the new object. To add custom behaviour you can overwrite the method.
-
-_Model
-~~~~~~
-Used as a model parent class and provides CRUD and caching logic for the JSON data.
-
-
-.. js:class:: _Model
-
- .. js:function:: add(data)
-
- :param object data: The object that should be added
-
- Adds a new item. If the item id is already present, it will be updated
-
- .. js:function:: update(data[, clearCache=true])
-
- :param object data: The object that should be updated
- :param boolean clearCache: clears the existing queries cache. Set this to false if the update does not affect the queries on the model to improve performance
-
- Updates an existing object by copying the provided attributes to the old one. That means that if you want to update only one field simply pass an object with the correct id and the fields that should be overwritten.
-
- Example:
-
- .. code-block:: js
-
- // udpate name and email
- itemModel.update({id: 3, name: 'newName', email: 'newEmail'})
-
- .. js:function:: add(data[, clearCache=true])
-
- :param object data: The object that should be added
- :param boolean clearCache: clears the existing queries cache. Set this to false if the update does not affect the queries on the model to improve performance
-
-
- .. js:function:: getById(id[, clearCache=true])
-
- :param int id: The id of the object
- :param boolean clearCache: clears the existing queries cache. Set this to false if the update does not affect the queries on the model to improve performance
- :returns object: a data object by its id
-
-
- .. js:function:: getAll()
-
- :returns array: an array with all stored objects
-
-
- .. js:function:: clear()
-
- Deletes all stored data objects
-
-
- .. js:function:: size()
-
- :returns int: the count of all stored data objects
-
- .. js:function:: get(Query query)
-
- :param Query query: an instance of a Query class or subclass
- :returns mixed: the returnvalue of the query
-
- Runs a query over all stored objects and returns the result which is calculated in the query. This is cached by params and query. The cache is deleted after a new add/update/remove method was called.
-
-
-Queries
-^^^^^^^
-Because AngularJS getters have to be fast (Angular checks for changed objects after each digest) the App Framework provides cachable queries. The following queries are available:
-
-* **_BiggerThanQuery**
-* **_BiggerThanEqualQuery**
-* **_LessThanQuery**
-* **_LessThanEqualQuery**
-* **_EuqalQuery**
-* **_NotEuqalQuery**
-* **_ContainsQuery**
-* **_DoesNotContainQuery**
-* **_MinimumQuery**
-* **_MaximumQuery**
-
-To query an object with a **_BiggerThanQuery** use its **get** method:
-
-.. code-block:: js
-
- valuesBiggerThan4 = myModel.get(new _BiggerThanQuery('id', 4))
-
-This query is cached until a new entry is added, removed or updated.
-
-.. note:: Do not update the objects by hand only. Always use the model's update method to tell it that a model has changed. Otherwise you run into an invalid cache!
-
-Writing your own queries
-^^^^^^^^^^^^^^^^^^^^^^^^
-For more complex queries the **_Query** object can be extended. Each query object has a **hashCode** and **exec** method. The **hashCode** method is used to generate a unique hash for the query and its arguments so that it can be cached. The built in method works like this:
-
-* Take all the arguments values
-* replace _ with __ in the argument values
-* Construct the hash by: QUERYNAME_ARG1Value_ARG2Value etc.
-
-You can override this method if you need to. The **exec** method is used to run the query. It receives an array with all objects and returns the filtered content.
-
-A query that would select only ids between a range of numbers would look like this:
-
-.. code-block:: ruby
-
- angular.module('YourApp').factory '_LessThanQuery', ['_Query', (_Query) ->
-
- class RangeQuery extends _Query
-
- # @_field is the attribute name of the object
- constructor: (@_field, @_lowerBound, @_upperBound) ->
- name = 'range'
- super(name, [@_field, @_lowerBound, @_upperBound])
-
- exec: (data) ->
- filtered = []
- for entry in data
- if entry[@_field] < @_upperBound and entry[@_field] > @_lowerBound
- filtered.push(entry)
-
- return filtered
-
-
- return RangeQuery
- ]
-
-If **hashCode** is not overwritten it would produce the following output:
-
-.. code-block:: ruby
-
- query = new _RangeQuery('id', 3, 6)
- query.hashCode() # prints range_id_3_6
-
-
-Directives
-----------
-The App Framework provides the following directives:
-
-ocClickSlideToggle
-~~~~~~~~~~~~~~~~~~
-Can be used for the settings slideup or to slide up any area and hide it on focus lost.
-
-Can be enhanced by passing an expression:
-
-.. code-block:: js
-
- {
- selector: '#jquery .selector'
- hideOnFocusLost: true
- cssClass: 'opened'
- }
-
-* **selector**: if defined, a different area is slid up on click
-* **hideOnFocusLost**: if defined, the slid up area will hide when the focus is lost
-* **cssClass**: if defined, the class which should be toggled on the element where the directive is bound to
-
-Example:
-
-.. code-block:: html
-
- <button oc-click-slide-toggle="{selector: '#settings', hideOnFocusLost: true}" />
- <div id="settings"></div>
-
-
-ocClickFocus
-~~~~~~~~~~~~
-Can be used to focus a different element when the element is being clicked that has this directive
-
-Must pass an expression:
-
-.. code-block:: js
-
- {
- selector: '#jquery .selector',
- timeout: 300
- }
-
-* **selector**: the area that should be focused
-* **timeout**: optional, if the focus should be done after a timeout
-
-Example:
-
-.. code-block:: html
-
- <button oc-click-focus="{selector: '#settings'}" />
- <input id="settings" type="text" />
-
-
-ocReadFile
-~~~~~~~~~~~~
-Can be used to pass the contents of a file input field to a function. The directive binds to the **change** event of the input. The read content will be assigned to the scope as $fileContent variable and the given function will be called.
-
-Example:
-
-.. code-block:: html
-
- <input type="file" name="import" oc-read-file="import($fileContent)"/>
-
-
-ocDraggable
-~~~~~~~~~~~
-Shortcut for using jquery-ui draggable. The expression is passed to $.draggable.
-
-These two are equivalent:
-
-.. code-block:: js
-
- $('#settings').draggable({ cursor: "move", cursorAt: { top: 56, left: 56 } });
-
-.. code-block:: html
-
- <div id="settings" oc-draggable="{ cursor: 'move', cursorAt: { top: 56, left: 56 } }"></div>
-
-
-ocForwardClick
-~~~~~~~~~~~~~~
-Used to forward a click. Useful to trigger a hidden file upload field by clicking a visible button.
-
-Needs an expression:
-
-.. code-block:: js
-
- {
- selector: '#jquery .selector'
- }
-
-* **selector**: the are where the click needs to redirected to
-
-Example:
-
-.. code-block:: html
-
- <button oc-forward-click="{selector: '#upload'}" />
- <input type="file" id="upload" />
-
-
-ocTooltip
-~~~~~~~~~
-Binds a bootstrap tooltip on the item.
-
-Example:
-
-.. code-block:: html
-
- <button oc-tooltip title="tooltip text" />
-
-
-Filters
-----------
-The App Framework provides the following filters:
-
-ocRemoveTags
-~~~~~~~~~~~~
-Used to remove certain HTML tags from a string.
-
-You can pass in a string or an array of strings which HTML tags which will be removed.
-
-Example:
-
-.. code-block:: html
-
- <!-- remove all em tags -->
- <h1>{{ title|ocRemoveTags:'em' }}</h1>
-
- <!-- remove all em,b and i tags -->
- <h1>{{ title|ocRemoveTags:['em', 'i', 'b'] }}</h1>
-
-
-
-ocSanitizeURL
-~~~~~~~~~~~~~
-Used to sanitize an URL to prevent XSS in **src** and **href** attributes (e.g. <a href="javascript:alert(1)">).
-
-
-Example:
-
-.. code-block:: html
-
- <a href="{{ link|ocSanitizeURL }}">My link</a>
-
-
diff --git a/developer_manual/app/appframework/angularsetup.rst b/developer_manual/app/appframework/angularsetup.rst
deleted file mode 100644
index a038841..0000000
--- a/developer_manual/app/appframework/angularsetup.rst
+++ /dev/null
@@ -1,335 +0,0 @@
-Angular Setup
-=============
-.. sectionauthor:: Bernhard Posselt <nukeawhale at gmail.com>
-
-The following tools are recommended when including :doc:`../general/angular` into the app.
-
-Recommended layout
-------------------
-
-If AngularJS should be used for the app, the following files layout is recommended. If CoffeeScript is used, use the same layout only with the **.coffee** extension instead of the **.js** extension.
-
-The main logic goes into:
-
-* **js/app/app.js**: The main file where the module is being initiated
-* **js/app/directives/**: folder for directives
-* **js/app/controllers/**: folder for controllers
-* **js/app/filters/**: folder for filters
-* **js/app/services/**: folder for services
-
-Tests go into:
-
-* **js/tests/stubs/app.js**: Use this for initializing the container for tests
-* **js/tests/directives/**: folder for directive tests
-* **js/tests/controllers/**: folder for controller tests
-* **js/tests/filters/**: folder for filter tests
-* **js/tests/services/**: folder for service tests
-* **js/tests/vendor/**: folder for js libs that are only included in the tests for instance jquery
-
-Configuration files go into:
-
-* **js/config/testacular_conf.js**: `Testacular <http://testacular.github.com/0.6.0/index.html>`_ (used for unittests) configuration
-
-The compiled files go into:
-
-* **js/public/app.js**: The compiled JavaScript
-
-Additional JavaScript libs that are used in the app go into:
-
-* **js/vendor/**
-
-Build
------
-The app will likely depend on various **node.js** tools for building the JavaScript/CoffeeScript. To make setup and development easy it is recommended to provide a **package.json** inside the **js/** directory.
-
-This example contains additional dependencies for CoffeeScript. Adjust this to your needs.
-
-:file:`js/package.json`
-
-.. code-block:: js
-
- {
- "name": "owncloud-appframework",
- "description": "ownCloud App Framework",
- "version": "0.0.1",
- "author": {
- "name": "Bernhard Posselt",
- "email": "nukeawhale at gmail.com"
- },
- "private": true,
- "homepage": "https://github.com/owncloud/apps/tree/appframework-js/appframework/",
- "repository": {
- "type": "git",
- "url": "git at github.com:owncloud/apps.git"
- },
- "bugs": "https://github.com/owncloud/apps/issues",
- "contributors": [],
- "dependencies": {},
- "devDependencies": {
- "grunt": "~0.4.0",
- "grunt-cli": "~0.1.6",
- "coffee-script": "~1.4.0",
- "grunt-contrib-concat": "~0.1.2",
- "grunt-contrib-watch": "~0.2.0",
- "grunt-coffeelint": "0.0.6",
- "grunt-wrap": "~0.2.0",
- "phantomjs": "~1.8.1-3",
- "grunt-phpunit": "0.2.0",
- "gruntacular": "~0.3.0"
- },
- "engine": "node >= 0.8"
- }
-
-
-To build the JavaScript/CoffeeScript a buildsystem like `Grunt <http://gruntjs.com/>`_ is recommended. To get a good overview watch the `Tutorial video with Ben Alman <http://www.youtube.com/watch?v=Xp6aFno24x4>`_.
-
-The configfile for Grunt should be placed in the **js/** directory and can either contain CoffeeScript or JavaScript.
-
-An example for a CoffeeScript configuration would be:
-
-:file:`js/Gruntfile.coffee`
-
-.. code-block:: python
-
- module.exports = (grunt) ->
-
- grunt.loadNpmTasks('grunt-contrib-concat')
- grunt.loadNpmTasks('grunt-contrib-watch')
- grunt.loadNpmTasks('grunt-coffeelint')
- grunt.loadNpmTasks('grunt-wrap');
- grunt.loadNpmTasks('grunt-phpunit');
- grunt.loadNpmTasks('gruntacular');
-
- grunt.initConfig
-
- meta:
- pkg: grunt.file.readJSON('package.json')
- version: '<%= meta.pkg.version %>'
- banner: '/**\n' +
- ' * <%= meta.pkg.description %> - v<%= meta.version %>\n' +
- ' *\n' +
- ' * Copyright (c) <%= grunt.template.today("yyyy") %> - ' +
- '<%= meta.pkg.author.name %> <<%= meta.pkg.author.email %>>\n' +
- ' *\n' +
- ' * This file is licensed under the Affero General Public License version 3 or later.\n' +
- ' * See the COPYING-README file\n' +
- ' *\n' +
- ' */\n\n'
- build: 'build/'
- production: 'public/'
-
- concat:
- app:
- options:
- banner: '<%= meta.banner %>\n'
- stripBanners:
- options: 'block'
- src: [
- '<%= meta.build %>app/app.js'
- '<%= meta.build %>app/directives/*.js'
- '<%= meta.build %>app/services/**/*.js'
- ]
- dest: '<%= meta.production %>app.js'
- wrap:
- app:
- src: '<%= meta.production %>app.js'
- dest: ''
- # adjust this to include more top level js libs
- wrapper: [
- '(function(angular, $, undefined){\n\n'
- '\n})(window.angular, jQuery);'
- ]
-
- coffeelint:
- app: [
- 'app/**/*.coffee'
- 'tests/**/*.coffee'
- ]
- options:
- 'no_tabs':
- 'level': 'ignore'
- 'indentation':
- 'level': 'ignore'
- 'no_trailing_whitespace':
- 'level': 'warn'
-
- watch:
- concat:
- files: [
- '<%= meta.build %>app/**/*.js'
- '<%= meta.build %>tests/**/*.js'
- ]
- tasks: 'compile'
- phpunit:
- files: '../**/*.php'
- tasks: ['phpunit']
-
- testacular:
- unit:
- configFile: 'config/testacular.conf.js'
- continuous:
- configFile: 'config/testacular.conf.js'
- singleRun: true
- browsers: ['PhantomJS']
- reporters: ['progress', 'junit']
- junitReporter:
- outputFile: 'test-results.xml'
-
- phpunit:
- classes:
- dir: '../tests'
- options:
- colors: true
-
-
- grunt.registerTask('run', ['watch:concat'])
- grunt.registerTask('compile', ['concat', 'wrap', 'coffeelint'])
- grunt.registerTask('ci', ['testacular:continuous'])
- grunt.registerTask('testphp', ['watch:phpunit'])
-
-
-If no CoffeeScript is being used, coffeelint should be replaced with jshint and jslint.
-
-To give people a well known environment a Makefile is recommended to start the various tasks:
-
-.. code-block:: make
-
- firefox_bin=/usr/bin/firefox
- chrome_bin=/usr/bin/chromium
- coffee=$(CURDIR)/node_modules/coffee-script/bin/coffee
- grunt=$(CURDIR)/node_modules/grunt-cli/bin/grunt
- phantomjs=$(CURDIR)/node_modules/phantomjs/bin/phantomjs
-
- all: compile
-
- deps:
- cd $(CURDIR)/
- npm install --deps
-
- watch: compile
- $(coffee) --compile --watch --output $(CURDIR)/build/app $(CURDIR)/app/ & \
- $(coffee) --compile --watch --output $(CURDIR)/build/tests $(CURDIR)/tests/ & \
- $(grunt) --config $(CURDIR)/Gruntfile.coffee run
-
- testacular: deps
- export CHROME_BIN=$(chrome_bin) && export FIREFOX_BIN=$(firefox_bin) && \
- $(grunt) --config $(CURDIR)/Gruntfile.coffee testacular:unit
-
- phpunit: deps
- $(grunt) --config $(CURDIR)/Gruntfile.coffee testphp
-
- compile: deps
- mkdir -p $(CURDIR)/build/app
- mkdir -p $(CURDIR)/build/tests
- mkdir -p $(CURDIR)/public
- $(coffee) --compile --output $(CURDIR)/build/app $(CURDIR)/app/
- $(coffee) --compile --output $(CURDIR)/build/tests $(CURDIR)/tests/
- $(grunt) --config $(CURDIR)/Gruntfile.coffee compile
-
- test: deps compile
- export PHANTOMJS_BIN=$(phantomjs) && \
- $(grunt) --config $(CURDIR)/Gruntfile.coffee ci
-
-
- clean:
- rm -rf $(CURDIR)/build
- rm -rf $(CURDIR)/test-results.xml
-
-The above makefile can be used to watch and compile the changes with::
-
- make watch
-
-The unittests can be automatically run on change in a second terminal window::
-
- make testacular
-
-
-Set up Testacular
------------------
-`Testacular <http://testacular.github.com/0.6.0/index.html>`_ is able to run unittests when a JavaScript file changes. On the continues integration server these tests can be run with **PhantomJS** (or if a graphical environment is installed also with other browsers). A **JUnit** compatible testresult can be configured.
-
-.. note:: The config values can be overwritten in the Gruntfile
-
-An example file would look like:
-
-:file:`js/config/testacular_conf.js`
-
-.. code-block:: js
-
- // base path, that will be used to resolve files and exclude
- // since this is in the config/ folder we have to go one directory higher
- basePath = '../';
-
-
- // list of files / patterns to load in the browser
- files = [
-
- // your favorite test library, needs to have an adapter
- JASMINE,
- JASMINE_ADAPTER,
-
- // commonly included libraries that are provided by owncloud need to be
- // loaded because we dont have access to those in the test environment
- 'tests/vendor/jquery-1.9.1/jquery-1.9.1.js',
- 'tests/vendor/jquery-ui-1.10.0/jquery-ui-1.10.0.custom.js',
- 'tests/vendor/angular-1.0.4/angular.js',
- 'tests/vendor/angular-1.0.4/angular-mocks.js',
-
- // you want to use the ngMocks container thats why you have to redefine the
- // main js file
- 'tests/stubs/app.js',
-
- // these are your js and testfiles that you want to use
- 'build/app/directives/*.js',
- 'build/app/filters/*.js',
- 'build/app/services/**/*.js',
- 'build/tests/**/*Spec.js'
- ];
-
-
- // list of files to exclude
- // reason: see the files array
- exclude = [
- 'build/app/app.js'
- ];
-
- // test results reporter to use
- // possible values: 'dots', 'progress', 'junit'
- reporters = ['progress'];
-
- // web server port
- port = 8080;
-
- // cli runner port
- runnerPort = 9100;
-
- // enable / disable colors in the output (reporters and logs)
- colors = true;
-
- // level of logging
- // possible values: LOG_DISABLE || LOG_ERROR || LOG_WARN || LOG_INFO || LOG_DEBUG
- logLevel = LOG_INFO;
-
-
- // enable / disable watching file and executing tests whenever any file changes
- autoWatch = true;
-
-
- // Start these browsers, currently available:
- // - Chrome
- // - ChromeCanary
- // - Firefox
- // - Opera
- // - Safari (only Mac)
- // - PhantomJS
- // - IE (only Windows)
- browsers = ['Chrome'];
-
-
- // If browser does not capture in given timeout [ms], kill it
- captureTimeout = 5000;
-
-
- // Continuous Integration mode
- // if true, it capture browsers, run tests and exit
- singleRun = false;
diff --git a/developer_manual/app/classloader.rst b/developer_manual/app/classloader.rst
new file mode 100644
index 0000000..ff22590
--- /dev/null
+++ b/developer_manual/app/classloader.rst
@@ -0,0 +1,36 @@
+Classloader
+===========
+
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
+
+The classloader is provided by ownCloud and loads all your classes automatically. The only thing left to include by yourself are 3rdparty libraries.
+Note that this means that the classes need to be named and organized in folders according to their full qualifier.
+
+The classloader works like this:
+
+* Take the full qualifier of a class::
+
+ \OCA\MyApp\Controller\PageController
+
+* If it starts with \\OCA include file from the apps directory
+* Cut off \\OCA::
+
+ \MyApp\Controller\PageController
+
+* Convert all charactes to lowercase::
+
+ \myapp\controller\pagecontroller
+
+* Replace \\ with /::
+
+ /myapp/controller/pagecontroller
+
+* Append .php::
+
+ /myapp/controller/pagecontroller.php
+
+* Prepend /apps because of the **OCA** namespace and include the file::
+
+ require_once '/apps/myapp/controller/pagecontroller.php';
+
+**In other words**: In order for the PageController class to be autoloaded, the :file:`pagecontroller.php` needs to either be stored in the **/apps/myapp/controller/** folder
\ No newline at end of file
diff --git a/developer_manual/app/appframework/container.rst b/developer_manual/app/container.rst
similarity index 100%
rename from developer_manual/app/appframework/container.rst
rename to developer_manual/app/container.rst
diff --git a/developer_manual/app/general/angular.rst b/developer_manual/app/general/angular.rst
deleted file mode 100644
index bfffcc0..0000000
--- a/developer_manual/app/general/angular.rst
+++ /dev/null
@@ -1,118 +0,0 @@
-AngularJS
-=========
-
-.. sectionauthor:: Bernhard Posselt <nukeawhale at gmail.com>
-
-`AngularJS <http://angularjs.org/>`_ is an MV* JavaScript framework by Google.
-
-Documentation is available at these sources:
-
-* `Official tutorial <http://docs.angularjs.org/tutorial/>`_
-* `Developer guide <http://docs.angularjs.org/guide/>`_
-* `API reference <http://docs.angularjs.org/api/>`_
-* `Screencasts on Youtube <http://www.youtube.com/user/angularjs>`_
-* `More screencasts <http://www.egghead.io/>`_
-* `Collection of resources <https://github.com/jmcunningham/AngularJS-Learning>`_
-
-What problem does it solve
---------------------------
-jQuery is a nice library but when it comes to building webapplications, one will soon reach a point where its becoming increasingly impossible to split view and logic.
-
-That problem is caused by jQueries habit to operate directly on dom elements. Most jQuery code looks like this:
-
-.. code-block:: javascript
-
- $('.someElement').doSomething();
-
-
-That makes it incredible hard to refactor your view because your whole JavaScript code is tightly coupled to the structure and classes in your HTML.
-
-Another problem is the dynamic generation of DOM elements. You'd normally go with one of these three approaches:
-
-
-**1**) Create new element, bind event listeners and append it to the dom:
-
-.. code-block:: javascript
-
- var $newButton = $('<button>').text('A new button');
- $newButton.click(function(){
- alert('I was clicked!');
- });
- $('.someElement').append($newButton);
-
-
-**2**) Fetch HTML from the server and bind event listeners:
-
-.. code-block:: javascript
-
- $.post('/some/url', function(data){
- $newButton = $(data);
- $newButton.click(function(){
- alert('I was clicked!');
- });
- $('.someElement').append($newButton);
- });
-
-**3**) Use jquery templates:
-
-.. code-block:: javascript
-
- var buttons = [
- text: 'A new button'
- ];
- var markup = "<button>${text}</button>";
-
- $.template( "myTemplate", markup );
- $.tmpl( "myTemplate", buttons ).appendTo( ".someElement" );
- // and bind the click listener
-
-
-All of the above split the HTML from the original HTML and its hard to bind event listeners (yes, there's $.on(), but its slow). You are also in need of updating the DOM by hand.
-
-In contrast to the above solutions, Angular uses XML attributes to define the template logic. This approach does not only good for your editor, but you're also less likely to create HTML errors. You can even validate the HTML. Furthermore, every value that is written into the HTML is escaped to prevent XSS.
-
-Concerning testability: Angular uses Dependency Injection to glue the code together and it's easy to run your unittests(look at the examples in the official docs). Angular also ships with mocks for common areas like HTTP requests or logging.
-
-Thats how the code would look with Angular:
-
-.. code-block:: html
-
- <div ng-app="MyApp" class="someElement" ng-controller="ButtonController">
- <button ng-repeat="button in buttons" ng-click="showClicked()">{{ button.text }}</button>
- </div>
-
-The button controller handles the complete logic. It would look something like this:
-
-.. code-block:: javascript
-
- var app = angular.module('MyApp', []);
-
- app.controller('ButtonController', ['$scope',
- function($scope){
- $scope.buttons = [
- {text: 'A new button'}
- ];
- $scope.showClicked = function(){
- alert('I was clicked!');
- };
- }
- );
-
-Now your logic is nicely decoupled from your view and the template logic is where you would expect it to be: in the HTML markup.
-
-Angular also knows when your data has changed: when a new element is added to the **$scope.buttons** array, the view will automatically update. It also updates the view when an existing element in the array changes.
-
-
-Drawbacks of AngularJS
-----------------------
-That brings us also to the biggest problem of AngularJS: It can be slow at times. This is caused by `the way Angular works <http://docs.angularjs.org/guide/concepts>`_
-
-Should you somehow require to show more than around 1000 complex elements at once (like 1000 buttons with lots of wiring inside the code and a ton of attributes) there will most likely be performance problems (To be fair: normal JavaScript would also run into performance problems).
-
-One way to tackle this is to use autopaging (progressive loading) that only renders X elements and loads the next batch when the user scrolls down for instance. This also reduces the traffic. Software that successfully uses this approach is Google Reader for instance.
-
-When porting the News app to AngularJS we found that the benefits outweighed the drawbacks and that we could optimize the Code well enough to offer a good user experience.
-
-But all in all you should build an optimized prototype and compare it to a non angular app to make sure that the user experience is good.
-
-
diff --git a/developer_manual/app/index.rst b/developer_manual/app/index.rst
index 4baa1aa..de3678e 100644
--- a/developer_manual/app/index.rst
+++ b/developer_manual/app/index.rst
@@ -1,5 +1,7 @@
.. _appindex:
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
+
===============
App Development
===============
@@ -8,131 +10,112 @@ App Development
:maxdepth: 1
:hidden:
- general/index
- intro/index
- app/index
- appframework/index
+ ../general/index
+ tutorial
+ main
+ classloader
+ container
+ routes
+ info
+ controllers
+ schema
+ database
+ templates
+ js
+ css
+ middleware
+ hooks
+ backgroundjobs
+ api
+ testing
+
Intro
------
+=====
Before you start, please check if there already is a `similar app <http://apps.owncloud.com>`_ you could contribute to. Also, feel free to communicate your idea and plans to the `user mailing list <http://mailman.owncloud.org/mailman/listinfo/user>`_ or `developer mailing list <http://mailman.owncloud.org/mailman/listinfo/devel>`_ so other contributors might join in.
Then, please make sure you have set up a development environment:
-* :ref:`devenv`
+* :doc:`../general/devenv`
Before starting to write an app please read the security and coding guidelines:
-* :doc:`general/security`
-* :doc:`general/codingguidelines`
-
-After this you can start to write your app:
+* :doc:`../general/security`
+* :doc:`../general/codingguidelines`
-* :doc:`intro/createapp`
+After this you can start to write your first app:
-App Development using ownCloud App API
---------------------------------------
-You can choose between the traditional and MVC style (App Framework) approach. For a comparison see :ref:`appframework-compare`. This approach uses the basic ownCloud libraries and provides no classes to use for MVC development and testing.
+* :doc:`tutorial`
-* :doc:`app/tutorial`
+App development
+===============
+Inner parts of an app:
+* :doc:`main`
+* :doc:`classloader`
+* :doc:`container`
+* :doc:`routes`
+* :doc:`info`
-General
-~~~~~~~
-Inner parts of an app
+Controllers
+-----------
+Contain the logic for each request
-* :doc:`app/classloader`
-* :doc:`app/routes`
-* :doc:`app/info`
-* :doc:`general/debugging`
+* :doc:`controllers`
Database
-~~~~~~~~
-Database access
+--------
+Create database tables and run Sql queries:
-* :doc:`app/schema` | :doc:`app/database`
+* :doc:`schema`
+* :doc:`database`
Templates
-~~~~~~~~~
+---------
HTML and inclusion of JavaScript and CSS
-* :doc:`app/templates`
+* :doc:`templates`
JavaScript & CSS
-~~~~~~~~~~~~~~~~
-* :doc:`app/static`
-* :doc:`app/css`
+----------------
+Add JavaScript and CSS to your app:
-Testing
-~~~~~~~
-* :doc:`app/acceptancetesting`
+* :doc:`js`
+* :doc:`css`
-API Documentation
-~~~~~~~~~~~~~~~~~
-* `ownCloud App API <http://api.owncloud.org/namespaces/OCP.html>`_
-
-App Development using the App Framework App
--------------------------------------------
-Develop an app using an MVC Framework. The App Framework provides enhanced Security, MVC classes and testing tools but you need to read more until you can produce the first output.
-
-* :doc:`appframework/tutorial`
-
-General
-~~~~~~~
-Inner parts of an app
-
-* :doc:`appframework/classloader`
-* :doc:`appframework/container` | :doc:`general/dependencyinjection`
-* :doc:`appframework/routes`
-* :doc:`appframework/info`
-* :doc:`general/debugging`
-
-Controllers
-~~~~~~~~~~~
-Contain the logic for each request
+Middleware
+----------
+Hook before or after controller execution and exceptions:
-* :doc:`appframework/controllers`
+* :doc:`middleware`
-Database
-~~~~~~~~
-Database access
+Hooks
+-----
+Listen on events like user creation and execute code:
-* :doc:`appframework/schema` | :doc:`appframework/database`
+* :doc:`hooks`
-Templates
-~~~~~~~~~
-HTML and inclusion of JavaScript and CSS
+Background Jobs
+---------------
+Periodically run code in the background:
+* :doc:`:`backgroundjobs`
-* :doc:`appframework/templates`
-JavaScript & CSS
-~~~~~~~~~~~~~~~~
-* :doc:`appframework/static`
-* :doc:`general/angular` | :doc:`appframework/angularsetup` | :doc:`appframework/angular`
-* :doc:`appframework/css`
+Testing
+-------
+Write automated tests to ensure stability and ease maintenance:
-Middleware
-~~~~~~~~~~
-Hook before or after controller execution
+* :doc:`testing`
-* :doc:`appframework/middleware`
+Creating a RESTful API
+----------------------
+How to create an API that other apps can connect to:
-Testing
-~~~~~~~
-* :doc:`appframework/unittesting`
-* :doc:`app/acceptancetesting`
+* :doc:`api`
API Documentation
-~~~~~~~~~~~~~~~~~
-* :doc:`appframework/api/index`
-* `ownCloud App API <http://api.owncloud.org/namespaces/OCP.html>`_
-
-Additional APIs
----------------
-Can be used with and without App Framework
-
-* :doc:`appframework/data-migration`
-* :doc:`appframework/hooks`
-* :doc:`appframework/filesystem`
+-----------------
+ownCloud class and function documentation:
+* `ownCloud App API <http://api.owncloud.org/namespaces/OCP.html>`_
\ No newline at end of file
diff --git a/developer_manual/app/intro/createapp.rst b/developer_manual/app/intro/createapp.rst
deleted file mode 100644
index 40f8e3d..0000000
--- a/developer_manual/app/intro/createapp.rst
+++ /dev/null
@@ -1,126 +0,0 @@
-Creating An App
-===============
-
-.. sectionauthor:: Bernhard Posselt <nukeawhale at gmail.com>
-
-After the apps were cloned into either
-
-* **/var/www**
-* **/var/www/html**
-* **/srv/http**
-
-Depending on the used distribution change into that directory inside a terminal::
-
- cd /var/www/
-
-Create the app automatically
-----------------------------
-The scaffolding script provides an easy way to generate boilerplate code for an app. To install the tool, install **Python 3** and **python-pip**, then run::
-
- sudo pip install owncloud_scaffolding
-
-To create an app using the **App Framework** run::
-
- owncloud.py startapp myapp
-
-To create a standard ownCloud app run::
-
- owncloud.py startapp --classic myapp
-
-This will create all the needed files in the current directory. For more information on how to customize the generated app, see the `GitHub page <https://github.com/Raydiation/owncloud_scaffolding>`_
-
-Create the app manually
------------------------
-If you dont want to use the scaffolding tool, heres how you create all the needed files: create a directory for the app and make it writable::
-
- mkdir apps/YOUR_APP
- sudo chown -R YOUR_USER:users apps/YOUR_APP
-
-If you are unsure about your user **whoami** to find out your user::
-
- whoami
-
-Create basic files
-~~~~~~~~~~~~~~~~~~
-The following files need to be created: :file:`appinfo/info.xml`, :file:`appinfo/version` and :file:`appinfo/app.php`. To do that change into the directory of your app::
-
- cd apps/YOUR_APP
- mkdir appinfo
- touch appinfo/version appinfo/app.php appinfo/info.xml
-
-Set app version
-~~~~~~~~~~~~~~~
-To set the version of the app, simply write the following into :file:`appinfo/version`::
-
- 0.1
-
-Create metadata
-~~~~~~~~~~~~~~~
-ownCloud has to know what your app is. This information is located inside the :file:`appinfo/info.xml`:
-
-.. code-block:: xml
-
- <?xml version="1.0"?>
- <info>
- <id>appname</id>
- <name>My App</name>
- <description>Simple app that does some computing</description>
- <version>1.0</version>
- <licence>AGPL</licence>
- <author>Your Name</author>
- <require>5</require>
- </info>
-
-For more information on the content of :file:`appinfo/info.xml` see: :doc:`../app/info`
-
-Enable the app
---------------
-The easiest way to enable is to symlink it into the **owncloud/apps** directory::
-
- ln -s /var/www/apps/YOUR_APP /var/www/owncloud/apps/
-
-This is also how other apps from the **apps** directory have to be enabled. A second way is to tell ownCloud about the directory. Use :doc:`../../core/configfile` to set up multiple app directories.
-
-The app can now be enabled on the ownCloud apps page.
-
-.. note:: The app does not show up yet in the navigation. This is intended. How to create an entry in the navigation is explained in the following tutorials.
-
-Start coding
-------------
-The basic files are now in place and the app is enabled. There are two ways to create the app:
-
-* Use the :doc:`ownCloud app API <../app/tutorial>`
-* Use the :doc:`App Framework app <../appframework/tutorial>`
-
-If you are new to programming and want to create an app fast you migth want to use the ownCloud app API, if you are an advanced programmer or used to frameworks you might want to use the App Framework App.
-
-.. _appframework-compare:
-
-App Framework Comparison
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-To simplify the decision see this comparison chart:
-
-+-----------------+-------------------------+--------------------------------+
-| Criteria | ownCloud app API | App Framework |
-+=================+=========================+================================+
-| Difficulty | easy | medium |
-+-----------------+-------------------------+--------------------------------+
-| Architecture | routes and templates | routes and MVC |
-+-----------------+-------------------------+--------------------------------+
-| Testability | hard | easy: built-in :doc:`\ |
-| | | ../general/dependencyinjection`|
-| | | and `TDD`_ tools |
-+-----------------+-------------------------+--------------------------------+
-| Maintainability | hard | easy |
-+-----------------+-------------------------+--------------------------------+
-| Templates | :php:class:`OC_Template`| :php:class:`OC_Template` |
-| | | and `Twig`_ |
-+-----------------+-------------------------+--------------------------------+
-| Security | manual checks | escapse XSS (Twig only), does |
-| | | CSRF and Authentication checks |
-| | | by default |
-+-----------------+-------------------------+--------------------------------+
-
-.. _Twig: http://twig.sensiolabs.org
-.. _TDD: http://en.wikipedia.org/wiki/Test-driven_development
diff --git a/developer_manual/app/main.rst b/developer_manual/app/main.rst
new file mode 100644
index 0000000..5b8323b
--- /dev/null
+++ b/developer_manual/app/main.rst
@@ -0,0 +1,5 @@
+Main
+====
+
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
+
diff --git a/developer_manual/app/tutorial.rst b/developer_manual/app/tutorial.rst
new file mode 100644
index 0000000..497e37a
--- /dev/null
+++ b/developer_manual/app/tutorial.rst
@@ -0,0 +1,32 @@
+Tutorial
+========
+
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
+
+After :doc:`you've set up the development environment and installed the dev tool <../general/devenv>` change into the ownCloud apps directory::
+
+ cd /var/www/core/apps
+
+Then run::
+
+ ocdev startapp MyApp --mail mail at example.com --author "Your Name" --description "My first app"
+
+This will create all the needed files in the current directory. For more information on how to customize the generated app, see the `Project's GitHub page <https://github.com/Raydiation/ocdev>`_ or run::
+
+ ocdev startapp -h
+
+Enable the app
+--------------
+The app can now be enabled on the ownCloud apps page
+
+App architecture
+----------------
+The following directories have now been created:
+
+* **appinfo/**: Contains app metadata and configuration
+* **controller/**: Contains the controllers
+* **css/**: Contains the CSS
+* **js/**: Contains the JavaScript files
+* **templates/**: Contains the templates
+* **tests/**: Contains the tests
+
diff --git a/developer_manual/contents.rst b/developer_manual/contents.rst
index 8089411..372a656 100644
--- a/developer_manual/contents.rst
+++ b/developer_manual/contents.rst
@@ -12,7 +12,7 @@ ownCloud documentation contents
.. toctree::
:maxdepth: 3
- devenv/index
+ general/index
app/index
core/index
testing/index
diff --git a/developer_manual/devenv/index.rst b/developer_manual/devenv/index.rst
deleted file mode 100644
index 48441a4..0000000
--- a/developer_manual/devenv/index.rst
+++ /dev/null
@@ -1,105 +0,0 @@
-.. _devenv:
-
-=======================
-Development Environment
-=======================
-
-Please follow the steps on this page to set up your development environment.
-
-Set up web server and database
-------------------------------
-
-First `set up your webserver and database <http://doc.owncloud.org/server/5.0/admin_manual/installation.html>`_ (**Section**: Manual Installation - Prerequisites).
-
-Get the source
---------------
-
-There are two ways to obtain ownCloud sources:
-
-* Using the `stable version <http://doc.owncloud.org/server/5.0/admin_manual/installation.html>`_
-* Using the developement version from `GitHub`_ which will be explained below.
-
-To check out the source from `GitHub`_ you will need to install git (see `Setting up git <https://help.github.com/articles/set-up-git>`_ from the GitHub help)
-
-Identify the web server's directories
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To get started the basic git repositories need to cloned into the webserver's directory. Depending on the distro this will either be
-
-* **/var/www**
-* **/var/www/html**
-* **/srv/http**
-
-Identify the user and group the web server is running as
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-and the Apache user and group for the **chown** command will either be
-
-* **http**
-* **www-data**
-* **apache**
-
-Check out the code
-~~~~~~~~~~~~~~~~~~
-
-The following commands are using "/var/www" as the web server's directory and "www-data" as user name and group.
-
-.. code-block:: bash
-
- sudo chmod o+rw /var/www
- cd /var/www
- git clone https://github.com/owncloud/core.git owncloud
- git clone https://github.com/owncloud/apps.git
- cd owncloud/
- git submodule init
- git submodule update
- mkdir data
- sudo chown -R www-data:www-data config/
- sudo chown -R www-data:www-data data/
- sudo chown -R www-data:www-data apps/
- sudo chmod -R o-rw /var/www
-
-Now **restart the web server**.
-
-Check out code from additional apps (optional)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you would like to develop on non-core apps, you can check them out into the `apps` directory as well.
-For example for the calendar, contact and notes apps:
-
-.. code-block:: bash
-
- cd /var/www
- git clone https://github.com/owncloud/calendar.git
- git clone https://github.com/owncloud/contacts.git
- git clone https://github.com/owncloud/notes.git
-
-Set up ownCloud
-~~~~~~~~~~~~~~~
-
-Open http://localhost/owncloud (or the corresponding URL) in your web browser to set up your instance.
-
-Start developing
-~~~~~~~~~~~~~~~~
-
-* :doc:`App Development<../app/index>`
-* :doc:`Core Development<../core/index>`
-
-
-.. _debugmode:
-
-Enabling debug mode
--------------------
-.. note:: Do not enable this for production! This can create security problems and is only meant for debugging and development!
-
-To disable JavaScript and CSS caching debugging has to be enabled in :file:`owncloud/config/config.php` by adding this to the end of the file::
-
- DEFINE('DEBUG', true);
-
-
-This is often overwritten after a **git pull** from core. Always check :file:`owncloud/config/config.php` afterwards.
-
-.. _GitHub: https://github.com/owncloud
-.. _GitHub Help Page: https://help.github.com/
-.. _set up ownCloud: http://doc.owncloud.org/server/5.0/admin_manual/installation.html
-
diff --git a/developer_manual/app/general/codingguidelines.rst b/developer_manual/general/codingguidelines.rst
similarity index 99%
rename from developer_manual/app/general/codingguidelines.rst
rename to developer_manual/general/codingguidelines.rst
index e7baa5e..9c44f74 100644
--- a/developer_manual/app/general/codingguidelines.rst
+++ b/developer_manual/general/codingguidelines.rst
@@ -1,7 +1,7 @@
Coding Style & General Guidelines
=================================
-.. sectionauthor:: Bernhard Posselt <nukeawhale at gmail.com>
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
General
-------
diff --git a/developer_manual/app/general/debugging.rst b/developer_manual/general/debugging.rst
similarity index 100%
rename from developer_manual/app/general/debugging.rst
rename to developer_manual/general/debugging.rst
diff --git a/developer_manual/app/general/dependencyinjection.rst b/developer_manual/general/dependencyinjection.rst
similarity index 99%
rename from developer_manual/app/general/dependencyinjection.rst
rename to developer_manual/general/dependencyinjection.rst
index fbce787..316c094 100644
--- a/developer_manual/app/general/dependencyinjection.rst
+++ b/developer_manual/general/dependencyinjection.rst
@@ -1,7 +1,7 @@
Dependency Injection
====================
-.. sectionauthor:: Bernhard Posselt <nukeawhale at gmail.com>
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
`Dependency Injection <http://en.wikipedia.org/wiki/Dependency_injection>`_ is a programming pattern that helps you decouple dependencies between classes. The result is cleaner and more testable code. A good overview over how it works and what the benefits are can be read on `Google's Clean Code Talks <http://www.youtube.com/watch?v=RlfLCWKxHJ0>`_
diff --git a/developer_manual/general/devenv.rst b/developer_manual/general/devenv.rst
new file mode 100644
index 0000000..d707642
--- /dev/null
+++ b/developer_manual/general/devenv.rst
@@ -0,0 +1,86 @@
+.. _devenv:
+
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>
+
+=======================
+Development Environment
+=======================
+
+Please follow the steps on this page to set up your development environment.
+
+Set up web server and database
+==============================
+
+First `set up your webserver and database <http://doc.owncloud.org/server/7.0/admin_manual/installation.html>`_ (**Section**: Manual Installation - Prerequisites).
+
+Get the source
+==============
+
+There are two ways to obtain ownCloud sources:
+
+* Using the `stable version <http://doc.owncloud.org/server/7.0/admin_manual/installation.html>`_
+* Using the developement version from `GitHub`_ which will be explained below.
+
+To check out the source from `GitHub`_ you will need to install git (see `Setting up git <https://help.github.com/articles/set-up-git>`_ from the GitHub help)
+
+Gather information about server setup
+-------------------------------------
+
+To get started the basic git repositories need to cloned into the webserver's directory. Depending on the distro this will either be
+
+* **/var/www**
+* **/var/www/html**
+* **/srv/http**
+
+
+Then identify the user and group the web server is running as and the Apache user and group for the **chown** command will either be
+
+* **http**
+* **www-data**
+* **apache**
+
+Check out the code
+------------------
+
+The following commands are using **/var/www** as the web server's directory and **www-data** as user name and group.
+
+.. note:: Python 3.4 includes pip by default
+
+Install the development tool (**depends on Python 3 and pip**)::
+
+ sudo pip install ocdev
+
+Make the directory writable::
+
+ sudo chmod o+rw /var/www
+
+Then install ownCloud from git::
+
+ ocdev setup base
+
+Adjust rights::
+
+ sudo chown -R www-data:www-data /var/www/core/data/
+ sudo chmod o-rw /var/www
+
+
+Finally restart the web server (this might vary depending on your installation)::
+
+ sudo systemctl restart httpd.service
+
+
+After the clone Open http://localhost/core (or the corresponding URL) in your web browser to set up your instance.
+
+Enabling debug mode
+-------------------
+.. _debugmode:
+
+.. note:: Do not enable this for production! This can create security problems and is only meant for debugging and development!
+
+To disable JavaScript and CSS caching debugging has to be enabled in :file:`core/config/config.php` by adding this to the end of the file::
+
+ DEFINE('DEBUG', true);
+
+.. _GitHub: https://github.com/owncloud
+.. _GitHub Help Page: https://help.github.com/
+
diff --git a/developer_manual/app/general/index.rst b/developer_manual/general/index.rst
similarity index 91%
rename from developer_manual/app/general/index.rst
rename to developer_manual/general/index.rst
index 1fd5ff6..250ecc0 100644
--- a/developer_manual/app/general/index.rst
+++ b/developer_manual/general/index.rst
@@ -5,8 +5,8 @@ General
.. toctree::
:maxdepth: 1
+ devenv
security
codingguidelines
debugging
- angular
dependencyinjection
diff --git a/developer_manual/app/general/security.rst b/developer_manual/general/security.rst
similarity index 96%
rename from developer_manual/app/general/security.rst
rename to developer_manual/general/security.rst
index 457dee9..332489c 100644
--- a/developer_manual/app/general/security.rst
+++ b/developer_manual/general/security.rst
@@ -1,7 +1,7 @@
Security Guidelines
===================
-.. sectionauthor:: Bernhard Posselt <nukeawhale at gmail.com>, Lukas Reschke <lukas at statuscode.ch>
+.. sectionauthor:: Bernhard Posselt <dev at bernhard-posselt.com>, Lukas Reschke <lukas at statuscode.ch>
This guideline highlights some of the most common security problems and how to prevent them. Please review your app if it contains any of the following security holes.
@@ -202,7 +202,7 @@ ownCloud offers three simple checks:
* **OCP\JSON::checkAdminUser()**: Checks if the logged in user has admin privileges
* **OCP\JSON::checkSubAdminUser()**: Checks if the logged in user has group admin privileges
-Using the App Framework, these checks are already automatically performed for each request and have to be explicitely turned off by using annotations above your controller method, see :doc:`../appframework/controllers`.
+Using the App Framework, these checks are already automatically performed for each request and have to be explicitely turned off by using annotations above your controller method, see :doc:`../app/controllers`.
Additionally always check if the user has the right to perform that action. (e.g. a user should not be able to delete other users' bookmarks).
@@ -224,7 +224,7 @@ To prevent CSRF in an app, be sure to call the following method at the top of al
<?php
OCP\JSON::callCheck();
-If you are using the App Framework, every controller method is automatically checked for CSRF unless you explicitely exclude it by setting the @CSRFExemption annotation before the controller method, see :doc:`../appframework/controllers`
+If you are using the App Framework, every controller method is automatically checked for CSRF unless you explicitely exclude it by setting the @NoCSRFRequired annotation before the controller method, see :doc:`../app/controllers`
Unvalidated redirects
---------------------
@@ -248,4 +248,4 @@ Always validate the URL before redirecting if the requested URL is on the same d
Getting help
------------
-If you need help to ensure that a function is secure please ask on our `mailing list <https://mail.kde.org/mailman/listinfo/owncloud>`_ or on our IRC channel #owncloud-dev on Freenode.
+If you need help to ensure that a function is secure please ask on our `mailing list <http://mailman.owncloud.org/mailman/listinfo/devel>`_ or on our IRC channel **#owncloud-dev** on **irc.freenode.net**.
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/owncloud-doc.git
More information about the Pkg-owncloud-commits
mailing list