Folders are an independent layer above the brew system. They are collections of references/bookmarks providing alternative views into the existing brew space; they do not move, copy, modify, or otherwise alter brews.

Previously on Github..

The chat about folders has brought up many questions and doubts about how to approach the project

here lies a list of related issues that may contain related info, for the purpose of completeness, i will be including all important info from them as well.

clippings....

Why?

Folders have been suggested for years, as a way to organize work, de-clutter the userpage, and group related documents.

Minimum Viable Product (MVP)

As a project starter, a definition of a MVP has been set, that is a product with the minimum necessary features for it to work, and from which we can expand by adding little by little.

The MVP should include:

Features

"CRUD" features: create folders, delete folders, update name and contents, and be able to read the contents.

Author-specific

opening a link for a non-existant folder should trigger a 404
a brew should be able to be in multiple folders at once
no duplicate names for folders inside the same view
folder should appear in the brew title inside the share and edit pages("Examples: how to make tables")
folders should appear before any brew in the user page

A URI/link should be /user/:userId/:folder-slug or /user/:userId/:folder-slug/:folder-slug

Data Model

Folders exist as entities in their own table/collection.

Each folder is owned by one user, and it only appears in the context of their userpage. It may contain references to brews owned by any user. If the folder isPublished then the folder itself per se is visible on the owner's userpage by other users.

Multiple brews can be assigned to a folder by listing the brew.shareID in the folder entity. (This is distinct and different from a model where the association is achieved via an attribute on the brew entity).

Sub-folders are linked via a list of subfolderIds, in the same manner as how brews are linked. The folder graph should not be allowed to form cycles, even though folders may have multiple parents.

Minimal Data structure

__Id (mongo specific ID field, exists wether we create it or not)
folderId (nanoid, required, auto)
slug (to use in the URL) (string, required)
displayName (to display in the UI) (string, required)
owner
brewIds (list of shareId)
CreatedAt (auto)
UpdatedAt (auto)
isPublished (boolean, or later: published/unpublished/hidden)

More substantial data structure

These folders should be displayed in the user page of the author of such folder , opening the folder would bring the user to another page with the content of the folder displayed as if it was a user page.

So all unpublished files will still be invisible to unauthored accounts, even if they are inside a publicly viewable folder.

"Yes, so the "my campaign" folder can contain a published "magic ring" document that the players can see (because they have attained said ring) and also private "magic sword" document because players have not attained it."

Optimal Final Product

Features:

are private folders publicly viewable?

thumbnails
tags
~~view counts~~ (useless?)
description
brewCount - how many visible brews this folder contains (considering brew.isPublished)
put someone else's brews into your folder (e.g. faves, bookmarks, public resources)
folders can have subfolders of their own
move brews from folderA to folderB (a UI wrapper for "add to B, remove from A")
ability to hit a button to publish all brews inside
select multiple brews to file into a folder
folder password
select via a picker UI (not by typing strings, unless we support type-ahead magic)
smart and dumb folders - additional properties
plausible deniability if bad password or no password (give me access or give me death aka 404)

The brew metadata panel and folder picker UI should only show the folders belonging to that user, but also maintain back-end the other user's folder assignments. The associating link between brew and folder is not maintained within the brew itself, but in the folder entity.

We do want to facilitate sharing of folder views. That is, a user could share /user/erics/friday-game to his Friday Game participants; or share publicly /user/erics/monsters to the world.

Data structure

Add these to the minimal data structure (above)

description
tags
password (string, optional, hashed)
icon or image (uri-string, optional) (#240)
styling (css-text-block, optional) (#240, #1843) ??
background (uri-string or color-code-string, optional)
subFolderIds [list of nanoids]
pinnedBrewId - one brew of brewIds which appears at top of folder, regardless of sort order
folder type (smart/dumb) ?? -- or: absence of smart rules ⇒ dumb folder
smart-rules
~~authors~~ -- brews have author(s), but folders are owner-specific
~~view-count (integer, auto)~~ -- views are a in-browser experience only, no server hits involved, so no count to accumulate
~~brewCount~~ -- can/should be calculated on the fly though
~~folderCount~~ -- can/should be calculated on the fly though

Smart Folders?

Smart Folders are simply dumb folders with rules attached that show extra brews in the folder (shown, not added or moved).

They will be ordinary folders with rules layered on later, and their rules will operate only over the owner's brews, not the entire Homebrewery database.

Smart folders are well out of scope for MVP.

Problem: multiple authors

If we do go with the brew-in-many-folders idea, then reflecting "this brew is in these of your folders" could be informative. Searching by filter or tag on the userpage should also show locally top-level folders that contain matching brews at any depth. ("Now, where did I put that brew?!?")

Roadmap (needs review)

More detail:

MVP

create/delete folders on user page
give folder a title, and a slug
make folder navigable by URL e.g. /users/:author/:slug
navigate into folder by clicking, revealing visible contents
navigate out of folder, up one level
add/move brew to a folder on userpage (via picker UI)
- brew can be in multiple folders
designate folder for brew in metadata pane (via picker UI)
create/delete/rename folders via picker UI (prereq: picker UI)

Next Version after MVP

tags on brews (prereq: dumb flat folders)
descriptions on brews
folder properties editor (title, slug, description, tags, published, etc)
nested folders (prereq: folder.subfolderIds structure, not folder.parentID))
update picker UI for nested folders (prereq: nested folders)

Later Versions

use folders for Favouriting brews, including other authors
use folders for Bookmarking brews, including other authors

Far Horizon Version

smart folders

UI scratchings

Things free with every browser:

folder path visible in window.location for folder views

Things that will need to be visually designed, and also programatically implemented:

folders appearing as tiles on userpage
folder path appearing on folder-tiles on userpage
current folder name/path as a subtitle on userpage
button on userpage/view for initiating creation of a folder
dialog for creating a folder (name, path, etc)
dialog for defining "smart rules" for a smart folder
button widget on brew/folder tile for adding/moving that brew/folder to a folder (or removing)
button widget on folder view for adding/moving that brew/folder to a folder (or removing)
button on userpage for starting a process of selecting many brews/folders for adding/moving to a folder
button on /shared/:id page to facilitate saving that particular brew to a folder (i.e to support bookmarking)
dialog for selecting a folder for the process of adding/moving a brew/folder
- should include option for initiating create-a-folder process
- should include options for Cancel (i.e. do nothing) but also "Remove from Folder"

Folder Tiles

How a folder might appear in the userpage:

Notes:

the folder slug is displayed, and is also a link to the folder
a count of visible brews within that folder (not counting subfolders)
a count of immediate subfolders (not counting deeper)
no date created/updated metadata (likely won't be the dates that users expect, e.g. date of most recently edited brew)

Add Brew to Folder

On each brew tile, there would be a button to add that brew to another folder.

Clicking that button would pop an overlay dialog for navigating a tree of your folders — the design for that is not finessed yet.

Remove Brew from Folder

We'd also have a button for removing that brew from the current folder.

If the current view is of a folder, and this is the only place that brew is placed, then clicking that will cause that brew to re-appear on your top-level /user/yourname view (because no folder was found in which it was filed).
If the current view is of a folder, and that brew is in other places also, then clicking that will simply remove the brew from that folder.
If the current view is of the top-level, and it's not also filed anywhere else, that folder-minus button would be disabled.

Appendix A

Old content about publishing has been moved to https://github.com/naturalcrit/homebrewery/wiki/Published---public---hidden-brews

related issues and discussions