Developer Blog

Storing User Settings with LocalConfig

A common question from coders new to the Boxee platform is the storage of configuration settings for their users. From display preferences for the user interface to ID/password combos for subscription systems, many of the apps on Boxee need the ability to store these user preferences.

Many developers ask how to easily write files to Boxee’s temporary directory, taking it upon themselves to develop their own file format to store their settings in. However, if your preferences can be stored as key/value pairs, Boxee has a built in class that makes storing settings far easier called LocalConfig.

LocalConfig is the object all Boxee apps can use to store key/value pairs that will persist from user session to user session on the same Boxee install. While these settings will have to be entered (for now at least) in every Boxee install the user logs into, it is an easy way to keep your users from having to input the same data for every session.

Let’s take a look at the LocalConfig object in action with the example storing a username and password combination. The first thing we want to do is store a username and password with our app. We can do this easily first by creating a login button in our main.xml.

<control type="button" id="100">
	<description>Login</description>
	<width>114</width>
	<height>37</height>
	<texturefocus>button-loginfocused.png</texturefocus>
	<texturenofocus>button-login.png</texturenofocus>	
</control>

Once the user clicks “Login,” we want to present the user to input their username and password with Boxee’s built-in keyboard interface. We can accomplish this by adding two ShowDialogKeyboard requests to an onclick event for the login button.

<control type="button" id="100">
	<description>Login</description>
	<width>114</width>
	<height>37</height>
	<texturefocus>button-loginfocused.png</texturefocus>
	<texturenofocus>button-login.png</texturenofocus>	
	<onclick lang="python"><![CDATA[
emailaddress = mc.ShowDialogKeyboard("Email", "", False)
userpassword = mc.ShowDialogKeyboard("Password", "", True)
]]></onclick>
</control>

Next we’ll check to make sure the user entered their username and password and, if so, store them in our LocalConfig. We add this code to the login event.

<control type="button" id="100">
	<description>Login</description>
	<width>114</width>
	<height>37</height>
	<texturefocus>button-loginfocused.png</texturefocus>
	<texturenofocus>button-login.png</texturenofocus>	
	<onclick lang="python"><![CDATA[
emailaddress = mc.ShowDialogKeyboard("Email", "", False)
userpassword = mc.ShowDialogKeyboard("Password", "", True)
if emailaddress and userpassword:
	config = mc.GetApp().GetLocalConfig()
	config.SetValue("username", emailaddress)
	config.SetValue("password", userpassword)
	mc.ShowDialogNotification("Credentials stored.")
       # Insert login code here
else:
	mc.ShowDialogNotification("Please enter username and password.")
]]></onclick>
</control>

Now that we have stored the username and password, we want to make sure the app knows this and logs the user every time the application is launched without asking the user for his/her credentials again. With the LocalConfig object, we can check if values exist in an onload event for the window and then take appropriate action if it does.

config = mc.GetApp().GetLocalConfig()
emailaddress = config.GetValue("username")
userpassword = config.GetValue("password")
 
if emailaddress:
	mc.ShowDialogNotification("Logging in...")
        # Insert login code here

Lastly, we would be remiss in our duties as courteous developers if we didn’t also give our users the ability to logout. With the paradigm we’ve set up here using LocalConfig, all we have to do is clear the LocalConfig for the app and the user will not no longer login on app start.

<control type="button" id="101">
	<description>Logout</description>
	<posx>200</posx>
	<posy>0</posy>
	<width>114</width>
	<height>37</height>
	<texturefocus>button-logoutfocused.png</texturefocus>
	<texturenofocus>button-logout.png</texturenofocus>
	<onclick lang="python"><![CDATA[
config = mc.GetApp().GetLocalConfig()
config.ResetAll()	
mc.ShowDialogNotification("Logging out...")
# Insert logout code here
]]></onclick>
</control>

Here’s the complete main.xml as an example. Enjoy!

<?xml version="1.0"?>
<window type="window" id="14000">
<onload lang="python"><![CDATA[
config = mc.GetApp().GetLocalConfig()
emailaddress = config.GetValue("username")
userpassword = config.GetValue("password")
 
if emailaddress:
	mc.ShowDialogNotification("Logging in...")
	# Insert login code here
]]></onload>
	<defaultcontrol always="true">111</defaultcontrol>
	<allowoverlay>no</allowoverlay>
	<controls>
		<control type="group">
			<control type="button" id="100">
				<description>Login</description>
				<width>114</width>
				<height>37</height>
				<texturefocus>button-loginfocused.png</texturefocus>
				<texturenofocus>button-login.png</texturenofocus>	
				<onclick lang="python"><![CDATA[
emailaddress = mc.ShowDialogKeyboard("Email", "", False)
userpassword = mc.ShowDialogKeyboard("Password", "", True)
if emailaddress and userpassword:
	config = mc.GetApp().GetLocalConfig()
	config.SetValue("username", emailaddress)
	config.SetValue("password", userpassword)
	mc.ShowDialogNotification("Credentials stored.")
else:
	mc.ShowDialogNotification("Please enter username and password.")
]]></onclick>
			</control>
			<control type="button" id="101">
				<description>Logout</description>
				<posx>200</posx>
				<posy>0</posy>
				<width>114</width>
				<height>37</height>
				<texturefocus>button-logoutfocused.png</texturefocus>
				<texturenofocus>button-logout.png</texturenofocus>
				<onclick lang="python"><![CDATA[
config = mc.GetApp().GetLocalConfig()
config.ResetAll()	
mc.ShowDialogNotification("Logging out...")
]]></onclick>
			</control>
		</control>
	</controls>
</window>
July 2, 2010 at 4:44 pm