Add examples & fix read-only display

LICENSE

@@ -1,5 +1,3 @@
-The MIT License (MIT)
-
 Copyright (c) 2014 marmelab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
@@ -9,13 +7,13 @@ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -8,7 +8,7 @@ Plug me to your RESTFul API to get a complete administration tool in no time!
 - Clone the repository.
 - Add a configuration file to describe your entities in `lib/config.js`.
 - Run the server with the `grunt` command.
-- See the result at [http://localhost:8000/](http://localhost:8000/)
+- See the result at [http://localhost:8000/](http://localhost:8000/).
 
 # Configuration
 
@@ -33,16 +33,16 @@ define([
     // Declare a new entity
     var tag = Entity('tags')
         .label('Tags')
-        // display in dashboard ?
+        // how many element should be displayed in dashboard ?
         .dashboard(10)
-        // define your specific pagination function
+        // define your specific pagination function returning GET parameters
         .pagination(function(page, maxPerPage) {
             return {
                 _start: (page - 1) * maxPerPage,
                 _end: (page) * maxPerPage
             };
         })
-        // lazyload pagination
+        // enable lazyload pagination
         .infinitePagination(true)
         .addField(Field('id')
             .order(1)
@@ -64,12 +64,6 @@ define([
     var comment = Entity('comments')
         .label('Comments')
         .dashboard(10)
-        .pagination(function(page, maxPerPage) {
-            return {
-                _start: (page - 1) * maxPerPage,
-                _end: (page) * maxPerPage
-            };
-        })
         .infinitePagination(true)
         .addField(postId = Field('id')
             .order(1)
@@ -87,7 +81,7 @@ define([
                 "max-length" : 150,
                 // define your custom validation function
                 "validator" : function(value) {
-                    return value.indexOf('chat') > -1;
+                    return value.indexOf('cat') > -1;
                 }
             })
         )
@@ -137,25 +131,94 @@ define([
 
 ## List of field types
 
-- Field : simple field
-- Reference : association 1-N with another entity
-- ReferenceList : association N-1
-- ReferenceMany : association N-N
+- `Field` : simple field
+- `Reference` : association 1-N with another entity
+- `ReferenceList` : association N-1
+- `ReferenceMany` : association N-N
+
+## List of options for `Field` type
 
-## List of field options
+* `type(string ['number'|'text'|'email'|'date'])`
+Define the field type.
 
-* label(string label)
+* `label(string label)`
 Define the label of the field.
 
-* type(string ['number'|'text'|'email'|'date'])
-Define the field type.
+* `edition(string ['read-only'|'editable'])`
+Define if the field is editable in the edition form.
 
-* identifier(boolean [true|false])
+* `order(number|null)`
+Define the position of the field in the form.
+
+* `identifier(boolean [true|false])`
 Define if this field is the entity's identifier (to build the REST requests).
 
-* edition(string ['read-only'|'editable'])
-Define if the field is editable in the edition form.
+* `format(string ['yyyy-MM-dd' by default])`
+Define the format for `date` type.
+
+* `valueTransformer(function)`
+Define a custom function to transform the value.
 
-* dashboard(int number)
+```js
+.addField(Field('characters')
+    .valueTransformer(function(value) {
+        return value && value.items ? value.items[0] : value;
+    })
+)
+```
+
+* `list(boolean)`
+Define if the field should be display in the list.
+
+* `dashboard(number|false)`
 Number of elements displayed in dashboard.
 
+* `validation(function)`
+Define a custom validation function.
+
+
+## List of options for `Reference` type
+
+The `Reference` type also defines `label`, `order`, `valueTransformer`, `list` & `validation` options like the `Field` type.
+
+* `targetEntity(Entity)`
+Define the referenced entity.
+
+* `targetLabel(string)`
+Define the target field name used to retrieve the label of the referenced element.
+
+## List of options for `ReferencedList` type
+
+The `ReferencedList` type also defines `label`, `order`, `valueTransformer`, `list` & `validation` options like the `Field` type.
+
+* `targetEntity(Entity)`
+Define the referenced entity.
+
+* `targetField(string)`
+Define the field name used to link the referenced entity.
+
+* `targetFields(Array(Field))`
+Define an array of fields that will be display in the list of the form.
+
+## List of options for `ReferencedMany` type
+
+The `ReferencedMany` type also defines `label`, `order`, `valueTransformer`, `list` & `validation` options like the `Field` type.
+
+* `targetEntity(Entity)`
+Define the referenced entity.
+
+* `targetField(string)`
+Define the field name used to link the referenced entity.
+
+* `targetLabel(string)`
+Define the target field name used to retrieve the label of the referenced element.
+
+## Contributing
+
+Your feedback about the usage of ng-admin in your specific context is valuable, don't hesitate to [open GitHub Issues](https://github.com/marmelab/ng-admin/issues) for any problem or question you may have.
+
+All contributions are welcome. New applications or options should be tested  with go unit test tool.
+
+## License
+
+ng-admin is licensed under the [MIT Licence](LICENSE), courtesy of [marmelab](http://marmelab.com).

app/scripts/app/Crud/view/edit-attribute.html

@@ -38,10 +38,8 @@
 </div>
 
 <div ng-if="field.edition() == 'read-only'">
-    <div class="col-sm-10 read-only" ng-switch="field.type()">
-        <p ng-switch-when="text">{{ field.value }}</p>
-
-        <p ng-switch-when="number">{{ field.value }}</p>
+    <div class="col-sm-10 read-only">
+        <p>{{ field.value }}</p>
     </div>
 </div>
 

app/scripts/config-dist.js

@@ -2,28 +2,43 @@ define([
     'lib/config/Application',
     'lib/config/Entity',
     'lib/config/Field',
-    'lib/config/Reference'
-], function (Application, Entity, Field, Reference) {
+    'lib/config/Reference',
+    'lib/config/ReferencedList',
+    'lib/config/ReferenceMany'
+], function (Application, Entity, Field, Reference, ReferencedList, ReferenceMany) {
     "use strict";
 
-    var post = Entity('posts')
-        .label('Posts')
-        .dashboard(5)
-        .pagination(null)
+    var post = Entity('posts'),
+        commentBody = Field('body'),
+        postId = Field('id'),
+        postCreatedAt = Field('created_at'),
+        commentTags = ReferenceMany('tags');
+
+    var tag = Entity('tags')
+        .label('Tags')
+        .dashboard(10)
+        .pagination(function(page, maxPerPage) {
+            return {
+                _start: (page - 1) * maxPerPage,
+                _end: (page) * maxPerPage
+            };
+        })
+        .infinitePagination(false)
         .addField(Field('id')
+            .order(1)
             .label('ID')
             .type('number')
             .identifier(true)
             .edition('read-only')
         )
-        .addField(Field('title')
-            .label('Title')
+        .addField(Field('name')
+            .order(2)
+            .label('Name')
+            .edition('editable')
             .validation({
                 "required": true,
                 "max-length" : 150
             })
-        ).addField(Field('body')
-            .label('Body')
         );
 
     var comment = Entity('comments')
@@ -36,29 +51,79 @@ define([
             };
         })
         .infinitePagination(true)
-        .addField(Field('id')
+        .addField(postId
+            .order(1)
             .label('ID')
             .type('number')
             .identifier(true)
             .edition('read-only')
         )
-        .addField(Field('body')
+        .addField(Reference('post_id')
+            .targetEntity(post)
+            .targetLabel('title')
+        )
+        .addField(commentBody
+            .order(2)
+            .type('text')
             .label('Comment')
             .edition('editable')
             .validation({
                 "required": true,
-                "max-length" : 150
+                "max-length" : 150,
+                "validator" : function(value) {
+                    return value.indexOf('chat') > -1;
+                }
             })
         )
-        .addField(Reference('post_id')
-            .label('Post')
-            .targetEntity(post)
-            .targetLabel('title')
+        .addField(postCreatedAt
+            .order(3)
+            .label('Creation Date')
+            .type('date')
+            .edition('editable')
+            .validation({
+                "required": true
+            })
+        )
+        .addField(commentTags
+            .label('Tags')
+            .targetEntity(tag)
+            .targetLabel('name')
+        );
+
+    post
+        .label('Posts')
+        .dashboard(null)
+        .pagination(false)
+        .addField(Field('id')
+            .label('ID')
+            .type('number')
+            .identifier(true)
+            .edition('read-only')
+        )
+        .addField(Field('title')
+            .label('Title')
+            .edition('editable')
+        )
+        .addField(Field('body')
+            .label('Body')
+            .type('text')
+            .edition('editable')
+        )
+        .addField(ReferencedList('comments')
+            .label('Comments')
+            .targetEntity(comment)
+            .targetField('post_id')
+            .targetFields([postId, commentBody, commentTags])
+        )
+        .addField(ReferenceMany('tags')
+            .label('Tags')
+            .targetEntity(tag)
+            .targetLabel('name')
         );
 
-    return Application()
-        .title('Backend')
+    return Application('My backend')
         .baseApiUrl('http://localhost:3000/')
         .addEntity(post)
-        .addEntity(comment);
+        .addEntity(comment)
+        .addEntity(tag);
 });