extension_tutorial.rst 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978
  1. .. _extension_tutorial:
  2. Extension Tutorial
  3. ==================
  4. JupyterLab extensions add features to the user experience. This page
  5. describes how to create one type of extension, an *application plugin*,
  6. that:
  7. - Adds a "Random `Astronomy Picture <https://apod.nasa.gov/apod/astropix.html>`__" command to the
  8. *command palette* sidebar
  9. - Fetches the image and metadata when activated
  10. - Shows the image and metadata in a tab panel
  11. By working through this tutorial, you'll learn:
  12. - How to set up an extension development environment from scratch on a
  13. Linux or OSX machine. (You'll need to modify the commands slightly if you are on Windows.)
  14. - How to start an extension project from
  15. `jupyterlab/extension-cookiecutter-ts <https://github.com/jupyterlab/extension-cookiecutter-ts>`__
  16. - How to iteratively code, build, and load your extension in JupyterLab
  17. - How to version control your work with git
  18. - How to release your extension for others to enjoy
  19. .. figure:: images/extension_tutorial_complete.png
  20. :align: center
  21. :class: jp-screenshot
  22. :alt: The completed extension, showing the Astronomy Picture of the Day for 24 Jul 2015.
  23. The completed extension, showing the `Astronomy Picture of the Day for 24 Jul 2015 <https://apod.nasa.gov/apod/ap150724.html>`__.
  24. Sound like fun? Excellent. Here we go!
  25. Set up a development environment
  26. --------------------------------
  27. Install conda using miniconda
  28. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  29. Start by installing miniconda, following
  30. `Conda's installation documentation <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html>`__.
  31. .. _install-nodejs-jupyterlab-etc-in-a-conda-environment:
  32. Install NodeJS, JupyterLab, etc. in a conda environment
  33. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  34. Next create a conda environment that includes:
  35. 1. the latest release of JupyterLab
  36. 2. `cookiecutter <https://github.com/audreyr/cookiecutter>`__, the tool
  37. you'll use to bootstrap your extension project structure (this is a Python tool
  38. which we'll install using conda below).
  39. 3. `NodeJS <https://nodejs.org>`__, the JavaScript runtime you'll use to
  40. compile the web assets (e.g., TypeScript, CSS) for your extension
  41. 4. `git <https://git-scm.com>`__, a version control system you'll use to
  42. take snapshots of your work as you progress through this tutorial
  43. It's a best practice to leave the root conda environment (i.e., the environment created
  44. by the miniconda installer) untouched and install your project-specific
  45. dependencies in a named conda environment. Run this command to create a
  46. new environment named ``jupyterlab-ext``.
  47. .. code:: bash
  48. conda create -n jupyterlab-ext --override-channels --strict-channel-priority -c conda-forge -c anaconda cookiecutter nodejs jupyter-packaging git
  49. Now activate the new environment so that all further commands you run
  50. work out of that environment.
  51. .. code:: bash
  52. conda activate jupyterlab-ext
  53. Note: You'll need to run the command above in each new terminal you open
  54. before you can work with the tools you installed in the
  55. ``jupyterlab-ext`` environment.
  56. Now we can install the latest version of JupyterLab.
  57. .. code:: bash
  58. pip install jupyterlab --pre
  59. Create a repository
  60. -------------------
  61. Create a new repository for your extension (see, for example, the
  62. `GitHub instructions <https://help.github.com/articles/create-a-repo/>`__. This is an
  63. optional step, but highly recommended if you want to share your
  64. extension.
  65. Create an extension project
  66. ---------------------------
  67. Initialize the project from a cookiecutter
  68. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  69. Next use cookiecutter to create a new project for your extension.
  70. This will create a new folder for your extension in your current directory.
  71. .. code:: bash
  72. cookiecutter https://github.com/jupyterlab/extension-cookiecutter-ts --checkout 3.0
  73. When prompted, enter values like the following for all of the cookiecutter
  74. prompts (``apod`` stands for Astronomy Picture of the Day, the NASA service we
  75. are using to fetch pictures).
  76. ::
  77. author_name []: Your Name
  78. python_name [myextension]: jupyterlab_apod
  79. labextension_name [myextension]: jupyterlab_apod
  80. project_short_description [A JupyterLab extension.]: Show a random NASA Astronomy Picture of the Day in a JupyterLab panel
  81. has_server_extension [n]: n
  82. has_binder [n]: y
  83. repository [https://github.com/my_name/myextension]: https://github.com/my_name/jupyterlab_apod
  84. Note: if not using a repository, leave the repository field blank. You can come
  85. back and edit the repository field in the ``package.json`` file later.
  86. Change to the directory the cookiecutter created and list the files.
  87. .. code:: bash
  88. cd jupyterlab_apod
  89. ls
  90. You should see a list like the following.
  91. ::
  92. LICENSE MANIFEST.in README.md binder/ jupyterlab_apod/ package.json pyproject.toml setup.py src/ style/ tsconfig.json
  93. Commit what you have to git
  94. ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  95. Run the following commands in your ``jupyterlab_apod`` folder to
  96. initialize it as a git repository and commit the current code.
  97. .. code:: bash
  98. git init
  99. git add .
  100. git commit -m 'Seed apod project from cookiecutter'
  101. Note: This step is not technically necessary, but it is good practice to
  102. track changes in version control system in case you need to rollback to
  103. an earlier version or want to collaborate with others. You
  104. can compare your work throughout this tutorial with the commits in a
  105. reference version of ``jupyterlab_apod`` on GitHub at
  106. https://github.com/jupyterlab/jupyterlab_apod.
  107. Build and install the extension for development
  108. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  109. Your new extension project has enough code in it to see it working in your
  110. JupyterLab. Run the following commands to install the initial project
  111. dependencies and install the extension into the JupyterLab environment.
  112. .. code:: bash
  113. pip install -ve .
  114. The above command copies the frontend part of the extension into JupyterLab.
  115. We can run this ``pip install`` command again every time we make a change to
  116. copy the change into JupyterLab. Even better, on Linux or macOS, we can use
  117. the ``develop`` command to create a symbolic link from JupyterLab to our
  118. source directory. This means our changes are automatically available in
  119. JupyterLab:
  120. .. code:: bash
  121. jupyter labextension develop --overwrite .
  122. See the initial extension in action
  123. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  124. After the install completes, open a second terminal. Run these commands to
  125. activate the ``jupyterlab-ext`` environment and start JupyterLab in your
  126. default web browser.
  127. .. code:: bash
  128. conda activate jupyterlab-ext
  129. jupyter lab
  130. In that browser window, open the JavaScript console
  131. by following the instructions for your browser:
  132. - `Accessing the DevTools in Google
  133. Chrome <https://developer.chrome.com/devtools#access>`__
  134. - `Opening the Web Console in
  135. Firefox <https://developer.mozilla.org/en-US/docs/Tools/Web_Console/Opening_the_Web_Console>`__
  136. After you reload the page with the console open, you should see a message that says
  137. ``JupyterLab extension jupyterlab_apod is activated!`` in the console.
  138. If you do, congratulations, you're ready to start modifying the extension!
  139. If not, go back make sure you didn't miss a step, and `reach
  140. out <https://github.com/jupyterlab/jupyterlab/blob/master/README.md#getting-help>`__ if you're stuck.
  141. Note: Leave the terminal running the ``jupyter lab`` command open and running
  142. JupyterLab to see the effects of changes below.
  143. Add an Astronomy Picture of the Day widget
  144. ------------------------------------------
  145. Show an empty panel
  146. ^^^^^^^^^^^^^^^^^^^
  147. The *command palette* is the primary view of all commands available to
  148. you in JupyterLab. For your first addition, you're going to add a
  149. *Random Astronomy Picture* command to the palette and get it to show an *Astronomy Picture*
  150. tab panel when invoked.
  151. Fire up your favorite text editor and open the ``src/index.ts`` file in your
  152. extension project. Change the import at the top of the file to get a reference
  153. to the command palette interface and the `JupyterFrontEnd` instance.
  154. .. code:: typescript
  155. import {
  156. JupyterFrontEnd,
  157. JupyterFrontEndPlugin
  158. } from '@jupyterlab/application';
  159. import { ICommandPalette } from '@jupyterlab/apputils';
  160. Locate the ``extension`` object of type ``JupyterFrontEndPlugin``. Change the
  161. definition so that it reads like so:
  162. .. code:: typescript
  163. /**
  164. * Initialization data for the jupyterlab_apod extension.
  165. */
  166. const extension: JupyterFrontEndPlugin<void> = {
  167. id: 'jupyterlab-apod',
  168. autoStart: true,
  169. requires: [ICommandPalette],
  170. activate: (app: JupyterFrontEnd, palette: ICommandPalette) => {
  171. console.log('JupyterLab extension jupyterlab_apod is activated!');
  172. console.log('ICommandPalette:', palette);
  173. }
  174. };
  175. The ``requires`` attribute states that your plugin needs an object that
  176. implements the ``ICommandPalette`` interface when it starts. JupyterLab
  177. will pass an instance of ``ICommandPalette`` as the second parameter of
  178. ``activate`` in order to satisfy this requirement. Defining
  179. ``palette: ICommandPalette`` makes this instance available to your code
  180. in that function. The second ``console.log`` line exists only so that
  181. you can immediately check that your changes work.
  182. Now you will need to install these dependencies. Run the following commands in the
  183. repository root folder to install the dependencies and save them to your
  184. `package.json`:
  185. .. code:: bash
  186. jlpm add @jupyterlab/apputils
  187. jlpm add @jupyterlab/application
  188. Finally, run the following to rebuild your extension.
  189. .. code:: bash
  190. jlpm run build
  191. .. note::
  192. This tutorial uses ``jlpm`` to install Javascript packages and
  193. run build commands, which is JupyterLab's bundled
  194. version of ``yarn``. If you prefer, you can use another Javascript
  195. package manager like ``npm`` or ``yarn`` itself.
  196. After the extension build finishes, return to the browser tab that opened when
  197. you started JupyterLab. Refresh it and look in the console. You should see the
  198. same activation message as before, plus the new message about the
  199. ICommandPalette instance you just added. If you don't, check the output of the
  200. build command for errors and correct your code.
  201. ::
  202. JupyterLab extension jupyterlab_apod is activated!
  203. ICommandPalette: Palette {_palette: CommandPalette}
  204. Note that we had to run ``jlpm run build`` in order for the bundle to
  205. update. This command does two things: compiles the TypeScript files in `src/`
  206. into JavaScript files in ``lib/`` (``jlpm run build``), then bundles the
  207. JavaScript files in ``lib/`` into a JupyterLab extension in
  208. ``jupyterlab_apod/static`` (``jlpm run build:extension``). If you wish to avoid
  209. running ``jlpm run build`` after each change, you can open a third terminal,
  210. activate the ``jupyterlab-ext`` environment, and run the ``jlpm run watch``
  211. command from your extension directory, which will automatically compile the
  212. TypeScript files as they are changed and saved.
  213. Now return to your editor. Modify the imports at the top of the file to add a few more imports:
  214. .. code:: typescript
  215. import { ICommandPalette, MainAreaWidget } from '@jupyterlab/apputils';
  216. import { Widget } from '@lumino/widgets';
  217. Install this new dependency as well:
  218. .. code:: bash
  219. jlpm add @lumino/widgets
  220. Then modify the ``activate`` function again so that it has the following
  221. code:
  222. .. code-block:: typescript
  223. activate: (app: JupyterFrontEnd, palette: ICommandPalette) => {
  224. console.log('JupyterLab extension jupyterlab_apod is activated!');
  225. // Create a blank content widget inside of a MainAreaWidget
  226. const content = new Widget();
  227. const widget = new MainAreaWidget({ content });
  228. widget.id = 'apod-jupyterlab';
  229. widget.title.label = 'Astronomy Picture';
  230. widget.title.closable = true;
  231. // Add an application command
  232. const command: string = 'apod:open';
  233. app.commands.addCommand(command, {
  234. label: 'Random Astronomy Picture',
  235. execute: () => {
  236. if (!widget.isAttached) {
  237. // Attach the widget to the main work area if it's not there
  238. app.shell.add(widget, 'main');
  239. }
  240. // Activate the widget
  241. app.shell.activateById(widget.id);
  242. }
  243. });
  244. // Add the command to the palette.
  245. palette.addItem({ command, category: 'Tutorial' });
  246. }
  247. The first new block of code creates a ``MainAreaWidget`` instance with an
  248. empty content ``Widget`` as its child. It also assigns the main area widget a
  249. unique ID, gives it a label that will appear as its tab title, and makes the
  250. tab closable by the user. The second block of code adds a new command with id
  251. ``apod:open`` and label *Random Astronomy Picture* to JupyterLab. When the
  252. command executes, it attaches the widget to the main display area if it is not
  253. already present and then makes it the active tab. The last new line of code
  254. uses the command id to add the command to the command palette in a section
  255. called *Tutorial*.
  256. Build your extension again using ``jlpm run build`` (unless you are using
  257. ``jlpm run watch`` already) and refresh the browser tab. Open the command
  258. palette on the left side by clicking on *Commands* and type *Astronomy* in the
  259. search box. Your *Random Astronomy Picture* command should appear. Click it or
  260. select it with the keyboard and press *Enter*. You should see a new, blank
  261. panel appear with the tab title *Astronomy Picture*. Click the *x* on the tab
  262. to close it and activate the command again. The tab should reappear. Finally,
  263. click one of the launcher tabs so that the *Astronomy Picture* panel is still
  264. open but no longer active. Now run the *Random Astronomy Picture* command one
  265. more time. The single *Astronomy Picture* tab should come to the foreground.
  266. .. figure:: images/extension_tutorial_empty.png
  267. :align: center
  268. :class: jp-screenshot
  269. :alt: The in-progress extension, showing a blank panel.
  270. The in-progress extension, showing a blank panel.
  271. If your widget is not behaving, compare your code with the reference
  272. project state at the `01-show-a-panel
  273. tag <https://github.com/jupyterlab/jupyterlab_apod/tree/3.0-01-show-a-panel>`__.
  274. Once you've got everything working properly, git commit your changes and
  275. carry on.
  276. .. code-block:: bash
  277. git add package.json src/index.ts
  278. git commit -m 'Show Astronomy Picture command in palette'
  279. Show a picture in the panel
  280. ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  281. You now have an empty panel. It's time to add a picture to it. Go back to
  282. your code editor. Add the following code below the lines that create a
  283. ``MainAreaWidget`` instance and above the lines that define the command.
  284. .. code-block:: typescript
  285. // Add an image element to the content
  286. let img = document.createElement('img');
  287. content.node.appendChild(img);
  288. // Get a random date string in YYYY-MM-DD format
  289. function randomDate() {
  290. const start = new Date(2010, 1, 1);
  291. const end = new Date();
  292. const randomDate = new Date(start.getTime() + Math.random()*(end.getTime() - start.getTime()));
  293. return randomDate.toISOString().slice(0, 10);
  294. }
  295. // Fetch info about a random picture
  296. const response = await fetch(`https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY&date=${randomDate()}`);
  297. const data = await response.json() as APODResponse;
  298. if (data.media_type === 'image') {
  299. // Populate the image
  300. img.src = data.url;
  301. img.title = data.title;
  302. } else {
  303. console.log('Random APOD was not a picture.');
  304. }
  305. The first two lines create a new HTML ``<img>`` element and add it to
  306. the widget DOM node. The next lines define a function get a random date in the form ``YYYY-MM-DD`` format, and then the function is used to make a request using the HTML
  307. `fetch <https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch>`__
  308. API that returns information about the Astronomy Picture of the Day for that date. Finally, we set the
  309. image source and title attributes based on the response.
  310. Now define the ``APODResponse`` type that was introduced in the code above. Put
  311. this definition just under the imports at the top of the file.
  312. .. code-block:: typescript
  313. interface APODResponse {
  314. copyright: string;
  315. date: string;
  316. explanation: string;
  317. media_type: 'video' | 'image';
  318. title: string;
  319. url: string;
  320. };
  321. And update the ``activate`` method to be ``async`` since we are now using
  322. ``await`` in the method body.
  323. .. code-block:: typescript
  324. activate: async (app: JupyterFrontEnd, palette: ICommandPalette) =>
  325. Rebuild your extension if necessary (``jlpm run build``), refresh your browser
  326. tab, and run the *Random Astronomy Picture* command again. You should now see a
  327. picture in the panel when it opens (if that random date had a picture and not a
  328. video).
  329. .. figure:: images/extension_tutorial_single.png
  330. :align: center
  331. :class: jp-screenshot
  332. The in-progress extension, showing the `Astronomy Picture of the Day for 19 Jan 2014 <https://apod.nasa.gov/apod/ap140119.html>`__.
  333. Note that the image is not centered in the panel nor does the panel
  334. scroll if the image is larger than the panel area. Also note that the
  335. image does not update no matter how many times you close and reopen the
  336. panel. You'll address both of these problems in the upcoming sections.
  337. If you don't see a image at all, compare your code with the
  338. `02-show-an-image
  339. tag <https://github.com/jupyterlab/jupyterlab_apod/tree/3.0-02-show-an-image>`__
  340. in the reference project. When it's working, make another git commit.
  341. .. code:: bash
  342. git add src/index.ts
  343. git commit -m 'Show a picture in the panel'
  344. Improve the widget behavior
  345. ---------------------------
  346. Center the image, add attribution, and error messaging
  347. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  348. Open ``style/index.css`` in our extension project directory for editing.
  349. Add the following lines to it.
  350. .. code-block:: css
  351. .my-apodWidget {
  352. display: flex;
  353. flex-direction: column;
  354. align-items: center;
  355. overflow: auto;
  356. }
  357. This CSS stacks content vertically within the widget panel and lets the panel
  358. scroll when the content overflows. This CSS file is included on the page
  359. automatically by JupyterLab because the ``package.json`` file has a ``style``
  360. field pointing to it. In general, you should import all of your styles into a
  361. single CSS file, such as this ``index.css`` file, and put the path to that CSS
  362. file in the ``package.json`` file ``style`` field.
  363. Return to the ``index.ts`` file. Modify the ``activate``
  364. function to apply the CSS classes, the copyright information, and error handling
  365. for the API response.
  366. The beginning of the function should read like the following:
  367. .. code-block:: typescript
  368. :emphasize-lines: 6,16-17,28-50
  369. activate: async (app: JupyterFrontEnd, palette: ICommandPalette) => {
  370. console.log('JupyterLab extension jupyterlab_apod is activated!');
  371. // Create a blank content widget inside of a MainAreaWidget
  372. const content = new Widget();
  373. content.addClass('my-apodWidget'); // new line
  374. const widget = new MainAreaWidget({content});
  375. widget.id = 'apod-jupyterlab';
  376. widget.title.label = 'Astronomy Picture';
  377. widget.title.closable = true;
  378. // Add an image element to the content
  379. let img = document.createElement('img');
  380. content.node.appendChild(img);
  381. let summary = document.createElement('p');
  382. content.node.appendChild(summary);
  383. // Get a random date string in YYYY-MM-DD format
  384. function randomDate() {
  385. const start = new Date(2010, 1, 1);
  386. const end = new Date();
  387. const randomDate = new Date(start.getTime() + Math.random()*(end.getTime() - start.getTime()));
  388. return randomDate.toISOString().slice(0, 10);
  389. }
  390. // Fetch info about a random picture
  391. const response = await fetch(`https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY&date=${randomDate()}`);
  392. if (!response.ok) {
  393. const data = await response.json();
  394. if (data.error) {
  395. summary.innerText = data.error.message;
  396. } else {
  397. summary.innerText = response.statusText;
  398. }
  399. } else {
  400. const data = await response.json() as APODResponse;
  401. if (data.media_type === 'image') {
  402. // Populate the image
  403. img.src = data.url;
  404. img.title = data.title;
  405. summary.innerText = data.title;
  406. if (data.copyright) {
  407. summary.innerText += ` (Copyright ${data.copyright})`;
  408. }
  409. } else {
  410. summary.innerText = 'Random APOD fetched was not an image.';
  411. }
  412. }
  413. // Keep all the remaining command lines the same
  414. // as before from here down ...
  415. Build your extension if necessary (``jlpm run build``) and refresh your
  416. JupyterLab browser tab. Invoke the *Random Astronomy Picture* command and
  417. confirm the image is centered with the copyright information below it. Resize
  418. the browser window or the panel so that the image is larger than the
  419. available area. Make sure you can scroll the panel over the entire area
  420. of the image.
  421. If anything is not working correctly, compare your code with the reference project
  422. `03-style-and-attribute
  423. tag <https://github.com/jupyterlab/jupyterlab_apod/tree/3.0-03-style-and-attribute>`__.
  424. When everything is working as expected, make another commit.
  425. .. code:: bash
  426. git add style/index.css src/index.ts
  427. git commit -m 'Add styling, attribution, error handling'
  428. Show a new image on demand
  429. ^^^^^^^^^^^^^^^^^^^^^^^^^^
  430. The ``activate`` function has grown quite long, and there's still more
  431. functionality to add. Let's refactor the code into two separate
  432. parts:
  433. 1. An ``APODWidget`` that encapsulates the Astronomy Picture panel elements,
  434. configuration, and soon-to-be-added update behavior
  435. 2. An ``activate`` function that adds the widget instance to the UI and
  436. decide when the picture should refresh
  437. Start by refactoring the widget code into the new ``APODWidget`` class.
  438. Add the following additional import to the top of the file.
  439. .. code-block:: typescript
  440. import { Message } from '@lumino/messaging';
  441. Install this dependency:
  442. .. code:: bash
  443. jlpm add @lumino/messaging
  444. Then add the class just below the definition of ``APODResponse`` in the ``index.ts``
  445. file.
  446. .. code-block:: typescript
  447. class APODWidget extends Widget {
  448. /**
  449. * Construct a new APOD widget.
  450. */
  451. constructor() {
  452. super();
  453. this.addClass('my-apodWidget');
  454. // Add an image element to the panel
  455. this.img = document.createElement('img');
  456. this.node.appendChild(this.img);
  457. // Add a summary element to the panel
  458. this.summary = document.createElement('p');
  459. this.node.appendChild(this.summary);
  460. }
  461. /**
  462. * The image element associated with the widget.
  463. */
  464. readonly img: HTMLImageElement;
  465. /**
  466. * The summary text element associated with the widget.
  467. */
  468. readonly summary: HTMLParagraphElement;
  469. /**
  470. * Handle update requests for the widget.
  471. */
  472. async onUpdateRequest(msg: Message): Promise<void> {
  473. const response = await fetch(`https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY&date=${this.randomDate()}`);
  474. if (!response.ok) {
  475. const data = await response.json();
  476. if (data.error) {
  477. this.summary.innerText = data.error.message;
  478. } else {
  479. this.summary.innerText = response.statusText;
  480. }
  481. return;
  482. }
  483. const data = await response.json() as APODResponse;
  484. if (data.media_type === 'image') {
  485. // Populate the image
  486. this.img.src = data.url;
  487. this.img.title = data.title;
  488. this.summary.innerText = data.title;
  489. if (data.copyright) {
  490. this.summary.innerText += ` (Copyright ${data.copyright})`;
  491. }
  492. } else {
  493. this.summary.innerText = 'Random APOD fetched was not an image.';
  494. }
  495. }
  496. /**
  497. * Get a random date string in YYYY-MM-DD format.
  498. */
  499. randomDate(): string {
  500. const start = new Date(2010, 1, 1);
  501. const end = new Date();
  502. const randomDate = new Date(start.getTime() + Math.random()*(end.getTime() - start.getTime()));
  503. return randomDate.toISOString().slice(0, 10);
  504. }
  505. }
  506. You've written all of the code before. All you've done is restructure it
  507. to use instance variables and move the image request to its own
  508. function.
  509. Next move the remaining logic in ``activate`` to a new, top-level
  510. function just below the ``APODWidget`` class definition. Modify the code
  511. to create a widget when one does not exist in the main JupyterLab area
  512. or to refresh the image in the existing widget when the command runs again.
  513. The code for the ``activate`` function should read as follows after
  514. these changes:
  515. .. code-block:: typescript
  516. /**
  517. * Activate the APOD widget extension.
  518. */
  519. function activate(app: JupyterFrontEnd, palette: ICommandPalette) {
  520. console.log('JupyterLab extension jupyterlab_apod is activated!');
  521. // Create a single widget
  522. const content = new APODWidget();
  523. const widget = new MainAreaWidget({content});
  524. widget.id = 'apod-jupyterlab';
  525. widget.title.label = 'Astronomy Picture';
  526. widget.title.closable = true;
  527. // Add an application command
  528. const command: string = 'apod:open';
  529. app.commands.addCommand(command, {
  530. label: 'Random Astronomy Picture',
  531. execute: () => {
  532. if (!widget.isAttached) {
  533. // Attach the widget to the main work area if it's not there
  534. app.shell.add(widget, 'main');
  535. }
  536. // Refresh the picture in the widget
  537. content.update();
  538. // Activate the widget
  539. app.shell.activateById(widget.id);
  540. }
  541. });
  542. // Add the command to the palette.
  543. palette.addItem({ command, category: 'Tutorial' });
  544. }
  545. Remove the ``activate`` function definition from the
  546. ``JupyterFrontEndPlugin`` object and refer instead to the top-level function
  547. like this:
  548. .. code-block:: typescript
  549. const extension: JupyterFrontEndPlugin<void> = {
  550. id: 'jupyterlab_apod',
  551. autoStart: true,
  552. requires: [ICommandPalette],
  553. activate: activate
  554. };
  555. Make sure you retain the ``export default extension;`` line in the file.
  556. Now build the extension again and refresh the JupyterLab browser tab.
  557. Run the *Random Astronomy Picture* command more than once without closing the
  558. panel. The picture should update each time you execute the command. Close
  559. the panel, run the command, and it should both reappear and show a new
  560. image.
  561. If anything is not working correctly, compare your code with the
  562. `04-refactor-and-refresh
  563. tag <https://github.com/jupyterlab/jupyterlab_apod/tree/3.0-04-refactor-and-refresh>`__
  564. to debug. Once it is working properly, commit it.
  565. .. code:: bash
  566. git add package.json src/index.ts
  567. git commit -m 'Refactor, refresh image'
  568. Restore panel state when the browser refreshes
  569. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  570. You may notice that every time you refresh your browser tab, the Astronomy Picture
  571. panel disappears, even if it was open before you refreshed. Other open
  572. panels, like notebooks, terminals, and text editors, all reappear and
  573. return to where you left them in the panel layout. You can make your
  574. extension behave this way too.
  575. Update the imports at the top of your ``index.ts`` file so that the
  576. entire list of import statements looks like the following:
  577. .. code-block:: typescript
  578. :emphasize-lines: 2,10
  579. import {
  580. ILayoutRestorer,
  581. JupyterFrontEnd,
  582. JupyterFrontEndPlugin
  583. } from '@jupyterlab/application';
  584. import {
  585. ICommandPalette,
  586. MainAreaWidget,
  587. WidgetTracker
  588. } from '@jupyterlab/apputils';
  589. import { Message } from '@lumino/messaging';
  590. import { Widget } from '@lumino/widgets';
  591. Then add the ``ILayoutRestorer`` interface to the ``JupyterFrontEndPlugin``
  592. definition. This addition passes the global ``LayoutRestorer`` as the
  593. third parameter of the ``activate`` function.
  594. .. code-block:: typescript
  595. :emphasize-lines: 4
  596. const extension: JupyterFrontEndPlugin<void> = {
  597. id: 'jupyterlab_apod',
  598. autoStart: true,
  599. requires: [ICommandPalette, ILayoutRestorer],
  600. activate: activate
  601. };
  602. Finally, rewrite the ``activate`` function so that it:
  603. 1. Declares a widget variable, but does not create an instance
  604. immediately.
  605. 2. Constructs a ``WidgetTracker`` and tells the ``ILayoutRestorer``
  606. to use it to save/restore panel state.
  607. 3. Creates, tracks, shows, and refreshes the widget panel appropriately.
  608. .. code-block:: typescript
  609. function activate(app: JupyterFrontEnd, palette: ICommandPalette, restorer: ILayoutRestorer) {
  610. console.log('JupyterLab extension jupyterlab_apod is activated!');
  611. // Declare a widget variable
  612. let widget: MainAreaWidget<APODWidget>;
  613. // Add an application command
  614. const command: string = 'apod:open';
  615. app.commands.addCommand(command, {
  616. label: 'Random Astronomy Picture',
  617. execute: () => {
  618. if (!widget || widget.isDisposed) {
  619. // Create a new widget if one does not exist
  620. // or if the previous one was disposed after closing the panel
  621. const content = new APODWidget();
  622. widget = new MainAreaWidget({content});
  623. widget.id = 'apod-jupyterlab';
  624. widget.title.label = 'Astronomy Picture';
  625. widget.title.closable = true;
  626. }
  627. if (!tracker.has(widget)) {
  628. // Track the state of the widget for later restoration
  629. tracker.add(widget);
  630. }
  631. if (!widget.isAttached) {
  632. // Attach the widget to the main work area if it's not there
  633. app.shell.add(widget, 'main');
  634. }
  635. widget.content.update();
  636. // Activate the widget
  637. app.shell.activateById(widget.id);
  638. }
  639. });
  640. // Add the command to the palette.
  641. palette.addItem({ command, category: 'Tutorial' });
  642. // Track and restore the widget state
  643. let tracker = new WidgetTracker<MainAreaWidget<APODWidget>>({
  644. namespace: 'apod'
  645. });
  646. restorer.restore(tracker, {
  647. command,
  648. name: () => 'apod'
  649. });
  650. }
  651. Rebuild your extension one last time and refresh your browser tab.
  652. Execute the *Random Astronomy Picture* command and validate that the panel
  653. appears with an image in it. Refresh the browser tab again. You should
  654. see an Astronomy Picture panel reappear immediately without running the command. Close
  655. the panel and refresh the browser tab. You should then not see an Astronomy Picture tab
  656. after the refresh.
  657. .. figure:: images/extension_tutorial_complete.png
  658. :align: center
  659. :class: jp-screenshot
  660. :alt: The completed extension, showing the Astronomy Picture of the Day for 24 Jul 2015.
  661. The completed extension, showing the `Astronomy Picture of the Day for 24 Jul 2015 <https://apod.nasa.gov/apod/ap150724.html>`__.
  662. Refer to the `05-restore-panel-state
  663. tag <https://github.com/jupyterlab/jupyterlab_apod/tree/3.0-05-restore-panel-state>`__
  664. if your extension is not working correctly. Make a commit when the state of your
  665. extension persists properly.
  666. .. code:: bash
  667. git add src/index.ts
  668. git commit -m 'Restore panel state'
  669. Congratulations! You've implemented all of the behaviors laid out at the start
  670. of this tutorial.
  671. .. _packaging your extension:
  672. Packaging your extension
  673. ------------------------
  674. JupyterLab extensions for JupyterLab 3.0 can be distributed as Python
  675. packages. The cookiecutter template we used contains all of the Python
  676. packaging instructions in the ``setup.py`` file to wrap your extension in a
  677. Python package. Before generating a package, we first need to install
  678. ``jupyter_packaging``.
  679. .. code:: bash
  680. pip install jupyter_packaging
  681. To create a Python source package (``.tar.gz``) in the ``dist/`` directory, do:
  682. .. code:: bash
  683. python setup.py sdist
  684. To create a Python wheel package (``.whl``) in the ``dist/`` directory, do:
  685. .. code:: bash
  686. python setup.py bdist_wheel
  687. Both of these commands will build the JavaScript into a bundle in the
  688. ``jupyterlab_apod/static`` directory, which is then distributed with the
  689. Python package. This bundle will include any necessary JavaScript dependencies
  690. as well. You may want to check in the ``jupyterlab_apod/static`` directory to
  691. retain a record of what JavaScript is distributed in your package, or you may
  692. want to keep this "build artifact" out of your source repository history.
  693. You can now try installing your extension as a user would. Open a new terminal
  694. and run the following commands to create a new environment and install your
  695. extension.
  696. .. code:: bash
  697. conda create -n jupyterlab-apod jupyterlab
  698. conda activate jupyterlab-apod
  699. pip install jupyterlab_apod/dist/jupyterlab_apod-0.1.0-py3-none-any.whl
  700. jupyter lab
  701. You should see a fresh JupyterLab browser tab appear. When it does,
  702. execute the *Random Astronomy Picture* command to check that your extension
  703. works.
  704. .. _extension_tutorial_publish:
  705. Publishing your extension
  706. -------------------------
  707. You can publish your Python package to the `PyPI <https://pypi.org>`_ or
  708. `conda-forge <https://conda-forge.org>`_ repositories so users can easily
  709. install the extension using ``pip`` or ``conda``.
  710. You may want to also publish your extension as a JavaScript package to the
  711. `npm <https://www.npmjs.com>`_ package repository for several reasons:
  712. 1. Distributing an extension as an npm package allows users to compile the
  713. extension into JupyterLab explicitly (similar to how was done in JupyterLab
  714. versions 1 and 2), which leads to a more optimal JupyterLab package.
  715. 2. As we saw above, JupyterLab enables extensions to use services provided by
  716. other extensions. For example, our extension above uses the ``ICommandPalette``
  717. and ``ILayoutRestorer`` services provided by core extensions in
  718. JupyterLab. We were able to tell JupyterLab we required these services by
  719. importing their tokens from the ``@jupyterlab/apputils`` and
  720. ``@jupyterlab/application`` npm packages and listing them in our plugin
  721. definition. If you want to provide a service to the JupyterLab system
  722. for other extensions to use, you will need to publish your JavaScript
  723. package to npm so other extensions can depend on it and import and require
  724. your token.
  725. Learn more
  726. ----------
  727. You've completed the tutorial. Nicely done! If you want to keep
  728. learning, here are some suggestions about what to try next:
  729. - Add the image description that comes in the API response to the panel.
  730. - Assign a default hotkey to the *Random Astronomy Picture* command.
  731. - Make the image a link to the picture on the NASA website (URLs are of the form ``https://apod.nasa.gov/apod/apYYMMDD.html``).
  732. - Make the image title and description update after the image loads so that the picture and description are always synced.
  733. - Give users the ability to pin pictures in separate, permanent panels.
  734. - Add a setting for the user to put in their `API key <https://api.nasa.gov/#authentication>`__ so they can make many more requests per hour than the demo key allows.
  735. - Push your extension git repository to GitHub.
  736. - Learn how to write :ref:`other kinds of extensions <developer_extensions>`.