-
Notifications
You must be signed in to change notification settings - Fork 293
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation very hard to follow/understand #183
Comments
@nmgeek Thanks for your feedback. |
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.
|
To use an update form, I'm using a resource, let's say
and then, using your form scope prefix:
Your form is now binded to that object. 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. =) |
@nmgeek : 👉 About 2), the three first section are:
👉 About 6), can you point me out the section of the docs you're talking about? 👉 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. |
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. |
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. |
Thanks for reporting the broken link. I fixed it this morning. |
Please also fix the broken link at On Fri, Jul 17, 2015 at 9:17 AM, Jacob Rief notifications@github.com
|
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? |
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 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.) |
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. |
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 :) |
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).
the definitive recommended way to define django model forms that takes into account the usual usage pattern (complete example).
onerous.
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?
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.
code that could maybe go into a generic base class??
Why?
The text was updated successfully, but these errors were encountered: