Skip to content

Commit

Permalink
tweak docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@fonsp
fonsp committed Nov 21, 2023
1 parent 1ab239c commit 8abe808
Show file tree
Hide file tree
Showing 2 changed files with 66 additions and 14 deletions.
2 changes: 1 addition & 1 deletion Project.toml
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name = "AbstractPlutoDingetjes"
uuid = "6e696c72-6542-2067-7265-42206c756150"
authors = ["Paul Berg <[email protected]>", "Fons van der Plas <[email protected]>"]
version = "1.2.0"
version = "1.2.1"

[deps]
Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
Expand Down
78 changes: 65 additions & 13 deletions src/AbstractPlutoDingetjes.jl
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,30 @@

"""
An abstract package to be implemented by packages/people who create widgets/*dingetjes* for Pluto. If you are just happy using Pluto to make cool stuff, you probably don't want to use this package directly.
A more technical package meant for people who develop widgets for other Pluto users. By using and implementing methods from this package, you can give your widget more advanced features.
Take a look at [`AbstractPlutoDingetjes.Bonds`](@ref) and [`AbstractPlutoDingetjes.Display`](@ref).
Most functions in AbstractPlutoDingetjes are most useful when used with the `type`–`show`–`@htl` recipe. A basic example:
```julia
import HypertextLiteral: @htl
struct MyCoolSlider
min::Real
max::Real
end
function Base.show(io::IO, m::MIME"text/html", d::MyCoolSlider)
show(io, m, @htl(
""\"
<input type=range min=\$(d.min) max=\$(d.max)>
\"""
))
end
# Use:
@bind value MyCoolSlider(5, 10)
```
This example **does not use** AbstractPlutoDingetjes, but AbstractPlutoDingetjes can be used to gradually enhance this widget.
"""
module AbstractPlutoDingetjes

Expand Down Expand Up @@ -109,13 +131,21 @@ When not overloaded for your widget, it defaults to returning `missing`.
# Example
```julia
import HypertextLiteral: @htl
struct MySlider
range::AbstractRange{<:Real}
end
Base.show(io::IO, m::MIME"text/html", s::MySlider) = show(io, m, HTML("<input type=range min=\$(first(s.values)) step=\$(step(s.values)) max=\$(last(s.values))>"))
function Base.show(io::IO, m::MIME"text/html", s::MySlider)
show(io, m, @htl(
"<input type=range min=\$(first(s.values)) step=\$(step(s.values)) max=\$(last(s.values))>"
))
end
AbstractPlutoDingetjes.Bonds.initial_value(s::MySlider) = first(s.range)
function AbstractPlutoDingetjes.Bonds.initial_value(s::MySlider)
first(s.range)
end
# Add the following for the same functionality on Pluto versions 0.17.0 and below. Will be ignored in future Pluto versions. See the compat info below.
Base.get(s::MySlider) = first(s.range)
Expand Down Expand Up @@ -146,11 +176,17 @@ When not overloaded for your widget, it defaults to returning the value unchange
# Example
```julia
import HypertextLiteral: @htl
struct MyVectorSlider
values::Vector{<:Any} # note! a vector of arbitrary objects, not just numbers
end
Base.show(io::IO, m::MIME"text/html", s::MyVectorSlider) = show(io, m, HTML("<input type=range min=1 max=\$(length(s.values))>"))
function Base.show(io::IO, m::MIME"text/html", s::MyVectorSlider)
show(io, m, @htl(
"<input type=range min=1 max=\$(length(s.values))>"
))
end
AbstractPlutoDingetjes.Bonds.transform_value(s::MyVectorSlider, value_from_javascript::Int) = s.values[value_from_javascript]
```
Expand All @@ -166,7 +202,7 @@ transform_value(bond::Any, value_from_javascript::Any) = value_from_javascript



"`NotGiven()` is the default return value of `possible_values(::Any)`."
"`NotGiven()` is the default return value of `possible_values(::Any)`, if you have not defined an overload."
struct NotGiven end
"Return `InfinitePossibilities()` from your overload of [`possible_values`](@ref) to signify that your bond has no finite set of possible values."
struct InfinitePossibilities end
Expand All @@ -179,19 +215,27 @@ The returned value should be an iterable object that you can call `length` on (l
# Examples
```julia
import HypertextLiteral: @htl
struct MySlider
range::AbstractRange{<:Real}
end
Base.show(io::IO, m::MIME"text/html", s::MySlider) = show(io, m, HTML("<input type=range min=\$(first(s.values)) step=\$(step(s.values)) max=\$(last(s.values))>"))
function Base.show(io::IO, m::MIME"text/html", s::MySlider)
show(io, m, @htl(
"<input type=range min=\$(first(s.values)) step=\$(step(s.values)) max=\$(last(s.values))>"
))
end
AbstractPlutoDingetjes.Bonds.possible_values(s::MySlider) = s.range
```
```julia
import HypertextLiteral: @htl
struct MyTextBox end
Base.show(io::IO, m::MIME"text/html", s::MyTextBox) = show(io, m, HTML("<input type=text>"))
Base.show(io::IO, m::MIME"text/html", s::MyTextBox) = show(io, m, @htl("<input type=text>"))
AbstractPlutoDingetjes.Bonds.possible_values(s::MySlider) = AbstractPlutoDingetjes.Bonds.InfinitePossibilities()
```
Expand All @@ -215,13 +259,21 @@ The returned value should be a `Boolean`.
# Example
```julia
import HypertextLiteral: @htl
struct MySlider
range::AbstractRange{<:Real}
end
Base.show(io::IO, m::MIME"text/html", s::MySlider) = show(io, m, HTML("<input type=range min=\$(first(s.values)) step=\$(step(s.values)) max=\$(last(s.values))>"))
function Base.show(io::IO, m::MIME"text/html", s::MySlider)
show(io, m, @htl(
"<input type=range min=\$(first(s.values)) step=\$(step(s.values)) max=\$(last(s.values))>"
))
end
AbstractPlutoDingetjes.Bonds.validate_value(s::MySlider, from_browser::Real) = first(s.range) <= from_browser <= last(s.range)
function AbstractPlutoDingetjes.Bonds.validate_value(s::MySlider, from_browser::Real)
first(s.range) <= from_browser <= last(s.range)
end
```
!!! info "Note about `transform_value`"
Expand Down Expand Up @@ -400,11 +452,11 @@ manually render published object to a string, using `io` as the context:
function Base.show(io::IO, m::MIME"text/html", x::MyType)
# 🟡 This works, but we recommend the HypertextLiteral.jl example instead.
published_js = repr(published_to_js(x.data); context=io)
rendered = repr(published_to_js(x.data); context=io)
println(io, "\""
<script>
let data = \$(published_js)
let data = \$(rendered)
console.log(data)
</script>
"\"")
Expand All @@ -419,7 +471,7 @@ means that Pluto already optimizes the performance of sending data from Julia to
Javascript and it is especially useful when the same object is rendered multiple
times within the notebook.
This means that: If you use published_to_js twice on the same object within the
Also: If you use `published_to_js` twice on the same object within the
same cell, or in two different cells, the data is only transmitted once. The
second `published_to_js` just contains a reference to the same data.
Expand Down

2 comments on commit 8abe808

@fonsp
Copy link
Member Author

@fonsp fonsp commented on 8abe808 Nov 21, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@JuliaRegistrator register()

@JuliaRegistrator
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Registration pull request created: JuliaRegistries/General/95738

Tip: Release Notes

Did you know you can add release notes too? Just add markdown formatted text underneath the comment after the text
"Release notes:" and it will be added to the registry PR, and if TagBot is installed it will also be added to the
release that TagBot creates. i.e.

@JuliaRegistrator register

Release notes:

## Breaking changes

- blah

To add them here just re-invoke and the PR will be updated.

Tagging

After the above pull request is merged, it is recommended that a tag is created on this repository for the registered package version.

This will be done automatically if the Julia TagBot GitHub Action is installed, or can be done manually through the github interface, or via:

git tag -a v1.2.1 -m "<description of version>" 8abe808f61667cc66d28d0130a1ed13f4ebf1ebe
git push origin v1.2.1

Please sign in to comment.