CanJS documentation questions

CanJS
1

QUESTION 1:

[tl;dr: is v2.canjs.com “legacy” documentation? If so, is there a reliable way to identify what is/isn’t legacy?]

The doc at CanJS - can.Component.extend says,

You will typically provide the following values on the prototype object.

And then lists: tag, events, helpers, viewModel, and template.

However, extend | can-component | Views | API Docs | CanJS says,

Parameters

  1. prototype {Object}:

    An object set as the prototype of the constructor function. You will typically provide the following values on the prototype object:

    • tag {tag} - Defines the tag on which instances of the component constructor function will be created.

    • ViewModel {ViewModel} - Specifies an object that is used to render the component’s view.

    • view {view} - Specifies the view rendered within the custom element.

    And sometimes the following values are provided:

    • events {events} - Defines events on dom elements or observable objects the component listens to.

    • helpers {helpers} - Specifies mustache helpers used to render the component’s view.

…and the code examples I’m studying such as Canvas Clock | beginner recipes | Guides | CanJS — Build CRUD apps in fewer lines of code. only define tag, view, and ViewModel.

If the answer is that the second set of documents supersedes the first, is there a FAQ or resource that would have informed me (and presumably other newbies) of that?

QUESTION 2:

API Docs | CanJS — Build CRUD apps in fewer lines of code. shows:

Legacy Collection

  "can-ejs": "",
  "can-list": "4.0.0",
  "can-map": "4.0.1",
  "can-map-backup": "",
  "can-map-define": "4.0.0",
  "can-view-href": "",

But the Menu at the left side of the screen (click MENU or zoom out far enough) shows:

LEGACY
can-compute
can-list
can-map
can-map-define

Q 2a. Which list is accurate?
Q 2b. If these are legacy, are they superseded by more modern equivalents, and if so what are the equivalents?

Any help appreciated, TIA.

2

Hi @code-read!

  1. Yes, the docs at v2.canjs.com are for older versions of CanJS—when you’re in the Guides or API sections, you’ll see a dropdown in the sidebar for selecting docs all the way back to CanJS 1.1. The v3.canjs.com docs (and the current docs for 4.x at canjs.com) have a dropdown in the upper left of the page that show you which version you’re looking at.

We don’t have a FAQ about how we host docs for different versions of CanJS. Where do you think you would’ve found this, or how do you think we could make this more clear?

  1. Thanks for pointing this out—can-ejs, can-map-backup, and can-view-href haven’t been updated for CanJS 4, so they shouldn’t be in the list on the API Docs page. The packages you see in the sidebar are correct for that version of the docs you’re looking at, so for example can-compute, can-list, and can-map have all been updated to work in CanJS 4.

In general, if you’re building a new app, you don’t need to use the legacy packages. We still keep them around and upgrade them with newer versions of CanJS so people can migrate to new versions more easily. :slight_smile:

can-list, can-map, and can-map-define are replaced by can-define/list/list and can-define/map/map. This is explained in the CanJS 3 migration docs.

can-compute was just moved to legacy with CanJS 4. For apps that are using can-compute, we’re in the process of creating a package named can-value, which will cover most of the same use cases. If anyone’s interested in providing feedback on that, there’s an open issue about it: https://github.com/canjs/can-value/issues/5

3

@chasen, thank you for your speedy reply, it helps!

You ask,

Where do you think you would’ve found this, or how do you think we could make this more clear?

I recall that I reached v2.canjs.com from a Google search. At one point I checked v2.canjs.com’s dropdown menu which seemed to indicate it that it DID refer to the latest documentation, i.e.:
image

It would have helped me had that dropdown pointed forward to newer releases. Even better would be some kind of “Legacy” indicator in the header, possibly even a modified canjs logo, e.g.,
image
Also, I think it would help if one of the menus in the legacy documentation pointed to the Migration Docs.

Why, you may ask, did I use a Google search as mentioned above, rather than the native canjs.com search? Perhaps I did and got a result like this:
image
I don’t understand how that could be.

Finally, the newer doc pages have canjs version dropdowns as you describe, but depend on screen dimensions so they didn’t appear for me (Firefox 60.0 (64-bit); Windows 7 Pro/64; screen=1440x2560). On my vertical screen at normal zoom the menu looks like:
image

If I zoom out I see the version dropdown:
image
Of course now that you’ve educated me I won’t have these problems, but I am concerned about future newbies.

1 Like
4

This is all GREAT feedback. Thanks!

5

Thanks again @code-read! The feedback is really helpful.

For anyone following along at home :smiley: I’ve already opened a PR for fixing the API Docs page and I created a few issues for fixing the other problems: