Since there have been so many additions in the latest major release of this best-selling form application builder for DotNetNuke, we thought it would be best to cover them in serial fashion. In this series of blog posts we’re covering the major new features in XMod Pro 4. In this installment let’s look at the new form Actions: AddToRoles and RemoveFromRoles which allow you to and and remove users from DotNetNuke security roles.

Even though XMod Pro makes it a pretty painless process to create your own custom forms in DotNetNuke, our customers have asked for the ability to take the data from those forms and do something with it beyond saving it in a database or sending it in an email.

So, for version 4 we’ve added a brand new architecture that enables this kind of behavior. We call them Actions. In reality, when you send an email from XMod Pro, you’re using Actions. Actions are executed after the form has been successfully submitted and any data saved to the database. We’ll dive into more of the details in a later post. For now we’re focusing the two related Actions: AddToRoles and RemoveFromRoles.

The syntax for these tags is very simple:

<AddToRoles RoleNames="role1|role2" UserID="int" RoleDelimiter="|" />

<RemoveFromRoles RoleNames="role1|role2" UserID="int" RoleDelimiter="|" />

Place these tags in your form – typically I’ll add them near the top where I keep on my non-control tags like Email and the Select and Submit commands. However, you may want to group your Actions near the bottom of each form – after the submit and cancel buttons to indicate they occur after the form is submitted. It’s really just a matter of preference.

As you can see from the syntax, it’s very simple. Simply specify a pipe-delimited (by default) list of DNN security role names for the RoleNames property and the ID for the user you want to add to the role(s). The RoleNames and UserID properties are required. The RoleDelimiter property is optional and allows you to make the RoleNames delimited by some other character like a comma. It uses a pipe character by default so it can be fed directly from a list control on your form without modification. These properties can be hard-coded. But the real power comes from their ability to use values from the form itself.

A great example of this is an administrative form where you can selectively add a user to one or more roles.

<AddForm>
	...
	<AddToRoles RoleNames='[[RoleList]]' UserID='[[User]]' />
	...
	
	<Label for="lstRoles" Text="Choose Roles" />
	
	<ListBox Id="lstRoles" DataField="RoleList" DataType="String" SelectionMode="Multiple">
		<ListItem Value="Editor">Editor</ListItem>
		<ListItem Value="Proofreader">Proofreader</ListItem>
		<ListItem Value="Illustrator">Illustrator</ListItem>
	</ListBox>
	
	<Label for="ddlUser" Text="Select User" />

	<DropdownList Id="ddlUser" DataField="User" DataType="Int32">
		<ListItem Value="123">John Smith</ListItem>
		<ListItem Value="215">Olivia Stalwart</ListItem>
		<ListItem Value="837">Xeke the XMod Dog</ListItem>
	</DropdownList>
</AddForm>

In the above example, the <ListBox> contains a list of roles and the user can select more than one role (SelectionMode="Multiple"). Notice the Value of each <ListItem> is the same as role name. This is necessary because <AddToRoles> is expecting role names and not role ID’s. By default the <ListBox> sends the selected items as one string, separated by pipe ( | ) characters. It just so happens this is what <AddToRoles> wants. If needed, we could change the SelectedItemsSeparator property of the <ListBox> to a comma and change the RoleDelimiter property of the <AddToRoles> tag to a comma as well, but why make extra work?

The <DropDownList> allows the user to select which user to add to those selected roles. In this case the Value of each ListItem is the numeric ID of the selected user. This is what the <AddToRoles> tag expects for the UserID property.

So, to hook the <ListBox> and <DropDownList> up to our <AddToRoles> tag just use field tokens. Now, when the user successfully submits the form, XMod Pro will add that user to the selected roles.

Need to remove a user from one or more roles? Use the <RemoveFromRoles> tag. The procedure is the same.