README.md in guacamole-0.3.0 vs README.md in guacamole-0.4.0
- old
+ new
@@ -1,14 +1,15 @@
[](http://rubydoc.info/gems/guacamole/frames)
[](https://travis-ci.org/triAGENS/guacamole)
[](https://codeclimate.com/github/triAGENS/guacamole)
[](http://inch-ci.org/github/triAGENS/guacamole)
[](https://rubygems.org/gems/guacamole)
+[](https://codeship.io/projects/40903)
# Guacamole
-Guacamole is an Object Document Mapper (ODM) for the multi-model NoSQL database [ArangoDB](https://www.arangodb.org/). Its main goal is to support easy integration into Ruby on Rails but will likely work in other Rack-based frameworks as well. There are a couple of design goals behind Guacamole which should drive all our development effort:
+Guacamole is an Object Document Mapper (ODM) for the multi-model NoSQL database [ArangoDB](https://www.arangodb.com/). Its main goal is to support easy integration into Ruby on Rails but will likely work in other Rack-based frameworks as well. There are a couple of design goals behind Guacamole which should drive all our development effort:
* Easy integration on the View layer (i.e. form builders)
* Reflect the nature of NoSQL in general and ArangoDB in particular
* Focus on long-term maintainability of your application
@@ -84,11 +85,11 @@
```shell
bundle exec rake db:create
```
-If you're using Capistrano or something else make sure you change your deployment recipes accordingly to use the `guacamole.yml` and not the `database.yml`. Of course you would want to add [authentication](https://www.arangodb.org/manuals/2/DbaManualAuthentication.html) for the production environment. Additionally you may want to consider putting ArangoDB behind a SSL-proxy or use the [built in SSL support](https://www.arangodb.org/manuals/2/CommandLine.html#CommandLineArangoEndpoint).
+If you're using Capistrano or something else make sure you change your deployment recipes accordingly to use the `guacamole.yml` and not the `database.yml`. Of course you would want to add [authentication](https://docs.arangodb.com/ConfigureArango/Authentication.html) for the production environment. Additionally you may want to consider putting ArangoDB behind a SSL-proxy or use the [built in SSL support](https://docs.arangodb.com/ConfigureArango/Arangod.html).
Now where everything is set up we can go ahead and create our application's logic. Before we give you some code to copy and paste we first give you a general usage and design overview.
## Usage
@@ -144,11 +145,11 @@
We will automatically add both a `created_at` and an `updated_at` attribute to all your models. Both will hold a `DateTime` and will be populated on creating or updating the model in the database.
#### The ID of a model
-In ArangoDB a document has three internal fields: `_id`, `_key` and `_rev`. For a detailed explanation how these three work together please refer to the [ArangoDB documentation](https://www.arangodb.org/manuals/2/HandlingDocuments.html#HandlingDocumentsIntro). Within Guacamole we will always use the `_key` because it is enough the identify any document within a collection. Both the `_key` and `_rev` attribute are available through the `Guacamole::Model#key` and `Guacamole::Model#rev` attribute. You don't have to do anything for this, we will take care of this for you.
+In ArangoDB a document has three internal fields: `_id`, `_key` and `_rev`. For a detailed explanation how these three work together please refer to the [ArangoDB documentation](https://docs.arangodb.com/Documents/DocumentAddress.html). Within Guacamole we will always use the `_key` because it is enough the identify any document within a collection. Both the `_key` and `_rev` attribute are available through the `Guacamole::Model#key` and `Guacamole::Model#rev` attribute. You don't have to do anything for this, we will take care of this for you.
Additionally you will find an `id` method on you models. This is just an alias for `key`. This was added for `ActiveModel::Conversion` compliance. You **should always** use `key`.
#### Validations
@@ -187,14 +188,14 @@
```shell
bundle exec rails generate collection ponies
```
-Currently your options what you can do with a collection are quire limited. We will eventually add more features, but for now you basically have this features:
+Currently your options what you can do with a collection are quite limited. We will eventually add more features, but for now you basically have this features:
* CRUD operations for your models
- * Where the "Read"-part is limited to [Simple Queries](https://www.arangodb.org/manuals/2/SimpleQueries.html). But more on this later.
+ * Where the "Read"-part is limited to [Simple Queries](https://docs.arangodb.com/SimpleQueries/README.html). But more on this later.
* Mapping embedded models
* Realizing basic associations
For all the mapping related parts you don't have any configuration options yet, but have to stick with the conventions. Obviously this will change in the future but for now there are more important parts to work on. Before we dig deeper into the mapping of embedded or associated models let us look at the CRUD functionality.
@@ -233,11 +234,11 @@
# => `existing_pony.key`
```
#### Retrieve models
-As mentioned before querying for models is quite limited as of now. We only support [Simple Queries](https://www.arangodb.org/manuals/2/SimpleQueries.html) at this point. You can perform the following basic operations with them:
+As mentioned before querying for models is quite limited as of now. We only support [Simple Queries](https://docs.arangodb.com/SimpleQueries/README.html) at this point. You can perform the following basic operations with them:
* Getting a single model `by_key`
* Getting `all` models from a collection.
* Query models `by_example`. You can **only** perform equality checks with this.
* You can `skip` and `limit` the results
@@ -250,11 +251,11 @@
some_ponies.first
# The request to the database is made
# => #<Pony:0x90u81 …>
```
-We're well aware this is not sufficient for building sophisticated applications. We're are working on something to make [AQL](https://www.arangodb.org/manuals/2/Aql.html) usable from Guacamole.
+We're well aware this is not sufficient for building sophisticated applications. We're are working on something to make [AQL](https://docs.arangodb.com/Aql/README.html) usable from Guacamole.
### Mapping
As the name "Data Mapper" suggests there is some sort of mapping going on behind the scenes. The mapping relates to the process of _mapping_ documents from the database to the domain models.
@@ -294,10 +295,11 @@
Currently there is no option to change the mapping of attributes. If you want to map more or less attributes you should create another model for that purpose.
#### Associations
+**TODO: This needs some work to include relations**
Besides simple attributes we want to handle associations between models. To add an association between your models you have two options: __embedded__ and __referenced__.
#### Embedded references
If you go with the `embeds` option the embedded model will be stored within the **same** document in the database. The comments of a blog post are a good example where this can be handy. While the database will have only one document the domain can still know about a `Comment` and a `Post`. In this case you would end up with two models and one collection:
@@ -352,72 +354,14 @@
}
```
**Note**: Again this will only work if you stick with the convention. So far there is no support to configure this more fine grained.
-#### References
+### Relations
-While there are perfect use cases to embed documents into each other there are still plenty of use cases where referencing documents makes perfect sense. In fact this one feature where ArangoDB can really shine: Instead of just getting all referenced documents with dedicated calls to the server and without the possibility to perform any functions like filtering or sorting the data, ArangoDB can perform joins over your data just like a RDBMS.
+**>>>> Insert documentation for relations here!**
-**Note**: In the current version we're not using this power since we need to support AQL before that. As of now references are realized with dedicated calls to the database.
-
-To define references between models you just add the appropriate attributes to the `Model` classes:
-
-```ruby
-class Author
- include Guacamole::Model
-
- attribute :name, String
- attribute :posts, Array[Post]
-end
-
-class Post
- include Guacamole::Model
-
- attribute :title, String
- attribute :author, Author
-end
-```
-
-As with the embedded models the real work happens in the `Collection` classes:
-
-```ruby
-class AuthorsCollection
- include Guacamole::Collection
-
- map do
- referenced_by :posts
- end
-end
-
-class PostsCollection
- include Guacamole::Collection
-
- map do
- references :author
- end
-end
-```
-
-Under the hood we will add an `author_id` to all posts holding the reference to the author. As a user this will be completely transparent for you:
-
-```ruby
-author = AuthorsCollection.by_key "23124"
-author.posts
-# => [#<Post:0x12341 …>, …]
-```
-
-The same goes for saving the data. Just add `Post`s to an `Author` as you would in plain Ruby. Passing one of the models to its `Collection` class will take care of the rest:
-
-```ruby
-author = Author.new(name: "Lauren Faust")
-author.posts << Post.new(title: "This is amazing")
-
-AuthorsCollection.save author
-# => Will save both the author and the post
-```
-
### Callbacks
Guacamole allows you to define callbacks for various actions performed on a model. Those callbacks need to be defined in a dedicate class per model. For example to hash the password of a user prior creating the document in the database you would write something like the following:
```ruby
@@ -440,11 +384,11 @@
callbacks :user_callbacks
end
```
-You can define define callbacks for the following actions:
+You can define callbacks for the following actions:
* `before_validate`
* `around_validate`
* `after_validate`
* `before_save`
@@ -558,35 +502,31 @@
* Configuration of mapping
* Callbacks and dirty tracking for models
* An example Rails application to be used as both an acceptance test suite and a head start for Guacamole and ArangoDB
* An AQL query builder
-### Experimental AQL Support
+### AQL Support
-As mentioned before we're working on [something more sophisticated to support AQL](https://github.com/moonglum/brazil/issues/8). But this will not be finished any time soon. Meanwhile you could play with the experimental AQL support:
+As mentioned before we're working on [something more sophisticated to support AQL](https://github.com/moonglum/brazil/issues/8). But this will not be finished any time soon. That said, there is still a way to to perform AQL queries against ArangoDB. For simple queries you can do something like this:
```ruby
-config.guacamole.experimental_features = [:aql_support]
-```
-
-After that you can perform very basic queries like this one:
-
-```ruby
PoniesCollection.by_aql('FILTER pony.name == @name', name: 'Rainbow Dash')
```
-The result of this will a correctly mapped Array of `Pony` models.
+The result of this will a correctly mapped Array of `Pony` models. If this is not enough thou, don't worry, you can get really fancy with this. Due to this you can deactivate the automatic mapping of the response. In that case you will receive just a raw document you can work with. **Note**: Please use only this form to pass parameters into a query. Using string interpolation will leave you vulnerable to AQL-injections.
-**Note**: Please use only this form to pass parameters into a query. Using string interpolation will leave you vulnerable to AQL-injections.
-
For more information about usage please refer to the RDoc and the code.
## Issues or Questions
-If you find a bug in this gem, please report it on [our tracker](https://github.com/triAGENS/guacamole/issues). We use [Waffle.io](https://waffle.io/triagens/guacamole) to manage the tickets – go there to see the current status of the ticket. If you have a question, just contact us via the [mailing list](https://groups.google.com/forum/?fromgroups#!forum/ashikawa) – we are happy to help you :smile:
+If you find a bug in this gem, please report it on [our tracker](https://github.com/triAGENS/guacamole/issues). If you have a question, just contact us via the [mailing list](https://groups.google.com/forum/?fromgroups#!forum/ashikawa) – we are happy to help you :smile:
## Contributing
-If you want to contribute to the project, see CONTRIBUTING.md for details. It contains information on our process and how to set up everything. The following people have contributed to this project:
+If you want to contribute to the project, see [CONTRIBUTING.md](CONTRIBUTING.md) for details. It contains information on our process and how to set up everything. The following people have contributed to this project:
* Lucas Dohmen ([@moonglum](https://github.com/moonglum)): Developer
* Dirk Breuer ([@railsbros-dirk](https://github.com/railsbros-dirk)): Developer
+
+## Inspiration
+
+The work on Guacamole is heavily inspired by the remarkable work of the [ROM](http://rom-rb.org) team and especially by [Piotr Solnica](http://solnic.eu).