Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updated _posts/modules/0100-01-01-document.md #7

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Updated _posts/modules/0100-01-01-document.md #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 8 additions & 7 deletions _posts/modules/0100-01-01-document.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,16 +18,17 @@ categories:
- modules
published: true
---
The [Substance Document Model](https://github.com/substance/document/blob/master/document.js) (a work in progress) aims to be a quasi-standard for representing arbitrary digital documents. It doesn't make any assumptions on a concrete type or structure. Instead it is supposed to be a foundation to create your own document model on top of it, tailored to your particular use-case. A Substance document model can range from loosly structured documents involving sections and text, such as reports or articles to things that you wouldn't consider a document anymore but in fact are. Let's take the mess of filling out forms as an example. The reason why we are still filling them out by hand and manually transfer them into a database system is simply the lack of suitable generic document representations and form composition tools. In many cases we are dealing with a mixture of structured and unstructured parts. There might be a disclaimer, which is not editable in conjunction with a person's contact info plus a list of purchased items. Most of today's web-based forms are created on a tight budget. As a result they not only look ugly, they are also incredibly error-prone. After carefully filling out that one important form for half an hour and submitting it, you're usually rewarded with a message that says something like this:

The [Substance Document Model](https://github.com/substance/document/blob/master/document.js) (a work in progress) aims to be a quasi-standard for representing arbitrary digital documents. It doesn't make any assumptions on a concrete type or structure. Instead it is supposed to be a foundation to create your own document model on top of it, tailored to your particular use-case. A Substance document model can range from loosely structured documents involving sections and text, such as reports or articles to things that you wouldn't consider a document anymore but in fact are. Let's take the mess of filling out forms as an example. The reason why we are still filling them out by hand and manually transfer them into a database system is simply the lack of suitable generic document representations and form composition tools. In many cases we are dealing with a mixture of structured and unstructured parts. There might be a disclaimer, which is not editable in conjunction with a person's contact info plus a list of purchased items. Most of today's web-based forms are created on a tight budget. As a result they not only look ugly, they are also incredibly error-prone. After carefully filling out that one important form for half an hour and submitting it, you're usually rewarded with a message that says something like this:

> Sorry your session has been expired. Or in other words, you were to slow. But no worries, if you click here you can safely fill it out again. From scratch of course.

Or does that just happen to me? :) Okay, it's not always that bad. But the only systems that are fun to use, are at the same time the most simple ones. I'd consider Twitter as such an example. Too bad the world's knowledge can't be represented within 140 characters plain-text. So we need to deal with a (manageable) amount of complexity. The Substance Stack helps you with that. And much more. And we take this mission very seriously.
Or does that just happen to me? :) Okay, it's not always that bad. But the only systems that are fun to use, are at the same time the most simple ones. I'd consider Twitter as such an example. Too bad the world knowledge can't be represented within 140 characters plain-text. So we need to deal with a (manageable) amount of complexity. The Substance Stack helps you with that. And much more. And we take this mission very seriously.

We're not giving you a solution for your particular problem. But we provide you a simple framework you can use to define a document model, plus a [building block](http://github.com/substance/composer) to create your own editor for manipulating those documents.


A Substance Document consists of a list of a content nodes that are linked together. Each node points to its successor and predecssor nodes. Nesting is not supported, for good reason.
A Substance Document consists of a list of a content nodes that are linked together. Each node points to its successor and predecessor nodes. Nesting is not supported, for good reason.

A concrete instance of a Substance document could look like so:

Expand Down Expand Up @@ -155,7 +156,7 @@ Your picturegallery editor could look like this. If you're using the Substance C

![Picturegallery Editor](http://f.cl.ly/items/3W3a2g38212C1M1m1z0z/Screen%20Shot%202012-05-25%20at%205.34.42%20PM.png)

Instead of creating a propriatory data representation format and database model (there might be millions of picturegallery variations around) you just transform the Picturegallery document using commands.
Instead of creating a proprietary data representation format and database model (there might be millions of picturegallery variations around) you just transform the Picturegallery document using commands.

For inserting a new picture a command would look like so:

Expand All @@ -175,7 +176,7 @@ For inserting a new picture a command would look like so:
}


If you were to change to title of the gallery, an update command should do it.
If you were to change the title of the gallery, an update command should do it:


{
Expand All @@ -190,7 +191,7 @@ If you were to change to title of the gallery, an update command should do it.
}
}

All of this can take place in the browser. At the end of the day you have a document that just contains the information you need. Store it whereever you want. Load it whenever you need it. And do further transformations. In fact this is not so much different from what you're used to do, except it unifies the process and separates tasks such as modelling the data and manipulating it (using commands).
All of this can take place in the browser. At the end of the day you have a document that just contains the information you need. Store it wherever you want. Load it whenever you need it. And do further transformations. In fact this is not so much different from what you're used to do, except it unifies the process and separates tasks such as modelling the data and manipulating it (using commands).


## Micropage
Expand Down Expand Up @@ -259,4 +260,4 @@ Instead of manually updating the center coordinates + zoom level, why not just r

![Microsite WYSIWYG Editor](http://f.cl.ly/items/1l0P36230Y3b0n0v1042/micropage-wysiwyg-editor.png)

However, these are just rough sketches for the purpose of illustrating what can be done with the Substance Document Model.
However, these are just rough sketches for the purpose of illustrating what can be done with the Substance Document Model.