Any *numeric* property initialized with the empty string is provided the default value by the
Any *numeric* property initialized with the empty string is provided the default value by the
frontend. Some numbers need to be sent as actual numbers (when non-null), whereas the ones representing
frontend. Some numbers need to be sent as actual numbers (when non-null), whereas the ones representing
lengths in CSS units need to be sent as strings.
lengths in CSS units need to be sent as strings specifying the size unit (px,em,cm,etc.).
The initial state must *at least* have the following fields in the `data.state` value of the message:
The initial state must *at least* have the following fields in the `data.state` value of the message:
...
@@ -40,7 +40,7 @@ the kernel.
...
@@ -40,7 +40,7 @@ the kernel.
### Buffer paths
### Buffer paths
To display some widgets, we need to use the `buffer_paths`. It's only an array with arrays of keys on how to get to the fields that are to considered a
To display some widgets, we need to use the `buffer_paths`. It's only an array with arrays of keys on how to get to the fields that are to considered a
byte stream. For example, in an image widget, `buffer_paths` would be the array `[ ["value"] ]`, which means that `state.value` is a buffer path. The buffers are specified in the header, so the n-th buffer corresponds to the n-th buffer path.
byte stream. For example, in an image widget, `buffer_paths` would be the array `[ ["value"] ]`, which means that `state.value` is a buffer path. The buffers are sent in the header of the message, just before the data, so the n-th buffer corresponds to the n-th buffer path in the array.
```json
```json
"data":{
"data":{
...
@@ -74,6 +74,18 @@ content = {
...
@@ -74,6 +74,18 @@ content = {
}
}
```
```
## Clear output messages
A simple message that indicates that the output of the header message id's should be cleaned.
-`wait=true` indicates that it should clean the output in the next append, while `wait=false` cleans the output inmediately.
```json
method="clear_output",
content={
"wait":bool
}
```
## Custom messages
## Custom messages
* Widgets can also send a custom message, having the form:
* Widgets can also send a custom message, having the form:
-[]Validate the JSON implementation of widgets against the MsgSpec schema
-[]Automatic validation of the JSON implementation of widgets against the MsgSpec schema
-[] Create integration tests for the widgets
-[] Create integration tests for the widgets
-[] Make the `output` widget work
-[] Make the `output` widget work with anything displayable
-[] Processing of widget messages concurrently
-[] Make the layout widget values more 'Haskelian': Instead of checking if the string is valid at runtime, make some types so it's checked at compile-time
-[] Make the layout widget values more 'Haskelian': Instead of checking if the string is valid at runtime, make some types so it's checked at compile-time
-[] Create a serializable color data type instead of using `Maybe String`
-[] Create a serializable color data type instead of using `Maybe String`
-[] Overload setField so it can be used with `Maybes`without having to put `Just` every time
-[] Overload setField so it can be used with `Maybes`or other wrapper types without having to put `Just` every time.
-[] Add some "utils" work:
-[] Add some "utils" work:
-[] Create media widget from file
-[] Create media widget from file
-[] Get the selected label from a selection value
-[] Get the selected label from a selection value
\ No newline at end of file
## How to...
This is a mini-guide for developers that want to update to a more recent widgets specification, but without
dwelling into the deeps of the project
### Add a new attribute
If you want to add a new attribute you'll have to:
1. Create a new singleton in [Singletons.hs](./Singletons.hs) inside the type `data Field`.
2. Write the serialization key of the field as specified in the model (see [MsgSpec.md](./MsgSpec.md)) inside the `toKey` function at [Singletons.hs](./Singletons.hs)
3. Because we use the `singletons-th` library, you have to define an alias for the attribute at [Common.hs](./Common.hs) to be able to use it at run-time more easily.
4. Now you have to specify the type of the field. Edit the type family `Fieldtype` at [Types.hs](./Types.hs)
### Add an attribute to a widget
First you have to check if the attribute is only for one widget, or is from a common class. You can check it at [ipywidget's repo](https://github.com/jupyter-widgets/ipywidgets/tree/master/ipywidgets/widgets).
- If it's only for one widget:
1. Edit the `type instance WidgetFields <WidgetNameType> = ...` at [Types.hs](./Types.hs), adding the new field to the field array.
2. Modify the `mk<WidgetName>` at `Module/WidgetName.hs`, adding the default value of the attribute. If the widget doesn't have any attributes yet, you can check how to do it on other widgets.
- If it's for a common class:
1. Edit the `type <ClassName> = ...` at [Types.hs](./Types.hs)
2. Edit the `default<ClassName>Widget` function from the same file, adding the default value for that attribute.
> Some widgets receive messages from the frontend when a value is modified (such as sliders, text areas, buttons...). You'll have to modify the `comm` function instantiated from the class `IHaskellWidget`. You can find an example at [IntSlider.hs](./Int/BoundedInt/IntSlider.hs)
## FAQ
When using widgets in ihaskell, you'll encounter a lot of compilation errors. If you are not very familiar with Haskell, they can be a bit hard to decipher, this is a mini guide that will (hopefully) appear when you paste the error in Google.
