document changes from effects rewrite:

[mikesherov]

deprecated

• .effect("transfer") -> .transfer()
• magic .show('size') which animated from 0 to to, which is now instead the same as .toggle('size') in that the to is the starting point and the original size is the endpoint.

new internals

• all effects are :animated detectable.
• $.fx.step.clip allows specifying an object rather than a string for clip values.

new api: $.effects

• $.effects.define: for specifying a new effect.
• $.effects.scaledDimensions: returns an object that has width / outerwidth measurements for an element scaled to a specified percent and direction.
• $.effects.clipToBox: given a TRBL set of clip dimensions, returns a WHLT set of dimensions. Useful for animatin a placeholder element during a clip animation.
• $.effects.unshift: considering that effects are not queued, if you're effect has multiple animations, queue them all up, and then unshift the number of animations you made to add them to the front of the queue. will not document in anticipation of using queueHooks.
• $.effect.saveStyle: saves inline styles before an effect, so they can be restored automatically later.
• $.effect.restoreStyle: restores the inline styles from before an effect that were last saved with $.effect.saveStyle.
• $.effect.getBaseline: gets fractional values for a vanishing point on an element.
• $.effect.createPlaceholder: in order to animate clip, the element needs to be absolute. This creates a placeholder element so that layout is not effected, and turns the original element absolute. Returns the placeholder, which can be undefined if none was created.
• $.effect.removePlaceholder: removes a placeholder from an element. noop if the element has no placeholder.

Private

• $.effect.cleanup: restores styles and removes placeholders from an element. Typically called at the end of an animation.
• $.effect.mode: normalizes "show", "hide", "toggle", and "effect" to "show", "hide", "none", or "effect" given an element's current display state.

new api: $.fn

• $.fn.cssClip: getter/setter for an object version of the css clip property.
• $.fn.transfer: same as the .effect("transfer") method but no longer the rest of the effects semantics.

[jzaefferer]

@mikesherov is this supposed to go on the relevant API pages? I guess it also needs to go into the upgrade guide?

[scottgonzalez]

Yes, the appropriate API pages need to be updated/created.

[jzaefferer]

magic .show('size') which animated from 0 to to, which is now instead the same as .toggle('size') in that the to is the starting point and the original size is the endpoint.

Neither the docs for .show() nor for the size effect mention the .show("size") combo at all. The size effect describes the to property as "Height and width to resize to.", which doesn't match the above new show behaviour or the existing toggle behaviour. I don't know if we really want to document that, and if so, where and how.

all effects are :animated detectable.
$.fx.step.clip allows specifying an object rather than a string for clip values.

Where should we document these, do we even have to?

new api: $.effects
new api $.fn.cssClip

Do we expect anyone to use these outside of our own effects? I'm not sure its worth the effort to document them. I also wouldn't want to blow up our docs with a dozen new pages for this.

[scottgonzalez]

Neither the docs for .show() nor for the size effect mention the .show("size") combo at all.

The .show() docs clearly explain that you can use effects. Obviously it doesn't list every effect. As for the size effect documentation, I'm not sure that we explicitly mention the use of .show(), .hide(), .toggle() in any of the individual effect docs.

all effects are :animated detectable.
$.fx.step.clip allows specifying an object rather than a string for clip values.

Where should we document these, do we even have to?

Being :animated detectable doesn't need to be documented, it's just something that's expected to work.

$.fx.step.clip should get its own page, it's a useful animation.

new api: $.effects
new api $.fn.cssClip

Do we expect anyone to use these outside of our own effects? I'm not sure its worth the effort to document them. I also wouldn't want to blow up our docs with a dozen new pages for this.

Yes, they're for public use. I'm not sure what the concern is about adding documentation.

[jzaefferer]

The .show() docs clearly explain that you can use effects. Obviously it doesn't list every effect. As for the size effect documentation, I'm not sure that we explicitly mention the use of .show(), .hide(), .toggle() in any of the individual effect docs.

So should I update the to argument on the size page to describe the exception for the show and toggle methods?

$.fx.step.clip should get its own page, it's a useful animation.

We already have a page for the clip-effect, this is something else (I think).

Yes, they're for public use. I'm not sure what the concern is about adding documentation.

So one page for each of these, like $.effect.saveStyle(), $.effect.loadStyle() and so on?

[scottgonzalez]

So should I update the to argument on the size page to describe the exception for the show and toggle methods?

I guess either there or in the general description.

We already have a page for the clip-effect, this is something else (I think).

Yes, this is for directly animating the clip property:

$( elem ).animate({
    clip: String
});

or the convenience form:

$( elem ).animate({
    clip: {
        top: Number,
        right: Number,
        bottom: Number,
        left: Number
    }
});

So one page for each of these, like $.effect.saveStyle(), $.effect.loadStyle() and so on?

Yup, just like http://api.jqueryui.com/jQuery.widget.bridge/.