Atomia Web Frame

User's guide

38 views 0

Overview

This User’s Guide will show you how to work with views that are backed by ASP.NET MVC models that have already been properly prepared for validation, i.e. where supported validation attributes have been added. (At this time models are properly prepared for all forms where customer and/or user details are submitted in OrderPage, BCUP and AdminPanel).

Assuming that the backend is prepared you only need to add some code to enable client-side validation in the view. This would also be the case for theme customization.

Two view related components are used for this:

  • AtomiaValidation.js, which includes the AtomiaValidation module
  • An HTML helper from Atomia.Web.Plugin.Validation.HtmlHelpers

(The latest version of AtomiaValidation.js can be found in Scripts in the Atomia.Web.Plugin.Validation project.)

AtomiaValidation.js is automatically included in every page in the Default theme for OrderPage, BCUP and AdminPanel, and should in most if not all cases also be available for custom themes.

Initializing Static jQuery Validation Methods

The following jQuery Validation methods from AtomiaValidation.js can be thought of as more or less static methods, meaning their code does not change depending on configuration (not static as in static methods in C#):

  • AtomiaRequired
  • AtomiaRange
  • AtomiaStringLength
  • AtomiaRegularExpression
  • AtomiaUsername
  • AtomiaPassword
  • AtomiaRepeatPassword

To use one of these methods in your view you call AtomiaValidation.init with the validation methods you want to use and that match the attributes you have used for the related ASP.NET MVC model.

          ...
          AtomiaValidation.init('AtomiaRequired', 'AtomiaRegularExpression', 'AtomiaUsername');
          ...

AtomiaRequired, AtomiaRange, AtomiaStringLength, AtomiaRegularExpression are initialized globally for OrderPage, BCUP and AdminPanel, and should be available for at least the Default theme, but also likely any custom themes. So normally you should only need to call AtomiaValidation.init if you need one of the specialized methods for username or password validation.

If you should happen to call AtomiaValidation.init with a validation method that has already been initialized somewhere else, init is smart enough to only register each method once, so you can always just call init with all the methods you know are needed by the page.

Initializing Dynamic jQuery Validation Methods

Currently, there is one attribute where code for the jQuery Validation methods is generated dynamically: CustomerValidation.

CustomerValidation can be configured with rules that take the country, product and product group into account for validating a field, and the jQuery Validation method code and code to re-validate if field dependencies change is then generated on the fly. (See Configuring CustomerValidation Rules below for info about how to configure these validation rules.)

This means that to initialize CustomerValidation in the view you do NOT call AtomiaValidation.init. Instead, you call an HTML helper that will generate and include the validation code. In the simplest case you import the HTML helper and call it with no arguments (it should be placed after the call to the Html.EnableClientValidation helper):

          ...
          <%@ Import Namespace="Atomia.Web.Plugin.Validation.HtmlHelpers" %>
          ...
          <% Html.EnableClientValidation(); %>
          <% Html.AddCustomerValidationRules(); %>
          ...

This will support client-side validation of all CustomerValidation rules except those that depend on products or product groups. Product and product group dependent validation will still always be done in the backend though if the correct validation attributes are present on the model.

Configuring CustomerValidation Rules

Default Atomia rules are included as embedded resources in Atomia.Common.dll, but this configuration can be overwritten with a simple override file. To do so, you need to add
C:\Program Files (x86)\Atomia\Common\atomiaConfigurationStore.overrides file (on all servers that host Atomia GUI applications) and add rules to it that will override the default rules. Details about configuring customer validation rules can be seen here.

Routing and Plugin Configuration

The CustomerValidation, AtomiaUsername and AtomiaPassword attributes have some special routing and configuration requirements to be aware of.

CustomerValidation The CustomerValidation attributes in some cases need to make Billing API calls. There is a configuration switch <pluginSetting name="UsePublicOrderApi" ... in Atomia.Web.Plugin.Web.Validation.dll.config to configure if the Public Order API or the unwrapped standard Billing API should be used.

AtomiaUsername The AtomiaUsername client-side validation makes an AJAX call to the CheckUsername action that is defined in Atomia.Web.Plugin.Validation.Controllers.ValidationController. There should be a route for this in Web.config. By default, the Validation namespace is checked.

AtomiaPassword There is an auxiliary GeneratePassword action in Atomia.Web.Plugin.Validation.Controllers.ValidationController that can be used in conjunction with fields validated by AtomiaPassword. It is as the name implies used to generate a password. In the Default theme, it is used as the AJAX call for generate password buttons. If you want to use this there should be a route in Web.config. By default, the Validationnamespace is checked.

Checklist for Updating Legacy Views (Custom Themes)

If you have a view that was written before the Atomia.Web.Plugin.Validation framework was in place there are likely somethings that you will need to add, update and/or remove from the view:

  • Is AtomiaValidation.js included in the page? In most cases, it should have been added globally to the application.
  • Are the most common validation methods initialized via AtomiaValidation.init? It is most likely done globally already.
  • Are there any special fields where the client-side validation needs to be initialized: AtomiaUsername, AtomiaPassword,AtomiaRepeatPassword
  • Is the routing up to date for supporting controller actions? Applies to AtomiaUsername and AtomiaPassword
  • Is the
  • Are there any old now redundant validation methods added to the view? Remove any old jQuery validation methods whose functionality has now been made obsolete. In general, anything that validates a single field by itself, or that validates a field based on country or product can better be configured as a CustomerValidation rule. Username and password validation should use dedicated methods for this.
  • Are there any special validation methods that cannot be removed? Take care to not remove validation methods that cannot be handled (yet) by the validation framework. An example is some of the Norid validation in OrderPage.
  • For product dependent fields, use the Default theme as reference for what JavaScript expression arguments to use when calling AddCustomerValidationRules
  • Also use the Default theme for reference to any JavaScript helper methods that may have been moved to other modules, or that are no longer needed.

Advanced: Initializing CustomerValidation for Products and Product Groups

If you want CustomerValidation rules that depend on the product and/or product group to be validated client-side you need to implement a small bit of JavaScript in the page, and then call the AddCustomerValidationRules HTML helper with some extra arguments:

          ...
          <% Html.EnableClientValidation(); %>
          <% Html.AddCustomerValidationRules(new CustomerValidationOptions {
          ProductsChangedEvent = "AtomiaOrderForm.productsChangedEvent",
          ArticleNumberList = "AtomiaOrderForm.getSelectedArticleNumbers()",
          ProductCategoryList = "AtomiaOrderForm.getSelectedProductCategories()"
          }); %>
          ...
  • ProductsChangedEvent should be a JavaScript expression that evaluates to the name of an event that is triggered when the products that impact validation change, e.g. if a shopping cart is updated.
  • ArticleNumberList is a JavaScript expression that can be called to get an updated list of the active products’s article numbers after the ProductsChangedEvent has fired.
  • ProductCategoryList is similar to ArticleNumberList but instead of active article numbers should return a list of active product category names.

In the example above AddCustomerValidationRules has been called with arguments that reference JavaScript defined in the AtomiaOrderForm module.

For OrderPage, BCUP and AdminPanel this JavaScript has already been implemented and integrated with $.fn.AtomiaShoppingCart. Please see the relevant views in the respective Default theme.

Advanced: Implementing Product and Product Group JavaScript for CustomerValidation

Coming up soon.

Advanced: Extra Helper Methods in AtomiaValidation.js

There are a couple of helper methods in the AtomiaValidation JavaScript module that can be helpful for some use cases:

AtomiaValidation.validateImmediatelyA call to AtomiaValidation.validateImmediately('#your_form_id') will trigger validation on a field even if the user has not entered or changed the value of the field after the page loaded. This is useful when you have a pre-filled form like an edit form, and some fields depend on the values of other fields. E.g. if a user decides to change country to one with a different zip code format, the zip code field should revalidate in a pre-filled edit form, even if the user has not touched that field yet.

AtomiaValidation.initValidationTriggerA call to AtomiaValidation.initValidationTrigger('#field_selector', '#trigger_selector'); will setup a trigger to validate the field(s) selected by '#field_selector' if the field referenced by '#trigger_selector' changes. This is useful for fields that depend on each other but where validation triggering is not setup automatically like it is for CustomerValidation fields that depend on each other. E.g. AtomiaValidation.initValidationTrigger('#Password', '#Username'); could be used to re-trigger password validation if the username changes and you have a password validation rule that says that the password cannot be the same as the username.

Was this helpful?