Merge pull request #56 from marmelab/readme

[RFR] Update Readme (follows #55)

Makefile

@@ -12,7 +12,6 @@ test:
 
 install:
 	composer install --no-interaction
-	npm install
 	bower install --config.interactive=false
 ifneq ($(autoconfig), false)
 	cp config/prod.yml-dist config/prod.yml
@@ -29,6 +28,14 @@ endif
 	cp web/assets/js/browser/config.js-dist web/assets/js/browser/config.js
 	gaudi
 
+update:
+	git pull
+	make install autoconfig=false
+
+update-gaudi:
+	git pull
+	make install-gaudi autoconfig=false
+
 install-test:
 	npm install
 

README.md

@@ -1,28 +1,83 @@
 # PHPCR Browser [![Build Status](https://travis-ci.org/marmelab/phpcr-browser.svg?branch=master)](https://travis-ci.org/marmelab/phpcr-browser)
 
-PHPCR Browser provides web interface to explore PHPCR repositories. The current implementation supports Jackalope Jackrabbit and Doctrine DBAL.
-
-You can create/delete a workspace (if supported by the repository), add/delete/move nodes, add/edit/delete properties.
+PHPCR Browser provides an intuitive web interface to explore and manage [PHPCR](http://phpcr.github.io/) repositories.
+The current implementation supports [Jackalope Jackrabbit](https://github.com/jackalope/jackalope-jackrabbit) and [Jackalope Doctrine DBAL](https://github.com/jackalope/jackalope-doctrine-dbal).
 
 ![screenshot](http://marmelab.com/phpcr-browser/img/phpcr-browser-screencast.gif)
 
+Supported Operations
+---------------
+
+**Jackalope Jackrabbit:**
+
+ - **Workspace:** create
+ - **Node:** create, delete, move
+ - **Property:** create, delete, update
+
+**Jackalope Doctrine DBAL:**
+
+ - **Workspace:** create, delete
+ - **Node:** create, delete, move
+ - **Property:** create, delete, update
+
+*See [marmelab/phpcr-api/config/factories.yml](https://github.com/marmelab/phpcr-api/blob/master/config/factories.yml) for more details.*
+
 Installation
 ------------
 
-You need to have installed globally [Composer](https://getcomposer.org/) and [Bower](http://bower.io/).
+PHPCR Browser uses [Composer](https://getcomposer.org/) and [Bower](http://bower.io/) to manage its dependencies. Make sure they are **globally installed** before continuing.
+
+#### 1. Clone the repository
+```sh
+git clone git@github.com:marmelab/phpcr-browser.git
+cd phpcr-browser
+```
 
-To install the web application with the default configuration (see below), run the following command into the browser root dir:
+#### 2. Install dependencies and configure the browser
+To install the web application with the default configuration (see below), run the following command:
 
 ```sh
-$ make install
+make install
 ```
 
-This will do the [Configuration](#Configuration) part for you. If you prefer do it on your own run:
+This will download all dependencies and do the [Configuration](#configuration) part for you. If you prefer do it on your own run:
+
+```sh
+make install autoconfig=false
+```
+---
+#### Adding support for Jackalope Doctrine DBAL (Optionnal)
+By default, the Jackalope Doctrine DBAL is not installed. If you want to use it run the following commands:
 
 ```sh
-$ make install autoconfig=false
+composer require jackalope/jackalope-doctrine-dbal:1.1.* --no-update
+composer update jackalope/jackalope-doctrine-dbal
 ```
 
+And update your configuration file to add your Doctrine repository by writing something equivalent to:
+
+```yml
+'My Doctrine DBAL Repository':
+        factory: jackalope.doctrine-dbal
+        parameters:
+            doctrine_dbal.config:
+                driver: pdo_sqlite
+                path: ../src/app.db
+            credentials.username: admin
+            credentials.password: admin
+```
+
+For more details on `doctrine_dbal.config` see [Doctrine website](http://doctrine-dbal.readthedocs.org/en/latest/reference/configuration.html).
+
+You can also find this config into `config/prod-with-dbal.yml.dist`
+
+Note you can install and use both Jackalope Jackrabbit and Doctrine DBAL at the same time.
+
+You can add as many repositories as you want into your config file.
+
+Installation with Gaudi
+-----------------
+
 You can also use [gaudi](http://gaudi.io) to install PHPCR Browser:
 
 ```sh
@@ -31,23 +86,25 @@ $ make install-gaudi
 $ make install-gaudi autoconfig=false
 ```
 
-In order to use Jackalope Doctrine DBAL now run the following:
+Update
+------
+
+If you want to retrieve the latest version of the browser, run the following commands:
 
-```sh
-$ composer require jackalope/jackalope-doctrine-dbal:1.1.* --no-update
-$ composer update jackalope/jackalope-doctrine-dbal
+```
+make udpate
 ```
 
-Note you can install and use both Jackalope Jackrabbit and Doctrine DBAL at the same time.
+Or if it is running with [gaudi](http://gaudi.io) run:
 
-Update
-------
+```
+make update-gaudi
+```
 
-To update the browser do a `git checkout` to the branch you want and `git pull`. Then run `make install autoconfig=false`.
 
 Configuration
 -------------
-Create a `config/prod.yml` with the connection settings for the repositories you need to browse. For instance, to use the browser with a local instance of jackrabbit:
+Create a `config/prod.yml` with the connection settings for the repositories you need to browse. For instance, to use the browser with a local instance of Jackalope Jackrabbit:
 
 ```yml
 phpcr_repositories:
@@ -57,14 +114,6 @@ phpcr_repositories:
             jackalope.jackrabbit_uri: 'http://localhost:8080/server'
             credentials.username: admin
             credentials.password: admin
-    'My Doctrine DBAL Repository':
-        factory: jackalope.doctrine-dbal
-        parameters:
-            doctrine_dbal.config:
-                driver: pdo_sqlite
-                path: ../src/app.db
-            credentials.username: admin
-            credentials.password: admin
 ```
 
 The `factory` setting is the type of PHPCR repository you want to browse. See available factories in [marmelab/phpcr-api/config/factories.yml](https://github.com/marmelab/phpcr-api/blob/master/config/factories.yml).
@@ -77,10 +126,33 @@ Copy also the angular app config dist file :
 cp web/assets/js/browser/config.js-dist web/assets/js/browser/config.js
 ```
 
+For using Jackalope Doctrine DBAL refer to [Installation](#installation).
+
 Usage
 -----
 
-Add a VirtualHost to your Apache config (and add in it 'AllowEncodedSlashes On'), or use PHP 5.4 integrated webserver by calling:
+####Using Apache VirtualHost
+
+Add a VirtualHost to your Apache config (and add in it 'AllowEncodedSlashes On'):
+
+```
+<VirtualHost *:80>
+  DocumentRoot /path/to/the/browser/web
+  ServerName phpcr-browser.lo
+  AllowEncodedSlashes On
+</VirtualHost>
+```
+And update your `/etc/hosts` file by adding:
+
+```
+127.0.0.1   phpcr-browser.lo
+```
+
+You can now access to the browser on `http://phpcr-browser.lo` (or equivalent domain as configured in your virtual host and hosts file).
+
+####Using PHP 5.4 integrated webserver
+
+You can also use PHP 5.4 integrated webserver by calling:
 
 ```sh
 $ php -S localhost:8000 -t web
@@ -92,19 +164,29 @@ Alternatively call:
 $ bin/run.sh
 ```
 
-You can now access the repository by browsing to http://localhost:8000/browser (or equivalent domain as configured in your virtual host).
+You can now access the repository by browsing to http://localhost:8000/browser.
 
 Tests
 -----
 
-Before running tests, install dependencies by running: `make install-test`
+The PHPCR Browser AngularJS part is fully unit tested with [Karma](http://karma-runner.github.io/) and [Jasmine](http://jasmine.github.io/).
+If you want to run them, install dependencies by running: `make install-test`
 
 Then run the following command: `make test`
 
 Sass
 ----
 
-If you update the sass files, run `make compass-watch` for development. When your work is done, run `make compass-compile`.
+The stylesheets are compiled by [Compass](http://compass-style.org/) and [Sass](http://sass-lang.com/).
+
+If you update the sass files, run `make compass-watch` during development.
+
+When your work is done, run `make compass-compile` before committing.
+
+Contributing
+---------
+
+All contributions are welcome and must pass the tests. If you add a new feature, write tests for it.
 
 License
 -------

config/prod-with-dbal.yml-dist

@@ -0,0 +1,15 @@
+phpcr_repositories:
+    'My Jackrabbit Repository':
+        factory: jackalope.jackrabbit
+        parameters:
+            jackalope.jackrabbit_uri: 'http://localhost:8080/server'
+            credentials.username: admin
+            credentials.password: admin
+    'My Doctrine DBAL Repository':
+        factory: jackalope.doctrine-dbal
+        parameters:
+            doctrine_dbal.config:
+                driver: pdo_sqlite
+                path: ../src/app.db
+            credentials.username: admin
+            credentials.password: admin

config/prod.yml-dist

@@ -5,11 +5,3 @@ phpcr_repositories:
             jackalope.jackrabbit_uri: 'http://localhost:8080/server'
             credentials.username: admin
             credentials.password: admin
-    'My Doctrine DBAL Repository':
-        factory: jackalope.doctrine-dbal
-        parameters:
-            doctrine_dbal.config:
-                driver: pdo_sqlite
-                path: ../src/app.db
-            credentials.username: admin
-            credentials.password: admin