PhotonUI logo

PhotonUI

A javascript framework to create user interfaces

Quick Start

Welcome to the PhotonUI quick start guide. If you want to learn how to build a UI using PhotonUI, you are in the right place.

Get PhotonUI

Standalone Version

To start using the standalone version of PhotonUI in your projects, you first need to download it:

All the files you need are in the dist folder. You just have to import

  • photonui-base.css (must be imported first),

  • photonui-theme-particle.css,

  • andphotonui.js (or photonui.min.js)

in your page:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>Boilerplate</title>
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        
        <link type="text/css" rel="stylesheet" href="photonui/photonui-base.css" />
        <link type="text/css" rel="stylesheet" href="photonui/photonui-theme-particle.css" />
        <script src="photonui/photonui.js"></script>
        
    </head>
    <body>
    </body>
</html>

NPM and Browserify

If you are using Browserify in your project, a NPM package is available. To install it, juste type:

1
npm install --save photonui

then, to use it in your project you just have to import PhotonUI:

1
var photonui = require("photonui");

NOTE: do not forget to import CSS files in your HTML page:

1
2
<link rel="stylesheet" href="./node_modules/photonui/dist/photonui-base.css" />
<link rel="stylesheet" href="./node_modules/photonui/dist/photonui-theme-particle.css" />

Using Your First Widgets

Some widgets, like photonui.Window are “root widgets” ; that means they don’t need a parent to be displayed on the page. To use a root widget, you just have to instantiate its class with the desired parameters:

1
2
3
4
5
6
var win = new photonui.Window({
    title: "Hello World",
    height: 100,
    x: 100, y: 400,
    visible: true
});

The majority of the widgets are not “root widgets”, they need a parent to be displayed.

You can give them any DOM element as parent:

1
2
3
4
5
// Create a button
var btn = new photonui.Button();
// and insert it in the HTML element whose id is "demo"
photonui.domInsert(btn, "demo");

… or any PhotonUI widget that can contain other widgets (“container” and “layout” widgets):

1
2
3
4
5
6
7
8
9
10
11
12
13
// Create a window
var win = new photonui.Window({
    title: "Hello World",
    padding: 10,
    x: 100, y: 400,
    visible: true
});
// Create a button
var btn = new photonui.Button();
// Add the button in the window
win.child = btn;

Binding Events

Each PhotonUI Widget comes with a set of defined events (called wEvent) to which you can attach one or more callbacks.

For example, the photonui.Button widget has a click wEvent that is fired each time the user clicks on the button:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Create a button
var btn = new photonui.Button();
// define a callback for the "click" WEvent
function onBtnClicked(widget, event) {
    alert("Button clicked!");
}
btn.registerCallback(
    "clic-clac",   // id (any string you want, must be unique for the widget)
    "click",       // wEvent (the name of the event)
    onBtnClicked   // callback (called when the wEvent is fired)
);
// and insert it in the HTML element whose id is "demo"
photonui.domInsert(btn, "demo");

Building More Complex UI Using Layouts

There are 5 main types of widgets in PhotonUI:

So if we want to create a window with two buttons inside, we will need to use a layout. The most basic and simple layout widget is photonui.BoxLayout. Let’s use it to build our UI:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// Create each widget of the UI
var win = new photonui.Window({
    title: "Layout Example",
    x: 100, y: 400,
    visible: true
});
var box = new photonui.BoxLayout({
    orientation: "vertical"
});
var btn1 = new photonui.Button({
    text: "Button 1"
});
var btn2 = new photonui.Button({
    text: "Button 2"
});
// Build the UI using the layout
box.addChild(btn1);  // Alternative syntax:
box.addChild(btn2);  // box.children = [btn1, btn2];
win.child = box;
// Add a callback to the first button
btn1.registerCallback("foobar", "click", function(widget, event) {
    alert("Button clicked!");
});

One more thing

In the examples above, we “manually” built the UI by declaring several variables to store widgets and then assembling everything. There is a more efficient way to build your UI (called “declarative way”) that is used in most of the example of the PhotonUI documentation.

Let’s rewrite our last example (the window with two buttons) in the declarative way:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
new photonui.Window({
    title: "Layout Example",
    x: 100, y: 400,
    visible: true,
    child: new photonui.BoxLayout({
        orientation: "vertical",
        children: [
            new photonui.Button({
                text: "Button 1",
                callbacks: {
                    click: function(widget, event) {
                        alert("Button clicked!");
                    }
                }
            }),
            new photonui.Button({
                text: "Button 2"
            })
        ]
    })
});

Here We Are

You are now ready to start using PhotonUI on your own project. :)