django-shop
django-shop copied to clipboard
awesto
Document requirements for integrating django-shop into custom projects
We should document in a nice, concise manner the exact requirements as well as the necessary steps to integrate django-shop into existing custom Django projects.
Related: #394, #392.
Ancillary to this issue is the fact that much of the django-shop codebase makes the task of integrating it very difficult. For example, the tight coupling with SCSS, Angular, and Django REST Framework. Integrating with an existing site involves a great deal of writing components from scratch if those arent already being used.
@rspeed Thank you for your input. I agree. I'd argue that it is better than it looks at first glance, because most of the tight coupling is not as tight as one might think, thanks to sensible software design.
Some background information: This is an open source project which was generously released by a single developer (@jrief) who implemented it for a customer. There is no big company behind it. Eliminating the coupling to SASS and Angular is high on our list. DRF will stay a dependency for the foreseeable future, I think. We are working on this project in our free time, so we cannot make any promises as to when these tasks will be finished.
We welcome all contributions, be they comments / thoughts, code, documentation or anything else that may be helpful. Thank you for your comment. If you have any concrete suggestions please do share them!
A REST-based API is in no way a requirement for building an e-commerce site, so it shouldn't be a base requirement. The utility of one however, makes it a textbook case of a batteries-included feature. The djangonic implementation would to provide true base classes for views, serializers (if any), CMS plugins, etc. then include a set of subclassed components in an package called shop.contrib.rest. Developers who need a REST API can implement their sites from that.
The same can be said for Haystack, SASS and Angular, though the latter two might be better to spin off into wholly separate packages.
I'm certainly happy to help, starting with a more detailed overview of my ideas.
@rspeed Adding DRF to django-SHOP was one of the best decisions I ever made. It makes it much more flexible, than most of it's competitors. Therefore I have no intention to remove REST from django-SHOP. In my opinion, modern Web frameworks should ship with a REST interface right from day one. In this respect, Django is a little bit too old for this.
Django-SHOP is shipped with sensible defaults, working out of the box, but all of them can be overridden.
About SASS, AngularJS and Haystack you're right. But these all are optional requirements. All template fragments, which currently use SASS or AngularJS, can be overridden by templates without those requirements. If there is a customer is willing to pay for this, I'm happy to replace that dependency immediately.
If you intend to do a bigger refactoring, please contact me. In the next major release (0.10.0) some of the REST serializers have been refactored to be better configurable.
There seems to be a miscommunication here. I said that DRF should be shipped with django-SHOP. My suggestion was that it be optional.
I whole-heartedly agree this documentation is necessary. I have proposed a section outline below. Some of this could just be a link to existing documentation. It also really needs annotating with change history, especially settings (e.g. "Changed in v0.10.1").
- Architecture a. Description of Django, CMS, admin, Angular, bootstrap, SASS, Haystack & DRF integration b. Features c. Exclusions/ ToDo list (link to reserved github issue number?) d. Compatibility (python, django, CMS, DRF, etc..)
- Required component installation & what they're used for a. python b. node / npm c. other (redis & elasticsearch?)
- Database integration a. Migrations b. Fixtures - items to include all CMS plugins & CMS shop pages (i.e. search, watch-list, cart, checkout, etc..)
- Minimum requirements a. Settings b. URLs c. CMS Templates d. Styling
- Customisation a. Models & admin b. Product Categories c. Overriding Templates & Styling d. Modifiers e. Serialisers f. Search
- Known external plugins (& degree of recommendation) e.g. Paypal, currencies, modifiers..
If you let me know where the best place to put it is, I may even be able to contribute a draft!
@racitup I've just added a Wiki page which can be used as a starting point for a better documentation. Btw. are you a native English speaker?
Excellent, thanks @jrief! I'll contribute some content soon. And yes I'm a native English speaker, from England so IMHO the best sort :wink: I have noticed a few typos in the documentation but didn't know how to suggest fixes; I guess just contribute a PR?
@racitup today I started to refactor the documentation a little bit. Could you please send me your email address, so that I can get in touch with you directly?
@jrief This is an old issue but it saves me creating another one that is very similar. I agree completely regarding Django REST, it is the modern and accepted way so should definitely stay. It has also been agreed above that Angular and SASS are implementation specific issues and could be separate from the project if someone is willing to put in the effort / pay for them.
I require Angular to be optional and see this as possibly a separate project for now that I will happily contribute to and create if one doesn't exist. Any ideas for a name? django-shop-minimal-template? I see a minimal project using plain JS, using ES6 components that are transpiled into ES5 and chunked out to a common.js that all scripts share i.e. fetch, error handling etc, then other chunks would be specific e.g. cart.js. The js can be included on the template with common.js and it will "just work". Completely stand alone and no plugins for angular etc required. This would also allow others to extend or use their own JS build tools that can import the JS modules if desired.
I have personally found it difficult to get into using the project due to the sheer amount of packages that the project requires that I'm not familiar with. Cascade with bootstrap is awesome btw, I'll definitely be using that!!
I have looked through and found which plugins are CMS specific, Django shop specific and implementation specific. I have seen that one of the packages in the common.txt file is virtualenv, surely this isn't a requirement for any of the project (developer specfic choice) and maybe a mistake to be included in this file? People with python3.4+ will be using the built in venv. Other projects with large lists group the requirements with labels / comments in the requirements file.
I totally agree, that AngularJS should be removed as a dependency. In theory that would be possible right now, if we remove all dynamic loading, ie. rendering plain HTML templates using DRF's HTMLTemplateRenderer. Then however, all the dynamics of the project is gone, and sincerely, nobody nowadays wants statically rendered HTML pages anymore.
Therefore we have to replace AngularJS by another MVVM framework. Angular2+ certainly is not a good candidate for this. ReactJS and Vue.js are very popular, but again, we would replace one opinionated framework against another. Aurelia is really cool, but has a very small user base. Native Webcomponents would be a good choice, but I'm unsure if I can do everything currently possible now. Therefore I really have a hard time making a decision. Also, please consider, that I have written a lot of AngularJS directives, which somehow would have to be adopted or rewritten.
Maybe, let's proceed with this discussion on the Gitter chat.
IMO, deciding on a frontend framework is fine if we want to be a more or less complete out of the box shop solution. For a reusable Django app, it's problematic.
Ideally, we would have several packages:
- A reusable app (or maybe a few of them) that is frontend-agnostic, has few and light dependencies and plays well with the Django ecosystem. This is where most of the models, serializers and views would live. People who want to build highly customized shops would probably use this one, extend it and implement their own frontend.
- A nice frontend for that app, built with some frontend framework.
- A complete out of the box shop solution that uses 1 and 2 and adds any other necessary parts to create something that you can "just install and run".
@jrief Canyou please direct me to the "Gitter chat" for this subject please?
@rfleschenberg @jrief My opinion with regards to a framework is different. I believe that one is not necessary and should just be plain self contained JS modules. Some will need to depend on others naturally. I visualise a simple webpack build script that pulls it all together and bundles it out into small self contained scripts, just like what Google are doing with material web components. They can be incorporated into any framework or used standalone. This method of using JS modules should suit any front end framework as they are treated as a third party script or one is not required at all.
I wish to create a small project which is effectively a demo theme to django shop with the front end that I defined above, I just need a suitable name for it and to ensure that you would be interested and feedback thoughts on it. It would also need ot be kept up to date so I will need a close relationship with the current example theme.
@Aiky30 If it is feasible to implement it that way, that is certainly preferable! I don't know enough about frontend development to judge how complex this will get.
@rfleschenberg I require what I stated above for a project that I have currently. I think I would add one component at a time and it could take me a while due to the fact that the project I have is a favour and not paid.
@rfleschenberg I misread your comments before. I have re-read them and I agree completely about the several packages 1, 2 and 3. I believe that a lot of my current confusion is with the actual shop app containing angular rather than the example. I would see it that the core shop could contain basic functionality (as you have stated) and the example shop would take the view of being an opinionated setup (includes angular).
I am personally finding difficulty studying what the core code and templates are that I can extend or re-write in my own project without having to literally rewrite it. As I have mentioned I will be creating an open project that tries to remove angular but keep it as simple as possible. Hopefully it will be of use for Jacob to decide the direction that he wishes to take once I have made sufficient progress with it.
For naming, I recommend the convention used by django-CMS for third party modules: djangoshop-...... Therefore my payment providers are named djangoshop-paypal, djangoshop-stripe and djangoshop-shipcloud.
BTW, what is your preferred frontend framework? It currently is hard for me to imagine how to change django-SHOP into being frontend-framework-agnostic, without sacrificing useful features such as client-side form-validation, infinite scroll, the progress bar, menu-dropdowns etc.
Therefore my proposal would be to switch over to a more modern framework. For instance I really like Aurelia, because you basically write pure ES6 JavaScript without getting in contact with the framework itself. It also is possible to wrap existing widgets from React, AngularJS, jQuery and others.
What's your opinion about webcomponents? Maybe that's the solution for becoming frontend-framework-agnostic. I'm not really familiar with it.
@jrief I have started a project to play with ideas regarding creating an agnostic setup: https://github.com/Aiky30/djangoshop-minimal-example
I believe that the core project should supply a fully functional example but with no decisions regarding framework and maybe even JS that others can hook into. I visualised small JS snippets for infinite scrolling, progress bar etc that can be included or removed. For instance I see the cart app as being a separate app that contains it's own styles, js and Python that can be reused or overridden. I shall have a play with some ideas in the project that I've created. If you can follow the project then we can share ideas with different approaches.
I am personally a React developer although React isn't really a framework. I would like to build vanilla JS scripts (no framework required, purely a term for raw javascript), maybe web components are the way to go. The main issues I foresee with the JS are: HTTP requests to the API and binding onto html that can change per project. Like angular we can add a data attribute to bind to elements so the template can be customised: An example: <someelement data-my-custom-bind="cart-add" />.