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

Standardize custom pseudo object #2073

Closed
gibson042 opened this Issue Feb 7, 2015 · 4 comments

Comments

Projects
None yet
2 participants
@gibson042
Member

gibson042 commented Feb 7, 2015

cc @timmywil @scottgonzalez

The Sizzle pseudos object is exposed on jQuery.expr as three distinct properties:

  • jQuery.expr.pseudos
  • jQuery.expr.filters
  • jQuery.expr[":"]

Sizzle defines the first two, and jQuery defines the third.

None of them appear in the current jQuery documentation, though Sizzle documents the object as pseudos (and separately documents the related setFilters), and I'm sure we have published instructions on how to define a custom pseudo at least once, which would necessarily reference one of them. We also have internal uses in at least two libraries:

  • core
    • defines jQuery.expr[":"] from jQuery.expr.pseudos
    • defines :hidden, :visible, and :animated by extending jQuery.expr.filters
    • calls jQuery.expr.filters.hidden in the :visible pseudo
  • UI
    • defines :data, :focusable, :tabbable, and widget pseudos by extending $.expr[ ":" ]
    • replaces the :animated filter at $.expr.filters.animated
    • calls $.expr.filters.visible and $.expr.filters.hidden

So now that this issue affects three source repositories and jquery/api.jquery.com, here's the crux of it: can we standardize on one internally and deprecate the others? All things considered, my vote would be on filters.

@timmywil

This comment has been minimized.

Show comment
Hide comment
@timmywil

timmywil Feb 8, 2015

Member

I actually would like to keep them all. [":"] is probably the most prevalent in user code and needs to stay regardless. filters has been there a long time, but it wasn't used as much. And pseudos is NWMatchers' name for filters, so it's a more intuitive name to some.

Regardless, I'd like to continue recommending the use of the .createPseudo() method for creating custom selectors, making the choice of one property somewhat moot – except for setFilter. jQuery UI already uses it where available.

Member

timmywil commented Feb 8, 2015

I actually would like to keep them all. [":"] is probably the most prevalent in user code and needs to stay regardless. filters has been there a long time, but it wasn't used as much. And pseudos is NWMatchers' name for filters, so it's a more intuitive name to some.

Regardless, I'd like to continue recommending the use of the .createPseudo() method for creating custom selectors, making the choice of one property somewhat moot – except for setFilter. jQuery UI already uses it where available.

@gibson042

This comment has been minimized.

Show comment
Hide comment
@gibson042

gibson042 Feb 8, 2015

Member

I actually would like to keep them all.

In the sense of not moving to deprecated, or of not standardizing?

[":"] is probably the most prevalent in user code and needs to stay regardless.

But still exceedingly rare from (among other things) its lack of documentation, and with a fix that couldn't be simpler. At any rate, though, I propose deprecation not because I think we can remove them anytime soon, but to promote consistency.

filters has been there a long time, but it wasn't used as much.

That would depend on your measurement criteria... it's probably the most used by execution count from jQuery UI alone. And to the extent that any such special-case functionality can be used "much", I bet updating api.jquery.com would address the educational gap.

And pseudos is NWMatchers' name for filters, so it's a more intuitive name to some.

Then it appears NWMatcher has moved on, at least from an API perspective (which is what I'm addressing). However, even if it hadn't, maintaining surface area in jQuery core to support transitioning from an independent selector engine seems... overaccommodating.

Regardless, I'd like to continue recommending the use of the .createPseudo() method for creating custom selectors, making the choice of one property somewhat moot – except for setFilter.

Not at all; the result of createPseudo still has to be assigned to an object property. e.g.: data: $.expr.createPseudo…

Member

gibson042 commented Feb 8, 2015

I actually would like to keep them all.

In the sense of not moving to deprecated, or of not standardizing?

[":"] is probably the most prevalent in user code and needs to stay regardless.

But still exceedingly rare from (among other things) its lack of documentation, and with a fix that couldn't be simpler. At any rate, though, I propose deprecation not because I think we can remove them anytime soon, but to promote consistency.

filters has been there a long time, but it wasn't used as much.

That would depend on your measurement criteria... it's probably the most used by execution count from jQuery UI alone. And to the extent that any such special-case functionality can be used "much", I bet updating api.jquery.com would address the educational gap.

And pseudos is NWMatchers' name for filters, so it's a more intuitive name to some.

Then it appears NWMatcher has moved on, at least from an API perspective (which is what I'm addressing). However, even if it hadn't, maintaining surface area in jQuery core to support transitioning from an independent selector engine seems... overaccommodating.

Regardless, I'd like to continue recommending the use of the .createPseudo() method for creating custom selectors, making the choice of one property somewhat moot – except for setFilter.

Not at all; the result of createPseudo still has to be assigned to an object property. e.g.: data: $.expr.createPseudo…

@timmywil

This comment has been minimized.

Show comment
Hide comment
@timmywil

timmywil Feb 8, 2015

Member

That would depend on your measurement criteria... it's probably the most used by execution count from jQuery UI alone. And to the extent that any such special-case functionality can be used "much", I bet updating api.jquery.com would address the educational gap.

I think we're on different wavelengths here. In terms of defining custom pseudos, you said jQuery UI mostly used [":"] and only used .filters once. Still, I was referring to user code in general and I just remember seeing [":"] much more often. Maybe my memory is off.

Not at all; the result of createPseudo still has to be assigned to an object property. e.g.: data: $.expr.createPseudo…

Totally true. Brain fart. However, the main point there was createPseudo isn't in jQuery's documentation either.

I'm all for documenting custom pseudo creation in jQuery (and I'm fine picking a property and sticking with it), but I still don't see the value behind deprecating the other properties. To me, deprecation voices the intention of removal whether we say it does or not. If we use the same property in all of our documentation, that seems like enough.

Member

timmywil commented Feb 8, 2015

That would depend on your measurement criteria... it's probably the most used by execution count from jQuery UI alone. And to the extent that any such special-case functionality can be used "much", I bet updating api.jquery.com would address the educational gap.

I think we're on different wavelengths here. In terms of defining custom pseudos, you said jQuery UI mostly used [":"] and only used .filters once. Still, I was referring to user code in general and I just remember seeing [":"] much more often. Maybe my memory is off.

Not at all; the result of createPseudo still has to be assigned to an object property. e.g.: data: $.expr.createPseudo…

Totally true. Brain fart. However, the main point there was createPseudo isn't in jQuery's documentation either.

I'm all for documenting custom pseudo creation in jQuery (and I'm fine picking a property and sticking with it), but I still don't see the value behind deprecating the other properties. To me, deprecation voices the intention of removal whether we say it does or not. If we use the same property in all of our documentation, that seems like enough.

@timmywil

This comment has been minimized.

Show comment
Hide comment
@timmywil

timmywil Feb 1, 2016

Member

Per meeting, decided on "pseudos".

Member

timmywil commented Feb 1, 2016

Per meeting, decided on "pseudos".

@timmywil timmywil removed the Needs review label Feb 1, 2016

@timmywil timmywil added this to the 3.0.0 milestone Feb 1, 2016

@timmywil timmywil self-assigned this Feb 1, 2016

timmywil added a commit to timmywil/jquery that referenced this issue Mar 3, 2016

@timmywil timmywil closed this in 0402963 Mar 7, 2016

@lock lock bot locked as resolved and limited conversation to collaborators Jun 18, 2018

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.