mirror of
https://github.com/Jermolene/TiddlyWiki5
synced 2024-08-30 13:02:53 +00:00
106 lines
5.9 KiB
Plaintext
106 lines
5.9 KiB
Plaintext
title: $:/plugins/tiddlywiki/dynaview/docs
|
|
|
|
! Documentation
|
|
|
|
The components of this plugin include:
|
|
|
|
* A background task that:
|
|
** performs specified actions when elements are scrolled into view
|
|
** updates certain base classes on the `document.body` according to the current zoom level
|
|
** if enabled in the DynaView config panel - dynamically stores the viewport dimensions in $:/state/viewport/width and $:/state/viewport/height
|
|
* Pre-configured CSS classes to simplify using those base classes
|
|
* Usage examples
|
|
|
|
! Scroll Features
|
|
|
|
!! Scroll position preservation during refresh
|
|
|
|
Some recent browsers have a feature called "scroll anchoring" whereby they suppress the apparent scrolling that occurs when elements are inserted or removed above the current viewport. (See https://github.com/WICG/ScrollAnchoring for more details).
|
|
|
|
~DynaView can optionally polyfill this behaviour for older browsers by setting the configuration tiddler $:/config/DynaView/PreserveScrollPosition to `yes`.
|
|
|
|
!! Startup scroll position restoration
|
|
|
|
Optionally, ~DynaView can store the current scroll position in local storage and restore it upon startup. Set the configuration tiddler $:/config/DynaView/RestoreScrollPositionAtStartup to `yes`.
|
|
|
|
Note that it is not recommended to use this setting at the same time as the "UpdateAddressBar" option.
|
|
|
|
!! Visibility tracking
|
|
|
|
The background task detects when elements with the class `tc-dynaview-track-tiddler-when-visible` scroll in and out of view. It tracks four different states:
|
|
|
|
* ''Blank/missing'' -- The element has not yet been scrolled into view
|
|
* ''0'' -- The element has been scrolled into view, but subsequently scrolled out of view
|
|
* ''1'' -- The element is near the viewport
|
|
* ''2'' -- The element is partially or wholly within the viewport
|
|
|
|
The processing applied to each element is as follows:
|
|
|
|
* If the element is partially or wholly within the viewport then set the state to "2"
|
|
* If the element is near the viewport then set the state to "1"
|
|
* If the element is fully outside the viewport then only set the state to "0" if it is currently unset (ie blank/missing)
|
|
|
|
Attributes on the tracked element specify the following parameters:
|
|
|
|
* ''data-dynaview-track-tiddler'' -- specifies the tiddler in which the element tracking state will be stored
|
|
|
|
!! Update address bar when scrolling
|
|
|
|
If the configuration tiddler $:/config/DynaView/UpdateAddressBar is set to `yes` the background task detects the tiddler at the top of the viewport and sets the address bar location hash to the title of that tiddler.
|
|
|
|
Note that it is not recommended to use this setting at the same time as the "RestoreScrollPositionAtStartup" option.
|
|
|
|
! Viewport Size Features
|
|
|
|
!! Resize Tracking
|
|
|
|
Some widgets require re-rendering or refreshing if the size of the viewport changes. This can be accomplished using "resize counting" in two steps:
|
|
|
|
* Ensure that a DOM element with the class `tc-dynaview-request-refresh-on-resize` is present in the DOM to enable resize counting
|
|
* Have the widget check for changes to the tiddler $:/state/DynaView/ViewportDimensions/ResizeCount to detect viewport resizes
|
|
|
|
!! Viewport Size Tracking
|
|
|
|
The background task can optionally dynamically update a pair of state tiddlers with the dimensions of the browser viewport.
|
|
|
|
* Set the configuration tiddler $:/config/DynaView/ViewportDimensions to the text "yes" to enable this feature
|
|
* The viewport dimensions can be found in $:/state/DynaView/ViewportDimensions/Width and $:/state/DynaView/ViewportDimensions/Height
|
|
|
|
! Zoom Features
|
|
|
|
!! Document Body Zoom Classes
|
|
|
|
The background task sets the following classes on `document.body` according to the current zoom level.
|
|
|
|
|!Class |!Description |
|
|
|`tc-dynaview-zoom-factor-1` |Set when the zoom level is less than 2.00 |
|
|
|`tc-dynaview-zoom-factor-2` |Set when the zoom level is greater than 2.00 and less than 3.00 |
|
|
|`tc-dynaview-zoom-factor-3` |Set when the zoom level is greater than 3.00 and less than 4.00 |
|
|
|`tc-dynaview-zoom-factor-4` |Set when the zoom level is greater than 4.00 |
|
|
|`tc-dynaview-zoom-factor-1-and-above` |Set when the zoom level is greater than or equal to 1.00 |
|
|
|`tc-dynaview-zoom-factor-1a-and-above` |Set when the zoom level is greater than or equal to 1.14 |
|
|
|`tc-dynaview-zoom-factor-1b-and-above` |Set when the zoom level is greater than or equal to 1.33 |
|
|
|`tc-dynaview-zoom-factor-1c-and-above` |Set when the zoom level is greater than or equal to 1.60 |
|
|
|`tc-dynaview-zoom-factor-2-and-above` |Set when the zoom level is greater than or equal to 2.00 |
|
|
|`tc-dynaview-zoom-factor-2a-and-above` |Set when the zoom level is greater than or equal to 2.66 |
|
|
|`tc-dynaview-zoom-factor-3-and-above` |Set when the zoom level is greater than or equal to 3.00 |
|
|
|`tc-dynaview-zoom-factor-4-and-above` |Set when the zoom level is greater than or equal to 4.00 |
|
|
|
|
!! Pre-configured Classes
|
|
|
|
These classes can be used on any element to control its visibility at different zoom levels.
|
|
|
|
|!Class |!Description |
|
|
|`tc-dynaview-zoom-visible-1-and-above` |Visible when the zoom level is 1.00 or more |
|
|
|`tc-dynaview-zoom-visible-1a-and-above` |Visible when the zoom level is 1.14 or more |
|
|
|`tc-dynaview-zoom-visible-1b-and-above` |Visible when the zoom level is 1.33 or more |
|
|
|`tc-dynaview-zoom-visible-1c-and-above` |Visible when the zoom level is 1.60 or more |
|
|
|`tc-dynaview-zoom-visible-2-and-above` |Visible when the zoom level is 2.00 or more |
|
|
|`tc-dynaview-zoom-visible-2a-and-above` |Visible when the zoom level is 2.66 or more |
|
|
|`tc-dynaview-zoom-visible-3-and-above` |Visible when the zoom level is 3.00 or more |
|
|
|`tc-dynaview-zoom-visible-4-and-above` |Visible when the zoom level is 4.00 or more |
|
|
|`tc-dynaview-zoom-visible-1` |Visible when the zoom level is less than 2.00 |
|
|
|`tc-dynaview-zoom-visible-2` |Visible when the zoom level is greater than or equal to 2.00 and less than 3.00 |
|
|
|`tc-dynaview-zoom-visible-3` |Visible when the zoom level is greater than or equal to 3.00 and less than 4.00 |
|
|
|`tc-dynaview-zoom-visible-4` |Visible when the zoom level is greater than or equal to 4.00 |
|