upstream/ipython Commit - r20546:a609e000

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. If you use the

15

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

15

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

16

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

16

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

17

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

17

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

18

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

18

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

19

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

19

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

20

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

21

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

21

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

22

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

22

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

23

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

23

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

24

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

24

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

25

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

25

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

26

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

26

``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

27

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

28

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

29

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

29

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

30

stateful list.

30

stateful list.

31

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

31

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

32

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

32

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

33

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

33

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

34

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

34

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

35

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

35

``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

36

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

37

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

38

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

39

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

40

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

40

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

41

42

Upgrading Custom Widgets

42

Upgrading Custom Widgets

43

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

43

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

44

45

Javascript

45

Javascript

46

~~~~~~~~~~

46

~~~~~~~~~~

47

48

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

48

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

49

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

49

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

50

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

50

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

51

section below for more information).

51

section below for more information).

52

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

52

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

53

loading works more like Python's import. Requiring

53

loading works more like Python's import. Requiring

54

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

54

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

55

instead it imports a dictionary that exposes the classes within that

55

instead it imports a dictionary that exposes the classes within that

56

module:

56

module:

57

58

.. code:: javascript

58

.. code:: javascript

59

60

{

60

{

61

'WidgetModel': WidgetModel,

61

'WidgetModel': WidgetModel,

62

'WidgetView': WidgetView,

62

'WidgetView': WidgetView,

63

'DOMWidgetView': DOMWidgetView,

63

'DOMWidgetView': DOMWidgetView,

64

'ViewList': ViewList,

64

'ViewList': ViewList,

65

}

65

}

66

67

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

67

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

68

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

68

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

69

handle to the WidgetManager class by requiring

69

handle to the WidgetManager class by requiring

70

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

70

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

71

72

.. code:: javascript

72

.. code:: javascript

73

74

{'WidgetManager': WidgetManager}

74

{'WidgetManager': WidgetManager}

75

76

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

76

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

77

the DOMWidgetView, WidgetView, or WidgetModel, require

77

the DOMWidgetView, WidgetView, or WidgetModel, require

78

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

78

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

79

DOMWidgetView, and the code looked like this:

79

DOMWidgetView, and the code looked like this:

80

81

.. code:: javascript

81

.. code:: javascript

82

83

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

83

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

84

85

It would become this:

85

It would become this:

86

87

.. code:: javascript

87

.. code:: javascript

88

89

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

89

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

90

91

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

91

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

92

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

92

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

93

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

93

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

94

95

Python

95

Python

96

~~~~~~

96

~~~~~~

97

98

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

98

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

99

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

99

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

100

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

100

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

101

is no longer the recommended way of distributing widget Javascript.

101

is no longer the recommended way of distributing widget Javascript.

102

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

102

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

103

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

103

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

104

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

104

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

105

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

105

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

106

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

106

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

107

is used for the first time.

107

is used for the first time.

108

109

Details

109

Details

110

-------

110

-------

111

112

Asynchronous

112

Asynchronous

113

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

113

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

114

115

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

115

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

116

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

116

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

117

using this method made ~~pack~~ing custom widgets difficult. The widget

117

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

118

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

118

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

119

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

119

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

120

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

120

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

121

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

121

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

122

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

122

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

123

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

123

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

124

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

124

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

125

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

125

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

126

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

126

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

127

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

127

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

128

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

128

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

129

130

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

130

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

131

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

131

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

132

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

132

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

133

code. HTML5 promises are used to accomplish that

133

code. HTML5 promises are used to accomplish that

134

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

134

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

135

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

135

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

136

137

Symmetry

137

Symmetry

138

~~~~~~~~

138

~~~~~~~~

139

140

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

140

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

141

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

141

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

142

this, a widget persistence API was added

142

this, a widget persistence API was added

143

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

143

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

144

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

144

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

145

widget persistence API, you can persist your widget instances using

145

widget persistence API, you can persist your widget instances using

146

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

146

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

147

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

147

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

148

persisted to your web browsers local storage which makes them reappear

148

persisted to your web browsers local storage which makes them reappear

149

when your refresh the page.

149

when your refresh the page.

150

151

Smaller Changes

151

Smaller Changes

152

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

152

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

153

154

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

154

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

155

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

155

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

156

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

156

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

157

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

157

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

158

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

158

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

159

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

159

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

160

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

160

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

161

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

161

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

162