Grails views documentation is misleading and confusing

woodmawa commented 5 years ago

Had a long play with Grails views for generating json. The documentation is misleading and probably erroneous in what its suggesting

based on explorations using grails 3.3.9/JsonView 1.2.10.

Task List

[ ] setup a normal grails project and a domain class
[ ] setup a controller and extend fro RestfulController
[ ] initially dont implement any gson views

Steps to Reproduce

1) run the app - and point browser at localhost:8080/api/ (based on your url mappings)

this renders a result even though no views have been created (using some default thats not really explained )

2) stop the app.

3) create a gson view template as suggested on page 4. Assuming domain object is person the template shows is like this

//_person.gson

model {
   Person person
}
json {
    name person.name
    age person.age
}

also create an index.gson (for default browser get query). the documentation on bottom of page 5 sasy you can also pass an Iterable like this

//index.gson

model {
   List<Person> people = []
}
json tmpl.person(people)  //(person:people)

4) restart the app - this clears the cache

now when you point your browser at localhost:8080/api/person (based on your url mappings)

you get an errors. First is that the 'people' variable in the index.gson cant me mapped to person in _person.gson template (model name mismatch. if you try and fix that using the mapped form it still errors as the PageResultList (List people) cant be passed to tmpl if the model variable is single Person.

5) despite the RestfulController default index passing in both list of and model:[Count: list.size() to respond - if you add an Integer Count into the model it does not get data bound with the size

6) middle of page 6. i t says by passing a collection, the plugin will iterate over each on the colelction and render the tmplate as json arrary. This just not work as documented.

Actual Behaviour

1) I believe the documentation should clearly state the default behaviour is (if no gson views are defined)

2) the example of _person.gson and show.gson needs to be rewritten more clearly - so its clear the show types have to be the same.

also in case of say index.gson (using List) that you have to interate and expand as required to exactly match the model name and type in any _templ.gson you write

In addition it should be made very clear that the view template needs to iterate through the list and call the _person template repeatedly to ensure the model variables are populated correctly

something like //index.gson

model {
  List<Person> people = []
}
people.each {
     json tmpl.person (person:it)
}

Its taken forever to try and figure out how to get the right interplay between the controller action, the corresponding view and the tmpl and manage the respective types appropriately, and the confusion on what gets rendered if no gson views exist all

Environment Information

Operating System: windows 10
Grails Version: 3.3.9
JsonViews: 1.2.10
JDK Version: v1.181

Example Application

https://github.com/woodmawa/LCM-network-app

osscontributor commented 5 years ago

Where are the docs that indicate that the following should work?

model {
    List people = []
}

Thanks for your feedback.

osscontributor commented 5 years ago

I think that model variable should be List<Person> personList (or something more general like Iterable<Person> personList.

Thanks for the feedback. We will look at updating the docs.

grails / grails-views