CanJS 4.0 migration guide

[JaneOri]

Changes to watch for

Stache:

• %event and other special symbols are now on scope
  • for example, %event is now scope.event
• can-view-scope doesn't do implicit scope walking, so change to use ../ and whatnot. Or use {{scope.find('foo')}}

Routes:

• can.route(":page", { page: "home" }); is now can.route("{page}", { page: "home" });
• can.route.ready(); is now can.route.start();
• can.route() is now can.route.register()

Packages

• can-stache/helpers/route is now can-stache-route-helpers

Code/ViewModels

• can.batch.start() is now can.queues.batch.start()
• can.batch.stop() is now can.queues.batch.stop()

[matthewp]

can-stache/helpers/route is now can-stache-route-helpers.

[matthewp]

can-view-scope doesn't do implicit scope walking, so change to use ../ and whatnot. Or use {{scope.find('foo')}}

[phillipskevin]

The .each method has been removed from can-define/map/map, can-define/list/list, can-map, and can-list.

You should use .forEach or canReflect.each instead.

[chasenlehara]

can-define uses can.keys as the event name for when keys are dispatched instead of __keys

[phillipskevin]

stache's log helper is now console.log (the other console methods are available also). It will not be passed the current context by default. You should use console.log(this) if you want that.

[phillipskevin]

These will no longer automatically call bar as a function:

{{bar}}

{{#bar}}
  ...
{{else}}
  ...
{{/bar}}

You need to now call them manually:

{{bar()}}

{{#bar()}}
  ...
{{else}}
  ...
{{/bar}}

Also, functions in bindings are not automatically called... so you need to call them if you're doing
on:click="foo" or on:click="foo.bar.baz()".

[chasenlehara]

• can-route-pushstate should now allow the browser to open a new tab/window when the user is holding down a modifier key (e.g. control, command, etc.)

• Changing a component element’s attribute will not update the viewmodel property; see can-component’s ViewModel “Using attribute values” docs for more details.

• The default ViewModel type has changed; if you were relying on it being a specific type, it’s changed.

• No need for @ when importing or exporting functions in stache.

• route.param no longer accepts route as a property on the object passed to it [this was an undocumented API]

[phillipskevin]

inserted and removed events on components should be moved to connectedCallback and disconnectedCallbacks on the component's ViewModel.

Or you should run this to make inserted and removed work:

import domEvents from "can-dom-events";
import domMutateDomEvents from "can-dom-mutate/dom-events";

domEvents.addEvent(domMutateDomEvents.inserted);
domEvents.addEvent(domMutateDomEvents.removed);

[matthewp]

Should we create can-dom-mutate-events-legacy or something that does the above?

[andrejewski]

@matthewp I would prefer a can-3-4-compat package that does more than add two events if there is anything else we could restore.

[matthewp]

The downside to that is it would be harder to remove the compat package if you depend on several of its internal behaviors.

[andrejewski]

We could have can-3-4-compat/dom-mutation-events be a module that is imported by can-3-4-compat/index and what not, allowing people more granularity without scattering legacy behavior across entire packages.

[matthewp]

I would favor not allowing importing can-3-4-compat and forcing people to import the individual things they need. Meaning you have to import can-3-4-compat/dom-mutation-events

[phillipskevin]

The default helper can no longer be called as function.

[justinbmeyer]

@phillipskevin is it possible to make {{default()}} still work?

[justinbmeyer]

DefineMap's value behavior should now be called default.

[matthewp]

can.route.deparam(routeString) no longer includes a .route property when there is a matching route. Use !!route.rule(routeString) instead.

JUSTIN NOTE: I'd use route.rule(...) !== undefined

[matthewp]

can-view-model no longer uses domData to get an element's viewModel. Instead it uses the can.viewModel symbol.

[matthewp]

Are there any uses cases for keeping can-event in a project @justinbmeyer @phillipskevin? I think everything it did is covered by can-queues.batch and can-event-queue, right?

[matthewp]

@chasenlehara @phillipskevin @m-mujica @justinbmeyer Here is the first version of the migration guide: https://canjs.github.io/next/doc/migrate-4.html . You can leave feedback here and I'll update in a PR.

[phillipskevin]

Some comments from reviewing the guide:

1. We might want to mention that not all ecosystem packages have been updated to 4.0. Especially if using the can package, it might not be super easy to tell if everything you're using has a 4.0 version. Maybe we have people check the site for the packages they're using. Or we could give a list of what has not been updated.

2. In the inserted/removed event section, this sentence reads a little strange:

Most if what was done in the inserted event can be replaced in places like value.

3. The connectedCallback is only on the ViewModel (pretty sure).

Component.extend({
    connectedCallback: function(){

should be

Component.extend({
    ViewModel: {
        connectedCallback: function(){
        }
    }

4. I think this is a typo:

In can-define 1.0, you would default a default value for a property

[justinbmeyer]

I have been thinking if we should call connected callback on both the component and the VM. Sometimes I feel like it makes more sense on the component.

[justinbmeyer]

Unlike previous versions of CanJS, in CanJS 4 there are a mixture of different package versions. This is because CanJS is now developed as separate independent packages.

Was this not true for 3.0? can-define was 1.0 for can@3.0.

Use can-queues instead of can-event

can-queues replaces most closely can-event/batch/batch.

If you were using can-event, then you likely want to use can-event-queue/map/map.

I actually think can-event-queue/map/map is the best thing to use at first. It includes .start() and .stop() and other old can-event/batch/batch methods:

https://github.com/canjs/can-event-queue/blob/master/map/map.js#L821

These warn, but fix those later ...

Implicit scope walking

I think this section should tell people that upgrading to the latest 3.0 will warn them of where they are using implicit scope walking.

[matthewp]

@justinbmeyer

Was this not true for 3.0? can-define was 1.0 for can@3.0.

No, can-define was not part of CanJS 2.3, so it wasn't part of the migration guide.

[phillipskevin]

@matthewp there are a few things missing from the migration guide:

• .each is removed from our Map and List types and you need to use .forEach (CanJS 4.0 migration guide #3781 (comment))
• functions are not automatically called by stache without () (CanJS 4.0 migration guide #3781 (comment))

Do you want me to add these? Or do you want to take care of it?

[matthewp]

I'll get it, thanks for the notes!

[matthewp]

@phillipskevin what was the reason for .each being dropped? Was it that it conflicted with something else?

[phillipskevin]

stache lookups will now check the context before checking helpers, so {{#each(list)}} would have called list.each instead of the each helper.

[phillipskevin]

About #3781 (comment) - I'm going to try to get {{#default()}} working today so we don't have to explain/codemod this.

[matthewp]

These are all added to https://canjs.github.io/next/doc/migrate-4.html