Tutorials for common tasks

Following are some basic instructions for performing most common GUI and Python tasks with htmlPy.

GUI to Python calls

These calls work only for htmlPy.AppGUI applications.

An essential aspect of GUI is to attach back-end calls to GUI events. htmlPy needs the corresponding back-end functions to be selectively exposed to GUI. The calls from GUI can be done in very HTML way.

The back-end functions that have to be attached to GUI events are defined as follows

import htmlPy
import json
from sample_app import app as htmlPy_app

class ClassName(htmlPy.Object):
    # GUI callable functions have to be inside a class.
    # The class should be inherited from htmlPy.Object.

    def __init__(self):
        super(ClassName. self).__init__()
        # Initialize the class here, if required.

    def function_name(self):
        # This is the function exposed to GUI events.
        # You can change app HTML from here.
        # Or, you can do pretty much any python from here.
        # NOTE: @htmlPy.Slot decorater needs argument and return data-types.
        # Refer to API documentation.

    @htmlPy.Slot(str, result=str)
    def form_function_name(self, json_data):
        # @htmlPy.Slot(arg1_type, arg2_type, ..., result=return_type)
        # This function can be used for GUI forms.
        form_data = json.loads(json_data)
        return json.dumps(form_data)

    def javascript_function(self):
        # Any function decorated with @htmlPy.Slot decorater can be called
        # using javascript in GUI

## You have to bind the class instance to the AppGUI instance to be
## callable from GUI

After exposing the class methods to GUI, they can be called from HTML as follows

<a href="ClassName.function_name" id="link" data-bind="true">GUI clickable link</a>
<!-- The "a" tag needs to have unique ID and data-bind attribute set to "true"
The ClassName and function_name have to be set in href attribute as displayed above.
The "a" tag can be styled using CSS with other HTML elements inside it -->

<form action="ClassName.form_function_name" id="form" data-bind="true">
    <input type="text" id="form_input" name="name">
    <input type="submit" value="Submit" id="form_submit">
<!-- The "form" tag needs to have unique ID and data-bind attribute set to "true".
The ClassName and form_function_name have to be set in action attribute as
displayed above. The argument given to ClassName.form_function_name on form submit
will be a json string of the form data. -->

// You can treat the class inherited from htmlPy.Object (in this case, ClassName)
// as a javascript object.

Python to GUI calls

from sample_app import app
# app imported from sample_app file is an instance of htmlPy.AppGUI class.

## Change HTML of the app
app.html = u"<html></html>"

## Change HTML of the app using Jinja2 templates
app.template = ("./index.html", {"template_variable_name": "value"})

## Execute javascript on currently displayed HTML in the app
app.evaluate_javascript("alert('Hello from back-end')")

General structure of htmlPy applications

Following should be a general directory structure for htmlPy applications


main.py is the driver file for the applications. In the driver file, you should initialize GUI, import functionalities from back_end_codes and bind it to GUI as explained on the first section of this page. Refer this section for sample driver file.

In the back_end_codes, you can import the app from main.py and perform operations on in as explained in this section.

Integration with django

Django can be used for standalone application development using htmlPy. The integration can be done easily. In the previous section, the django application and projects can be kept in back_end_codes directory. In the GUI driver file, include this code before initializing GUI for loading django settings.

import os
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "<project_name>.settings")


TODO: Add sample application developed using django and htmlPy

Using file input

htmlPy replaces the HTML file input code with PyQt’s file dialog. To use file input, write the file input tag with an additional data attribute for filtering extensions, if required. The filter attribute string should be of the form "[{'title': 'title for extension', 'extensions': 'space separated extensions'}, {'title': 'title for another extension', 'extensions': 'space separated extensions'}]". For example

<input type="file" name="file" id="file" data-filter="[{'title': 'Images', 'extensions': '*.png *.xpm *.jpg'}, {'title': 'Documents', 'extensions': '*.pdf *.doc *.docx'}]">

The json returned to the python backend for the form will have the absolute path of the selected file as the input value.