diff --git a/docs/make.jl b/docs/make.jl index bc04b14..bad3627 100644 --- 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 index a2758d0..fcbb170 100644 --- 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 index 0145bbd..483bed6 100644 --- 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` \ No newline at end of file + 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 + +``` + +## @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 + +``` + +## @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 + +``` + +## 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 + +``` + +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 + +``` + +## 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 + +``` + +## 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 +``` \ No newline at end of file diff --git a/docs/src/toc.md b/docs/src/toc.md index 169d44e..1d8abd4 100644 --- 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 index 943455b..f8ec184 100755 --- a/html_exports/test_bondstable.jl.html +++ b/html_exports/test_bondstable.jl.html @@ -3,11 +3,11 @@ diff --git a/test/notebooks/structbondmodule.jl b/test/notebooks/structbondmodule.jl index 009501b..69c1a27 100644 --- 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""" +# +# """ + # ╔═╡ 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("Field with HTML description"), 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