# HG changeset patch
# User Sebastien Jodogne <s.jodogne@gmail.com>
# Date 1693310688 -7200
# Node ID eb49a4ad8fbc1704f20f9990617ce07e62b9d682
# Parent  01f61385877fd90be23f6799e720f9585aff9ef8
Python plugin: Extending the Orthanc Explorer interface

diff -r 01f61385877f -r eb49a4ad8fbc Sphinx/source/plugins/python.rst
--- a/Sphinx/source/plugins/python.rst	Tue Aug 29 13:45:49 2023 +0200
+++ b/Sphinx/source/plugins/python.rst	Tue Aug 29 14:04:48 2023 +0200
@@ -813,6 +813,37 @@
                     :language: python
 
 
+.. _python_extend_orthanc_explorer:
+
+Extending the Orthanc Explorer interface
+........................................
+
+Here is a sample plugin that adds a new button to Orthanc Explorer
+that triggers a Python function:
+
+.. literalinclude:: python/sample-python-button.py
+                    :language: python
+
+As can be seen in this sample:
+
+* The call to ``orthanc.ExtendOrthancExplorer()`` installs the button
+  with JavaScript code that uses the `jQuery Mobile framework
+  <https://demos.jquerymobile.com/1.1.0/>`__ (as of Orthanc 1.12.1,
+  version 1.1.0 of jQuery Mobile is used in Orthanc Explorer).
+
+* If clicking on the button, a GET call to the REST API is made to
+  ``../execute-python``. The prefix ``../`` stems from the fact that
+  Orthanc Explorer is branched inside the ``app/`` folder of the REST
+  API of Orthanc.
+
+* The GET call to ``../execute-python`` executes the
+  ``ExecutePython()`` callback function that is written in Python.
+
+Note that it is only possible to extend Orthanc Explorer 1, which is
+the built-in Web interface of Orthanc. It is not possible to extend
+the :ref:`Orthanc Explorer 2 <orthanc-explorer-2>` interface.
+
+
 Performance and concurrency
 ---------------------------
 
diff -r 01f61385877f -r eb49a4ad8fbc Sphinx/source/plugins/python/sample-python-button.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Sphinx/source/plugins/python/sample-python-button.py	Tue Aug 29 14:04:48 2023 +0200
@@ -0,0 +1,30 @@
+import orthanc
+import platform
+
+def ExecutePython(output, uri, **request):
+    s = 'Python version: %s' % platform.python_version()
+    output.AnswerBuffer(s, 'text/plain')
+
+orthanc.RegisterRestCallback('/execute-python', ExecutePython)
+
+orthanc.ExtendOrthancExplorer('''
+$('#lookup').live('pagebeforeshow', function() {
+  $('#sample-python-button').remove();
+
+  var b = $('<a>')
+      .attr('id', 'sample-python-button')
+      .attr('data-role', 'button')
+      .attr('href', '#')
+      .attr('data-icon', 'forward')
+      .attr('data-theme', 'a')
+      .text('Execute sample Python plugin')
+      .button()
+      .click(function(e) {
+        $.get('../execute-python', function(answer) {
+          alert(answer);
+        });
+      });
+
+  b.insertAfter($('#lookup-result'));
+});
+''')