Merge pull request #1 from surveyjs/readme

Update README and code comments

Author: RomanTsukanov

DomainModelsViews/JsonFormGenerator.cs

@@ -17,11 +17,14 @@ public JSONGeneratorByModelClass(Type type)
         {
             this.type = type;
         }
+        // Generates a form JSON schema based upon a domain model type.
         public dynamic Generate()
         {
+            // Get domain model properties and their metadata
             List<PropertyInfo> properties = new List<PropertyInfo>();
             this.fillProperties(properties, this.type);
             if (properties.Count == 0) return new { };
+            // Arrays of form pages and elements (questions and panels)
             var pages = new List<dynamic>();
             var elements = new List<dynamic>();
             CustomAttributeData curPageAttr = getFormPageAttribute(properties[0]);
@@ -31,19 +34,23 @@ public dynamic Generate()
                 if (i > 0)
                 {
                     CustomAttributeData pageAttr = getFormPageAttribute(prop);
+                    // If `pageAttr` has a value, it means that the previous page has run out of form elements,
+                    // and we should add it to the `pages` array
                     if (pageAttr != null)
                     {
                         pages.Add(new { title = this.getAttributeValueByProp(curPageAttr, "Title"), elements = elements });
                         elements = new List<dynamic>();
                         curPageAttr = pageAttr;
                     }
                 }
+                // Create a form element for the current domain model property
                 var element = this.createElementByProp(prop);
                 if(element != null)
                 {
                     elements.Add(element);
                 }
             }
+            // If the `elements` array is not empty, create a form page for its elements. This page will be the last.
             if (elements.Count > 0)
             {
                 pages.Add(new { title = this.getAttributeValueByProp(curPageAttr, "Title"), elements = elements });
@@ -61,6 +68,8 @@ private void fillProperties(List<PropertyInfo> properties, Type type)
             }
             properties.AddRange(type.GetProperties(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly));
         }
+        // Creates a form element based upon the metadata of a domain model property.
+        // You can expand this method to process more attributes.
         private dynamic createElementByProp(PropertyInfo prop)
         {
             var el = new ExpandoObject();
@@ -93,6 +102,7 @@ private dynamic createElementByProp(PropertyInfo prop)
             }
             return el;
         }
+        // Sets a form element type based upon the type of the passed domain model property.
         private void setElementAttrByPropType(ExpandoObject el, PropertyInfo prop)
         {
             if (this.isGenericListType(prop.PropertyType))
@@ -117,6 +127,7 @@ private void setElementAttrByPropType(ExpandoObject el, PropertyInfo prop)
                 el.TryAdd("inputType", "number");
             }
         }
+        // Sets the type of cells in a Matrix Dynamic question based upon the type of the passed domain model property.
         private void setListElementAttrByPropType(ExpandoObject el, PropertyInfo prop)
         {
             el.TryAdd("type", "matrixdynamic");
@@ -142,6 +153,8 @@ private bool isGenericListType(Type type)
         {
             return type.IsGenericType && type.GetGenericTypeDefinition() == typeof(List<>);
         }
+
+        // Sets form element properties based upon `FormFieldAttribute` properties.
         private void setElementAttrByFormFieldAttr(ExpandoObject el, CustomAttributeData attr)
         {
             var choicesByUrl = getAttributeValueByProp(attr, "ChoicesByUrl");

DomainModelsViews/JsonForms.cs

@@ -22,7 +22,10 @@ public JSONForm(string formName)
         public dynamic GetFormJSON()
         {
             if(!this.IsValid) return null;
+            // Get a form JSON schema of the current `FormType` from the database
             string json = DataStorage.GetForm(this.FormType);
+            // If the JSON schema is not found, load a pre-generated JSON schema
+            // from a file in the Data directory
             if (string.IsNullOrEmpty(json)) {
                 json = this.getJsonFromData();
             }

README.md

@@ -1,66 +1,68 @@
-# SurveyJS as front-end form library for ASP.Net Core app
-
-The examples show how to use SurveyJS Library to edit Domain Models defined as C# classes.
-You can edit JSON Form Definition in our SurveyJS Creator and your end-user will see
-a different form for editing/filling forms without an application re-building/re-deploying.
-
-There are 3 Domain Classes in this example:
- * [JobApplication](/DomainModels/JobApplication.cs)
- * [NPSSurvey](/DomainModels/NPSSurvey.cs)
- * [PatientAssessment](/DomainModels/PatientAssessment.cs)
-
-## Mock database
-To make an example simple, the current implementation doesn't work with a database.
-DomainModel objects are stored in the memory by using a singleton [DataStorage](/DomainModels/DataStorage.cs) class.
-This singleton stores and retrieve data by class type and object Id (Unique string) 
-and serialize/deserialize objects by using MS .Net JsonSerializer Serialize/Deserialize functions.
-You can change our [DataStorage](/DomainModels/DataStorage.cs) class to write the code that will work with any database of your choice.
-As an alternative, you can use an ORM library.
-
-## Form List. Register a new form / DomainModel.
-To register a [DomainModelFormAttribute](/Code/FormAttributes.cs) class attribute is added.
-It has two parameters: "Name" and "Title".
-Here is the example of registering a new form:
-````csharp
-    [DomainModelForm("nps-survey", "NPS Survey (Domain Model without attributes)")]
-    public class NPSSurvey: DomainModel {
-        ...
-    }
-````
-The [DomainModelList](/DomainModels/DomainModelList.cs) can return the list of all registered DomainModel classes (forms)
-by calling static function `DomainModelList.GetAllForms();`. It get all classes in the running assembly
-and check all classes inherited from "DomainModel" with "DomainModelForm" attribute.
-You can get a DomainModel type by form name by calling a static function `DomainModelList.GetTypeByFormName(string formName);`.
-
-## Form Response View to fill out forms
-[Form Response View](/Views/Home/FormResponse.cshtml) shows SurveyJS runner to fill out a form.
-It uses SurveyJS Library for knockout to render the form. We use it instead of React or Angular or Vue versions, because of simplicity.
-The page contains minimim code related to JavaScript framework implementation.
-The survey runner shows on loading JSON form definition and survey data, by calling [loadFormAndData](/wwwroot/js/form_api.js) function.
-The form (survey) model is setup in [setupSurveyModel](/wwwroot/js/surveyjs.js) function. 
-Inside this function, on submitting form the [saveFormData](wwwroot/js/form_api.js) function is calling.
-
-## Getting JSON form definition
-There are two API server functions [loadform and loadform_and_data](/Controllers/FormController.cs).
-They return the JSON form definition by form name and the second function returns a previous entered form response by Id.
-The previous entered response data is getting by using our [DataStorage](/DomainModels/DataStorage.cs).
-JSON form definition is returning by the following rule. If there is a JSON with the same form name in "Data" directory then the context of this file is returned.
-If there is no such file in the directory, then the JSON form definition is generated on fly by DomainModel class corresponded with this form name.
-
-## Generating JSON by DomainModel
-By default the JSON form definition is generated based on DomainModel.
-[JsonFormGenerator](/DomainModelsViews/JsonFormGenerator.cs) class generates JSON by using .Net reflection API.
-Every public writable property in DomainModel is corresponded with a question in Form (Survey) JSON.
-Generator class uses property type and property attributes to generate the correct JSON.
-You can use .Net standard "Required" and "DisplayAttributes" as well as custom [FormPage and FormField](/Code/FormAttributes.cs) attributes.
-You can improve our current JSON generator class by adding new custom attributes or by adding more properties into our attributes.
-
-## Editing generating and existing Form JSONs
-You can edit default JSON Form Definition on [EditForm](/Views/Home/EditForm.cshtml) page.
-It loads form definition located in "Data" directory or generated by [JsonFormGenerator](/DomainModelsViews/JsonFormGenerator.cs) class
-and store changes in [DataStorage](/DomainModels/DataStorage.cs). After changing the JSON Form Definition, Form Response page will use new updated JSON for form editing.
-There are two modes for editing JSON Form Definition: admin and content manager.
-The first one has no limitation. Admin can add/delete any question/columns and so on.
-The mode for content manager doesn't allow to add/delete remove question or column or change question/column type or change their names.
-It means that content manager is not able to make form definition incorrect. It can change question title or change question location,
-but every question will be corresponded with a correct DomainModel property. 
+# Generate Forms from Domain Models with SurveyJS
+
+This example demonstrates how to generate forms in JSON format based on strongly-typed domain models and vice versa. Generated forms can be displayed by SurveyJS Form Library and edited in Survey Creator. This solution will be beneficial for content and product managers who regularly create forms and for backend developers who implement domain models based on these forms.
+
+<!-- TODO: Add illustration -->
+
+This application was built using ASP.NET Core. Follow the same instructions if you need to implement this functionality with any other server-side framework.
+
+- [Domain Models and Attributes](#domain-models-and-attributes)
+- [Generate Form JSON Schemas from Server-Side Domain Models](#generate-form-json-schemas-from-server-side-domain-models)
+- [Display a Form](#display-a-form)
+- [Edit JSON Schemas](#edit-json-schemas)
+- [Generate Domain Model Code Based on Form JSON Schemas](#generate-domain-model-code-based-on-form-json-schemas)
+
+## Domain Models and Attributes
+
+Domain models are declared in server-side code. You can generate form JSON schemas based on them. Domain model properties become form fields. You can then feed the JSON schemas into SurveyJS Form Library to display a form on your website or in your application. This project contains three sample domain models; each describes an individual form:
+
+- [`JobApplication`](/DomainModels/JobApplication.cs)
+- [`NPSSurvey`](/DomainModels/NPSSurvey.cs)
+- [`PatientAssessment`](/DomainModels/PatientAssessment.cs)
+
+A domain model and its properties can include [attributes](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/concepts/attributes/). A form generator uses attribute parameters to generate form JSON schemas. For instance, all domain models have the `DomainModelForm` attribute shown below. Its parameters configure a form's `name` and `title` properties.
+
+```csharp
+[DomainModelForm("nps-survey", "NPS Survey (Domain Model without attributes)")]
+public class NPSSurvey: DomainModel {
+    // ...
+}
+```
+
+A form generator can support predefined .NET attributes, such as [`Required`](https://learn.microsoft.com/en-us/dotnet/api/system.componentmodel.dataannotations.requiredattribute) or [`Display`](https://learn.microsoft.com/en-us/dotnet/api/system.componentmodel.dataannotations.displayattribute), as well as custom attributes, like `DomainModelForm`. The following file shows how this project implements custom attributes: [FormAttributes.cs](/Code/FormAttributes.cs).
+
+You can get a list of all domain models in the running assembly. Call the `DomainModelList.GetAllForms()` static method. It finds all classes that are inherited from `DomainModel` and have the `DomainModelForm` attribute. Refer to the following file for full code: [DomainModelList.cs](/DomainModels/DomainModelList.cs).
+
+## Generate Form JSON Schemas from Server-Side Domain Models
+
+Form JSON schemas are generated based on property types and attributes. Each public writable property in a `DomainModel` class becomes a form field in the form JSON schema. Refer to the [`JSONGeneratorByModelClass`](/DomainModelsViews/JsonFormGenerator.cs#L13) class to view the form generator code. The class implements a `Generate()` method that extracts all properties from a domain model, gets their type and attributes, and uses this information to build a JSON schema. You can extend the form generator's functionality: implement new custom attributes or add more properties to the existing attributes.
+
+## Display a Form
+
+SurveyJS ships with a tool that displays surveys and forms&mdash;[SurveyJS Form Library](https://surveyjs.io/form-library). You no longer need to create a separate page for each form you have in your application. Set up SurveyJS Form Library and assign different JSON schemas to it to display different forms. This tool supports all most popular JavaScript frameworks, including React, Angular, and Vue. However, this project uses the Form Library version for Knockout because it is the easiest version to set up. The [FormResponse.cshtml](/Views/Home/FormResponse.cshtml) file shows the Form Library configuration code.
+
+In this project, SurveyJS Form Library displays JSON schemas that come from different sources. The "NPS Survey" and "Patient Assessment" forms are pre-generated and stored as JSON files in the [Data](/Data/) directory. The "Job Application" form is generated from the `JobApplication` domain model on the fly. If a form JSON schema has been edited, its most recent version is stored in a database (or [database emulator](/DomainModels/DataStorage.cs), as in this application). When Form Library requests a JSON schema of a certain type, the server first searches for the most recently edited schema of that type in the database. If the schema is not found, the server returns a pre-generated schema from one of the JSON files. If a file with a schema of that type is also absent, the server generates the schema on the fly. Refer to the following file to find methods that implement this logic: [JsonForms.cs](/DomainModelsViews/JsonForms.cs).
+
+<!-- TODO: Add illustration -->
+
+## Edit JSON Schemas
+
+JSON schemas can be edited in any text editor, but they are easier to edit in [Survey Creator](https://surveyjs.io/survey-creator). This JavaScript component is a UI form designer by SurveyJS that content and product managers can use to create and modify JSON schemas without writing code. Similarly to SurveyJS Form Library, Survey Creator supports React, Angular, Vue, Knockout, and jQuery and is easy to integrate into your application. The project in this repository sets up the Knockout version (view the [EditForm.cshtml](/Views/Home/EditForm.cshtml) file).
+
+If in your team, more than one person creates and edits forms, you can configure multiple roles with different access rights. For example, you may define two roles: content manager and product manager. Content managers cannot create new forms and can edit only those form properties that do not require server-side code modification. These restrictions ensure the synchronization between domain models and form JSON schemas. Product managers, on the other hand, have unlimited capabilities and can request the backend development team to update domain models on the server. The role separation is implemented at the Survey Creator level. Refer to the [`creatorjs.js`](/wwwroot/js/creatorjs.js) file to see the implementation. You can also view the restricted UI for content managers in the following demo: [Setup for Content Managers](https://surveyjs.io/survey-creator/examples/setup-for-content-manager/).
+
+To make edited schemas available to the users, you do not need to wait until the backend development team rebuilds and redeploys the entire application. Edited schemas are saved in a database, and you can implement the functionality to prioritize them when SurveyJS Form Library loads a schema for display (see the [Display a Form](#display-a-form) section above). As a result, users can use an edited form immediately after the content or product manager modifies it. If the schema modification requires an update of domain models to maintain the model&ndash;schema synchronization, the backend development team may perform this update and rebuild and redeploy the application according to their own schedule.
+
+## Generate Domain Model Code Based on Form JSON Schemas
+
+Previously, you saw how to [implement a form generator](#generate-form-json-schemas-from-server-side-domain-models) that creates JSON schemas for client-side forms based on server-side domain models. You can also implement code that does the opposite&mdash;generates domain model code based on JSON schemas. This capability saves time for backend developers who implement domain models based on JSON schemas created by product managers.
+
+To implement a domain model generator, you need to parse the JSON schema being edited and convert the form fields to model properties. Users can view the generated domain model code under the Domain Model Code tab when they edit a form in Survey Creator as a product manager. View the following demo to see this functionality in action: [Create Domain Models](https://surveyjs.io/survey-creator/examples/create-domain-models/). Refer to the following file for full code: [codegenerator.js](/wwwroot/js/codegenerator.js).
+
+## Useful Links
+
+- [SurveyJS Website](https://surveyjs.io/)
+- [Form Library Documentation](https://surveyjs.io/form-library/documentation/overview)
+- [Form Library Demos](https://surveyjs.io/form-library/examples/nps-question/)
+- [Survey Creator Documentation](https://surveyjs.io/survey-creator/documentation/overview)
+- [Survey Creator Demos](https://surveyjs.io/survey-creator/examples/free-nps-survey-template/)

Views/Home/Index.cshtml

@@ -4,19 +4,18 @@
 </p>
 <p>
     Fill forms:
-        @for (var i = 0; i < Model.FormList.Count; i++)
-        {
-            var form = Model.FormList[i];
-            <div>@form.Title</div>
-            <ul>
-                <li><a href="/Home/[email protected]&id=new">Fill New Form</a></li>
-                @foreach (var obj in Model.GetObjectsByType(form.Name))
-                {
-                    <li><a href="/Home/[email protected]&[email protected]">Edit: @obj.ToString()</a></li>
-                }
-            </ul>
-        }
-    </ul>
+    @for (var i = 0; i < Model.FormList.Count; i++)
+    {
+        var form = Model.FormList[i];
+        <div>@form.Title</div>
+        <ul>
+            <li><a href="/Home/[email protected]&id=new">Fill New Form</a></li>
+            @foreach (var obj in Model.GetObjectsByType(form.Name))
+            {
+                <li><a href="/Home/[email protected]&[email protected]">Edit: @obj.ToString()</a></li>
+            }
+        </ul>
+    }
 </p>
 <p>
     Edit form presentation (as a content manager):