README.md in guacamole-0.1.0 vs README.md in guacamole-0.2.0

- old
+ new

@@ -9,19 +9,19 @@ * 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 -While the first two points don't need any further explanation we want to lay out the motivation behind the last point: 'Ease of use' is very important to us, but we made some fundamental decisions which will cause a stepper learning curve than other libraries, notably ActiveRecord. If you have a traditional Rails background you will find some things quite different. We decided to go this direction, because we think it better suites the features of ArangoDB. Applying the semantics of a different environment maybe helps with the first steps but will become problematic if you further advance in your understanding of the possibilities. +While the first two points don't need any further explanation we want to lay out the motivation behind the last point: 'Ease of use' is very important to us, but we made some fundamental decisions which will cause a steeper learning curve than other libraries, notably ActiveRecord. If you have a traditional Rails background you will find some things quite different. We decided to go this direction, because we think it better suites the features of ArangoDB. Applying the semantics of a different environment may help with the first steps but will become problematic if you further advance in your understanding of the possibilities. That said we still think we provide a sufficient API that is quite easy to get hold of. It is just a bit different from what you were doing with ActiveRecord. For a high-level introduction you can also refer to [this presentation](https://speakerdeck.com/railsbros_dirk/how-to-make-guacamole). ## Getting started (with a fresh Rails application) -Since Guacamole is in an alpha state we suggest you create a new Rails application to play around with it. We don't recommend adding it to a production application. +Since Guacamole is in an alpha state we suggest you to create a new Rails application to play around with it. We don't recommend adding it to a production application. First of all create your shiny new application, without ActiveRecord of course: ```shell rails new -O $my_awesome_app @@ -69,15 +69,15 @@ 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 -One of the key features of Guacamole is the implementation of the [Data Mapper Patter](http://martinfowler.com/eaaCatalog/dataMapper.html). This brings a lot of good things along, like +One of the key features of Guacamole is the implementation of the [Data Mapper Pattern](http://martinfowler.com/eaaCatalog/dataMapper.html). This brings a lot of good things along, like - * Improved testability - * Separation of Concern and - * Easier to support database
features like embedded objects + * improved testability + * separation of concerns and + * easier to support database features like embedded objects The gist of the pattern is you have two classes where you would have one when you use ActiveRecord: A `Collection` and a `Model`. The `Collection` is responsible for getting data from and writing data to the database. The `Model` represents the domain logic (i.e. attributes) and has no idea what a database is. Due to this you could far easier test the domain logic without a database dependency. But you have always two (or more) classes around. The following will introduce you to both those classes. ### Models @@ -97,21 +97,21 @@ attribute :birthday, Date attribute :color, String end ``` -Since the database doesn't know anything about a schema we must define the attributes in the model class itself. At the same time this has the advantage to open the model class and see what attributes it has. An attribute is defined with the `attribute` class method. We use [Virtus](https://github.com/solnic/virtus) for this purpose. Basically you add give the attribute a name and a type. The type have to be the actual class and **not** a string representation of the class. You could even define collection classes: +Since the database doesn't know anything about a schema we must define the attributes in the model class itself. At the same time this has the advantage to open the model class and see what attributes it has. An attribute is defined with the `attribute` class method. We use [Virtus](https://github.com/solnic/virtus) for this purpose. Basically you give the attribute a name and a type. The type have to be the actual class and **not** a string representation of the class. You could even define collection classes: ```ruby class Pony include Guacamole::Model attribute :type, Array[String] end ``` -For further reference what is possible please refer to the [Virtus documentation](http://rubydoc.info/gems/virtus/1.0.2/frames). One thing to add here, whenever you assign a value to an attribute Virtus will perform a type coercion: +For further reference what is possible please refer to the [Virtus documentation](http://rubydoc.info/gems/virtus/1.0.2/frames). One thing to note here: Whenever you assign a value to an attribute Virtus will perform a type coercion: ```ruby pinkie_pie = Pony.new pinkie_pie.color = :pink # => "pink" @@ -119,15 +119,15 @@ # => ["Earthpony"] ``` #### Timestamps -We will automatically add time stamp columns to all models when you include `Guacamole::Model`. We eventually will make this configurable, but for now it is not. +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 you 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://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. 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 @@ -173,11 +173,11 @@ * 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. * 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 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. +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. #### Create models To create a model just pass it to the `save` method of the `Collection` in charge: @@ -233,11 +233,11 @@ 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. ### 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. +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. The `Collection` class will lookup the appropriate `Model` class based on its own name (i.e.: the `PoniesCollection` will look for a `Pony` class). Currently there is no option to configure this so you're stuck with our conventions (for now): * Collections in ArangoDB are the plural form of the `Model` class name * The `Collection` class is the plural form of the `Model` class name with the suffix `Collection` @@ -252,19 +252,28 @@ "color": "green", "occupation": "Farmer" } ``` -When we receive this document and map it against the above mentioned model there will be no `occupation` attribute be present: +When we receive this document and map it against the `Pony` model there won't be a `occupation` attribute: ```ruby +class Pony + include Guacamole::Model + + attribute :name, String + attribute :color, String +end + pony = PoniesCollection.by_key "303" +pony.color +# => 'green' pony.occupation # => NoMethodError: undefined method `occupation' for #<Pony:0x00000105fc77f8> ``` -Currently there is not option to change the mapping of attributes. If you want to map more or less attributes you should create another model for that purpose. +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 Besides simple attributes we want to handle associations between models. To add an association between your models you have two options: __embedded__ and __referenced__. @@ -391,11 +400,11 @@ ### Testing Currently we're not providing any testing helper, thus you need to make sure to cleanup the database yourself before each run. You can look at the [`spec/acceptance/spec_helper.rb`](https://github.com/triAGENS/guacamole/blob/master/spec/acceptance/spec_helper.rb) of Guacamole for inspiration of how to do that. -For test data generation we're using the awesome [Fabrication gem](http://www.fabricationgem.org/). Again you find some usage examples in under Guacamole's own acceptance tests. We didn't tested Factory Girl yet, but it eventually will work, too. +For test data generation we're using the awesome [Fabrication gem](http://www.fabricationgem.org/). Again you find some usage examples in Guacamole's own acceptance tests. We didn't tested Factory Girl yet, but it eventually will work, too. ### Authentication Any integration into an authentication framework need to be done by you. At this time we have nothing to share with you about this topic. @@ -412,9 +421,29 @@ * Basic AQL support for more useful queries * 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 + +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: + +```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. + +**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: