DNN Custom Forms by OnyakTech
OnyakTech Custom Forms DNN Module
by OnyakTech

Custom Forms DNN Extension Tokens

Should you use all Tokens? Tokens for validation and loading data can also be added using the Control Panel. To get to the Control Panel you must be in Edit mode on the page while viewing your form, at the top of the module you will see a list where you can select your controls and click a link to open the Control Panel for that control.

The benefit of using Tokens is that it's contained within your Form Template, making it easy to reuse on other portals or web sites. But there are limitations. With data tokens the result will always be displayed in capital letters and there are some restrictions to the SQL that can be used. With REGEX for validation there are also some characters that cannot be used.

The benefit of using the Control Panel for the advanced control features is that you are not limited in any way, data is displayed as it is returned and there are no limitations on REGEX strings.

  • Calendar
    • Calendar Control: Displays a calendar control on your form to collect a date from the user.
      Example: [CALENDAR-NAME]
  • TextBox
    • Text Box Control: Displays a Text Box control on your form to collect standard form values from your users.
      A simple text box can be shown using this token: [TEXTBOX-NAME]

      Another example that sets the width, height and the Text Mode to Multi-Line:
      [TEXTBOX-NAMEMULTI::TextMode=MultiLine::Width=255px::Height=100px]

      If you also want to force the user to enter at least five digits then you can connect a REGEX control to your Text Box.
      Here is an example of validating a Text Box:
      [REGEX-REGNAME::ControlToValidate=NAME::ValidationExpression=\d{5}::ErrorMessage=Must be 5 numeric digits]
  • Checkbox
    • Checkbox Control: Displays a Checkbox to the user.
      e.g. [CHECKBOX-CHECKNAME]

      If you name the control "AGREE" then people will be forced to check the beckbox before they can submit the form. Use this to force people to accept your term.
  • Listbox
    • ListBox Control: Displays a ListBox to the user. You can provide values in the list box using two methods. Manual values or SQL.
      Example of a manual list: [LISTBOX-MYLIST-VALUE1-VALUE2::SelectionMode=Multiple]
      Example using SQL: [LISTBOX-MYLISTSQL-[SQL:Select UserName From Users]]

      You can also populate the values of another List Box when a user clicks a value in a List Box control. To do this you need to setup an Event. The TestControlClicks.htm sample form that is included with this Forms Module provides the details for this.

      Also look at the item "Dynamic Value Based on Selection" in the list box on the left of this for more information.
  • Dropdown
    • Drop Down List Control: Displays a Drop Down ListBox to the user. You can provide values in the drop down using two methods. Manual values or SQL.
      Example of a manual list: [DROPDOWNLIST-MYLISTD-VALUE1-VALUE2]
      Example using SQL: [DROPDOWNLIST-MYLISTSQL-[SQL:Select UserName From Users]]

      You can also populate the values of another Drop Down List Box when a user clicks a value from this control. To do this you need to setup an Event. The TestControlClicks.htm sample form that is included with this Forms Module provides the details for this.

      Also look at the item "Dynamic Value Based on Selection" in the list box on the left of this for more information.
  • Radio Button List
    • Radio Button List Control: Displays a Radio Button List to the user. You can provide values using two methods. Manual values or SQL.
      Example of a manual list: [RADIOBUTTONLIST-MYLISTR2-VALUE1-VALUE2::RepeatDirection=Vertical]
      Example using SQL: [RADIOBUTTONLIST-MYLISTSQL-[SQL:Select UserName From Users]]

      You can also populate the values of another control when a user clicks a value from this control. To do this you need to setup an Event. The TestControlClicks.htm sample form that is included with this Forms Module provides the details for this.

      Also look at the item "Dynamic Value Based on Selection" in the list box on the left of this for more information.
  • Checkbox List
    • Checkbox List Control: Displays a series of Checkbox controls to the user.
      e.g. [CHECKBOXLIST-CHECKNAME]
  • Image
    • Image Button Control:There is an Image Button version for each of the form submission link control. To switch to a Image Button control from a Link Button control you just need to "IMAGE" after the control name and include a property for "ImageURL".

      Examples:
      [SUBMITEMAILIMAGE::Text=Submit::ImageURL=http://www.yoursite.com/image.png]

      [SUBMITIMAGE::Text=Submit::ImageURL=http://www.yoursite.com/image.png]

      [REGISTERIMAGE::Text=Submit::ImageURL=http://www.yoursite.com/image.png]

      [DELETEIMAGE::Text=Submit::ImageURL=http://www.yoursite.com/image.png]
  • Label
    • Label:Labels are only necessary when you want to display and save dynamic information (from profile, SQL, query string, etc). Otherwise you can simply type the string into the Form Template.

      Examples:
      [LABEL-COMPANYID]
  • Google ReCaptcha
    • ReCaptcha: A more advanced captcha control to protect your website from spam and abuse while letting real people pass through with ease. You will need to create your own account to obtain your access keys on https://www.google.com/recaptcha/intro/index.html
      Example: [RECAPTCHA-MYRECAPTCHA::PublicKey=xxx::PrivateKey=xxx::Theme=blackglass]


      Themes available to you are: blackglass, red, white and clean
  • Text Editor
    • Text Editor: An HTML Text Editor control that can be used to capture HTML content from people who may not know HTML.
      Example: [TEXTEDITOR-MYBLOG]
  • Signature Control
    • Signature: This control allows you to collect a users signature on your form. The signature string and a generated image of the signature is stored on your web server. If your saving the information to a table then this information is also stored in the table. The image location is stored into the table, the actual image is not stored to the table.

      Example: [SIGNATURE-USERSIGNATURE]
  • Data Grid
    • Data Grid:Use a Data Grid control to display data loaded from a SQL Statement into your form. The SQL must be set through the Control Panel and you can style it with CSS.

      Examples:
      [DATAGRID-TEST]
      [DATAGRID2-TEST] - The DATAGRID2 control allows group expressions you can set from the Control Panel.


      CSS:To set the CSS, use the CSS classes GRID_CSS_GRIDNAME, GRID_CSS_HEADER_GRIDNAME, GRID_CSS_ITEM_GRIDNAME and GRID_CSS_ALTERNATE_GRIDNAME.


      So if your control token is [DATAGRID-TEST] you would modify your skins CSS or the Forms module module.css by adding the following...
      .GRID_CSS_TEST { border: solid 1px Tan; }
      .GRID_CSS_HEADER_TEST { font-weight: bold; background-color: Tan; }
      .GRID_CSS_ITEM_TEST { background-color: LightGoldenrodYellow; }
      .GRID_CSS_ALTERNATE_TEST { background-color: PaleGoldenrod; }
  • Submit Button - Test
    • Submit Test Control: Displays a Submit Button that will display the form values on the page. Note that you can also use the DEBUG mode with the Submit Email control for the same results.
      Example: [SUBMITTEST::Text=Submit]
  • Submit Button
    • Submit Test Control: Displays a Submit Button that will display the form values on the page. Note that you can also use the DEBUG mode with the Submit Email control for the same results.
      Example: [SUBMITTEST::Text=Submit]
  • Submit Button with Email
    • Submit with Email Control: Displays a Submit Button that will also send an email.
      Example: [SUBMITEMAIL::Text=Submit]

      The Submit Email button will also execute any actions you specify in the Display Options and from other tokens you add to your form. Note that if you are in DEBUG mode then some actions will not be executed. For example, any redirects you set will not occur while in debug mode.
  • Submit Reset
    • Submit Form Reset: A simple button that clears all controls.
      Example: [SUBMITRESET::Text=Reset::cssclass=btn]
  • Search Button
    • Search Control: A search button that renders the Search Plugins set in the Display Options.
      Example: [SEARCH::Text=Search]
  • Submit Purchase
    • Submit Purchase There are two ways to turn your Form into a purchase. You can an enable the "Is Product" purchase options in the Control Panel for a control on your Form or you can use the [SUBMITPURCHASE] Submit button control and complete the "Submit Purchase" options in Display Setup to indicate the details of the product to be purchased when users submit your Form. When using the [SUBMITPURCHASE] token you can only include the purchase of a single product or service. When using the Control Panel you can add multiple product purchases to a single Form by enabling the "Is Product" option for one ore more controls on your Form.

      If you want to add a specific product to the users shopping cart when they check a CheckBox or when they enter a positive value into a TextBox then you will use the Control Panel. In this case you can use any Button control on your form, you would not use the [SUBMITPURCHASE-XXXX] token.

      When you want to add a single product or service to the users shopping cart after they submit your Form then you will want to use the [SUBMITPURCHASE-XXXX] Submit Button Token.

      Example: [SUBMITPURCHASE-PURCHASE]
  • Login Button
    • Login: This button can be used to login a user. Requires the [TEXT-USERNAME] and [TEXT-PASSWORD] tokens to also exist on your form. Can be used with the [ACCOUNTLOGINLINK] token that displays a "Login" link if the user is not logged in and a "Sign-Out" link if the user is logged in. The [ACCOUNTLOGINLINK] token will hide your form if the user is not logged in and when clicked it will display your form in a popup.
      Example: [LOGIN::Text=Login::cssclass=btn]
  • Forced Redirect Button
    • Forced Redirect: This button can be used as a "Go Back" or "Edit" button on a form where the previous form may have submitted to this form with form values. So on PAGE 1 you have a form that submits to PAGE 2. Both forms have the same control names and you checked the option in Display Setup include form values in the redirect. This will make PAGE 2 show the values entered into PAGE 1 since the control names are the same and the values were passed in the URL. By adding the Forced Redirect, you can set the URL in Display Setup for the Forced Redirect to go to PAGE 1, allowing the user to go back and edit FORM 1.

      Example: [SUBMITREDIRECT::Text=GOBACK]
  • Update User Profile Button
    • Update User Profile: This button can be used to update a users profile, however you can get the same result using any of the OnyakTech Form Button controls by enabling "Auto Profiling" in Display Setup. Great for a "My Account" page. This works the same as the Register User button but updates the current users profile instead of registering their account and logging them in.

      Control names should match the user profile field names.

      Example: [UPDATEPROFILE::Text=Update Profile]
  • Register User Button
    • Register User: This button can be used to register new users to your site. Control names should match the user profile field names. The only required field is the email address. If you have a form with just an email address then all of the users required attributes will be set to the email address entered. However, this really depends on the options you set in Display Setup.

      Example: [REGISTER::Text=Update Profile]
  • Delete Button
    • Delete Control: A simple delete control to be used when you want to execute the forms post actions set in the Display Options and delete a record in the database. Make sure you set the option "Save to Database" and that you include the Form Tokens [TABLE] and [TABLEPRIMARYKEY] in your Form Template. You must also set the primary key value from the Query String which can be easily accomplished by using the OnyakTech Data Viewer module and setting it's option to redirect to this page on row click while passing the row data in the query string.
      Example: [DELETE::Text=Delete]
  • Cancel Button
    • Cancel Control: A simple cancel button to be used when you want to simply redirect back to the original calling page. This would usually be used with the OnyakTech Data Viewer or another instance of the OnyakTech Forms module.
      Example: [CANCEL::Text=Cancel]
  • Redirect If Checked
    • Redirect if Checked:This is a token that will redirect to the specified URL if the user checks a specific checkbox control you have added to your form.

      Examples:
      Your checkbox control: [CHECKBOX-ORDERMORE] [REDIRECT-ORDERMORE;http://www.yoursite.com/ordermoreproducts]

      You can also do this with a Listbox contorl: [REDIRECTLIST-ORDERMORE]
      You can only have one of these tokens per form. You can also set a form redirect in the Display Options.
  • Hidden Field
    • Hidden Field:Hidden Fields can be set to contain values (from query string, current user profile, etc) and then that value can be stored in a CSV, in emails or direct to the database.

      Examples:
      [HIDDENFIELD-COMPANYID]
  • Required Value
    • Required Value Control: Forces a user to enter a value into the specified control.
      Example: [REQUIRED-REQNAME::ControlToValidate=NAME::ErrorMessage=Textbox must have a value]

      In the example above, the control being validated is set to "NAME" and the message displayed to the user if that control "NAME" doesn't have a value is "Textbox must have a value".

      The ControlsSample.htm sample form includes more examples of this control.
  • File Upload
    • File Control:Displays a file upload control to the user.
      Example: [FILE-MYFILE]

      The Version2.5Sample.htm sample form includes more examples of this control. You can allow multiple file uploads by simply adding multiple file controls to your form. Note that each file control you add must have it's own name.
  • Current Date and Time
    • Current Date and Time:This is really just a display token, it doesn't render a control but shows the user the current date and time.
      Example: [Now]
  • User Information
    • User Information:These are a set of tokens you can use to display information about the current user on your form.
      Display the current users display name: [User:DisplayName]
      Display the current users email: [User:Email]
      Display the current users first name: [User:FirstName]
      Display the current users last name: [User:LastName]
      Display the current users user name: [User:UserName]
      Display the current users user id: [User:UserId]

      Additional information tokens are...
      Display the current module path: [User:ControlPath]
      Display the current portal id: [User:PortalId]
      Display the current users custom user profile values. Replace 'xxx' with the actual name of the custom user profile field: [User:xxx]
  • SQL
    • Dynamic Data from SQL:This token executes SQL and displays the return value in your form where the token is located.
      Example: [SQL:Select Count(*) From Users]

      The ControlsSample.htm sample form includes more examples of this control.
  • HTML 5 Controls
    • HTML 5 Controls:These are a set of tokens that render HTML 5 controls on your form. They are much like the Text Box control but provide additional features for data collection. Note that not all browsers render these controls the same. You can use all of the same TextBox control properties with these HTML 5 controls.

      [TEXTBOXWEEK-NAME]
      [TEXTBOXURL-NAME]
      [TEXTBOXTIME-NAME]
      [TEXTBOXTEL-NAME]
      [TEXTBOXSEARCH-NAME]
      [TEXTBOXRANGE-NAME]
      [TEXTBOXNUMBER-NAME]
      [TEXTBOXMONTH-NAME]
      [TEXTBOXEMAIL-NAME]
      [TEXTBOXDATETIMELOCAL-NAME]
      [TEXTBOXDATETIME-NAME]
      [TEXTBOXDATE-NAME]
      [TEXTBOXCOLOR-NAME]

      The HTML5Controls.htm sample form includes examples of these controls.
  • Mobile Enabled
    • Mobile Enable:This token loads additional frameworks into the page to mobilize your form making it more user friendly on mobile devices. With the new styling options in the OnyakTech Custom Forms module for DNN version 6.0 this token is no longer necessary, but is there if you want to load jQuery Mobile.
      Example: [MOBILEME]
  • Dynamic Email To
    • Dynamic Email To:These set of tokens make it possible to dynamically set the recipient of the email the form sends based on the selection the user makes in a list type control. For example, you might display a list that contains Support and Sales. If the user selects "Support" then form is email to Suppport@YourSite.com. If the user selects "Sales" then the form is emailed to Sales@YourSite.com. Use the following token set to complete this setup in your own form.

      [EVENT-CATEGORY-SUPPORT-SUPPORT@YOURSITE.COM]
      [EVENT-CATEGORY-SALES-SALES@YOURSITE.COM]


      This is the first list box that will set the TO address in the email that is sent from this form:
      [LISTBOX-CATEGORY-SUPPORT-SALES::width=150::height=50]

      The 'Dynamically Set Email To.htm' sample form includes examples of these controls.
  • Event - Dynamic Selection
    • Dynamic value based on selection: Note that the Event Tokens are more powerful if setup through the Event Manager. These set of tokens make it possible to dynamically load content into another control based on a value the user selects in the current control. For example, you might have two list boxes on your form. When a user selects a value in the first list box this will trigger a post back to the server to execute a SQL Statement that includes the value the user selected in your WHERE clause to dynamically load the 2nd list box with values based on the users selection.

      Display the selected users roles in a List Box:
      [EVENT-USERS-ROLES-SELECT ROLENAME FROM USERROLES INNER JOIN ROLES ON USERROLES.ROLEID=ROLES.ROLEID WHERE USERROLES.USERID=SELECTEDVALUE]


      This is the first list box that will load with all users:
      [LISTBOX-USERS-[SQL:Select USERID, USERNAME from Users]::width=150::height=250]


      This is the second list box that will populate with values when a user clicks an item in the first list box.
      [LISTBOX-ROLES::width=150::height=250]

      The 'DynamicSelect.htm' sample form includes examples of these controls.
  • Data Storage
    • Custom Table Data Storage:This token indicates to the Forms Module to save the data to a different table of your choice instead of the default Forms Tables that are created based on your forms name.
      Example: [TABLE-OKY_CONTACTS] < - this indicates that the form data will be saved to the table OKY_CONTACTS

      The SaveToTable.htm sample form includes more examples of this control.
  • Agree Control
    • Agree To Terms Control: Displays a Checkbox to the user and the user must check before they can submit the form.
      e.g. [CHECKBOX-AGREE]

      This is just like the CheckBox control but you must name the control "AGREE" to force people to check the beckbox before they can submit the form.

      To display your own custom message, use the token [AGREEMESSAGE-YOUR MESSAGE HERE]. An example of this is: [AGREEMESSAGE-Please check to confirm before submit]
  • OnyakTech Axon Opt-In Module Integration
    • Axon Opt-In:If you have the OnyakTech Axon module installed and have enabled the Axon Integration in the Display Setup, you can add a checkbox control to your form that (if checked) will automatically add the user to the opt-in list for the Axon Campaign you select in the Display Setup.

      If the user is logged in then the user information in their profile will be used in the Opt-In. You can also add controls to your form to collect user information from the user directly. Here is an example Form: First Name: [TEXTBOX-FIRSTNAME]
      Last Name: [TEXTBOX-LASTNAME]
      Email Address: [TEXTBOX-EMAIL]
      Subscribe? [CHECKBOX-AXONOPTIN]
      [SUBMIT::Text=Submit::cssclass=btn]

      Examples:
      [CHECKBOX-AXONOPTIN]
  • REGEX
    • REGEX Control: Note that validation with REGEX is handled better if you set this up in the Control Panel, using tokens you may have issues if you have too many REGEX tokens on a single form; REGEX set in the Control Panel do not have this limitation. This control uses a regular expression to validate a controls input and display a message if it's not valid.
      e.g. [REGEX-REGNAME::ControlToValidate=NAME::ValidationExpression=\d{5}::ErrorMessage=Must be 5 numeric digits]

      The ControlsSample.htm sample form includes more examples of this control.

      For REGEX you may find it easier to use the Control Panel instead of this token. To access the Control Panel for each control, go into Edit mode on your DotNetNuke page and then right-click the control you want to add REGEX validation to access the context menu for the Control Panel.
  • Database Table
    • Table: This token defines the table that the data should be stored to if you have selected the option to save the form to the database in Display Setup. If you don't include this token in your form then the Forms module will create a table for you based on the name of your form.

      Example: [TABLE-TABLENAMEHERE]
  • Database Table Primary Key
    • Submit without Redirect: This Form Submit button is the same as the normal SUBMIT button but will not trigger a Redirect if you have one set in the Form Display Setup. You can use this in cases where you may need the standard SUBMIT button to save information to the database and redirect to a new page but also need the option of the standard SUBMIT button without the redirect for users that want to stay on the same page and submit another entry.

      Example: [SUBMITWITHOUTREDIRECT::Text=Save and Add Another]
  • Database Table Primary Key Lookup
    • Primary Key Look-Up: This token should contain a SQL Statement that will obtain the primary key of your table that the data should be stored to if you have selected the option to save the form to the database in Display Setup. If you don't include this token in your form then the Forms module will create a primary key for you based on the name of your form. You can use this to open a specific record for editing with your form based on a query string parameter passed to the page with the Forms module in situations where you may need to lookup the primary key value. An example of this is when you may be storing the name of something instead of it's ID in another table, so you only have it's related name and not the ID. In other words, if your form displays a Users Record and you want to open the record by passing the user name instead of the User ID (where the UserID is the primary key) then you will need to use this token to execute SQL to get the UserID of the UserName you pass in the query string.

      Example: [TABLEPRIMARYKEYVALUEFROMLOOKUP-SELECT SOMECOLUMN FROM SOMETABLE WHERE SOMECOLUMN=`YOURQUERYSTRINGPARMATER`]


      IMPORTANT: Note how the query string parameter token is enclosed in a tilde instead of a bracket and does NOT contain "QRY". When using SQL in the TABLEPRIMARYKEYVALUEFROMLOOKUP you will need to use `YOURQUERYSTRINGPARMATER` where in the Control Panel you would use [QRY-YOURQUERYSTRINGPARMATER]. You do not need to include single quotes around your parameter.

      When the query string parameter value is to be used as the Column in your Where clause with SQL you can use the following token instead to prevent the column from being marked as a string value in your SQL.
      Example: [TABLEPRIMARYKEYVALUEFROMLOOKUPASCOLUMN-SELECT SOMECOLUMN FROM SOMETABLE WHERE `YOURQUERYSTRINGPARMATER`=1]


      NOTE: You will still need the [TABLE-TABLENAMEHERE] and [TABLEPRIMARYKEY-PRIMARYKEYNAME] tokens with this token in order to let the Forms module know what table and primary key are related to this.
  • Database Table Value
    • Table Value: This token can be used when you have loaded your form from a table record using the table tokens. Simply enclose the column name in brackets using either all upper or all lower case characters. For example, if you have a column named "Email" you would use the token anywhere on your form as [EMAIL] or [email].

      Example: [YOURCONTROLNAMEHERE]
  • Hyperlink
    • Hyperlink: This control will display a hyperlink on your form. The benefit of using this control over a standard HTML hyperlink is that you can dynamically set the URL. If your "PostBackUrl" contains the keyword "CONTROLNAME" it will get replaced with the name of the control before it is displayed. So if your form loads from a table that has a column called SHOWDETAILS and you add a HYPERLINK control named after that column and you check the option in Display Setup (under Other Options) "When using Labels or Hyperlink controls, if value is "True" then show the Control Name otherwise show nothing" then the URL for this control will be parsed having the property "PostBackUrl=http://www.yoursite.com?someval=CONTROLNAME" changed to "PostBackUrl=http://www.yoursite.com?someval=SHOWDETAILS". Allowing you to dynamically generate URL's, showing the link if the source data column is true and hiding it if false.

      Example: [HYPERLINK-MYLINK::PostBackUrl=http://www.yoursite.com?someval=CONTROLNAME]
  • Replace Value
    • Replace Value: When a controls value is set (from the database, querystring, etc) you can use this token to replace the value. For example, if you have a control named "USERTYPE" and it has values of EMP and STD you would use this token to replace EMP with Employee and STD with Student. Example: [REPLACEVALUE-EMP=EMPLOYEE;STD=STUDENT;]

      Example: [REPLACEVALUE-MYVALUE=MYNEWVALUE;MYVALUE2=MYNEWVALUE2;] -- Note that you must use all capital letters