New Tutorial: Mutable File System

[terichadbourne]

Following up on a Slack convo with @mikeal (cc @olizilla & @marcooliveira based on recent related convos)

The existing ProtoSchool workshops (basics and blog) use the DAG API, but we never introduce it as one of many APIs for working with IPFS. I had incorrectly thought that the data being stored in IPFS in these examples just happened to be JavaScript objects because it was a simple example to demonstrate, not realizing that it's the only type of data that can be stored with that particular API and that you need to use a different API to use IPFS for file transfer.

Since file transfer is a more practical use case that a beginner could see a need for, it would be nice to also build a simple lesson using the file API. We could either build a net new beginner workshop using the file API or replace the existing basics workshop. My inclination is to do the former and make it clear that one workshop is about transferring data and one about transferring files, linking between them so users can see the alternatives. We might also want to link from this lesson about transferring files yourself to the GUI file sharing service at share.ipfs.io so users have an example of the types of applications they could build using this API.

The blog workshop would remain using the DAG API, since it's a more advanced lesson about structured data that makes sense in that format.

Note that this is not being proposed as part of the 1.0 release.

[mikeal]

The thing I was stuck on mentally for a while was "how do we get a file into the browser based code workflow." I thought that we'd have to figure out a way to incorporate UI programming into the lesson.

The other day I thought of a much better solution. We create a new Lesson sub-component called "FileLesson" and in the exercise box we have a drop area for files. Instead of a run function that takes no arguments the run function will take the arguments of the files dropped into the drop area.

The first lesson should pass automatically if they drop anything in, just to get them accustomed to the workflow. The next lesson or two should just be a quick primer on working with File objects in the browser, cause the API is pretty rough around the edges.

Then we can get into how to store files in IPFS :)

[terichadbourne]

Would the lesson not be possible with them typing filepaths (my/computer/awesome.doc) because there's some lack of ability to access their file system from the editor, or is it just friendlier the way you're describing @mikeal?

[mikeal]

@terichadbourne not unless we have them download an Electron desktop app or something. The browser security model won't allow us any direct file access without the user explicitly dropping the file into our web application.

[mikeal]

Alternatively, instead of a "drop area" we could have a button that asks them to select a file. I usually implement a drop area that also kicks off that workflow if you click it instead of dropping a file in.

[lidel]

Some relevant prior art:

• js-ipfs/examples#js-ipfs-examples-and-tutorials
  • browser-browserify (old&ugly boilerplate with basic file picker)
  • exchange-files-in-browser (advanced demo with nice UI for dropping a file in)
  • browser-mfs (various MFS demos)
• js-ipfs-http-client/examples/upload-file-via-browser (basic "Choose File" file picker)

Creating a workshop for Files API (MFS) may be a good opportunity to refine or deprecate examples above.

ps. Files API has been recently refactored – ipfs/js-ipfs#1720

[marcooliveira]

@lidel's comment has a lot of nice examples. In terms of choosing the right use case for an introduction, I don't think I'm the right person to choose. I will add that we do have an example on https://js.ipfs.io/ as well, worth considering.

The key point, in my view, is that we should eventually go through all existing artefacts that have introductions/examples and, instead of having them live there, point to proto.school. If anything, proto.school could be embeddable, so that the user is kept in place, but the learning material should live in one place, for everyone's sanity, making it easier to maintain documentation and examples, further freeing people to upgrade APIs, and not fear outdated examples/doc being forgotten somewhere.

[mikeal]

Just so that we're all on the same page, by "File" we mean MFS :)

[terichadbourne]

@mikeal has started working on the functionality to add files in WIP PR #111. I'll circle around to this after launch to build out the lesson content.

[terichadbourne]

I plan to start work on this tutorial next week, and I think I'll need to poke around and explore existing documentation / tutorials on the FIle API before proposing the specific concepts and exercises we might want to introduce and asking for feedback in this issue.

My first step will be poking around the https://js.ipfs.io/ site and seeing what resources I find my way to first, circling back to this trail for some specific suggestions. If anyone would like to watch me attempt this as some free usability testing for your own projects, I'm happy to coordinate time to get on Zoom together. (@alanshaw I believe you expressed an interest in this.) Otherwise I'm more than happy to explore myself and request help / share feedback when I get lost.

I'm planning to set aside 9-12 Eastern (2-5 UK/Portugal) on Tuesday 1/22 to start poking around. If anyone would like to spectate for part of that period, feel free to send a Calendly invite (https://calendly.com/teri-chadbourne) for the time that works for you for a Zoom call.

After I feel I have a grip on what the File API is capable of, I'll circle back to the work @mikeal has done to enable file uploads in WIP PR #111 and see what additional instructions we'll need to provide just to introduce users to how to get files into their browser to start working with.

I'll be sharing ideas for lesson design here as I go, so I look forward to feedback and suggestions as I go!