Add documentation for widget

Added documentation for current widget usage, currently supported arguments, using custom CSS/JS
kiwix · Aug 6, 2022 · f42d773 · f42d773
1 parent 08bb95d
commit f42d773
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 0 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,3 +12,4 @@ Welcome to libkiwix's documentation!
 
    usage
    api/ref_api
+   widget
diff --git a/docs/widget.rst b/docs/widget.rst
@@ -0,0 +1,88 @@
+Kiwix serve widget
+====================
+
+Introduction
+------------
+
+The kiwix-serve widget provides an easy to embed way to show the `kiwix-serve` homepage.
+
+Usage
+-----
+
+To use the widget, simply add an iframe with its `src` attribute set to the `widget` endpoint.
+Example HTML Page ::
+
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+    <title>Widget Test</title>
+    </head>
+    <body>
+    <iframe src="http://192.168.18.8:8080/widget?disabledesc&disablefilter&disabledownload" width=1000 height=1000></iframe>
+    </body>
+    </html>
+
+This creates an iframe with the kiwix-serve homepage contents.
+
+Arguments are explained below.
+
+Possible Arguments
+-------------------
+
+Currently, the following arguments are supported.
+
+disabledesc (value = N/A)
+    Disables the description part of a tile.
+
+disablefilter (value = N/A)
+    Disables the search filters: language, category, tag and search function.
+
+disableclick (value = N/A)
+    Disables clicking the book to open it for reading.
+
+disabledownload (value = N/A)
+    Disables the download button (if avaialable at all) on the tile.
+
+book (value = yes)
+    Multivalue argument. Takes the name of books to display.
+
+    Example::
+    
+        <iframe src="http://192.168.18.8:8080/widget?book=wikiversity_en_all&book=bitcoin_en_all">
+
+Custom CSS and JS
+-----------------
+
+You can add your custom CSS rules and Javascript code to the widget.
+
+To do that, use the following code as template::
+
+    <iframe id="receiver" src="http://192.168.18.8:8080/widget?disabledesc=&disablefilter=&disabledownload=" width="1000" height="1000">
+    <p>Your browser does not support iframes.</p>
+    </iframe>
+
+    <script>
+    window.onload = function() {
+    var receiver = document.getElementById('receiver').contentWindow;
+    function sendMessage() {
+        let msg = {
+        css: `
+        .book__header {
+            color:red;
+        }`,
+        js: `
+        function widgetTest() {
+        console.log("Testing widget");
+        }
+        widgetTest();
+        `
+        }
+        receiver.postMessage(msg, 'http://192.168.18.8:8080/widget');
+    }
+    sendMessage();
+    }
+    </script>
+
+
+The CSS/JS fields are optional, you may send both or only one.
+
Original file line number	Diff line number	Diff line change
Expand Up		@@ -12,3 +12,4 @@ Welcome to libkiwix's documentation!

		usage
		api/ref_api
		widget