Documentation very hard to follow/understand

[nmgeek]

Please take this as constructive feedback: I'd like to use djangular, assuming it adds value for the application I am developing. If we work through these issues the documentation could be much, much better and there will be more users getting more out of djangular.

I'm starting with the easy stuff for me to articulate. I'm sorry that it is somewhat vague. We can make it more specific given more time (but maybe that isn't necessary if you already know what I am talking about).

1. There are so many caveats and special cases covered in the document I can nowhere find the definitive recommended way to define django model forms that takes into account the usual usage pattern (complete example).
2. The very first sections of the documentation feel like release notes: I cannot put them in context with anything else.
3. I like that you provided complete working examples in the git repository but it took me almost two hours to set up the complicated example and I find having to switch back and forth between the documentation embedded in the examples files and the main read-the-docs section on the tutorial onerous.
4. There is no explanation of what happens when there is more than one form in your application. Do you have to copy that boilerplate javascript form controller for every form? If so that doesn't seem like concise coding. If not then how do you separate the scope properties for multiple forms and make sure you call the right URL for each form?
5. There seem to be 4+ types of form mixins. If they each have their own API type documentation then it wasn't immediately clear where that is. Is there any API documentation? I really don't get the subtleties of all those mixins. If I need more than one shouldn't I just create a base class that combines them all and derive all my forms from that? An example would be helpful.
6. I don't understand why the form class is instantiated into the view context. This is more boilerplate code that could maybe go into a generic base class??
7. You show a derived dispatch class that does nothing but call the super class's dispatch method. Why?

[jrief]

@nmgeek Thanks for your feedback. Would you mind to add some more documentation or a tutorial? I hoped that by adding a running example things are much clearer. First lets start with the basics, how would you structure the documentation? Would a tutorial make sense? Please also keep in mind, that English is not my native language.

[nmgeek]

You do have a tutorial but as I said, much of the documentation is displayed on the pages you can only see if you get all the pieces working to run the tutorial. That documentation should be moved to a easily accessible web page.

In searching today I found that the tutorial does seem to be live on a public web site. Unfortunately, the link to the site is wrong in your documentation. It should be http://djangular.aws.awesto.com/classic_form/ rather than */basic_form/.

Before I could really contribute I need info on how to post to a Django update form. All your examples appear to create django objects and I'm stuck on the update functionality. Specifically, the examples use a post method in python that looks like the code below. This bombs out if a matching object already exists in the database. Instead it should update the object.

   def post(self, request, **kwargs):
        if request.is_ajax():
            return self.ajax(request, **kwargs)
        return super(QA_PlanUpdate, self).post(request, **kwargs)

    # from the djangular combined_validation example
    def ajax(self, request, **kwargs):
        # tbd: need update specific logic here: pass in instance
        # parameter (object) or set it from pk??  (Base class post methods use self.get_object)
        form = self.form_class(data=json.loads(request.body))
        response_data = {'errors': form.errors, 
                         'success_url': force_text(self.success_url)}
        return HttpResponse(json.dumps(response_data), content_type="application/json")

[adrienbrunet]

To use an update form, I'm using a resource, let's say MyResource. NgCRUDView is provided to help you create CRUD operations on one model. . On angular side, you can do:

myResource = MyResource.get({pk: myPk});

and then, using your form scope prefix:

$scope.dj_my_form = myResource;

Your form is now binded to that object. Again, if you're using NgCRUDView, (If you use something like django rest framework, it shouldn't be really more complicated), when you call $save via your submit button for example, if a 'pk' is provided, it performs an update rather than a create action. (see dispatch method of NgCRUDView).

Thanks for your feedback, @jrief already changed the link to */classic_form. I hope we can achieve to build a better documentation from your input. =) @jrief , can you confirm I'm not plain wrong for the form update?

[adrienbrunet]

@nmgeek :

:point_right: About 2), the three first section are:

• "Installation" which is for me, quite clear (did you have any troubles with it?)
• "Integrate AngularJS with Django": a few settings/tips you'll need to perform for your application to behave correctly with angular
• "Running the demos" Do you think the second section should appear after the "Running the demos" section?

:point_right: About 6), can you point me out the section of the docs you're talking about?

:point_right: About 7), the dispatch method is not really interesting but the decorator is. Refer to the warning note just below that explains why here this decorator is used.

[nmgeek]

I'm sorry that I don't have more time to put into this right now: first I have to get a web site up and running ASAP. I have to think about the Running the Demos question: The AngularJS tutorial is more helpful in that it build systematically and allows you to see a full diff of the code between each set up steps. I read another one on Thinkster which includes highlights of the 'interesting' parts of code introduces in each step.

The thing about "Integrate AngularJS with Django" is that, from my point of view that's what everything in djangular is about. I even think there is another section in the documentation with almost the same title. Those things in the second section are more about "Setting up the programming environment" or "Global settings for a project".

About 6) It turns out you have to instantiate a form in order to process post requests. This is the most complicated part of using djangular and from my previous post you can see that posts with updates are very complicated and not covered (at all?) in the djangular documentation. More explanation of handling post requests is definitely in order. Instantiating the form is a prerequisite to sending the repopulated values to the html view and having them be visible.

About 7) It's an example of what not to do. For someone starting from scratch such examples are distracting and confusing. I'm sure its helpful for someone who has some preconceived notion of how to implement form classes. Maybe if you titled a subsection 'How Not To Handle CSRF' then people not inclined to make the mistake would just skip it??

Much of what is missing from the documentation is the 'why explanations'. For example, why would someone be inclined to use that csrf decorator that doesn't work in djangular? Why does Angular defeat pre population of field values for bound forms?

And, again, an API document is really needed. The solution to the problem with Angular defeating prepoulation of of form values is to use an Ng* directive in your html (NgForm??). The documentation needs a section listing all the djangular-specific directives and python classes.

@adrienbrunet, I will look at the CRUD view. I'm using the generic Django model views, though. But Maybe the CRUD update view uses the solution you need for generic views.

[nmgeek]

I was just looking at the Demo again. The documentation in the demo is actually very good. Since the link to the demo site was broken when I first started learning djangular I assumed there was no demo at all and tried to get along without it. Many of the "missing" pieces I have been writing about are covered in the demo.

Had I found the demo and started there I may never have posted this issue.

So, Ideally, the main djangular documentation would walk you through the demo and the documentation would be appropriately cross-linked.

[jrief]

Thanks for reporting the broken link. I fixed it this morning. I focused only on the link onto the demo site in the main README file. Sorry for the inconvenience.

[nmgeek]

Please also fix the broken link at http://django-angular.readthedocs.org/en/latest/tutorial-forms.html

On Fri, Jul 17, 2015 at 9:17 AM, Jacob Rief notifications@github.com wrote:

Thanks for reporting the broken link. I fixed it this morning. I focused only on the link onto the demo site in the main README file. Sorry for the inconvenience.

— Reply to this email directly or view it on GitHub https://github.com/jrief/django-angular/issues/183#issuecomment-122308799 .

[adrienbrunet]

The link to /basic_form has been updated to classic_form this morning. Have you found another broken link? Now that you found out he demos, could we close the ticket and maybe open a new one for the remaining part you'd like to improve?

[nmgeek]

I don't know how you want to handle this: some readers simply don't run demos. These readers read the documentation from beginning to end before diving in to work with code. By distributing the documentation so it's at the bottom of 4-5 demo pages disconnected from the main document (and if you have a small screen you have to scroll to even see that there is such documentation) you are hiding it from those readers.

A better tutorial integrates the text and examples into one readable document.

See https://docs.angularjs.org/tutorial/step_00. Each step includes full documentation in the main document, a Live Demo button, and a Code Diff button. It's more user friendly.

This was the original thought behind this issue.

If I were running this project I'd add this issue to the backlog for addition to a future release. (I use github milestones to tag issues for future releases.)

[jrief]

I really "love" these kind of users. They never contribute anything to OSS (look at @nmgeek 's hollow profile) but then complain about other peoples work, just as if everything should be free, but maintained as if a companies like Microsoft or Apple stands behind it.

[adrienbrunet]

And also, working with a backend framework means we cannot run code on the browser like all fancy js framework do in their documentation. Anyway, I think the real problem was the broken link which is fixed :)