upstream/ipython Commit - r22910:4fd45e58

1

Migrating Widgets to IPython 3

1

Migrating Widgets to IPython 3

2

==============================

2

==============================

3

4

Upgrading Notebooks

4

Upgrading Notebooks

5

-------------------

5

-------------------

6

7

1. The first thing you'll notice when upgrading an IPython 2.0 widget

7

1. The first thing you'll notice when upgrading an IPython 2.0 widget

8

notebook to IPython 3.0 is the "Notebook converted" dialog. Click

8

notebook to IPython 3.0 is the "Notebook converted" dialog. Click

9

"ok".

9

"ok".

10

2. All of the widgets distributed with IPython have been renamed. The

10

2. All of the widgets distributed with IPython have been renamed. The

11

"Widget" suffix was removed from the end of the class name. i.e.

11

"Widget" suffix was removed from the end of the class name. i.e.

12

``ButtonWidget`` is now ``Button``.

12

``ButtonWidget`` is now ``Button``.

13

3. ``ContainerWidget`` was renamed to ``Box``.

13

3. ``ContainerWidget`` was renamed to ``Box``.

14

4. ``PopupWidget`` was removed from IPython~~. If you use the~~

14

4. ``PopupWidget`` was removed from IPython, because bootstrapjs was

15

problematic (creates global variables, etc.). If you use the

15

``PopupWidget``, try using a ``Box`` widget instead. If your notebook

16

``PopupWidget``, try using a ``Box`` widget instead. If your notebook

16

can't live without the popup functionality, subclass the ``Box``

17

can't live without the popup functionality, subclass the ``Box``

17

widget (both in Python and JS) and use JQuery UI's ``draggable()``

18

widget (both in Python and JS) and use JQuery UI's ``draggable()``

18

and ``resizable()`` methods to mimic the behavior.

19

and ``resizable()`` methods to mimic the behavior.

19

5. ``add_class`` and ``remove_class`` were removed. More often than not

20

5. ``add_class`` and ``remove_class`` were removed. More often than not

20

a new attribute exists on the widget that allows you to achieve the

21

a new attribute exists on the widget that allows you to achieve the

21

same explicitly. i.e. the ``Button`` widget now has a

22

same explicitly. i.e. the ``Button`` widget now has a

22

``button_style`` attribute which you can set to 'primary', 'success',

23

``button_style`` attribute which you can set to 'primary', 'success',

23

'info', 'warning', 'danger', or '' instead of using ``add_class`` to

24

'info', 'warning', 'danger', or '' instead of using ``add_class`` to

24

add the bootstrap class. ``VBox`` and ``HBox`` classes (flexible

25

add the bootstrap class. ``VBox`` and ``HBox`` classes (flexible

25

``Box`` subclasses) were added that allow you to avoid using

26

``Box`` subclasses) were added that allow you to avoid using

26

``add_class`` and ``remove_class`` to make flexible box model

27

``add_class`` and ``remove_class`` to make flexible box model

27

layouts. As a last resort, if you can't find a built in attribute for

28

layouts. As a last resort, if you can't find a built in attribute for

28

the class you want to use, a new ``_dom_classes`` list trait was

29

the class you want to use, a new ``_dom_classes`` list trait was

29

added, which combines ``add_class`` and ``remove_class`` into one

30

added, which combines ``add_class`` and ``remove_class`` into one

30

stateful list.

31

stateful list.

31

6. ``set_css`` and ``get_css`` were removed in favor of explicit style

32

6. ``set_css`` and ``get_css`` were removed in favor of explicit style

32

attributes - ``visible``, ``width``, ``height``, ``padding``,

33

attributes - ``visible``, ``width``, ``height``, ``padding``,

33

``margin``, ``color``, ``background_color``, ``border_color``,

34

``margin``, ``color``, ``background_color``, ``border_color``,

34

``border_width``, ``border_radius``, ``border_style``,

35

``border_width``, ``border_radius``, ``border_style``,

35

``font_style``, ``font_weight``, ``font_size``, and ``font_family``

36

``font_style``, ``font_weight``, ``font_size``, and ``font_family``

36

are a few. If you can't find a trait to see the css attribute you

37

are a few. If you can't find a trait to see the css attribute you

37

need, you can, in order of preference, (A) subclass to create your

38

need, you can, in order of preference, (A) subclass to create your

38

own custom widget, (B) use CSS and the ``_dom_classes`` trait to set

39

own custom widget, (B) use CSS and the ``_dom_classes`` trait to set

39

``_dom_classes``, or (C) use the ``_css`` dictionary to set CSS

40

``_dom_classes``, or (C) use the ``_css`` dictionary to set CSS

40

styling like ``set_css`` and ``get_css``.

41

styling like ``set_css`` and ``get_css``.

41

7. For selection widgets, such as ``Dropdown``, the ``values`` argument

42

7. For selection widgets, such as ``Dropdown``, the ``values`` argument

42

has been renamed to ``options``.

43

has been renamed to ``options``.

43

44

Upgrading Custom Widgets

45

Upgrading Custom Widgets

45

------------------------

46

------------------------

46

47

Javascript

48

Javascript

48

~~~~~~~~~~

49

~~~~~~~~~~

49

50

1. If you are distributing your widget and decide to use the deferred

51

1. If you are distributing your widget and decide to use the deferred

51

loading technique (preferred), you can remove all references to the

52

loading technique (preferred), you can remove all references to the

52

WidgetManager and the register model/view calls (see the Python

53

WidgetManager and the register model/view calls (see the Python

53

section below for more information).

54

section below for more information).

54

2. In 2.0 require.js was used incorrectly, that has been fixed and now

55

2. In 2.0 require.js was used incorrectly, that has been fixed and now

55

loading works more like Python's import. Requiring

56

loading works more like Python's import. Requiring

56

``widgets/js/widget`` doesn't import the ``WidgetManager`` class,

57

``widgets/js/widget`` doesn't import the ``WidgetManager`` class,

57

instead it imports a dictionary that exposes the classes within that

58

instead it imports a dictionary that exposes the classes within that

58

module:

59

module:

59

60

.. code:: javascript

61

.. code:: javascript

61

62

{

63

{

63

'WidgetModel': WidgetModel,

64

'WidgetModel': WidgetModel,

64

'WidgetView': WidgetView,

65

'WidgetView': WidgetView,

65

'DOMWidgetView': DOMWidgetView,

66

'DOMWidgetView': DOMWidgetView,

66

'ViewList': ViewList,

67

'ViewList': ViewList,

67

}

68

}

68

69

If you decide to continue to use the widget registry (by registering

70

If you decide to continue to use the widget registry (by registering

70

your widgets with the manager), you can import a dictionary with a

71

your widgets with the manager), you can import a dictionary with a

71

handle to the WidgetManager class by requiring

72

handle to the WidgetManager class by requiring

72

``widgets/js/manager``. Doing so will import:

73

``widgets/js/manager``. Doing so will import:

73

74

.. code:: javascript

75

.. code:: javascript

75

76

{'WidgetManager': WidgetManager}

77

{'WidgetManager': WidgetManager}

77

78

3. Don't rely on the ``IPython`` namespace for anything. To inherit from

79

3. Don't rely on the ``IPython`` namespace for anything. To inherit from

79

the DOMWidgetView, WidgetView, or WidgetModel, require

80

the DOMWidgetView, WidgetView, or WidgetModel, require

80

``widgets/js/widget`` as ``widget``. If you were inheriting from

81

``widgets/js/widget`` as ``widget``. If you were inheriting from

81

DOMWidgetView, and the code looked like this:

82

DOMWidgetView, and the code looked like this:

82

83

.. code:: javascript

84

.. code:: javascript

84

85

IPython.DOMWidgetView.extend({...})

86

IPython.DOMWidgetView.extend({...})

86

87

It would become this:

88

It would become this:

88

89

.. code:: javascript

90

.. code:: javascript

90

91

widget.DOMWidgetView.extend({...})

92

widget.DOMWidgetView.extend({...})

92

93

4. Custom models are encouraged. When possible, it's recommended to move

94

4. Custom models are encouraged. When possible, it's recommended to move

94

your code into a custom model, so actions are performed 1 time,

95

your code into a custom model, so actions are performed 1 time,

95

instead of N times where N is the number of displayed views.

96

instead of N times where N is the number of displayed views.

96

97

Python

98

Python

98

~~~~~~

99

~~~~~~

99

100

Generally, custom widget Python code can remain unchanged. If you

101

Generally, custom widget Python code can remain unchanged. If you

101

distribute your custom widget, you may be using ``display`` and

102

distribute your custom widget, you may be using ``display`` and

102

``Javascript`` to publish the widget's Javascript to the front-end. That

103

``Javascript`` to publish the widget's Javascript to the front-end. That

103

is no longer the recommended way of distributing widget Javascript.

104

is no longer the recommended way of distributing widget Javascript.

104

Instead have the user install the Javascript to his/her nbextension

105

Instead have the user install the Javascript to his/her nbextension

105

directory or their profile's static directory. Then use the new

106

directory or their profile's static directory. Then use the new

106

``_view_module`` and ``_model_module`` traitlets in combination with

107

``_view_module`` and ``_model_module`` traitlets in combination with

107

``_view_name`` and ``_model_name`` to instruct require.js on how to load

108

``_view_name`` and ``_model_name`` to instruct require.js on how to load

108

the widget's Javascript. The Javascript is then loaded when the widget

109

the widget's Javascript. The Javascript is then loaded when the widget

109

is used for the first time.

110

is used for the first time.

110

111

Details

112

Details

112

-------

113

-------

113

114

Asynchronous

115

Asynchronous

115

~~~~~~~~~~~~

116

~~~~~~~~~~~~

116

117

In the IPython 2.x series the only way to register custom widget views

118

In the IPython 2.x series the only way to register custom widget views

118

and models was to use the registry in the widget manager. Unfortunately,

119

and models was to use the registry in the widget manager. Unfortunately,

119

using this method made distributing and running custom widgets difficult. The widget

120

using this method made distributing and running custom widgets difficult. The widget

120

maintainer had to either use the rich display framework to push the

121

maintainer had to either use the rich display framework to push the

121

widget's Javascript to the notebook or instruct the users to install the

122

widget's Javascript to the notebook or instruct the users to install the

122

Javascript by hand in a custom profile. With the first method, the

123

Javascript by hand in a custom profile. With the first method, the

123

maintainer would have to be careful about when the Javascript was pushed

124

maintainer would have to be careful about when the Javascript was pushed

124

to the front-end. If the Javascript was pushed on Python widget

125

to the front-end. If the Javascript was pushed on Python widget

125

``import``, the widgets wouldn't work after page refresh. This is

126

``import``, the widgets wouldn't work after page refresh. This is

126

because refreshing the page does not restart the kernel, and the Python

127

because refreshing the page does not restart the kernel, and the Python

127

``import`` statement only runs once in a given kernel instance (unless

128

``import`` statement only runs once in a given kernel instance (unless

128

you reload the Python modules, which isn't straight forward). This meant

129

you reload the Python modules, which isn't straight forward). This meant

129

the maintainer would have to have a separate ``push_js()`` method that

130

the maintainer would have to have a separate ``push_js()`` method that

130

the user would have to call after importing the widget's Python code.

131

the user would have to call after importing the widget's Python code.

131

132

Our solution was to add support for loading widget views and models

133

Our solution was to add support for loading widget views and models

133

using require.js paths. Thus the comm and widget frameworks now support

134

using require.js paths. Thus the comm and widget frameworks now support

134

lazy loading. To do so, everything had to be converted to asynchronous

135

lazy loading. To do so, everything had to be converted to asynchronous

135

code. HTML5 promises are used to accomplish that

136

code. HTML5 promises are used to accomplish that

136

(`#6818 <https://github.com/ipython/ipython/pull/6818>`__,

137

(`#6818 <https://github.com/ipython/ipython/pull/6818>`__,

137

`#6914 <https://github.com/ipython/ipython/pull/6914>`__).

138

`#6914 <https://github.com/ipython/ipython/pull/6914>`__).

138

139

Symmetry

140

Symmetry

140

~~~~~~~~

141

~~~~~~~~

141

142

In IPython 3.0, widgets can be instantiated from the front-end

143

In IPython 3.0, widgets can be instantiated from the front-end

143

(`#6664 <https://github.com/ipython/ipython/pull/6664>`__). On top of

144

(`#6664 <https://github.com/ipython/ipython/pull/6664>`__). On top of

144

this, a widget persistence API was added

145

this, a widget persistence API was added

145

(`#7163 <https://github.com/ipython/ipython/pull/7163>`__,

146

(`#7163 <https://github.com/ipython/ipython/pull/7163>`__,

146

`#7227 <https://github.com/ipython/ipython/pull/7227>`__). With the

147

`#7227 <https://github.com/ipython/ipython/pull/7227>`__). With the

147

widget persistence API, you can persist your widget instances using

148

widget persistence API, you can persist your widget instances using

148

Javascript. This makes it easy to persist your widgets to your notebook

149

Javascript. This makes it easy to persist your widgets to your notebook

149

document (with a small amount of custom JS). By default, the widgets are

150

document (with a small amount of custom JS). By default, the widgets are

150

persisted to your web browsers local storage which makes them reappear

151

persisted to your web browsers local storage which makes them reappear

151

when your refresh the page.

152

when your refresh the page.

152

153

Smaller Changes

154

Smaller Changes

154

~~~~~~~~~~~~~~~

155

~~~~~~~~~~~~~~~

155

156

- Latex math is supported in widget ``description``\ s

157

- Latex math is supported in widget ``description``\ s

157

(`#5937 <https://github.com/ipython/ipython/pull/5937>`__).

158

(`#5937 <https://github.com/ipython/ipython/pull/5937>`__).

158

- Widgets can be display more than once within a single container

159

- Widgets can be display more than once within a single container

159

widget (`#5963 <https://github.com/ipython/ipython/pull/5963>`__,

160

widget (`#5963 <https://github.com/ipython/ipython/pull/5963>`__,

160

`#6990 <https://github.com/ipython/ipython/pull/6990>`__).

161

`#6990 <https://github.com/ipython/ipython/pull/6990>`__).

161

- ``FloatRangeSlider`` and ``IntRangeSlider`` were added

162

- ``FloatRangeSlider`` and ``IntRangeSlider`` were added

162

(`#6050 <https://github.com/ipython/ipython/pull/6050>`__).

163

(`#6050 <https://github.com/ipython/ipython/pull/6050>`__).

163

- "Widget" was removed from the ends of all of the widget class names

164

- "Widget" was removed from the ends of all of the widget class names

164