Skip to content

Saving user settings

Jump to bottom Edit New page
Brent Moberly edited this page Jan 12, 2015 · 1 revision

###Overview

This tutorial will demonstrate how to use the InCert engine's persistent settings store to preserve user settings across multiple sessions.

Requirements

In order to complete this tutorial, you will need the following:

  • A web-server to host your content files
  • An operational InCert server
  • An xml or text editor

Setup

This tutorial assumes that you have completed the tutorial, Handling authentication issues, and have a version of the engine that will start and attempt to contact your web-server.

Preserving user settings

As we have seen, the InCert engine features a flexible, temporary settings store that can be leveraged to preserve state while the engine is running. There are some cases, though, where you might want to preserve settings between engine sessions. For example, it would be nice if the engine would remember the user's username between sessions. The Settings.PersistSettingsString and Settings.RetrieveSettingsString tasks allow for this functionality.

Security and implementation

Before we get to the tutorial proper, we should note two things:

  • Security - the engine preserves all settings as string data via Microsoft's Application Settings Architecture. The result is, basically, that the preserved settings are serialized to Xml and saved to a "user.config" file in the user's application data folder. All of the data saved to this file is readable to all users who have access to the file, so you do not want to use Settings.PersistSettingsString or Settings.RetrieveSettingsString to save or retrieve sensitive information.
  • Persistence over different engine versions - currently, updating the engine to a new version will reset its persistent settings store.

Saving the user's username

  1. In tasklist.xml, add the following to the start of the authenticate branch:
<Settings.RetrieveSettingsString>
  <Properties>
    <Setter key="username">Username</Setter>
  </Properties>
</Settings.RetrieveSettingsString>

This task block will retrieve the preserved setting associated with the key Username and assign it to the username temporary setting. If the key Username does not exist in the preserved settings store, an empty string ("") will be assigned to the username temporary setting.

  1. In tasklist.xml, add the following to the authenticate branch immediately after the UserInterface.ShowBorderedBannerModel task block:
<Settings.PersistSettingsString>
  <Properties>
    <Setter key="username">Username</Setter>
  </Properties>
</Settings.PersistSettingsString>

This task block will persist the contents of the username temporary settings string under the key Username.

  1. Your tasklist.xml file should be as follows:
<Content xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://incert.incommon.org/schemas ../Schemas/tasklist.xsd">
  <Branches>
    <RoleBranch name="main" role="Remote" roleMode="Normal">
      <Control.GetContentFromEndpoint>
        <Properties>
          <ContentName>banners.xml</ContentName>
        </Properties>
      </Control.GetContentFromEndpoint>
      <UserInterface.StopMessageTimer>
        <Properties>
          <SettingKey>Splash screen progress text</SettingKey>
        </Properties>
      </UserInterface.StopMessageTimer>
      <UserInterface.HideDialog>
        <Properties>
          <Dialog>Splash screen dialog</Dialog>
        </Properties>
      </UserInterface.HideDialog>
      <Control.ReturnBranchResult errorBranch="handle authentication issues">
        <Properties>
          <Branch>authenticate</Branch>
        </Properties>
      </Control.ReturnBranchResult>
    </RoleBranch>

    <TaskBranch name="authenticate">
      <Settings.RetrieveSettingsString>
        <Properties>
          <Setter key="username">Username</Setter>
        </Properties>
      </Settings.RetrieveSettingsString>
      <UserInterface.StopMessageTimer>
        <Conditions.Any>
          <UserInterface.TimedMessageExists key="AuthenticatingMessage"/>
        </Conditions.Any>
        <Properties>
          <SettingKey>AuthenticatingMessage</SettingKey>
        </Properties>
      </UserInterface.StopMessageTimer>
      <UserInterface.HideBannerControl>
        <Conditions.Any>
          <UserInterface.BannerControlExists key="AuthenticatingMessage" dialog="Main dialog"/>
        </Conditions.Any>
        <Properties>
          <Dialog>Main dialog</Dialog>
          <ControlKey>AuthenticatingMessage</ControlKey>
        </Properties>
      </UserInterface.HideBannerControl>
      <UserInterface.ShowBannerControl>
        <Conditions.Any>
          <UserInterface.BannerControlExists key="Instructions" dialog="Main dialog"/>
        </Conditions.Any>
        <Properties>
          <Dialog>Main dialog</Dialog>
          <ControlKey>Instructions</ControlKey>
        </Properties>
      </UserInterface.ShowBannerControl>
      <Settings.SetSettingText>
        <Properties>
          <Setter key="authenticating">false</Setter>
        </Properties>
      </Settings.SetSettingText>
      <UserInterface.ShowBorderedBannerModal>
        <Properties>
          <Dialog>Main dialog</Dialog>
          <Banner>LoginBanner</Banner>
        </Properties>
      </UserInterface.ShowBorderedBannerModal>
      <Settings.PersistSettingsString>
        <Properties>
          <Setter key="username">Username</Setter>
        </Properties>
      </Settings.PersistSettingsString>
      <Settings.SetSettingText>
        <Properties>
          <Setter key="authenticating">true</Setter>
        </Properties>
      </Settings.SetSettingText>
      <UserInterface.DisableAllBannerDialogControls>
        <Properties>
          <Dialog>Main dialog</Dialog>
          <ExcludeControlKey>HelpButton</ExcludeControlKey>
          <ExcludeControlKey>AuthenticatingMessage</ExcludeControlKey>
        </Properties>
      </UserInterface.DisableAllBannerDialogControls>
      <UserInterface.CollapseBannerControl>
        <Properties>
          <Dialog>Main dialog</Dialog>
          <ControlKey>Instructions</ControlKey>
        </Properties>
      </UserInterface.CollapseBannerControl>
      <UserInterface.ShowBannerControl>
        <Properties>
          <Dialog>Main dialog</Dialog>
          <ControlKey>AuthenticatingMessage</ControlKey>
        </Properties>
      </UserInterface.ShowBannerControl>
      <UserInterface.StartMessageTimer>
        <Properties>
          <SettingKey>AuthenticatingMessage</SettingKey>
        </Properties>
      </UserInterface.StartMessageTimer>
      <Authentication.AuthenticateUser minimumTaskTime="10">
        <Properties>
          <UsernameKey>username</UsernameKey>
          <PassphraseKey>passphrase</PassphraseKey>
          <Credential2Key>credential2</Credential2Key>
          <Credential3Key>credential3</Credential3Key>
          <Credential4Key>credential4</Credential4Key>
          <CertificateProvider>incommontest.org</CertificateProvider>
        </Properties>
      </Authentication.AuthenticateUser>
    </TaskBranch>

    <TaskBranch name="handle authentication issues">
      <Control.PreserveLastResult>
        <Properties>
          <SettingKey>generic issue retry banner stored result</SettingKey>
        </Properties>
      </Control.PreserveLastResult>
      <UserInterface.StopMessageTimer>
        <Properties>
          <SettingKey>AuthenticatingMessage</SettingKey>
        </Properties>
      </UserInterface.StopMessageTimer>
      <Settings.SetSettingText>
        <Properties>
          <Setter key="generic issue retry banner title">Authentication Failed - Retry?</Setter>
          <Setter key="generic issue retry banner description">!ApplicationTitle! could not verify your network credentials.</Setter>
          <Setter key="generic issue retry banner retry cancel text">Click Retry to try again or Cancel to exit.</Setter>
        </Properties>
      </Settings.SetSettingText>
      <UserInterface.ShowChildBannerModal>
        <Properties>
          <ParentDialog>Main dialog</ParentDialog>
          <ChildDialog>notification dialog manager</ChildDialog>
          <Banner>Generic issue retry banner</Banner>
        </Properties>
      </UserInterface.ShowChildBannerModal>
    </TaskBranch>
  </Branches>
</Content>
  1. Upload tasklist.xml to your server and run the engine. Enter a username and click the "Login" button. Exit and restart the engine. Your username should be preserved.

Conclusion

In future tutorials, we will be using Settings.PersistSettingsString and Settings.RetrieveSettingsString to persist more user settings. We will also be saving and retrieving timestamps using the PersistSettingsTimestamp and the RetrieveSettingsTimestamp task classes. In the next tutorial, we will cover using control actions to set the input focus for the authentication dialog, and then we will finally move on to implementing other dialogs and using the engine to configure the user's computer.

Add a custom footer
Add a custom sidebar
Clone this wiki locally