add structbond docs

disberd · Aug 31, 2023 · 0e3153d · 0e3153d
1 parent 8da2d36
commit 0e3153d
Show file tree

Hide file tree

Showing 6 changed files with 156 additions and 6 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -18,6 +18,7 @@ makedocs(;
         "basic_widgets.md",
         "latex_equations.md",
         "toc.md",
+        "structbond.md",
     ],
 )
 

diff --git a/docs/src/latex_equations.md b/docs/src/latex_equations.md
@@ -23,6 +23,8 @@ If one wants the exploit equation referencing with automatic numbering update, t
 ```
 Open the [latex test notebook](https://github.com/disberd/PlutoExtras.jl/blob/master/test/notebooks/latex_equations.jl) to check this functionality in action!
 
+!!! note
+    The notebook must be run from the original folder (`test/notebooks`) within the `PlutoExtras` package folder to properly load the PlutoExtras package
 ## API
 ```@docs
 initialize_eqref

diff --git a/docs/src/structbond.md b/docs/src/structbond.md
@@ -3,4 +3,108 @@
 The StructBondModule submodule of PlutoExtras defines and exports functionality to easily create widgets for custom structure and combine multiple bonds together in a convenient floating side table.
 
 !!! note
-    The StructBondModule is currently not re-exported by PlutoExtras so it has to be explicitly used with `using PlutoExtras.StructBondModule`
+    The StructBondModule is currently not re-exported by PlutoExtras so it has to be explicitly used with `using PlutoExtras.StructBondModule`
+
+Open the [structbond test notebook static html](https://rawcdn.githack.com/disberd/PlutoExtras.jl/5b57bbb25276ff44cd79e93b72b8c504fd46a432/html_exports/test_bondstable.jl.html) to see the look of the widgets exported.\
+Or open the [related notebook](https://github.com/disberd/PlutoExtras.jl/blob/master/test/notebooks/structbondmodule.jl) directy in Pluto to check their functionality in action!
+!!! note
+    The notebook must be run from the original folder (`test/notebooks`) within the `PlutoExtras` package folder to properly load the PlutoExtras package
+
+## StructBond
+Generating automatic widgets for custom structs is quite straightforward with
+the aid of the [`@fielddata`](@ref) macro and the [`StructBond`](@ref) type.
+
+The `StructBond` structure wraps another structure and generates a widget that can be used together with `@bind` to obtain instances of a custom structure.
+In order to correctly display the widget, the description and widget associated to each field of the structure must be specified either.
+
+This can be done either using [`@fielddata`](@ref) as in the example video below or by using the separate [`@fieldbond`](@ref) and [`@fielddescription`](@ref) separately.
+
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264639467-ecda1c22-141a-4297-98d7-0667d2e8d5a4.mp4" type="video/mp4">
+</video>
+```
+
+## @NTBond
+Sometimes custom structs are not needed and it would be useful to just use the same nice bond structure of [`StructBond`](@ref) to simply create arbitrary NamedTuples. 
+
+This is possible with the convenience macro [`@NTBond`](@ref) which can be called as shown below to create a nice display for an interactive bond creating an arbitrary NamedTuple.
+
+The macro simply create a [`StructBond`](@ref) wrapping the desired NamedTuple type.
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264640510-c605d3af-77c8-4752-9b80-8bc85545d566.mp4" type="video/mp4">
+</video>
+```
+
+## @BondsList
+In some cases, one does not want to have a single bond wrapping either a Structure or a NamedTuple because single independent bonds are more convenient.
+
+[`@BondsList`](@ref) is a convenience macro to create an object of type [`BondsList`](@ref) which simply allow to add a description to separate bonds and group them all together in a table-like format equivalent to those of [`StructBond`](@ref).
+
+!!! note
+	Unlike [`StructBond`](@ref), a BondsList is already composed of bond created with [`@bind`](@ref) and it just groups them up with a description. The output of [`@BondsList`](@ref) is not supposed to be bound to a variable using [`@bind`](@ref).\
+	The bonds grouped in a BondsList still act and update independently from one another.
+
+See the example below for understanding the synthax. The header of a BondsList is shown in an orange background to easily differentiate it from [`StructBond`](@ref).
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264641605-7ab58c12-2c30-47c3-a93a-d64784c34a71.mp4" type="video/mp4">
+</video>
+```
+
+## Popout/popoutwrap
+The structures above can also be used nested within one another. To facilitate accessing nested structures, one can use the [`Popout`](@ref) type.
+
+In its simple form, you can give an instance of a StructBond, a bond wrapping a StructBond or a BondsList as input to Popout to create a table that is hidden behind a popup window.
+If an instance present, but you want a custom type for which you have defined custom bonds and descriptions with [`@fielddata`](@ref) to appear as popout, you can use the function `popoutwrap(TYPE)` to generate a small icon which hides a popup containing the [`StructBond`](@ref) of the provided type `TYPE`.
+
+The StructBond table appears on hover upon the icon, can be made fixed by clicking on the icon and can then be moved around or resized.
+A double click on the header of the popout hides it again:
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264643126-cdf19078-70cb-46e2-aeb0-304a05ecf08a.mp4" type="video/mp4">
+</video>
+```
+
+The ability to also wrap pre-existing bonds around StructBonds is convenient for organizing the various bonds one have in a [`BondsList`](@ref) or [`BondTable`](@ref)
+
+As an example, one can create a [`BondsList`](@ref) containing the two [`StructBond`](@ref) bonds generated at the beginning of this notebook (the videos in the [structbond section above](#StructBond)) like in the following example:
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264645841-263f0cb3-ac79-4fe2-b66a-f8d5a4a70896.mp4" type="video/mp4">
+</video>
+```
+
+## BondTable
+The final convenience structure provided by this module is the [`BondTable`](@ref). It can be created to group a list of bonds in a floating table that stays on the left side of the notebook (similar to the TableOfContents of PlutoUI) and can be moved around and resized or hidden for convenience.
+
+The BondTable is intended to be used either with bonds containing [`StructBond`](@ref) or with [`BondsList`](@ref). Future types with similar structure will also be added.
+
+Here is an example of a bondtable containing all the examples seen so far.
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264646632-8c1b3eed-1adf-434b-925a-d57b99fc3c29.mp4" type="video/mp4">
+</video>
+```
+
+## API
+
+### Main
+```@docs
+StructBondModule.StructBond
+StructBondModule.@fielddata
+StructBondModule.@NTBond
+StructBondModule.@BondsList
+StructBondModule.popoutwrap
+StructBondModule.BondTable
+```
+
+### Secondary/Advanced
+```@docs
+StructBondModule.@fieldbond
+StructBondModule.@fielddescription
+StructBondModule.Popout
+StructBondModule.@popoutasfield
+StructBondModule.@typeasfield
+```
diff --git a/docs/src/toc.md b/docs/src/toc.md
@@ -34,6 +34,10 @@ The `ExtendedTableOfContents` allow to re-order the cell groups identified by ea
   - Holding shift during the dragging process allows to put headings before/after any other heading regardless of the level
 
 ## Examples
+Open the [extended ToC test notebook](https://github.com/disberd/PlutoExtras.jl/blob/master/test/notebooks/extended_toc.jl) to check this functionality in action!
+!!! note
+    The notebook must be run from the original folder (`test/notebooks`) within the `PlutoExtras` package folder to properly load the PlutoExtras package
+
 ### State Manipulation
 ![State_Manipulation](https://user-images.githubusercontent.com/12846528/217245898-5166682d-b41d-4f1e-b71b-4d7f69c8f192.gif)
 

diff --git a/html_exports/test_bondstable.jl.html b/html_exports/test_bondstable.jl.html
diff --git a/test/notebooks/structbondmodule.jl b/test/notebooks/structbondmodule.jl
@@ -37,6 +37,15 @@ md"""
 # ╔═╡ 707175a9-d356-43cf-8038-620ebc401c93
 ExtendedTableOfContents()
 
+# ╔═╡ cbfc6eec-8991-4a9c-ada0-295c8052854d
+# html"""
+# <style>
+# main {
+# 	margin-right: 350px !important;
+# }
+# </style>
+# """
+
 # ╔═╡ 4843983c-df64-4b94-8634-7a10d9423a70
 md"""
 # StructBond
@@ -62,11 +71,12 @@ Base.@kwdef struct ASD
 	d::String
 	e::Int
 end
+@typeasfield String = TextField() # String fields with no struct-specific default will use this 
 @fielddata ASD begin
 	a = (md"Markdown description, including ``LaTeX``", Slider(1:10))
 	b = (@htl("<span>Field with <b>HTML</b> description</span>"), Scrubbable(1:10))
 	c = ("Normal String Description", TextField())
-	d = TextField() # No description, defaults to the docstring since it's present
+	# d has no ASD-specific custom bond, so it will use the field docstring as description and the default String widget as widget
 	e = Slider(20:25) # No description, defaults to the fieldname as no docstring is present
 end
 asd_bond = @bind asd StructBond(ASD; description = "Custom Description")
@@ -131,7 +141,7 @@ md"""
 
 # ╔═╡ 959acb40-1fd6-43f5-a1a6-73a6ceaae1d7
 md"""
-In some cases, one does not want to have a single bond wrapping either a Structure or a NamedTuple, and single independent bonds are more convenient.
+In some cases, one does not want to have a single bond wrapping either a Structure or a NamedTuple because single independent bonds are more convenient.
 
 `@BondsList` is a convenience macro to create an object of type `BondsList` which simply allow to add a description to separate bonds and group them all together in a table-like format equivalent to those of `StructBond`.
 
@@ -184,7 +194,10 @@ end
 end
 
 # ╔═╡ 633029af-8cac-426e-b35c-c9fb3938b784
-popoutwrap(LOL)
+@bind lol_pop popoutwrap(LOL)
+
+# ╔═╡ 065bad73-5fa8-4496-ba33-9e66940b5806
+lol_pop
 
 # ╔═╡ 2073f11e-8196-4ebc-922f-5fa589e91797
 md"""
@@ -199,6 +212,12 @@ blc = @BondsList "Popout Container" begin
 	"NamedTuple" = Popout(nt_bond)
 end
 
+# ╔═╡ e7d67662-77b3-482a-b032-8db4afbc01a6
+asd
+
+# ╔═╡ 996b4085-114c-48f4-9f90-8e637f29c06a
+nt
+
 # ╔═╡ 3a066bf4-3466-469e-90d0-6b14be3ed8d5
 md"""
 # BondTable
@@ -221,6 +240,18 @@ BondTable([
 	blc
 ]; description = "My Bonds")
 
+# ╔═╡ 08d711c0-e2cc-4444-94ca-0c4c3cfe901f
+nt
+
+# ╔═╡ 03e9d75e-e6c9-4199-933b-2be306daf978
+asd
+
+# ╔═╡ 26d11600-2827-4e08-9195-109c8a8bddc3
+freq
+
+# ╔═╡ be2a7820-e194-4410-b00d-a9332b234ad6
+alt
+
 # ╔═╡ 00000000-0000-0000-0000-000000000001
 PLUTO_PROJECT_TOML_CONTENTS = """
 [deps]
@@ -394,6 +425,7 @@ version = "17.4.0+2"
 # ╠═8db82e94-5c81-4c52-9228-7e22395fb68f
 # ╠═949ac1ef-c502-4e28-81ff-f99b0d19aa03
 # ╠═707175a9-d356-43cf-8038-620ebc401c93
+# ╠═cbfc6eec-8991-4a9c-ada0-295c8052854d
 # ╟─4843983c-df64-4b94-8634-7a10d9423a70
 # ╟─a8995224-83c6-4f82-b5a5-87a6f86fc7a0
 # ╠═9e3601f5-efc2-44e9-83d8-5b65ce7e9ccf
@@ -414,10 +446,17 @@ version = "17.4.0+2"
 # ╟─79beba88-932f-4147-b3a0-d821ef1bc1e2
 # ╠═63d6c2df-a411-407c-af11-4f5d09fbb322
 # ╠═633029af-8cac-426e-b35c-c9fb3938b784
+# ╠═065bad73-5fa8-4496-ba33-9e66940b5806
 # ╟─2073f11e-8196-4ebc-922f-5fa589e91797
 # ╠═811cf78b-e870-45bb-9173-89a3b3d495f5
+# ╠═e7d67662-77b3-482a-b032-8db4afbc01a6
+# ╠═996b4085-114c-48f4-9f90-8e637f29c06a
 # ╟─3a066bf4-3466-469e-90d0-6b14be3ed8d5
 # ╟─3213d977-7b65-43b0-a881-10fcc2523f14
 # ╠═903fee67-6b23-41dc-a03d-f1040b696be6
+# ╠═08d711c0-e2cc-4444-94ca-0c4c3cfe901f
+# ╠═03e9d75e-e6c9-4199-933b-2be306daf978
+# ╠═26d11600-2827-4e08-9195-109c8a8bddc3
+# ╠═be2a7820-e194-4410-b00d-a9332b234ad6
 # ╟─00000000-0000-0000-0000-000000000001
 # ╟─00000000-0000-0000-0000-000000000002