Wallpaper Engine

Wallpaper Engine

71 ratings
Advanced: Web user customization - colors/sliders/booleans/combo boxes
By Biohazard
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.
 
Rate  
Favorite
Favorited
Unfavorite
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" }
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.
< >
63 Comments
Biohazard  [author] Aug 21 @ 2:57am 
@Squee
Sorry I miss the comments in these guides somehow. Arthesian mentioned that before I think, tbh I'm not quite sure right now why the translation doesn't kick in there.

The default language is always en-us for the entire program if there are strings missing - or does not work as expected?

I think there is a separate guide for image files and directories.
s м о ᴳ ᴼ ᴺ Aug 21 @ 2:27am 
just checked it: type directory works , but why is it not listed here?
s м о ᴳ ᴼ ᴺ Aug 21 @ 2:24am 
what about type directory or is there none? read on https://steamcommunity.com/app/431960/discussions/1/2333276539598127985/
ÐarkruneÐK Aug 18 @ 3:35pm 
Is it possible to choose the default language used by the localization? Is there any system in which it will choose if none apply?
LY_aplaser Jul 31 @ 8:32pm 
中文有没有啊啊啊啊啊
Squee Jul 23 @ 7:27am 
It works ... but .. is it also possible to translate the labels of the combo/select input?
Squee Jul 22 @ 2:45pm 
@Bio Thanks .. I will test it again. Had a script that could already convert the old json settings to way the translation work so I don't have to edit them all by hand :)
Biohazard  [author] Jul 18 @ 1:56pm 
@Squee
Looks like it isn't loading the localization object for local files right now, should be fixed on the next beta update.
Christina-LovelyKiss Jul 18 @ 11:36am 
111
Squee Jul 12 @ 1:57pm 
Question about the translations. Is the guide still correct, could I be missing something? When trying the example json from the guide it doesn't seem to translate for me. I just see ui_background as the label in the settings and it wasn't translated .

My language is set to english ( default ) , the general properties callback reports "en-us" as langauge.