Advanced: Web user customization - colors/sliders/booleans/combo boxes

Add customizable options to your web wallpaper to make it more interesting and unique! This guide will show you how you can add custom colors, sliders and checkboxes to let users control your web wallpaper in all kinds of ways.

NEW DOCUMENTATION WEBSITE OUT

Please check out our new documentation website, the guides on Steam are old and deprecated!

https://docs.wallpaperengine.io

Prerequisites

This tutorial requires knowledge about HTML, JavaScript and JSON. If you have never made a web wallpaper before, check out the starter tutorial for web wallpapers here: http://steamcommunity.com/sharedfiles/filedetails/?id=770801435

Introduction

Follow this tutorial to learn how you can add customization controls to the wallpaper browser for your own web wallpaper! Making it possible for the user to change colors and tweak your wallpaper to their preferences will make it all the more interesting. At this time you can create color pickers, sliders and check boxes to the browser and handle those in your own JavaScript accordingly.

Declaring your properties

First, create your web wallpaper as usual and navigate to its path (click on edit -> open in explorer). Now open the project.json in your favorite text editor. First, you will need to create two objects inside of the JSON file, general and properties. If you set a custom scheme color in the editor, these properties might exist already. Your project file should now look similar to this one:

{
    "file" : "index.html",
    "general" : 
    {
        "properties" : 
        {
        }
    },
    "title" : "Advanced Web Tutorial - User Properties",
    "type" : "web"
}

Adding colors

We are going to add two colors now, schemecolor and customcolor. schemecolor is a predefined name that will also change the DWM/Windows color accordingly, but you can call your custom properties whatever you like. Each property has three members:

• text: a string that is shown in the editor, this is visible to the user.
  
• type: a string that defines which control to use in the editor, the following are possible: color, text, slider, bool.
  
• value: the default value either as a string (color/text type), integer (slider) or boolean (bool). Colors are stored as floats in RGB with spaces inbetween, so red (#F00) would equivalent to this: "1 0 0".

Adding the schemecolor and customcolor will change our project file to this:

{
	"file" : "index.html",
	"general" : 
	{
		"properties" : 
		{
			"customcolor" : 
			{
				"text" : "User accent",
				"type" : "color",
				"value" : "0.2 0.8 1"
			},
			"schemecolor" : 
			{
				"text" : "Scheme color",
				"type" : "color",
				"value" : "0.7 0.2 0.1"
			}
		}
	},
	"title" : "Advanced Web Tutorial - User Properties",
	"type" : "web"
}

Adding a boolean

This is straight forward, just change the type to 'bool' and use either true or false as value, we will call this new property custombool:

{
    "file" : "index.html",
    "general" : 
    {
        "properties" : 
        {
            "customcolor" : 
            {
                "text" : "User accent",
                "type" : "color",
                "value" : "0.2 0.8 1"
            },
            "schemecolor" : 
            {
                "text" : "Scheme color",
                "type" : "color",
                "value" : "0.7 0.2 0.1"
            },
            "custombool" : 
            {
                "text" : "User bool",
                "type" : "bool",
                "value" : false
            }
        }
    },
    "title" : "Advanced Web Tutorial - User Properties",
    "type" : "web"
}

Adding a slider (integer)

Besides changing the type to 'slider' and specifiying an integer as value, you also need to define a 'max' and 'min' integer. We are going to set them to 0 and 100 respectively here and assign the property name 'customint'.

Optionally set 'editable' to 'true', which will allow users to enter their own values instead of being limited to the slider range. Make sure to handle arbitrary value correctly.

{
    "file" : "index.html",
    "general" : 
    {
        "properties" : 
        {
            "customcolor" : 
            {
                "text" : "User accent",
                "type" : "color",
                "value" : "0.2 0.8 1"
            },
            "schemecolor" : 
            {
                "text" : "Scheme color",
                "type" : "color",
                "value" : "0.7 0.2 0.1"
            },
            "custombool" : 
            {
                "text" : "User bool",
                "type" : "bool",
                "value" : false
            },
            "customint" :
            {
                "text" : "User slider",
                "type" : "slider",
                "value" : 50,
                "min" : 0,
                "max" : 100,
                "editable" : true
            }
        }
    },
    "title" : "Advanced Web Tutorial - User Properties",
    "type" : "web"
}

Adding a combo box (integer or string)

A combo box requires the special member 'options' that points to an array of objects, which each have a 'value' and 'label' member themselves. The 'value' of an option will be sent to the web wallpaper, the 'label' will be shown to the user. The type name for this property is 'combo'. You can add a combo box as follows:

{
    "file" : "index.html",
    "general" : 
    {
        "properties" : 
        {
            "customcolor" : 
            {
                "text" : "User accent",
                "type" : "color",
                "value" : "0.2 0.8 1"
            },
            "schemecolor" : 
            {
                "text" : "Scheme color",
                "type" : "color",
                "value" : "0.7 0.2 0.1"
            },
            "custombool" : 
            {
                "text" : "User bool",
                "type" : "bool",
                "value" : false
            },
            "customint" :
            {
                "text" : "User slider",
                "type" : "slider",
                "value" : 50,
                "min" : 0,
                "max" : 100
            },
            "customcombo" :
            {
                "text" : "User combo",
                "type" : "combo",
                "value" : 1,
                "options" :
                [
                    {
                        "value" : 1,
                        "label" : "First"
                    },
                    {
                        "value" : 2,
                        "label" : "Second"
                    },
                    {
                        "value" : 3,
                        "label" : "Third"
                    }
                ]
            }
        }
    },
    "title" : "Advanced Web Tutorial - User Properties",
    "type" : "web"
}

Now these five properties (customcolor, schemecolor, custombool, customint and customcombo) will show up in the browser already. We still need to process them in the web wallpaper though which the next section will explain.

Adding a text input

A text input allows a user to send a string of arbitrary text to the wallpaper. If you just want to send a number though, consider using the slider with 'editable':true. Furthermore, you must not use this input for passwords or user credentials. For starters, because the data is stored in plaintext.

{
    "file" : "index.html",
    "general" : 
    {
        "properties" : 
        {
            "customtext" : 
            {
                "text" : "User text",
                "type" : "textinput",
                "value" : ""
            }
        }
    }
}

Reading properties from the wallpaper

Using JavaScript, you need to extend the global 'window' object with a new member, named 'wallpaperPropertyListener' which itself is an object. Define it like this:

window.wallpaperPropertyListener = {

};

Now create a new member named 'applyUserProperties' which is a function that takes one argument, the properties:

window.wallpaperPropertyListener = {
    applyUserProperties: function(properties) {

    }
};

This function will be called as soon as the document has been loaded to apply initial properties but also while the user is applying changes in the browser. The 'properties' argument is an object that contains all changed properties, so before accessing them, make sure they are indeed defined:

window.wallpaperPropertyListener = {
    applyUserProperties: function(properties) {

        // Read scheme color
        if (properties.schemecolor) {
            // Convert the scheme color to be applied as a CSS style
            var schemeColor = properties.schemecolor.value.split(' ');
            schemeColor = schemeColor.map(function(c) {
                return Math.ceil(c * 255);
            });
            var schemeColorAsCSS = 'rgb(' + schemeColor + ')';
        }

        // Read custom color
        if (properties.customcolor) {
            // Convert the custom color to be applied as a CSS style
            var customColor = properties.customcolor.value.split(' ');
            customColor = customColor.map(function(c) {
                return Math.ceil(c * 255);
            });
            var customColorAsCSS = 'rgb(' + customColor + ')';
        }

        // Read custom boolean
        if (properties.custombool) {
            var myBoolValue = properties.custombool.value;
        }

        // Read custom slider
        if (properties.customint) {
            var myIntValue = properties.customint.value;
        }

        // Read custom combo box
        if (properties.customcombo) {
            var myComboValue = properties.customcombo.value;
        }
    }
};

The two color properties arrive as strings like such: '1 0 0' or '0.2 0.566 0'. So you can use the above code to translate these strings into CSS style values, for example: '1 0 0' turns into 'rgb(255, 0, 0)'. The boolean property is just that, a bool, and the slider property is an integer, access them both by their .value member as demonstrated above. The combo box can have different types, in this example we use integers as values.

From here on out it's up to you! Use the properties to change colors or other options in your wallpaper dynamically and make it even more impressive.

Conditions to control property visibility

You can optionally add a condition to a property to toggle its visibility based on other properties. Just add a string with the key 'condition' like this:

{
    "file" : "index.html",
    "general" : 
    {
        "properties" : 
        {
            "custombool" : 
            {
                "text" : "User bool",
                "type" : "bool",
                "value" : false
            },
            "customint" :
            {
                "text" : "User slider",
                "type" : "slider",
                "value" : 50,
                "min" : 0,
                "max" : 100,
                "condition" : "custombool.value"
            }
        }
    },
    "title" : "Advanced Web Tutorial - User Properties",
    "type" : "web"
}

The string is evaluated as JavaScript, so you can also use more complex expressions:

{
    "file" : "index.html",
    "general" : 
    {
        "properties" : 
        {
            "customcombo" :
            {
                "text" : "User combo",
                "type" : "combo",
                "value" : 1,
                "options" :
                [
                    {
                        "value" : 1,
                        "label" : "First"
                    },
                    {
                        "value" : 2,
                        "label" : "Second"
                    },
                    {
                        "value" : 3,
                        "label" : "Third"
                    }
                ]
            },
            "customint" :
            {
                "text" : "User slider",
                "type" : "slider",
                "value" : 50,
                "min" : 0,
                "max" : 100,
                "condition" : "customcombo.value == 2"
            }
        }
    },
    "title" : "Advanced Web Tutorial - User Properties",
    "type" : "web"
}

Translating properties

To translate properties, add a new object 'localization' next to 'properties'. This object holds members with the shorthand notation for each language (check the /locale/ directory for currently available languages).

Use a token for the 'text' value of your properties that starts with ui_ and replicate this token including its translation for each language. Make sure that you don't forget the ui_ prefix or the token won't be accepted.

{
    "file" : "index.html",
    "general" : 
    {
        "properties" : 
        {
            "customcolor" : 
            {
                "text" : "ui_background",
                "type" : "color",
                "value" : "0.2 0.8 1"
            }
        },
        "localization" : 
        {
            "en-us" :
            {
                "ui_background" : "Background"
            },
            "de-de" :
            {
                "ui_background" : "Hintergrund"
            }
        }
    },
    "title" : "Advanced Web Tutorial - User Properties",
    "type" : "web"
}

You can find a additional tutorial about translations by Arthesian here. It simplifies the creation of the project.json:

http://steamcommunity.com/sharedfiles/filedetails/?id=1267591429

Attachments

Demo wallpaper with user properties: http://www.mediafire .com/file/n5yaxssy4ggvpv9/web_properties_v2.zip (REMOVE THE SPACE.)
Copy this folder into wallpaper_engine/projects/myprojects to use it.