ivelum / djangoql

Advanced search language for Django
MIT License
1.02k stars 89 forks source link

Request for dedicated wiki page / tutorial on how to include DjangoQL autocompletion on webpage #96

Open simplylu opened 2 years ago

simplylu commented 2 years ago

Hi, thanks for this awesome package. Whilst all is working great for now, I do not have a working autocompletion in my frontend. When copying your example, all is working great. But as soon as I'm trying to adapt to my model, it fails miserably. Thus, I now left it as nice to have on my pile of features.

But I'd like to request a tutorial on how to build this example with detailed explanation on the different blocks of code, especially in models.py / views.py, since they are not explained right now. This makes it kinda difficult (at least for me) to adapt to other models. At least an explanation would be really nice.

Thx!

stebunovd commented 2 years ago

Hi there!

The DjangoQL completion widget can be installed separately as an NPM package. The Python DjangoQL distribution already includes a compiled version of djangoql-completion, but if you'd like to use it in your custom-built frontend, it could be much more convenient to use the NPM package.

The djangoql-completion repo includes a basic readme that describes the completion widget public API. Of course, this is not a complete tutorial, but maybe it could be helpful - please check it out.

simplylu commented 2 years ago

Hi, thanks for the quick reply. I know the page and I tried to follow it, but I'm not using JS on the backend site, unfortunately. I'm also a little confused, since the example from your repo works without the npm package, doesn't it? And if so, how can I do so as well, but for a different model?

I'll again try it tomorrow, but I don't think I'll be successful, since I'm struggling with this since days.

stebunovd commented 2 years ago

Sorry, it seems that I misunderstood your original question. If you only need to use the autocompletion widget for another model, you probably don't have to deal with the npm package or customize the widget.

... the example from your repo works without the npm package, doesn't it?

The Python DjangoQL distribution is already shipped with the compiled version of the npm package for your convenience, and this is good enough for simple use cases. However, if you have a custom-built frontend based on Webpack or a similar JS bundler, you may want to switch to the npm widget distribution.

Back to your original question, the Using completion widget outside of Django admin section in the readme provides an example based on the User model. The template in this example doesn't have any model-specific code, and it should work out of the box with any other model. No changes in your models.py are required either; everything is in the views.py. If you'd like to use it for another model, replace Userin the views.py with your model and (optionally) provide a custom search schema for your model.

Search schema defines limitations and additional capabilities: which fields and models can be used in the search, should there be any field value suggestions, custom search fields, or a custom search logic. Suppose you don't need to customize the search schema just yet. In that case, you can omit the custom search schema definition entirely (UserQLSchema in the readme's example) and just use the base built-in DjangoQLSchema instead of it, which is universal and compatible with any model.