Sample Walkthrough

So you've decided to use YLOD in your app. How to proceed now?

Your Options Class

YLOD does not require you to implement a specific interface or use specific types to function. You simply can use your own custom classes as options data containers, because YLOD will pull all information from these objects automatically using reflection. Let's
say in your application you have the following requirements regarding user settings:

A selection of choices presented to the user which are mapped to some enum values internally (e.g. to select from different flavors of a feature).

The possibility for the user to provide an email address (e.g. for email notifications).

A feature that is activated by default, but you want to give the user the possibility to opt-out, once they have confirmed a message (e.g. confirmation because it turns off an essential feature of your app).

What you would do then is simply create a class that holds all that information (if you don't have one already). This you also would have to do without using YLOD.

A First Look

Usually you would navigate to a settings page when the user taps an application bar button or menu entry, but of course you can also do that in response to a button click event or similar actions. To show the options page, simply get access to an instance of
your options, and then use the OptionsService like this:

As you can see, this already renders a full options dialog, and values edited in the dialog are written back to your original
MyOptions instance. The engine tries to take the property names of your object and do some very basic beautification, i.e. split words by capital letters. Of course there's no validation yet, and none of the additional features are configured.

Using the "Extras"

If you decided to use the "Extras" version of the library (with support for additional data types), then you need to configure the
OptionsService to make use of these explicitly. You do that by changing the above code snippet to:

Without these two additional configuration lines, the support for the additional data types in the "Extras" project won't be picked up.

Configuration Through Attributes

All features of YLOD are configured by decorating your properties with attributes. Take a look at the documentation of supported data types to get a detailed idea of all the values you can configure for each type, but common properties you're most likely
interested in are the display name, description, group name and display order. Make sure to use the appropriate attribute for the property value you're decorating to avoid problems. All these attributes are conveniently named
OptionXYZAttribute, so Intellisense will show you all the options nicely.

The following is an improved version of the above introduced options data container. It adds better display names, descriptions, splits the available options into two groups and plays with the display order:

Note how two different group names are used, and how this results in different pivot items being created in the options page. Also note that the display order rearranges the properties in the page even though in code they're still in the same declaration
order:

Of course the user can still enter bogus email addresses, and no confirmation is required if they turn off that great feature. We'll work on that in a second.

Enum configuration

For enums, the ListPicker control is used. Since enum names can be quite meaningless to the user you have the possibility to change their appearance in the options dialog too. For this you should use the default
DescriptionAttribute of the System.ComponentModel namespace that is meant for things like these:

using System.ComponentModel;
// [...]publicenum FeatureChoice
{
[Description("The first flavor")]
One,
[Description("Flavor number two")]
Two,
[Description("Last but not least")]
Three
}

This will result in nicely formatted enum lookup values for the ListPicker:

Special features

Most of the supported data types have built-in additional features, for example minimum/maximum value checks for numeric values, specifying an input scope for the SIP keyboard in case of string values, or-what we need in our case-confirmation prompts when the
user tries to change them. The boolean option type allows you to add prompts to have the user confirm a decision, and to provide additional information to them what consequences their choice will have, for example.

With this configuration, you will see that a confirmation prompt will appear, and that the option will only be changed when the user accepts the message.

Validation

As mentioned above, some data types already have built-in support for simple validation checks (min/max etc.). In other cases you are able to do more sophisticated validation. In particular, for string properties you're able to specify a regular expression
the user-entered value must satisfy. In case of the email field, a simple check for a valid email address can be performed using the following configuration. Also note how the input scope is set to
Email to provide a better user experience, and how the validation error message is defined:

Additional configuration

Some general aspects of the options page can be configured by using an overload of the
Show method that takes an OptionsConfiguration instance. That way you can for example influence what the page title will be:

Comments

Is there a way to add a range of values for example a list of possible strings that are options? Here's are some examples I have that I use in my settings pages that uses a LoopingSelector in order to display a range of values: