5 ms·

Show HN: Marginotes, quick and elegant side notes for your paragraphs

111 points by Stately 11y ago

anacleto 11y ago
Pretty. Thanks.
gberger 11y ago
http://youmightnotneedjquery.com/ http://youmightnotneedjquery.com/
- plugnburn 11y ago
  I second this. JQuery must die.
- have_faith 11y ago
  What do you consider a reasonable reason to build something as a jQuery plugin as opposed to pure-js? or do you believe jQuery plugins are redundant by default? Just interested.
  - jakejake 11y ago
    I personally find it odd to create every component as a jquery plugin. To me, it makes more sense to write a plugin only when you're extending jquery core functionality itself in some way. As far as "extending" goes though, it's not always clear. Is a date picker extending jquery's core? I personally think not, but there has evolved an expectation that every web component must be initialized like so: $('#container').doSomething(); So I suppose a lot of people do it that way just to have a familiar look to their API, or even just to show up in listing as a jquery plugin.
    - bobm_kite9 11y ago
      Basically, this function is just an onMouseOver event, which then inspects the element and displays text from the "desc" tab in the right place. I've been thinking for a while that it would be nice if we could add events to the CSS syntax, something like: a[desc] { onMouseOver: asideFunction(); } I _kind_ of worry that this is subverting the purpose of the css, but since it also handles hover and selected behaviour, it seems like the line isn't well-drawn anyway as to where styling ends and where behaviour begins. What do other people think?
      - codingdave 11y ago
        I think that would be mixing presentation with functionality in a way that would become a maintenance nightmare.
- zelcon5 11y ago
  Yes, this would have been awesome without the jQuery dependency. I don't think Javascript libraries should introduce ANY dependencies, because you are limiting the audience to codebases that already include said dependency. (No one will introduce a huge dependency like jQuery for just ONE library.)
kozak 11y ago
Very nice. It would be even better if it had some CSS media query-based fallbacks for the case when the page is being printed. And yes, jQuery should not be a requirement.
lolc 11y ago
Looks nice! I was a little surprised at the last line in your code: window.jQuery.prototype.marginotes = window.$.prototype.marginotes = marginotes Last I checked (one minute ago) jQuery and $ refer to the same object. jQuery === $ unless somebody is using $ to refer to something else in which case thanks you just clobbered $'s prototype. You should follow the jQuery conventions https://learn.jquery.com/plugins/basic-plugin-creation/ https://learn.jquery.com/plugins/basic-plugin-creation/
gkya 11y ago
What happens if I have JavaScript disabled (and I do have)?
- onion2k 11y ago
 You don't see anything.
 - gkya 11y ago
 Which is bad if them notes are not ornaments only. So there should be some fallback. I guess a good approach would be to collect the content from some p.marginnote elements which would be hidden if JS is present and left intact if not. So, like <a href='#' mnref='gcc'>GCC</a> ... The GNU Compiler Collection With JS, they'd become margin notes, whithout it, they'd render as plain footnotes.
 - onion2k 11y ago
 Sure, but as the README.md states "adds notes to the margin with the text provided in HTML attributes" it's presumably left up to the user how else they display the data if they want it to be visible for people who disable JS. This library is a progressive enhancement. It's very much the right way to do web dev in my opinion.
 - NoGravitas 11y ago
 It's almost the right way -- somewhat better would be to do what one of the above comments say, to add the notes as footnotes using POSH. Then the javascript can rewrite the footnotes into hide/show marginal notes with the same appearance and user interface as this library.
 - geocar 11y ago
 Why not just: <a href="#fn-gcc" class="has-footnote">GCC[1]</a> … <label>1. </label>The GNU Compiler Collection It's compatible with the W3C recommended idiom for footnotes[2], is accessible without JavaScript, and you can still use `.marginnote` to provide CSS styling. [2]: https://www.w3.org/TR/html5/common-idioms.html#footnotes https://www.w3.org/TR/html5/common-idioms.html#footnotes
tauchunfall 11y ago
Mouse-over actions are nice on desktop. But what happens if I use a touch device?
- Mahn 11y ago
  Tap to show, tap to hide? Not quite the same, but that's how I'd do the fallback for mouse hover effects.
Chris_Newton 11y ago
Notes on web pages are tricky because there are so many edge cases, and they tend to expose the limitations of our current HTML+CSS model. For example, we can achieve an effect similar to the one shown here using just CSS (no JS) if we’re able to use position:relative on the containing paragraph without breaking anything else in the styling: HTML: This is some text with a marginal note. Lorem ipsum dolor sit amet... CSS: .note-container { position: relative; width: 400px; } .note { text-decoration: underline; } .note:hover::after { content: attr(desc); position: absolute; top: 0; left: 440px; width: 150px; height: 100%; border-left: 1px solid black; padding-left: 9px; } I put a quick demo of this one here: https://jsfiddle.net/2ejk2who/ https://jsfiddle.net/2ejk2who/ However, what happens if we need to work with touch-only devices, where hover effects aren’t available? Two options would be to show the notes all the time, or to embed a hidden checkbox and make the anchor text its label. In the latter case, tapping on the text could then toggle whether the marginal note appears if we used something based on :checked instead of :hover. But now what if more than one note is set to visible at once? We can’t combine the position:absolute technique to get neat alignment at the top of the paragraph with using floats so multiple notes automatically fall under one another. I don’t have a good pure-CSS answer for this one. In any case, on a smaller screen we might not want to show marginal notes alongside the main text anyway. It would be helpful if there were a way to have the notes drop underneath the paragraph and stack up, but again, we can’t combine the kind of absolute positioning that would place a note there with something that extends the paragraph’s box so later content moves down after any visible notes. Perhaps one day we’ll have more flexible options for generated content and CSS positioning that will let us do these things, but for now the only ways I know to achieve some of these effects still rely on JS.
joeclark77 11y ago
This is excellent. I've been thinking about rolling my own blog software since Medium took away their marginal note feature (IIRC, you can now make notes but they're for yourself only, readers can't see them). Since reading Ed Tufte's books, I'm convinced that margin notes are infinitely better than footnotes or (egad) endnotes for sharing little "extras" with your readers.
mshenfield 11y ago
I made a little experiment, and converted this to a vanilla Javascript library. Relevant to some of the questions below about whether this should use jQuery or not. Edit: There were two gotchas beyond browser compatibility. jQuery provides a consistent interface to set numeric style values - in vanilla Javascript you have to remember to turn these numbers into strings suffixed with "px". And I hacked together the code that stops fadein and fadeout from stepping on each other. Changes: https://github.com/fdansv/marginotes/pull/2 https://github.com/fdansv/marginotes/pull/2 Working Example: http://mshenfield.github.io/fdansv.github.io/ http://mshenfield.github.io/fdansv.github.io/
- cornstalks 11y ago
  Looks like you've got a bug when the mouse passes over a link that has no sidenote. To reproduce: 1. Hover over a link with a sidenote (i.e. "Bill Gates"). 2. Hover over a link without a sidenote (i.e. "unrecognised"). 3. Move your mouse off of the link. During step 3 the previous sidenote will briefly appear. (I'm running Chrome 48.0.2564.116 on OS X 10.11.3 if that matters)
  - mshenfield 11y ago
    Nice catch! My fadeout function mistakenly set the opacity to 1 to start off. Fixed.
DenisAyumu 11y ago
Last time I checked you couldn't add HTML properties that don't exist. It's not valid HTML code. The exception are "data-*" properties. So the HTML markup should be whatever.

111 points by Stately 11y ago

anacleto 11y ago

Pretty. Thanks.

gberger 11y ago

http://youmightnotneedjquery.com/ http://youmightnotneedjquery.com/

plugnburn 11y ago
I second this. JQuery must die.
have_faith 11y ago
What do you consider a reasonable reason to build something as a jQuery plugin as opposed to pure-js? or do you believe jQuery plugins are redundant by default? Just interested.
- jakejake 11y ago
  I personally find it odd to create every component as a jquery plugin. To me, it makes more sense to write a plugin only when you're extending jquery core functionality itself in some way. As far as "extending" goes though, it's not always clear. Is a date picker extending jquery's core? I personally think not, but there has evolved an expectation that every web component must be initialized like so: $('#container').doSomething(); So I suppose a lot of people do it that way just to have a familiar look to their API, or even just to show up in listing as a jquery plugin.
  - bobm_kite9 11y ago
    Basically, this function is just an onMouseOver event, which then inspects the element and displays text from the "desc" tab in the right place. I've been thinking for a while that it would be nice if we could add events to the CSS syntax, something like: a[desc] { onMouseOver: asideFunction(); } I _kind_ of worry that this is subverting the purpose of the css, but since it also handles hover and selected behaviour, it seems like the line isn't well-drawn anyway as to where styling ends and where behaviour begins. What do other people think?
    - codingdave 11y ago
      I think that would be mixing presentation with functionality in a way that would become a maintenance nightmare.
zelcon5 11y ago
Yes, this would have been awesome without the jQuery dependency. I don't think Javascript libraries should introduce ANY dependencies, because you are limiting the audience to codebases that already include said dependency. (No one will introduce a huge dependency like jQuery for just ONE library.)

kozak 11y ago

Very nice. It would be even better if it had some CSS media query-based fallbacks for the case when the page is being printed. And yes, jQuery should not be a requirement.

lolc 11y ago

Looks nice! I was a little surprised at the last line in your code: window.jQuery.prototype.marginotes = window.$.prototype.marginotes = marginotes Last I checked (one minute ago) jQuery and $ refer to the same object. jQuery === $ unless somebody is using $ to refer to something else in which case thanks you just clobbered $'s prototype. You should follow the jQuery conventions https://learn.jquery.com/plugins/basic-plugin-creation/ https://learn.jquery.com/plugins/basic-plugin-creation/

gkya 11y ago

What happens if I have JavaScript disabled (and I do have)?

onion2k 11y ago
You don't see anything.
- gkya 11y ago
 Which is bad if them notes are not ornaments only. So there should be some fallback. I guess a good approach would be to collect the content from some p.marginnote elements which would be hidden if JS is present and left intact if not. So, like <a href='#' mnref='gcc'>GCC</a> ... The GNU Compiler Collection With JS, they'd become margin notes, whithout it, they'd render as plain footnotes.
 - onion2k 11y ago
 Sure, but as the README.md states "adds notes to the margin with the text provided in HTML attributes" it's presumably left up to the user how else they display the data if they want it to be visible for people who disable JS. This library is a progressive enhancement. It's very much the right way to do web dev in my opinion.
 - NoGravitas 11y ago
 It's almost the right way -- somewhat better would be to do what one of the above comments say, to add the notes as footnotes using POSH. Then the javascript can rewrite the footnotes into hide/show marginal notes with the same appearance and user interface as this library.
 - geocar 11y ago
 Why not just: <a href="#fn-gcc" class="has-footnote">GCC[1]</a> … <label>1. </label>The GNU Compiler Collection It's compatible with the W3C recommended idiom for footnotes[2], is accessible without JavaScript, and you can still use `.marginnote` to provide CSS styling. [2]: https://www.w3.org/TR/html5/common-idioms.html#footnotes https://www.w3.org/TR/html5/common-idioms.html#footnotes

tauchunfall 11y ago

Mouse-over actions are nice on desktop. But what happens if I use a touch device?

Mahn 11y ago
Tap to show, tap to hide? Not quite the same, but that's how I'd do the fallback for mouse hover effects.

Chris_Newton 11y ago

Notes on web pages are tricky because there are so many edge cases, and they tend to expose the limitations of our current HTML+CSS model. For example, we can achieve an effect similar to the one shown here using just CSS (no JS) if we’re able to use position:relative on the containing paragraph without breaking anything else in the styling: HTML: This is some text with a marginal note. Lorem ipsum dolor sit amet... CSS: .note-container { position: relative; width: 400px; } .note { text-decoration: underline; } .note:hover::after { content: attr(desc); position: absolute; top: 0; left: 440px; width: 150px; height: 100%; border-left: 1px solid black; padding-left: 9px; } I put a quick demo of this one here: https://jsfiddle.net/2ejk2who/ https://jsfiddle.net/2ejk2who/ However, what happens if we need to work with touch-only devices, where hover effects aren’t available? Two options would be to show the notes all the time, or to embed a hidden checkbox and make the anchor text its label. In the latter case, tapping on the text could then toggle whether the marginal note appears if we used something based on :checked instead of :hover. But now what if more than one note is set to visible at once? We can’t combine the position:absolute technique to get neat alignment at the top of the paragraph with using floats so multiple notes automatically fall under one another. I don’t have a good pure-CSS answer for this one. In any case, on a smaller screen we might not want to show marginal notes alongside the main text anyway. It would be helpful if there were a way to have the notes drop underneath the paragraph and stack up, but again, we can’t combine the kind of absolute positioning that would place a note there with something that extends the paragraph’s box so later content moves down after any visible notes. Perhaps one day we’ll have more flexible options for generated content and CSS positioning that will let us do these things, but for now the only ways I know to achieve some of these effects still rely on JS.

joeclark77 11y ago

This is excellent. I've been thinking about rolling my own blog software since Medium took away their marginal note feature (IIRC, you can now make notes but they're for yourself only, readers can't see them). Since reading Ed Tufte's books, I'm convinced that margin notes are infinitely better than footnotes or (egad) endnotes for sharing little "extras" with your readers.

mshenfield 11y ago

I made a little experiment, and converted this to a vanilla Javascript library. Relevant to some of the questions below about whether this should use jQuery or not. Edit: There were two gotchas beyond browser compatibility. jQuery provides a consistent interface to set numeric style values - in vanilla Javascript you have to remember to turn these numbers into strings suffixed with "px". And I hacked together the code that stops fadein and fadeout from stepping on each other. Changes: https://github.com/fdansv/marginotes/pull/2 https://github.com/fdansv/marginotes/pull/2 Working Example: http://mshenfield.github.io/fdansv.github.io/ http://mshenfield.github.io/fdansv.github.io/

cornstalks 11y ago
Looks like you've got a bug when the mouse passes over a link that has no sidenote. To reproduce: 1. Hover over a link with a sidenote (i.e. "Bill Gates"). 2. Hover over a link without a sidenote (i.e. "unrecognised"). 3. Move your mouse off of the link. During step 3 the previous sidenote will briefly appear. (I'm running Chrome 48.0.2564.116 on OS X 10.11.3 if that matters)
- mshenfield 11y ago
  Nice catch! My fadeout function mistakenly set the opacity to 1 to start off. Fixed.

DenisAyumu 11y ago

Last time I checked you couldn't add HTML properties that don't exist. It's not valid HTML code. The exception are "data-*" properties. So the HTML markup should be whatever.