# Planning our Module
###### tags: `module-tutorial` `foundry-vtt`

Let's take a step back and think about the structure of what our `todo-list` module should look like when it's done.

## I. ESModules vs Scripts

There are two ways we can tell Foundry Core about a module's javascript files in its Manifest: `"scripts"` and `"esmodules"`. There's a lot of philosophical difference between these approaches but we're going to focus on the practical here.

Practically speaking, the difference comes down to the scope in which your script is run.

:::info
**Programming Concept: Scope**

Think of "scope" in this context like a room in an office building where a script is allowed to work.
:::

### Scripts

Since the beginning of javascript, scripts have been loaded all together and all at once and expected to co-exist in a single global 'scope'.

Putting all of the scripts in the same scope has both benefits and drawbacks.
- For simple cases (like a website which needs only 1 or 2 scripts) it's simpler and faster.
- For cases where scripts want to work together, working in the same scope is easy.
- The more scripts you add, the more likely a conflict will arise where Script F overrides something Script B was using, etc.

> Office Example:
> When there's only one or two people working together in a room things work great. They can share a whiteboard, table space, etc. without getting in eachother's way.
>
> When there's a _lot_ of people working together in a single room, things get complicated. Conflicts might arise where multiple individuals need the whiteboard or the table at once. And that one person comes along who starts eating other peoples' lunches.

### ES Modules

Recently there has been a shift in javascript development away from putting all scripts in the same scope and instead introducing "modules" which can import eachother to work together. A single "module" in this context is a single "script." Each "script" in this setup works within its own scope with no overlap between them.

This solves a lot of problems, but also has some drawbacks:
- For simple cases, this is probably overkill.
- For cases where scripts want to work together, they must explicitly define which parts of themselves are exported to be importable by other scripts.
- It doesn't matter how many scripts you add, they will never conflict with eachother.

> Office Example:
> ES Modules are like cubicles. The office room got so hectic that to make things easier, every person gets their own mini-room within the larger room in which to work.
>
> When someone wants to interact with another person, they have to go to that other person and ask for stuff from the cubicle entrace. Only the things that the person inside the cubicle wants to can leave it.

There's a lot more to unpack about this topic and I'll refer you to [this article](https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/) if you want to know more.

### Why Scripts?

I chose to leverage scripts for this project because it is a simpler concept to grasp.

Since we're not making an overly complex module, we're going to stick to scripts with some Object Oriented principles to help protect ourself and the other modules around us.

## II. Object Oriented Javascript?

There's a lot of very philosophical talk out there among professional javascript developers on frontend, backend, and anywhere in-between about topics like this. Mozilla has an excellent [tutorial](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/Object-oriented_JS) going into more details if you are interested. I will leave you with why I chose to write this tutorial as following some basic Object Oriented principles:

1. It's a way to keep your code safe from other peoples' code.

All of the modules active in a Foundry instance are sharing the same "scope." This can lead to unexpected problems if your module is installed alongside another module.

2. This methodology draws inspiration from how Core is laid out.

By working in a way that echos how Core works, you can get a better feeling for how to read Core code when you need to.

### The Basics

Everything you care about should be grouped into `Class`es. A [`Class`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/class) governs one 'concern'. These `Class`es are namespaced in such a way that they are easy to find and differentiate.

Classes have `methods`/`properties` defined on their namespace. Some of these are `static`, which means they are accessible from outside the scope of the Class (most are not).

:::info
**Programming Concept: Terminology**

There's a lot of overlapping teminology in Javascript-land. It's easy to get lost when the words switch half-way through a tutorial and I'm sure I'll end up doing that here.

A [`method`](https://developer.mozilla.org/en-US/docs/Glossary/Method) is a [`function`](https://developer.mozilla.org/en-US/docs/Glossary/Function) which belongs to a Class (aka is a ["property"](https://developer.mozilla.org/en-US/docs/Glossary/property/JavaScript) of that Class).
:::

---

## III. Moving Parts

At the most fundamental level, our TODO module needs two things:
- A place to persist our data in the database.
- A UI to interact with that data.

We can break this task up and do things one at a time. We'll handle our data problem first, then make a UI later.

:::info
**Programming Concept: Separation of Concerns**

From a theoretical standpoint, how we store the data should not care about the user interface. We should instead build an API for our data 'layer' which can be used by any number of consumers.

For example, if done correctly a todo could be created, updated, or deleted by a macro, or by another module.
:::

---

## IV. Data Layer

There's a few ways modules can [handle data](https://foundryvtt.wiki/en/development/guides/handling-data) in Foundry, which you use depends on your needs. Here's our assumptions:

- Any user can create, edit, or delete a todo.
- A todo can only be viewed/edited/deleted by its creator.
- A todo should follow the user to whichever machine they log into.

A `'client'` scoped setting almost fills these requirements and is a good option. However, since we want these todos to follow the user when the log in on a different machine, that won't work. Instead, we'll use a `flag` on the `User` Document to store todos.

### What is a `ToDo`?

/**
 * A single ToDo in our list of Todos.
 * @typedef {Object} ToDo
 * @property {string} id - A unique ID to identify this todo.
 * @property {string} label - The text of the todo.
 * @property {boolean} isDone - Marks whether the todo is done.
 * @property {string} userId - The user's id which owns this ToDo.
 */

This is a [jsdoc](https://jsdoc.app) [`@typedef`](https://jsdoc.app/tags-typedef.html) which defines the structure of our `ToDo` object. It notes that the ToDo is an object with four keys (`id`, `label`, `isDone`, `userId`) as well as what each of these do. An [IDE](https://developer.mozilla.org/en-US/docs/Glossary/IDE) like [Visual Studio Code](https://code.visualstudio.com/) has built-in tooling to make use of this kind of in-code documentation.

### What do we need to be able to do with it?

| Description | Operation |
| ---------------------------------------------- | ----------- |
| User should be able to make new ToDos | Create |
| User should be able to view one of their ToDos | Read |
| An existing ToDo's `label` should be editable | Edit Label |
| An existing ToDo should be mark-able as "Done" | Toggle Done |
| User should be able to delete ToDos. | Delete |

:::info
**Programming Concept: CRUD**

**C**reate, **R**ead, **U**pdate, and **D**elete is often abbreviated as simply **"CRUD"**
In our table of operations above, "Edit Label" and "Toggle Done" are both really the same data operation: "Update and existing ToDo"
:::

---

## V. Recap

We want a User Interface which allows Users to Create, Read, Update, and Delete `ToDo`s which are objects consisting of some Text for a `label` and a Boolean for `isDone` stored on `User` `flags`.

Next Step: [Setting Up](/ojFSOsrNTySh9HbzTE3Orw)

{%hackmd io_aG7zdTKyRe3cpLcsxzw %}