Check out the File Navigator for an example that doesn't make data requests.

The final widget looks like:

See the Pen File Navigator advanced [Finished] by Bitovi (@bitovi) on CodePen.

Note: If you don’t see any files show up, run the CodePen again. This CodePen uses randomly generated files, so it’s possible nothing shows up.

START THIS TUTORIAL BY CLICKING THE “EDIT ON CODEPEN” BUTTON IN THE TOP RIGHT CORNER OF THE FOLLOWING EMBED:

See the Pen File Navigator Guide (Advanced) [Starter] by Bitovi (@bitovi) on CodePen.

This CodePen has initial prototype CSS and JS which is useful for getting the application to look right.

The following sections are broken down into:

• Problem - A description of what the section is trying to accomplish.
• Things to know - Information about CanJS that is useful for solving the problem.
• Solution - The solution to the problem.

Build a service layer with fixtures

Problem

Make an /api/entities service layer that provides the files and folders for another folder. An entity can be either a file or folder. A single entity looks like:

{
  id: "2",
  name: "dogs",
  parentId: "0",     // The id of the folder this file or folder is within.
  type: "folder",    // or "file",
  hasChildren: true  // false for a folder with no children, or a file
}

To get the list of files and folders within a given folder, a GET request should be made as follows:

GET /api/entities?folderId=0

This should return the list of folders and files directly within that folder like:

{
  data: [
   { id: "7", name: "pekingese.png", parentId: "0", type: "file",   hasChildren: false },
   { id: "8", name: "poodles",       parentId: "0", type: "folder", hasChildren: false },
   { id: "9", name: "hounds",        parentId: "0", type: "folder", hasChildren: true }
  ]
}

The first level files and folders should have a parentId of "0".

Things to know

• can-fixture is used to trap AJAX requests like:

  fixture("/api/entities", function(request) {
    // request.data.folderId -> "1"
    return {data: [
      // ...
    ]}
  })
  

• store can be used to automatically filter records using the query string:

  const entities = [
    // ...
  ];
  const entitiesStore = fixture.store( entities );
  fixture("/api/entities", entitiesStore);
  

• rand can be used to create a random integer:

  fixture.rand(10) //-> 10
  fixture.rand(10) //-> 0
  

Solution

Update the JavaScript tab to:

• Make a function that generates an array of entities that will be stored on our fake server.

• Make those entities, create a store to house them, and trap AJAX requests to use that store:

import { fixture } from "//unpkg.com/can@5/core.mjs";

// Stores the next entity id to use.
let entityId = 1;

// Returns an array of entities for the given `parentId`.
// Makes sure the `depth` of entities doesn’t exceed 5.
const makeEntities = function(parentId, depth) {
  if (depth > 5) {
    return [];
  }
  // The number of entities to create.
  const entitiesCount = fixture.rand(10);

  // The array of entities we will return.
  const entities = [];

  for (let i = 0; i < entitiesCount; i++) {

    // The id for this entity
    const id = "" + (entityId++);

    // If the entity is a folder or file
    const isFolder = Math.random() > 0.3;

    // The children for this folder.
    const children = isFolder ? makeEntities(id, depth+1) : [];

    const entity = {
      id: id,
      name: (isFolder ? "Folder" : "File") + " " + id,
      parentId: parentId,
      type: (isFolder ? "folder" : "file"),
      hasChildren: children.length > 0
    };
    entities.push(entity);

    // Add the children of a folder
    [].push.apply(entities,  children)

  }
  return entities;
};

// Make the entities for the demo
const entities = makeEntities("0", 0);

// Add them to a client-like DB store
const entitiesStore = fixture.store(entities);

// Trap requests to /api/entities to read items from the entities store.
fixture("/api/entities", entitiesStore);

// Make requests to /api/entities take 1 second
fixture.delay = 1000;

Create the Entity Model

The problem

When we load entities from the server, it’s useful to convert them into Entity type instances. We will want to create an observable Entity type using can-define/map/map so we can do:

const entity = new Entity({
  id: "2",
  name: "dogs",
  parentId: "0",     // The id of the folder this file or folder is within.
  type: "folder",    // or "file",
  hasChildren: true  // false for a folder with no children, or a file
});

entity.on("name", function(ev, newName) {
  console.log("entity name changed to ", newName);
});

entity.name = "cats" //-> logs "entity name changed to cats"

Things to know

You can create a DefineMap type using DefineMap.extend with the type’s properties and the properties’ types like:

import { DefineMap } from "can";
const Type = DefineMap.extend({
  id: "string",
  hasChildren: "boolean",
  // ...
});

The solution

Extend DefineMap with each property and its type as follows:

import { DefineMap, fixture } from "//unpkg.com/can@5/core.mjs";

// Stores the next entity id to use.
let entityId = 1;

// Returns an array of entities for the given `parentId`.
// Makes sure the `depth` of entities doesn’t exceed 5.
const makeEntities = function(parentId, depth) {
  if (depth > 5) {
    return [];
  }
  // The number of entities to create.
  const entitiesCount = fixture.rand(10);

  // The array of entities we will return.
  const entities = [];

  for (let i = 0; i < entitiesCount; i++) {

    // The id for this entity
    const id = "" + (entityId++);

    // If the entity is a folder or file
    const isFolder = Math.random() > 0.3;

    // The children for this folder.
    const children = isFolder ? makeEntities(id, depth+1) : [];

    const entity = {
      id: id,
      name: (isFolder ? "Folder" : "File") + " " + id,
      parentId: parentId,
      type: (isFolder ? "folder" : "file"),
      hasChildren: children.length > 0
    };
    entities.push(entity);

    // Add the children of a folder
    [].push.apply(entities,  children)

  }
  return entities;
};

// Make the entities for the demo
const entities = makeEntities("0", 0);

// Add them to a client-like DB store
const entitiesStore = fixture.store(entities);

// Trap requests to /api/entities to read items from the entities store.
fixture("/api/entities", entitiesStore);

// Make requests to /api/entities take 1 second
fixture.delay = 1000;

const Entity = DefineMap.extend({
  id: {type: "string", identity: true},
  name: "string",
  parentId: "string",
  hasChildren: "boolean",
  type: "string"
});

Connect the Entity model to the service layer

The problem

We want to be able to load a list of Entity instances from GET /api/entities with:

Entity.getList({parentId: "0"}).then(function(entities) {
    console.log(entities.get()) //-> [ Entity{id: "1", parentId: "0", ...}, ...]
});

Things to know

restModel() can connect a Map type to a url like:

restModel({
  Map: Entity,
  url: "URL"
});

The solution

Use restModel to connect Entity to /api/entities like:

import { DefineMap, fixture, restModel } from "//unpkg.com/can@5/core.mjs";

// Stores the next entity id to use.
let entityId = 1;

// Returns an array of entities for the given `parentId`.
// Makes sure the `depth` of entities doesn’t exceed 5.
const makeEntities = function(parentId, depth) {
    if (depth > 5) {
        return [];
    }
    // The number of entities to create.
    const entitiesCount = fixture.rand(10);

    // The array of entities we will return.
    const entities = [];

    for (let i = 0; i < entitiesCount; i++) {

        // The id for this entity
        const id = "" + (entityId++);

        // If the entity is a folder or file
        const isFolder = Math.random() > 0.3;

        // The children for this folder.
        const children = isFolder ? makeEntities(id, depth + 1) : [];

        const entity = {
            id: id,
            name: (isFolder ? "Folder" : "File") + " " + id,
            parentId: parentId,
            type: (isFolder ? "folder" : "file"),
            hasChildren: children.length > 0
        };
        entities.push(entity);

        // Add the children of a folder
        [].push.apply(entities, children)

    }
    return entities;
};

// Make the entities for the demo
const entities = makeEntities("0", 0);

// Add them to a client-like DB store
const entitiesStore = fixture.store(entities);

// Trap requests to /api/entities to read items from the entities store.
fixture("/api/entities", entitiesStore);

// Make requests to /api/entities take 1 second
fixture.delay = 1000;

const Entity = DefineMap.extend({
  id: {type: "string", identity: true},
  name: "string",
  parentId: "string",
  hasChildren: "boolean",
  type: "string"
});

Entity.connection = restModel({
  Map: Entity,
  url: "/api/entities"
});

Create the ROOT entity and render it

The problem

We need to begin converting the static HTML the designer gave us into live HTML. This means rendering it in a template. We’ll start slow by rendering the root parent folder’s name in the same way it’s expected by the designer.

Things to know

• CanJS Component uses can-stache to render data in a template and keep it live. Templates can be authored in view property like:

  import { Component } from "can";
  
  Component.extend({
    tag: 'my-component',
    view: `TEMPLATE CONTENT`,
    ViewModel: {}
  });
  

  A can-stache template uses {{key}} magic tags to insert data into the HTML output like:

  import { Component } from "can";
  
  Component.extend({
    tag: 'my-component',
    view: `{{something.name}}`,
    ViewModel: {}
  });
  

• Mount the component into the page with it's custom tag:

  <my-component />
  

• You can create an Entity instance as follows:

  const folder = new Entity({/*...*/});
  

  Where {/*...*/} is an object of the properties you need to create like {id: "0", name: "ROOT", ...}. Pass this to the template.

The solution

Update the HTML tab to render the folder’s name.

<a-folder id="root"></a-folder>

Update the JavaScript tab to:

1. Define a component with a-folder custom tag
2. Write the component view template that displays the folder Entity name.
3. Write the component ViewModel that has the following properties:

• folder which references the folder being displayed.
• entitiesPromise which will be a promise of all files for that folder.

4. Set the component ViewModel values with can-view-model set function

import { Component, DefineMap, fixture, restModel } from "//unpkg.com/can@5/core.mjs";

// Stores the next entity id to use.
let entityId = 1;

// Returns an array of entities for the given `parentId`.
// Makes sure the `depth` of entities doesn’t exceed 5.
const makeEntities = function(parentId, depth) {
  if (depth > 5) {
    return [];
  }
  // The number of entities to create.
  const entitiesCount = fixture.rand(10);

  // The array of entities we will return.
  const entities = [];

  for (let i = 0; i < entitiesCount; i++) {

    // The id for this entity
    const id = "" + (entityId++);

    // If the entity is a folder or file
    const isFolder = Math.random() > 0.3;

    // The children for this folder.
    const children = isFolder ? makeEntities(id, depth+1) : [];

    const entity = {
      id: id,
      name: (isFolder ? "Folder" : "File") + " " + id,
      parentId: parentId,
      type: (isFolder ? "folder" : "file"),
      hasChildren: children.length > 0
    };
    entities.push(entity);

    // Add the children of a folder
    [].push.apply(entities,  children)

  }
  return entities;
};

// Make the entities for the demo
const entities = makeEntities("0", 0);

// Add them to a client-like DB store
const entitiesStore = fixture.store(entities);

// Trap requests to /api/entities to read items from the entities store.
fixture("/api/entities", entitiesStore);

// Make requests to /api/entities take 1 second
fixture.delay = 1000;

const Entity = DefineMap.extend({
  id: {type: "string", identity: true},
  name: "string",
  parentId: "string",
  hasChildren: "boolean",
  type: "string"
});

Entity.connection = restModel({
  Map: Entity,
  url: "/api/entities"
});

Component.extend({
  tag: "a-folder",
  view: `
    <span>{{ this.folder.name }}</span>
  `,
  ViewModel: {
    folder: Entity
  }
});

root.viewModel.assign({
  folder: new Entity({
    id: "0",
    name: "ROOT/",
    hasChildren: true,
    type: "folder"
  })
});

Render the ROOT entities children

The problem

In this section, we’ll list the files and folders within the root folder.

Things to know

• Use {{#if(value)}} to do if/else branching in can-stache.
• Use {{#for(of)}} to do looping in can-stache.
• Use {{#eq(value1, value2)}} to test equality in can-stache.
• Promises are observable in can-stache. Given a promise somePromise, you can:
  • Check if the promise is loading like: {{#if(somePromise.isPending)}}.
  • Loop through the resolved value of the promise like: {{#for(item of somePromise.value)}}.
• Write <div class="loading">Loading</div> when files are loading.
• Write a <ul> to contain all the files. Within the <ul> there should be:
  • An <li> with a class attribute that includes file or folder and hasChildren if the folder has children.
  • The <li> should have 📝 <span>{{FILE_NAME}}</span> if a file and 📁 <span>{{FOLDER_NAME}}</span> if a folder.

The solution

Update the JavaScript tab to:

• Add entitiesPromise property to the ViewModel. entitiesPromise will contain the files and folders that are directly within the root folder.

• Use entitiesPromise to write <div class="loading">Loading</div> while the promise is pending, and then writes out an <li> for each entity in the resolved entitiesPromise

import { Component, DefineMap, fixture, restModel } from "//unpkg.com/can@5/core.mjs";

// Stores the next entity id to use.
let entityId = 1;

// Returns an array of entities for the given `parentId`.
// Makes sure the `depth` of entities doesn’t exceed 5.
const makeEntities = function(parentId, depth) {
  if (depth > 5) {
    return [];
  }
  // The number of entities to create.
  const entitiesCount = fixture.rand(10);

  // The array of entities we will return.
  const entities = [];

  for (let i = 0; i < entitiesCount; i++) {

    // The id for this entity
    const id = "" + (entityId++);

    // If the entity is a folder or file
    const isFolder = Math.random() > 0.3;

    // The children for this folder.
    const children = isFolder ? makeEntities(id, depth+1) : [];

    const entity = {
      id: id,
      name: (isFolder ? "Folder" : "File") + " " + id,
      parentId: parentId,
      type: (isFolder ? "folder" : "file"),
      hasChildren: children.length > 0
    };
    entities.push(entity);

    // Add the children of a folder
    [].push.apply(entities,  children)

  }
  return entities;
};

// Make the entities for the demo
const entities = makeEntities("0", 0);

// Add them to a client-like DB store
const entitiesStore = fixture.store(entities);

// Trap requests to /api/entities to read items from the entities store.
fixture("/api/entities", entitiesStore);

// Make requests to /api/entities take 1 second
fixture.delay = 1000;

const Entity = DefineMap.extend({
  id: {type: "string", identity: true},
  name: "string",
  parentId: "string",
  hasChildren: "boolean",
  type: "string"
});

Entity.connection = restModel({
  Map: Entity,
  url: "/api/entities"
});

Component.extend({
  tag: "a-folder",
  view: `
    <span>{{ this.folder.name }}</span>
    {{# if(this.entitiesPromise.isPending) }}
      <div class="loading">Loading</div>
    {{ else }}
      <ul>
        {{# for(entity of this.entitiesPromise.value) }}
          <li class="{{entity.type}} {{# if(entity.hasChildren) }}hasChildren{{/ if }}">
            {{# eq(entity.type, 'file') }}
              📝 <span>{{ entity.name }}</span>
            {{ else }}
              📁 <span>{{ entity.name }}</span>
            {{/ eq }}
          </li>
        {{/ for }}
      </ul>
    {{/ if }}
  `,
  ViewModel: {
    folder: Entity,
    get entitiesPromise() {
      if (this.folder) {
        return Entity.getList({ filter: { parentId: this.folder.id }});
      }
    }
  }
});

root.viewModel.assign({
  folder: new Entity({
    id: "0",
    name: "ROOT/",
    hasChildren: true,
    type: "folder"
  })
});

Manage <a-folder> custom element behavior

The problem

Now we want to make all the folders able to open and close.

Things to know

• CanJS uses ViewModels to manage the behavior of views. ViewModels can have their own state, such as if a folder isOpen and should be showing its children. ViewModels are constructor functions created with DefineMap.

• DefineMap can detail the type of a property with another type like:

  import { DefineMap } from "can";
  const Address = DefineMap.extend({
    street: "string",
    city: "string"
  });
  const Person = DefineMap.extend({
    address: Address
  });
  

• DefineMap can also specify default values:

  const Person = DefineMap.extend({
    address: Address,
    age: {default: 33}
  });
  

• DefineMap can also specify a default value and a type:

  const Person = DefineMap.extend({
    address: Address,
    age: {default: 33, type: "number"}
  });
  

• DefineMap can also have methods:

  const Person = DefineMap.extend({
    address: Address,
    age: {default: 33, type: "number"},
    birthday: function() {
      this.age++;
    }
  });
  

• Use on:event to listen to an event on an element and call a method in can-stache. For example, the following calls doSomething() when the <div> is clicked.

  <div on:click="doSomething()"> ... </div>
  

The solution

The following:

3. Define ViewModel properties that will manage the UI state around a folder.:
   • isOpen which tracks if the folder’s children should be displayed.
   • toggleOpen which changes isOpen.
4. Recursively renders each child folder with <a-folder folder:from="entity" />.
5. Set the root folder isOpen property to true in the ViewModel mounting invocation (root.viewModel.assign).

import { Component, DefineMap, fixture, restModel } from "//unpkg.com/can@5/core.mjs";

// Stores the next entity id to use.
let entityId = 1;

// Returns an array of entities for the given `parentId`.
// Makes sure the `depth` of entities doesn’t exceed 5.
const makeEntities = function(parentId, depth) {
  if (depth > 5) {
    return [];
  }
  // The number of entities to create.
  const entitiesCount = fixture.rand(10);

  // The array of entities we will return.
  const entities = [];

  for (let i = 0; i < entitiesCount; i++) {

    // The id for this entity
    const id = "" + (entityId++);

    // If the entity is a folder or file
    const isFolder = Math.random() > 0.3;

    // The children for this folder.
    const children = isFolder ? makeEntities(id, depth+1) : [];

    const entity = {
      id: id,
      name: (isFolder ? "Folder" : "File") + " " + id,
      parentId: parentId,
      type: (isFolder ? "folder" : "file"),
      hasChildren: children.length > 0
    };
    entities.push(entity);

    // Add the children of a folder
    [].push.apply(entities,  children)

  }
  return entities;
};

// Make the entities for the demo
const entities = makeEntities("0", 0);

// Add them to a client-like DB store
const entitiesStore = fixture.store(entities);

// Trap requests to /api/entities to read items from the entities store.
fixture("/api/entities", entitiesStore);

// Make requests to /api/entities take 1 second
fixture.delay = 1000;

const Entity = DefineMap.extend({
  id: {type: "string", identity: true},
  name: "string",
  parentId: "string",
  hasChildren: "boolean",
  type: "string"
});

Entity.connection = restModel({
  Map: Entity,
  url: "/api/entities"
});

Component.extend({
  tag: "a-folder",
  view: `
    <span on:click="this.toggleOpen()">{{ this.folder.name }}</span>
    {{# if(this.isOpen) }}
      {{# if(this.entitiesPromise.isPending) }}
        <div class="loading">Loading</div>
      {{ else }}
        <ul>
          {{# for(entity of this.entitiesPromise.value) }}
            <li class=" {{entity.type}}
                        {{# if(entity.hasChildren) }}hasChildren{{/ if }}">
              {{# eq(entity.type, 'file') }}
                📝 <span>{{ entity.name }}</span>
              {{ else }}
                📁 <a-folder folder:from="entity" />
              {{/ eq }}
            </li>
          {{/ for }}
        </ul>
      {{/ if }}
    {{/ if }}
  `,
  ViewModel: {
    folder: Entity,
    isOpen: {type: "boolean", default: false},
    get entitiesPromise() {
      if (this.folder) {
        return Entity.getList({ filter: { parentId: this.folder.id }});
      }
    },
    toggleOpen: function() {
      this.isOpen = !this.isOpen;
    }
  }
});

root.viewModel.assign({
  isOpen: true,
  folder: new Entity({
    id: "0",
    name: "ROOT/",
    hasChildren: true,
    type: "folder"
  })
});

Result

When complete, you should have a working file-navigation widget like the following CodePen:

See the Pen File Navigator advanced [Finished] by Bitovi (@bitovi) on CodePen.