rhythmagency / formulate

An advanced form builder for Umbraco.

Formulate Overview

A form builder for Umbraco. More info here: www.formulate.rocks

Contributors

These are some of the people who have made Formulate possible:

• Nicholas Westby - Rhythm Agency - nicholaswestby.com
• Jamie Pollock - Rhythm Agency = @jamiepollock
• Josef Kohout - Rhythm Agency - rhythmagency.com

Contributing

Requires:

• Visual Studio 2017
• Node.js
• npm
• grunt-cli (installed globally)

Building

To build the source code, you can use the simple building technique or the advanced building technique. Both versions are described below.

Simple Building Technique

Double click the file "build/build.bat". The Umbraco package will be created in the "dist" folder. You can then install this Umbraco package into your website.

If you would like to use the built-in sample website, refer to the advanced building technique below.

Advanced Building Technique

These are the steps you can take to build and test Formulate:

• Build the solution.
• Run npm install (this only needs to be done once).
• Run npm i grunt-cli -g (this only needs to be done once).
• Run grunt.
  • Pro-tip: Running grunt frontend is faster
• Run the sample website.
• Run grunt package to create an Umbraco installer package (in the "dist" folder).

There are a few nuances to building you may want to consider:

• Most grunt tasks will use whichever build configuration is most recent, but will otherwise default to "Release".
• The grunt package-full task always defaults to "Release".
• You can specify a particular build configuration like this: grunt package-full --buildConfiguration=Debug.

Assemblies / Projects / Folders

Each project is built into an assembly, and each assembly has a different purpose. Here is a description of each project's purpose:

• formulate.api: This contains the easy to use functionality that a developer rendering Formulate forms will need.
• formulate.app: This is the main core of Formulate. It contains all of the functionality necessary for the back office to work.
• formulate.core: This contains some basic functionality shared by all of the assemblies.
• formulate.meta: This contains information about Formulate (e.g., version number). Used primarily during the build process.
• formulate.deploy: This project contains the functionality necessary for Formulate to extend Umbraco Deploy.
• Website: This is a sample website for developers who wish to contribute to the Formulate codebase. The binary is not part of the packaged releases, though a few of the files it contains are (e.g., some CSHTML, config, and XDT files).

There a few a few other folders as well:

• formulate.backoffice.ui This contains the styles for the Formulate components in the Umbraco back office.
• formulate.frontend This contains the frontend code for Formulate (e.g., the JavaScript to render the forms on your website).

Maintainers

To create a new release to NuGet, see the NuGet documentation. Releases should also be made to Our and to GitHub.

Thanks

Thanks to the creators of the following Umbraco packages, which served as excellent points of reference while building Formulate:

• Archetype
• Umbraco Bookshelf
• Form Editor
• Merchello

formulate's Issues

Implement Server-Side Validations

Currently, validations only happen on the client side. They are not yet implemented on the server-side:

formulate/src/formulate.api/Submissions.cs

Line 101 in 77d1247

//TODO: var validationResult = validation.Validate(form, field, valuesById);

Allow Non-Uniform Column Widths in Layout Designer

A good example is here: https://our.umbraco.org/projects/backoffice-extensions/formulate/formulate-questions/77200-layout-with-non-uniform-column-widths

Use Grunt to Create Umbraco Package

I can use this: https://github.com/tomfulton/grunt-umbraco-package

I'll have to create a fork to add support for including package actions, unless this other task is completed: tomfulton/grunt-umbraco-package#10

Replace Placeholders in Validation Messages

For example, if somebody types this as the validation message:

The {name} field is mandatory.

When somebody attaches that validation to the "First Name" field, the validation message on the frontend of the website should read:

The First Name field is mandatory.

Of course, we'd want to support all 3 aspects of the field: name, alias, and label.

Remove Field Previews

The field previews aren't all that useful (at least, in their current incarnation). Might as well just get rid of them.

I believe text and text area both have previews. Checkbox might also.

Add Configurable Workflow Support

Would like to be able to allow the editor to send an email or perform some other action on form submission.

Otherwise, I'll just have to create some event that developers can subscribe to in order to perform custom actions.

Populate Aliases and Labels Automatically

For example, when typing the name for a newly added field, automatically populate the field alias and field label based on what the user is typing into the name field.

Once a save occurs or once the user manually changes the automatically generated properties, discontinue automatically modifying those properties.

This will help speed up form creation, as many users will not modify the alias or label properties.

Duplicates in Dashboard.config on Upgrades

FormulateSection gets added to the dashboard.config a second time on Formulate upgrades.

Add Ability to Copy Forms

Would be nice if I could just right click a form and select "Copy" to create a new form that is identical (aside from ID's and such).

Saving Removes Validations

If you have a form with some fields that have validations, saving will remove those validations.

error when you choose them remove form selected

hi

im building a site with loads of forms on it for different treatments so i have created a partial view file to include within the pages @{ Html.RenderPartial("umbformulate"); }.

which has the following code:

@inherits Umbraco.Web.Mvc.UmbracoTemplatePage
@using formulate.app.Types

@{

// Get a view model for the picked form.
var pickedForm = Model.Content.GetPropertyValue<ConfiguredFormInfo>("formPicker");
var vm = formulate.api.Rendering.GetFormViewModel(pickedForm.FormId, pickedForm.LayoutId,
    pickedForm.TemplateId);

}

    <!-- Display the form. -->
    <div ng-if="status !== 'success'">
        <div class="container">
            @Html.Partial("~/Views/Partials/Formulate/RenderForm.cshtml", vm)
        </div>

    </div>

    <!-- Display the success message. -->
    <div ng-if="status === 'success'">
        Your request has been received!
    </div>

    <!-- Display the error message. -->
    <div ng-if="status === 'failure'">
        Unable to submit request. Please try again.
    </div>

</div>

I have a problem when I select a form page it renders fine (it has some style issues) but when I deselect the form i get an error.

Exception Details: formulate.core.Exceptions.ViewNotFoundException: The specified Formulate view could not be located on the file system.

Line 3: @{
Line 4: var viewPath = Model.TemplatePath;
Line 5: FileUtility.ValidateView(viewPath);
Line 6: }
Line 7: @Html.Partial(viewPath, Model)

i have tried an if statement to see if that will fix it

@if (CurrentPage.HasValue("formPicker"))
{
@{ Html.RenderPartial("umbformulate"); }
}

but no luck. any ideas? im not a full on coder so any help would be great.

regards,

Ian

Formulate in 7.3.4

Hi Nicholas,

I know the package is made for umbraco 7.4. I've tested in 7.3.4. Installs fine,
But after i add the "Formulate section" to the user, everytime i go the user section i lose session. This also is happening in Developer section "Packages Installed".

Another problem is that after install i have 3 Formulate Sections on umbraco backoffice.

The package will only be developed for 7.4 version?

Best regards,

Make Server-Side Validation Optional

For example, to prevent PHI from being sent from the server to a browser.

Document Steps for Installing From the Umbraco Package Repository

Add Button Field Type

A button will be a field type like any other field type. This will allow multiple buttons placed anywhere in the layout.

Later, we can also support the possibility of choosing the type of button (e.g., submit, cancel, reset). Would be really neat of those button types were extensible.

Allow Folder Aliases

Useful if somebody wants to programmatically refer to a folder (e.g., to render all forms in a particular folder with a particular style).

Create Sample Formulate Website

So people can play with it right away.

Disambiguate Text & Text Area

I believe they use the same icon currently, which can be confusing. Get a different icon for text area.

Add Message to Validations

Currently, the only validation is regex. Add a message to be shown to the user when the validation fails.

Add Documentation on Updating Formulate

This would supplement the install procedure: http://www.formulate.rocks/installing

attachment on forms & copy forms

hi

is it possible to have a file attachment on the forms for a pdf/word file that would send onto the recipient emails?

also is it possible to copy/duplicate a form.

thanks

Permit Button No Longer Works

The "Permit" button in the developer "Formulate" dashboard that is supposed to give the user access to Formulate no longer seems to work.

Create NuGet Packages

One for the main install, and one for the binaries.

Add Highlighting for All Node Types

Right now, only the main entities are highlighted in the tree when activated. Also highlight the folders and root nodes.

Convert Routes to Slug Case

For example, /umbraco#/formulate/formulate/editDataValue/85d32dc96d6043978424668012e122d4 should become /umbraco#/formulate/formulate/edit-data-value/85d32dc96d6043978424668012e122d4.

Avoid Errors on Install

Sometimes, errors occur when installing the Formulate package. My guess is this is because Formulate will run some code on application start that can make a number of modifications (e.g., to config files) that will initiate an application pool recycle. They may be tripping over each other, or they may be interfering with the package installer in Umbraco.

One idea would be to use QueueBackgroundWorkItem (QBWI) to delay application pool recycles until after all config changes have been made: https://blogs.msdn.microsoft.com/webdev/2014/06/04/queuebackgroundworkitem-to-reliably-schedule-and-run-background-processes-in-asp-net/

Another idea would be to delay the config changes a few seconds so the package installer has a chance to finish. The downside of that is that some people may be quick to close Umbraco after the package installation and wouldn't run the other config changes until the next time they run the site (which may lead to some confusion, as changes would be made for what would seem to them to be no apparent reason).

Will start with the QBWI idea, then try the delay if necessary.

FYI, a temporary workaround is to install Formulate twice. The first install does all the modifications (e.g., config transforms). The second install ensures everything is there.

Save Submitted Data. How?

Save Submitted Data. How?

Document Styling Formulate Forms

For example, styling error states and so on.

Correct Validation CSS Class

Seems like validation classes are added based on the alias of the validation rather than the type of validation. For styling, it seems like it'd be more useful to have a CSS class based on the validation type. For example, I'd prefer to see a CSS class of "ng-invalid-regex" rather than "ng-invalid-email".

Add "Move" Menu Action

That way, entities (forms, validations, layouts, forms, etc.) can be moved to a new parent (either root or folder). Will have to avoid moving folders under themselves.

Add Text Area Field Type

In contrast with a text field type, the text area will allow for a larger textbox.

Create Starter Kit with Formulate Functionality

Localization of tree nodes etc.

Ensure tree nodes, labels in views etc. are localizable.

Test Performance in Extreme Situations

Here's a forum post that outlines some good test conditions: https://our.umbraco.org/projects/backoffice-extensions/formulate/formulate-questions/76613-performance

• 100 fields
• 200 forms
• 10 pages

Formulate doesn't currently natively support pages in forms, though it does support the possibility of creating a custom layout designer that could support pages. One could also use the existing layout designer to support pages if they use the rows as pages rather than rows (though, that would reduce the layout options within pages). Something to consider if we add support for pages by the time we add this performance testing.

Should be easy enough to create 200 forms. Just need to create one form, then copy it a bunch of times, changing the form GUID in the process.

Give Installing User Permission to Formulate

That way, they don't even have to click the "Permit" button to have Formulate permission. If it can't be added as a package action, I'm thinking the install completed screen can have some JavaScript that initiates a call to the server that informs it to give the current user access to Formulate.

See forum thread: https://our.umbraco.org/projects/backoffice-extensions/formulate/formulate-questions/76554-formulate-feedback-does-it-work-for-you#comment-244763

Add "Delete Folder" Menu Action

Will probably want a confirmation (e.g., with a dialog) that all descendant elements should also be deleted.

Email Whitelist for Workflows

To be compliant with some standards, there may need to be a whitelist so that email can only be sent to a pre-approved list of people.

Install Code Runs Multiple Times

While it shouldn't be a problem, as I've built the install code to avoid errors when running multiple times, I did notice from my log that the Formulate install code is run about 6 times:

Not sure why that is. Maybe Umbraco runs the application started handler several times? Or maybe it has to do with application pool recycles?

Look into what is causing this, and fix it. One idea would be to create a static boolean indicating that the install code has run, so it doesn't run again.

Document How to Configure/Customize Templates

That way, people know not to modify existing templates without first copying the files and adding the new template to the proper config file.

Support CAPTCHA

This will help prevent bot spam.

Document Go Live Tasks / Checklist

It would be nice if there were a page on formulate.rocks that described a few things developers will want to do when deploying things to production. As an example, they might want to configure a different folder to store the JSON stuff in to avoid having their local dev forms overwrite their production forms.

System.Reflection.ReflectionTypeLoadException: Unable to load one or more of the requested types. Retrieve the LoaderExceptions property for more information.

at System.Reflection.RuntimeModule.GetTypes(RuntimeModule module)
at System.Reflection.RuntimeModule.GetTypes()
at System.Reflection.Assembly.GetTypes()
at formulate.app.Helpers.ReflectionHelper.<>c__91.<InstantiateInterfaceImplementations>b__9_0(Assembly x) in C:\r\formulate\src\formulate.app\Helpers\ReflectionHelper.cs:line 72 at System.Linq.Enumerable.<SelectManyIterator>d__142.MoveNext()
at System.Linq.Enumerable.WhereEnumerableIterator1.MoveNext() at System.Collections.Generic.List1..ctor(IEnumerable1 collection) at System.Linq.Enumerable.ToList[TSource](IEnumerable1 source)
at formulate.app.Helpers.ReflectionHelper.InstantiateInterfaceImplementationsT in C:\r\formulate\src\formulate.app\Helpers\ReflectionHelper.cs:line 71
at formulate.app.Serialization.FieldsJsonConverter.InstantiateFieldByTypeId(Guid typeId) in C:\r\formulate\src\formulate.app\Serialization\FieldsJsonConverter.cs:line 120
at formulate.app.Serialization.FieldsJsonConverter.ReadJson(JsonReader reader, Type objectType, Object existingValue, JsonSerializer serializer) in C:\r\formulate\src\formulate.app\Serialization\FieldsJsonConverter.cs:line 67
at Newtonsoft.Json.Serialization.JsonSerializerInternalReader.DeserializeConvertable(JsonConverter converter, JsonReader reader, Type objectType, Object existingValue)
at Newtonsoft.Json.Serialization.JsonSerializerInternalReader.SetPropertyValue(JsonProperty property, JsonConverter propertyConverter, JsonContainerContract containerContract, JsonProperty containerProperty, JsonReader reader, Object target)
at Newtonsoft.Json.Serialization.JsonSerializerInternalReader.PopulateObject(Object newObject, JsonReader reader, JsonObjectContract contract, JsonProperty member, String id)
at Newtonsoft.Json.Serialization.JsonSerializerInternalReader.CreateObject(JsonReader reader, Type objectType, JsonContract contract, JsonProperty member, JsonContainerContract containerContract, JsonProperty containerMember, Object existingValue)
at Newtonsoft.Json.Serialization.JsonSerializerInternalReader.CreateValueInternal(JsonReader reader, Type objectType, JsonContract contract, JsonProperty member, JsonContainerContract containerContract, JsonProperty containerMember, Object existingValue)
at Newtonsoft.Json.Serialization.JsonSerializerInternalReader.Deserialize(JsonReader reader, Type objectType, Boolean checkAdditionalContent)
at Newtonsoft.Json.JsonSerializer.DeserializeInternal(JsonReader reader, Type objectType)
at Newtonsoft.Json.JsonConvert.DeserializeObject(String value, Type type, JsonSerializerSettings settings)
at Newtonsoft.Json.JsonConvert.DeserializeObject[T](String value, JsonSerializerSettings settings)
at formulate.app.Helpers.JsonHelper.Deserialize[T](String value) in C:\r\formulate\src\formulate.app\Helpers\JsonHelper.cs:line 55
at formulate.app.Persistence.Internal.JsonPersistenceHelper.RetrieveAllEntityType in C:\r\formulate\src\formulate.app\Persistence\Internal\JsonPersistenceHelper.cs:line 227
at formulate.app.Persistence.Internal.JsonPersistenceHelper.RetrieveChildren[EntityType](Nullable1 parentId) in C:\r\formulate\src\formulate.app\Persistence\Internal\JsonPersistenceHelper.cs:line 188 at formulate.app.Persistence.Internal.JsonFormPersistence.RetrieveChildren(Nullable1 parentId) in C:\r\formulate\src\formulate.app\Persistence\Internal\JsonFormPersistence.cs:line 185
at formulate.app.Persistence.Internal.DefaultEntityPersistence.RetrieveChildren(Nullable1 parentId) in C:\r\formulate\src\formulate.app\Persistence\Internal\DefaultEntityPersistence.cs:line 165 at formulate.app.Trees.FormulateTreeController.GetTreeNodes(String id, FormDataCollection queryStrings) in C:\r\formulate\src\formulate.app\Trees\FormulateTreeController.cs:line 187 at Umbraco.Web.Trees.TreeControllerBase.GetNodes(String id, FormDataCollection queryStrings) at Umbraco.Web.Trees.ApplicationTreeExtensions.TryLoadFromControllerTree(ApplicationTree appTree, String id, FormDataCollection formCollection, HttpControllerContext controllerContext) at Umbraco.Web.Trees.ApplicationTreeController.<GetRootForSingleAppTree>d__17.MoveNext() --- End of stack trace from previous location where exception was thrown --- at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task) at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task) at Umbraco.Web.Trees.ApplicationTreeController.<GetApplicationTrees>d__4.MoveNext() --- End of stack trace from previous location where exception was thrown --- at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task) at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task) at System.Threading.Tasks.TaskHelpersExtensions.<CastToObject>d__31.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Controllers.ApiControllerActionInvoker.d__0.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Filters.ActionFilterAttribute.d__5.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Web.Http.Filters.ActionFilterAttribute.d__5.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Filters.ActionFilterAttribute.d__0.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Filters.ActionFilterAttribute.d__5.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Web.Http.Filters.ActionFilterAttribute.d__5.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Filters.ActionFilterAttribute.d__0.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Filters.ActionFilterAttribute.d__5.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Web.Http.Filters.ActionFilterAttribute.d__5.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Filters.ActionFilterAttribute.d__0.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Controllers.ActionFilterResult.d__2.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Filters.AuthorizationFilterAttribute.d__2.MoveNext()
--- End of stack trace from previous location where exception was thrown ---
at System.Runtime.CompilerServices.TaskAwaiter.ThrowForNonSuccess(Task task)
at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)
at System.Web.Http.Dispatcher.HttpControllerDispatcher.d__1.MoveNext()

Move Handlers to Form Configuration

For example, it is common to want to send emails to different people based on which page a form appears on. Would be much easier to facilitate this if handlers had their own tree section and could be picked as part of the form configuration.

Include Sample Validations

It would be fairly easy to include a few sample validations (e.g., a regex validation for email addresses). Would just have to include the JSON files in the Formulate install.

Document AngularJS Template Code

The code could use a little extra documentation (so that people can make further customizations without having to know the code intimately).

Suggestion - RTE field

Hi man,

you form editor is as simple as powerfull. That's a great great job!

The only thing i found missing is a Rich Text Editor Field to better style the header of the form.
Are you planning to support it?

Thanks again for you work,
Alessandro

Formulate breaks other custom fonts icons

It seems you package is breaking other custom font icons, e.g Font Awesome font package and my Material Design Icon Pack.

In this line you should prefix it with icon-formulate- instead.
https://github.com/rhythmagency/formulate/blob/master/src/formulate.app/App_Plugins/formulate/styles/formulate-icomoon.css#L14

An example:
https://github.com/bjarnef/Material-Design-Icon-Pack/blob/master/GMD.IconPack/css/material-design-iconic-font.css#L18-L19

The first "home" icon is from font awesome, the second Google Material and the third in core.

but it also conflict with other icons, e.g. the three first icons is in font awesome icon package (but Formulate override the custom font):

Add Support for Sorting Entities

Right now, it is arbitrarily sorted (perhaps by file system order).

Add Settings to Disable Most Features

For example, it would be useful if there were a setting to disable the "Button" field type (e.g., if the user creates their own more advanced button field type and doesn't want the old one available). Same for the rest of the field types. And other features (e.g., handlers).

One scenario where this may be especially important is if I create a "Formulate Samples" project. Maybe some people would want some aspects from that project, but not all of the features it would provide.

I'm thinking we should make these settings generic (e.g., pass in the GUID for a field type to disable it, rather than have an explicit setting to disable specific field types). That would make it so even third-party items can be disabled (e.g., things in "Formulate Samples").

Add Submissions Handler & Dashboard

Create a form handler that submits the data to some data store (maybe swappable as part of the persistence layer) and a submissions dashboard that can read entries from that data store.