hsablonniere
commented
8 years ago Configuration
The bespoke-bullets plugin works by specifying a CSS selector to define elements (bullets) that should appear progressively. If not specified, selector defaults to [data-bespoke-bullet].
In DZSlides, authors cannot modify the selector that targets steps elements. It uses the .incremental class and it must be set on the parent container. It will make the direct children appear one by one. We should keep the bespoke-bullets behaviour. Specifying items directly instead of parent provides wider possibilities and if authors really want direct children of something, they can always use this selector ul > *.
The default selector should be [data-bespoke-build].
This won't work for code samples where lines cannot be selected by CSS selectors. More on that later...
Classes and states
In DZSlides, it's a bit complicated to style a bullet/step. Authors need to specify stuff and override them with the ~ operator. We should keep the same simple classes from the bespoke-bullets plugin (with a little renaming) :
.bespoke-build: All build items.bespoke-build-active: All active build items.bespoke-build-inactive: All inactive build items.bespoke-build-highlight: The current build item
I think .bespoke-build-highlight conveys a better meaning than .bespoke-bullet-current, at least for code samples. We could have a way to define multiple elements as .bespoke-build-highlight.
Non linear build scenario for code samples?
The main idea of a non linear build scenario is to help progressive disclosure of code samples in an arbitrary way.
Something that would allow this :
Build 1/5 (first state) :
Build 2/5 :
var foo = function (bar) {
};Build 3/5 :
var foo = function (bar) {
if (bar) { // highlight
}
};Build 4/5 :
var foo = function (bar) {
if (bar) {
}
else { // highlight
}
};Build 5/5 :
var foo = function (bar) {
if (bar) {
console.log('yes'); // highlight
}
else {
console.log('no'); // highlight
}
};Scenarios description (propositions) :
Full description
The author needs to fully describe the state of each build :
`(nothing.active`)1;8(line 1 and 8.active)1;2;4;8(line 1, 2, 4 and 8.active)1;2;4;5;7;8(line 1, 2, 4, 5, 7 and 8.active)1-8(lines 1 to 8.active)
This does not provide a way to know which lines are currently highlighted. This could be computed from the previous build. We could set the lines that just changed state as "highlighted".
The full scenario would look like this :
<pre data-bespoke-build-line-scenario="|1;8|1;2;4;8|1;2;4;5;7;8|1-8">
<!-- ... -->
</pre>I think that spaces and line breaks should not matter. It can be a good rule :
<pre data-bespoke-build-line-scenario=" | 1;8 | 1;2;4;8 | 1;2;4;5;7;8 | 1-8"><pre data-bespoke-build-line-scenario=" | 1;8
| 1;2;4;8
| 1;2;4;5;7;8
| 1-8">Even if we enforce the use of AsciiDoc (and maybe Jade), direct HTML will be usable.
Full description (with current/highlight)
The author needs to fully describe the state of each build and also need to specify the highlighted lines :
`(nothing.active`)1;8(line 1 and 8.active)1;(2);4;8(line 1, 2, 4 and 8.active) (line 2.current)1;2;4;(5);7;8(line 1, 2, 4, 5, 7 and 8.active) (line 5.current)1-(3)-(6)-8(lines 1 to 8.active) (lines 3 and 6.current)
This solves the highlight ambiguity but it starts to get pretty verbose. I don't think it's really a problem since in general more than 20 lines of code on a screen tend to be unreadable from the back of the room.
<pre data-bespoke-build-line-scenario=" | 1;8 | 1;(2);4;8 | 1;2;4;(5);7;8 | 1-(3)-(6)-8">Accumulative description
Each build is based upon the previous one, a bit like a diff :
`(nothing.active`)+1;+8(line 1 and 8.active)+2;+4(line 1, 2, 4 and 8.active)+5;+7(line 1, 2, 4, 5, 7 and 8.active)+3;+6(lines 1 to 8.active)
Minus - would allow a reset to inactive state but it's also used for line intervals. There's also no simple way to describe what's not highlighted anymore.
It's a bit shorter to write but authors will need to think a bit before writing the scenario. The implementation will also need some computation to build scenario step #4 for example.
<pre data-bespoke-build-line-scenario=" | +1;+8 | +2;+4 | +4;+7 | +3;+6">
<!-- ... -->
</pre>Lines/groups split
The usage of data-bespoke-build-line-scenario attribute on a <pre> should split the code lines/groups in different HTML elements so they can be built as per the scenario.
Author should not need to specify any selector in the plugin config. By using data-bespoke-build-line-scenario, it's automatically registered. Is it a good idea?
Per character build?
Maybe we need some kind of per character grouping. This would be way easier to do directly in the code but my experience tells me it's not that maintainable and it won't be possible with code includes.
Something like this would highlight the 'yes' and then the 'no' :
<pre data-bespoke-build-line-scenario="1-8 | 1-3{0-(20-25)-27}-8 | 1-6{0-(20-24)-26}-8">
var foo = function (bar) {
if (bar) {
console.log('yes');
}
else {
console.log('no');
}
};
</pre>Be if we can highlight parts of a line, should we be able to display only one part of a line? How do I display this :
var foo = function (bar) {
if (bar) {
console.log( );
}
else {
console.log( );
}
};then this :
var foo = function (bar) {
if (bar) {
console.log('yes');
}
else {
console.log('no');
}
};Maybe like this :
<pre data-bespoke-build-line-scenario="1-8 | 1-3{0-20;25-27}-8 | 1-6{0-20;24-26}-8">Shortcuts
Should we need some shortcuts for first and last line and first and last character?
Maybe shorten this :
<pre data-bespoke-build-line-scenario="1-8 | 1-3{0-20;25-27}-8 | 1-6{0-20;24-26}-8">into this :
<pre data-bespoke-build-line-scenario="- | -3{-20;25-}- | -6{-20;24-}-">Maybe it's too far :trollface:?
Invisible vs. not displayed
How do we handle lines that should be display:none and lines that should be visibility:hidden? I we don't mix them in a given scenario, this could only be done by affecting those styles to .active and .inactive states.
Right now, bespokejs/bespoke-bullets answers a simple problem : making incremental bullet-points. This is too restrictive to handle code samples and maybe SVG graphs parts where some non-linear build is required.
NOTE: A non-linear build is a build (aka step or fragment) that does not follow the document order. (In other words, it's possible to show the last item, then the first item, then the middle item).
This plugin should address the following design limitations of bespokejs/bespoke-bullets :
<object>(requires navigating into the SVG DOM)What else?