Skip to content

Adding a License Dialog

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

Overview

In this tutorial, we will add a simple license dialog. This dialog will contain scroll-able license text as well as an "I agree" check box. This tutorial will cover a lot of the same ground as we have already covered while building the authentication dialog, but it will also demonstrate how to use nested banners in your dialogs.

Setup

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

A note on examples

Our xml files are starting to get too long to include their full text inline in these tutorials. When you see this symbol external link in the text, you can click on it to view the xml in question.

Creating the basic dialog and wiring it into the tasklist

  1. Add the following xml to the Banners block of your banners.xml file:
<SimpleBanner name="LicenseDialog" margin="12,12,12,6" height="550" width="500">
  <Content>
    <CheckInputField controlKey="agree checkbox" settingKey="agree to license" margin="0" padding="8,0,0,0" dock="Bottom">
      <Content>
        <DirectTextContent>I have read and agree to the above</DirectTextContent>
      </Content>
    </CheckInputField>
  </Content>
  <Buttons>
    <ResultButton>
      <Target>NextButton</Target>
      <Text>Next</Text>
      <IsDefaultButton>true</IsDefaultButton>
      <Result>ControlResults.NextResult</Result>
    </ResultButton>
    <ResultButton>
      <Target>BackButton</Target>
      <Text>Back</Text>
      <Result>ControlResults.BackResult</Result>
    </ResultButton>
  </Buttons>
  <Actions>
    <EnableControlAction>
      <Conditions.All>
        <Settings.SettingEquals key="agree to license" value="true" ignoreCase="true"/>
      </Conditions.All>
      <ControlKey>NextButton</ControlKey>
    </EnableControlAction>
    <DisableControlAction>
      <Conditions.All>
        <Settings.SettingNotEqual key="agree to license" value="true" ignoreCase="true"/>
      </Conditions.All>
      <ControlKey>NextButton</ControlKey>
    </DisableControlAction>
    <SetFocusAction onetime="true">
      <Conditions.All>
        <Settings.SettingNotEqual key="agree to license" value="true" ignoreCase="true"/>
      </Conditions.All>
      <ControlKey>agree checkbox</ControlKey>
    </SetFocusAction>
  </Actions>
</SimpleBanner>

We've already covered the basics of banner creation and control actions, so I won't go into too much detail here. The above will create a banner with an "I have read and agree to the above" check box. This checkbox will enable the next button when checked (and disable it when not).

Note that we've specified ignoreCase="true" in the declarations of our two control actions. Temporary settings comparisons are case sensitive by default, but you can turn this off by specifying ignoreCase="true".

This new dialog will have a back button as well. When clicked, this button will return a ControlResults.BackResult, which will, in turn, cause the engine to execute the previous task.

  1. Add the following xml Branches block to your tasklist.xml file:
<TaskBranch name="show license dialog">
  <UserInterface.ShowBorderedBannerModal>
    <Properties>
      <Dialog>Main dialog</Dialog>
      <Banner>LicenseDialog</Banner>
    </Properties>
  </UserInterface.ShowBorderedBannerModal>
</TaskBranch>
  1. Modify your 'main' rolebranch to execute the show license dialog branch after the authenticate branch:
<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>
  <Control.ReturnBranchResult>
    <Properties>
      <Branch>show license dialog</Branch>
    </Properties>
  </Control.ReturnBranchResult>
</RoleBranch>
  1. Upload tasklist.xml external link and banners.xml external link to your server and run the engine. The engine should now show our license dialog after you authenticate correctly:

license dialog

Checking and unchecking the check box should enable and disable the "Next" button, and clicking "Back" should return you to the authentication dialog.

  1. Add the following to the Banners block of your banners.xml file:
<SimpleBanner name="license text" scrollable="true" background="White">
  <Content>
    <SimpleParagraph fontWeight="Bold" alignment="Center" fontSize="14" padding="0,20,0,20" color="Black">
      <Content>
        <DirectTextContent>Lorem Ipsum Licensum</DirectTextContent>
      </Content>
    </SimpleParagraph>
    <SimpleParagraph padding="0,12,0,0" color="Black">
      <Content>
        <DirectTextContent>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. </DirectTextContent>
      </Content>
    </SimpleParagraph>
    <SimpleParagraph padding="0,12,0,0" color="Black">
      <Content>
        <DirectTextContent>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.</DirectTextContent>
      </Content>
    </SimpleParagraph>
    <SimpleParagraph padding="0,12,0,0" color="Black">
      <Content>
        <DirectTextContent>eque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.</DirectTextContent>
      </Content>
    </SimpleParagraph>
    <SimpleParagraph padding="0,12,0,0" color="Black">
      <Content>
        <DirectTextContent>Ut enim ad minima veniam, quis nostrum exercitationem ullam corporis suscipit laboriosam, nisi ut aliquid ex ea commodi consequatur? Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur?</DirectTextContent>
      </Content>
    </SimpleParagraph>
    <SimpleParagraph padding="0,12,0,0" color="Black">
      <Content>
        <DirectTextContent>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. </DirectTextContent>
      </Content>
    </SimpleParagraph>
    <SimpleParagraph padding="0,12,0,0" color="Black">
      <Content>
        <DirectTextContent>Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.</DirectTextContent>
      </Content>
    </SimpleParagraph>
  </Content>
</SimpleBanner>

Here, we're using a separate banner to hold our license text. Note that we've added a scrollable attribute to our SimpleBanner declaration and set it to true. This will make the content of this new banner scrollable.

  1. Update your license banner xml to show your license text banner:
<SimpleBanner name="LicenseDialog" margin="12,12,12,6" height="550" width="500">
  <Content>
    <CheckInputField controlKey="agree checkbox" settingKey="agree to license" margin="0" padding="8,0,0,0" dock="Bottom">
      <Content>
        <DirectTextContent>I have read and agree to the above</DirectTextContent>
      </Content>
    </CheckInputField>
    <ContentBlockParagraph banner="license text" margin="0,0,0,8" borderSize="2,2,2,2" borderColor="Black" padding="12"/>
  </Content>
  <Buttons>
    <ResultButton>
      <Target>NextButton</Target>
      <Text>Next</Text>
      <IsDefaultButton>true</IsDefaultButton>
      <Result>ControlResults.NextResult</Result>
    </ResultButton>
    <ResultButton>
      <Target>BackButton</Target>
      <Text>Back</Text>
      <Result>ControlResults.BackResult</Result>
    </ResultButton>
  </Buttons>
  <Actions>
    <EnableControlAction>
      <Conditions.All>
        <Settings.SettingEquals key="agree to license" value="true" ignoreCase="true"/>
      </Conditions.All>
      <ControlKey>NextButton</ControlKey>
    </EnableControlAction>
    <DisableControlAction>
      <Conditions.All>
        <Settings.SettingNotEqual key="agree to license" value="true" ignoreCase="true"/>
      </Conditions.All>
      <ControlKey>NextButton</ControlKey>
    </DisableControlAction>
    <SetFocusAction onetime="true">
      <Conditions.All>
        <Settings.SettingNotEqual key="agree to license" value="true" ignoreCase="true"/>
      </Conditions.All>
      <ControlKey>agree checkbox</ControlKey>
    </SetFocusAction>
  </Actions>
</SimpleBanner>

There are two things to note here: * We're using ContentBlockParagraph to display the contents of our license text banner within our license banner. * We've placed the ContentBlockParagraph xml after our CheckInputField xml. There currently is a quirk in the banner layout system where elements with docked to the bottom of the banner need to appear before other elements in the xml.

  1. Upload tasklist.xml external link and banners.xml external link to your server and run the engine. The engine should now show our license dialog after you authenticate correctly:

license dialog

If everything went correctly, the license dialog should now contain our license text.

  1. The last thing that we'll want to do is to tell the engine to remember whether users clicked 'I agree' in previous sessions. To do this, modify your show license dialog xml as follows:
<TaskBranch name="show license dialog">
  <Settings.RetrieveSettingsString forwardOnly="true">
    <Properties>
      <Setter key="agree to license">license accepted</Setter>
    </Properties>
  </Settings.RetrieveSettingsString>
  <UserInterface.ShowBorderedBannerModal>
    <Properties>
      <Dialog>Main dialog</Dialog>
      <Banner>LicenseDialog</Banner>
    </Properties>
  </UserInterface.ShowBorderedBannerModal>
  <Settings.PersistSettingsString forwardOnly="true">
    <Properties>
      <Setter key="agree to license">license accepted</Setter>
    </Properties>
  </Settings.PersistSettingsString>
</TaskBranch>

We covered persisted settings in the tutorial, Saving user settings, so there's not too much to add here.

Note, though, that we've specified forwardOnly="true" in the declaration of our Settings.RetrieveSettingsString xml block. Settings.RetrieveSettingsString, as with most tasks, returns ControlResults.NextResult if it executes successfully. Normally, this is Ok, but if the user clicks 'Back' from the license dialog, the engine will execute Settings.RetrieveSettingsString, which will return ControlResults.NextResult and this will cause the engine to show the license dialog again.

Specifying forwardOnly="true" tells the engine to only run a task when it is iterating forward through a branch's tasks. In the above, the engine will skip the Settings.RetrieveSettingsString task when the user clicks 'Back' from the license dialog.

  1. Upload tasklist.xml external link and banners.xml external link to your server and run the engine. Clicking 'Back' from the license dialog should return you to the authentication dialog.

If you check 'I agree' and click 'Next' from the license dialog, the engine should exit (because it has nothing else to do, at this point). But if you run the engine again, it should remember that you checked 'I agree' during a previous session.

Conclusion

In this tutorial we covered using the ContentBlockParagraph to present banner content from within another banner. We also covered the using the forwardOnly attribute to prevent the engine from executing tasks when it is moving backward through a branch's tasks.

We need to add two more dialogs, a 'ready to begin' and a 'finished' dialog, and then we can start making our version of InCert actually do something useful. We'll cover these last two dialogs in our next few tutorials.

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