2.0 Wishlist

[AlexCLeduc]

So I've been familiarizing myself with this codebase, wrote a bunch of tests, and I'm now ready to break everything and put it back together under a new 2.0 API. What should be the priorities?

1. Fix/remove class Meta API and bad class-based practices
   • this prevents inheritance, mixins and "abstract" classes
   • routes are also registered based on __subclasses__, this is another thing that'll have to change
2. Centralize all routes into a single route
   • or 2 routes, one for items/ and one for toggle/, the point is, no more new route for each different form field
     • Also, use GET rather than PUT for toggle/. We're not modifying DB data and the data is already sent in query-params format which is really weird for PUT requests
   • this isn't really something you notice as a consumer, but I want it so that AC classes can be registered dynamically after urlpatterns gets defined
3. Decouple AC classes from form-specific use-cases,
   • AC classes should be re-usable for different field-names
   • AC classes should be re-usable for different arities (multi vs. single)
   • AC classes should be re-usable for different required-ness, disabled-ness
     • this looks true right now, but there's a bug that forces it to be required if the field is required on a single form
4. Fix API weirdness
   • similar to 1 and 3, just overall make the API more pythonic and less surprising
   • Haven't yet thought about what an ideal API would look like. Ideally just plain classes, but open to ideas.
   • remove value/label/model shortcuts and force people to be explicit
     • We can have a first-party model-autocomplete that wraps around the forcefully explicit API
5. Remove the component/ route
   • I don't think this is ever being used anywhere? NEED TO CONFIRM
     • It seems to only be used by the {% autocomplete %} template helper, but I don't think we need that either
6. Add ability to access the request object in the get_items method
   • This has a workaround, but if we're breaking APIs anyway, might as well add this
7. Expose and document JS API
   • There is some level of JS api already exposed, but it's not documented and it's probably missing some things projects may want
   • Have some vague autocomplete class, whose instances represent an AC widget. This instance has utility methods for dynamic use-cases e.g. adding items, removing items, clearing, listening to change events, render-options, options-dismissed, etc.
8. Add an authorization hook that is called in items/ and toggle/
   • This is just a place to raise exceptions e.g. PermissionDenied or BadRequest, there's currently no way of protecting autocomplete routes without resorting to middleware
   • This is a good motivator for abstract classes, people will want a MustBeLoggedInAutocomplete Mixin
   • maybe, and this is kind of fancy, we could have a configurable default (via django settings) authorization hook that is called from the base AC class
9. Add a pythonic way to add additional filter conditions
   • One use case is the "cascading select" use-case, where we'd like to filter get_items based on other values in the form
   • Another use-case is filtering based on fields that are barely even dynamic, if you're dealing with a ProjectForm and want to filter available tag choices based on the project, you're modifying.
   • This is kind of possible using JS, but it's super fragile, you have to modify the hx-vals attributes of the input, and that input will get swapped immediately afterwards too
10. CSS and class customization (low priority)
    • Document markup/class structure so that people can write their own CSS
    • Add ability to add classes to all of the displayed elements
    • Add ability to add classes to individual chips, based on the item, this would be useful for tagging systems with different colored chips
    • Perhaps the ability to provide completely different templates for sub-components? definitely the most flexible
    • This whole point is lowest priority, could wait until later
11. Do we like how get_items receives values and search? Seems like an anti-pattern for this method to handle searching and selecting values based on ID
    • An alternative is to have 2 methods, one to fetch selected values by key and another to search
    • These methods would likely repeat things, e.g. assembling a queryset, filtering choices based on request details (as in 6)

[juleskuehn]

I would like to start with looking at what an ideal interaction with the API would be (i.e. adding widgets to a form for several use cases such as whole model, filtered based on form instantiation kwargs, filtered based on request user, etc.)

Priority 1, IMO:

• remove value/label/model shortcuts and force people to be explicit
• AC classes can be registered dynamically after urlpatterns gets defined
• Add ability to access the request object in the get_items method

Secondary but also really important:

• Expose and document JS API

Tertiary but easy:

• CSS and class customization (low priority)
  • ability to provide completely different templates for sub-components

"Do we like how get_items receives values and search?"

• I don't understand this part very well (which is why I don't like it)
• The ID-based implementation is indeed a bit weird. If you have two items with the same ID (rare, but possible), selecting one can actually return the other chip.

Missing items?

• I don't think the widget currently uses the Queryset property, if provided in the form.
• IIRC, you currently have to specify the form ID for accessibility. This should happen automatically.
• Paging / lazy loading!!! If a user is trying to see what options are available, the widget either has to retrieve the whole set (could be tens of thousands), or we set minimum search length > 0, which leads to counter-intuitive UX. When user presses the down icon in the select box, they should see a list of available options - always. This list should be short, i.e. max 100 items. Lazy load the rest if user scrolls. Same if user enters 1 or 2 characters and a huge result set would otherwise be returned.
• There are some UI bugs, i.e. focus ring remains after blur in some situations. Could try to address when creating/refactoring JS API. 

---

Here is the current way I'm using it, with some comments about what I don't like.

# "multiselect=True" should be implied when it is in a MultipleChoiceField
self.fields["qa_data_sources"] = forms.ModelMultipleChoiceField(
    # The queryset you define is never used, even in the basic usage.
    queryset=DataSource.objects.all(),  
    label=_("Select data source(s)"),
    required=False,
    widget=Autocomplete(
        use_ac=DataSourcesAutocomplete,
        attrs={
            "component_id": f"id_qa_data_sources",  # I shouldn't have to do this
            "id": f"id_qa_data_sources__textinput",  # I shouldn't have to do this
        },
    ),
)

class DataSourcesAutocomplete(HTMXAutoComplete):
    """Autocomplete component to select Data Sources from a library"""

    name = "qa_data_sources"
    multiselect = True  # This could/should be inferred
    # It is temping to set this higher for performance reasons, but we really need lazy loading
    minimum_search_length = 0  
    model = DataSource

    def get_items(self, search=None, values=None):
        request = get_request()  # Relying on a different library for this
        # For filtering based on other form fields. Will still have to do something like this,
        # but should be made easier on the client side via new Javascript API
        library_id = request.GET.get("library_id", None)
        if library_id:
            library = (
                Library.objects.filter(pk=library_id)
                .prefetch_related("data_sources")
                .first()
            )
            data = library.data_sources.all()
        else:
            data = DataSource.objects.all()
        if search is not None:
            items = [
                {"label": str(x), "value": str(x.id)}
                for x in data
                # Refactor so equality comparison is a function passed in?
                if search == "" or str(search).upper() in f"{x}".upper()
            ]
            return items
        if values is not None:  # I don't really understand what this is for.
            items = [
                {"label": str(x), "value": str(x.id)}
                for x in data
                if str(x.id) in values
            ]
            return items

        return []