adobe-webplatform
Missing documentation for library's Nouns
The nouns (or concepts) of Snap, like Element, Fragment, Paper, etc. are not defined in the documentation at doc/reference.html.
First, this leads to many dead anchor links within the doc page. But more importantly, it makes the documentation very hard to understand, especially for nouns which are not presented in the Getting Started page.
I agree 100%. I don't understand the difference between the following snippets
const s = Snap(100, 100);
s.rect(0, 0, 50, 50).attr({ fill: "red" });
const s = Snap(100, 100);
s.paper.rect(0, 0, 50, 50).attr({ fill: "red" });
They seem to do the same thing. What is paper for? The Docs don't seem to explain this.
My first question would probably be, why do you need to know what s.paper is ? I don't think I've ever known anyone use that, so I'm just pondering if you are trying to do something strange.
Anyway, to try and help folk with this question, I tend to think of the analogy of graph paper.
Snap(x,y) will create an 'svg' element, which can be thought of as a piece of graph paper. On top, or inside that paper, you can place other elements, like rects, circles etc, or indeed, other 'svg' elements (so like a graph paper on a graph paper.
So sometimes when you are looking at a shape or object, you may want to know the paper you are on, so you can do something with it, change its style, or find out its size for example.
The oddity in the example provided, is that you are asking for the paper (s.paper) of the paper (s). I'm assuming it will be itself (the main paper, graph paper, or svg element or whichever way you want to think about it) in this case.
Just to add some bits for the original post about nouns....
Paper: the SVG element which can contain other elements like rects. You can have nested SVG elements (nested graph papers).
Element: this is any svg element like a rect, circle, svg, group etc.
Fragment: this is a little more complex, depending on your understanding of the DOM. SVG is an XML language. Browsers take that markup and convert it to big tree structure called the DOM, like a big state object of the document you are looking at. When you look at this writing, it's on a page full have HTML etc that's been converted into the DOM tree structure, which is then rendered.
A fragment, is a piece of this tree structure or a partial DOM object, that isn't actually in the main document. So it's won't display. I think of it like a temporary storage for a piece of a page. We can do what we want with it, and it won't affect anything displayed. Then at some point later, we can add this fragment into the main document, and it will be displayed.
Some of those analogies or descriptions aren't perfect, but just trying to help for anyone reading to help with the concepts.
That's probably enough for now, but just in case someone had looked at the plugins you may see...
Snap.plugin(function (Snap, Element, Paper, global, Fragment) { ...}
It's important to note that Snap/Element/Paper/global/Fragments here in the plugin, with the capital letters are the objects/methods for adding to. Let's suppose you wanted to create a method element.bounce that would make any element bounce for 10 secs, within the plugin you would use something like the following, inside the Snap.plugin code.
Element.prototype.bounce = function() { <bouncecode using 'this'> }
or to create a hexagon method, so you can add a hexagon to the paper, you would do something like...
Paper.prototype.hexagon = function() { <createahexagonoutofpathsorsomething adding to 'this'> }
My first question would probably be, why do you need to know what s.paper is ?
It's mentioned 95 times on the documentation page. I figured it's important. But there is no explanation of why it exists.
I think you just mean paper, not s.paper ? I can't see any mention of s.paper on the docs page.
On Mon, Dec 17, 2018 at 10:44 PM Jesse Gavin [email protected] wrote:
My first question would probably be, why do you need to know what s.paper is ?
It's mentioned 95 times on the documentation page. I figured it's important. But there is no explanation of why it exists.
— You are receiving this because you commented. Reply to this email directly, view it on GitHub https://github.com/adobe-webplatform/Snap.svg/issues/518#issuecomment-448027306, or mute the thread https://github.com/notifications/unsubscribe-auth/ADuG9Z9g7yc3RHXp6XngdMcTCvlKua5Oks5u6B4_gaJpZM4MTWrt .