upstream/ipython Commit - r20634:41d62aac

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

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

42

has been renamed to ``options``.

41

43

42

Upgrading Custom Widgets

44

Upgrading Custom Widgets

43

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

45

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

44

46

45

Javascript

47

Javascript

46

~~~~~~~~~~

48

~~~~~~~~~~

47

49

48

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

50

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

49

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

51

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

50

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

52

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

51

section below for more information).

53

section below for more information).

52

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

54

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

53

loading works more like Python's import. Requiring

55

loading works more like Python's import. Requiring

54

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

56

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

55

instead it imports a dictionary that exposes the classes within that

57

instead it imports a dictionary that exposes the classes within that

56

module:

58

module:

57

59

58

.. code:: javascript

60

.. code:: javascript

59

61

60

{

62

{

61

'WidgetModel': WidgetModel,

63

'WidgetModel': WidgetModel,

62

'WidgetView': WidgetView,

64

'WidgetView': WidgetView,

63

'DOMWidgetView': DOMWidgetView,

65

'DOMWidgetView': DOMWidgetView,

64

'ViewList': ViewList,

66

'ViewList': ViewList,

65

}

67

}

66

68

67

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

69

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

70

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

69

handle to the WidgetManager class by requiring

71

handle to the WidgetManager class by requiring

70

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

72

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

71

73

72

.. code:: javascript

74

.. code:: javascript

73

75

74

{'WidgetManager': WidgetManager}

76

{'WidgetManager': WidgetManager}

75

77

76

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

78

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

77

the DOMWidgetView, WidgetView, or WidgetModel, require

79

the DOMWidgetView, WidgetView, or WidgetModel, require

78

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

80

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

79

DOMWidgetView, and the code looked like this:

81

DOMWidgetView, and the code looked like this:

80

82

81

.. code:: javascript

83

.. code:: javascript

82

84

83

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

85

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

84

86

85

It would become this:

87

It would become this:

86

88

87

.. code:: javascript

89

.. code:: javascript

88

90

89

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

91

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

90

92

91

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

93

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,

94

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.

95

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

94

96

95

Python

97

Python

96

~~~~~~

98

~~~~~~

97

99

98

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

100

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

99

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

101

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

100

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

102

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

101

is no longer the recommended way of distributing widget Javascript.

103

is no longer the recommended way of distributing widget Javascript.

102

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

104

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

103

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

105

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

104

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

106

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

105

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

107

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

108

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

107

is used for the first time.

109

is used for the first time.

108

110

109

Details

111

Details

110

-------

112

-------

111

113

112

Asynchronous

114

Asynchronous

113

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

115

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

114

116

115

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

117

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,

118

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

117

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

119

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

120

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

121

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

122

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

123

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

122

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

124

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

123

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

125

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

124

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

126

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

125

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

127

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

126

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

128

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

129

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.

130

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

129

131

130

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

132

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

133

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

134

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

133

code. HTML5 promises are used to accomplish that

135

code. HTML5 promises are used to accomplish that

134

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

136

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

135

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

137

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

136

138

137

Symmetry

139

Symmetry

138

~~~~~~~~

140

~~~~~~~~

139

141

140

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

142

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

141

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

143

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

142

this, a widget persistence API was added

144

this, a widget persistence API was added

143

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

145

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

144

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

146

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

145

widget persistence API, you can persist your widget instances using

147

widget persistence API, you can persist your widget instances using

146

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

148

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

149

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

150

persisted to your web browsers local storage which makes them reappear

149

when your refresh the page.

151

when your refresh the page.

150

152

151

Smaller Changes

153

Smaller Changes

152

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

154

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

153

155

154

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

156

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

155

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

157

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

156

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

158

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

157

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

159

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

158

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

160

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

159

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

161

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

160

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

162

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

161

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

163

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

162