This project has moved. For the latest updates, please go here.

SPEasyForms is a tool for applying jQuery constructs like tabs and accordion to SharePoint forms without necessarily knowing anything about JavaScript or HTML or CSS.  It works on SharePoint 2010, 2013, and Online (Office 365). The things you can configure fall into 3 broad categories:

  • Containers - the ability to organize fields in a form in some way; current implementations include:
    • Tabs - an implementation of jQueryUI tabs
    • Accordion - an implementation of jQueryUI Accordion
    • Columns - the ability to put fields or containers into 2 or more columns instead of one per row (technically, one or more, but one column doesn't really buy you much)
    • Stack (NEW!) - allows you to stack 2 or more containers on top of each other, so you can put multiple containers onto a single tab or accordion page.
    • Wizard (NEW!) - a specialty container that allows users to page through containers using next and previous buttons.
    • HTML Snippets (NEW!) - a specialty container, that doesn’t actually hold any fields, but allows you to inject arbitrary HTML into the page, including referencing external scripts and style sheets.
  • Conditional Visibility – conditionally format a field:
    • Based on various conditions like:
      • Membership in a SharePoint group
      • Which form is open (i.e. the new, edit or display form)
      • Comparing the values of other fields based on various comparison operators (i.e. make this field read only when the Color field is equal to Red), comparison operators include:
        • Equals - equals a string literal
        • Matches - matches a JavaScript regular expression
        • NotMatches - does not match a JavaScript regular expression
        • GreaterThan (NEW!) - greater than a string literal
        • GreaterThanOrEquals (NEW!) - greater than or equals to a string literal
        • LessThan (NEW!) - less than a string literal
        • LessThanOrEquals (NEW!) - less than or equals a string literal
        • NotEquals (NEW!) - is not equal to a string literal
* All comparison operators ignore case
** All comparison operators except Matches/NotMatches will check if both operands are valid dates and use date comparison, check if both operands are valid numbers and use numeric comparison second, and lastly use string comparison
    • Formatting Options:
      • Hiding a field completely
      • Making a field read-only
      • Highlighting a field in one of four colors
  • Field Control Adapters - modify the controls users see in the form to input data; current implementations include:
    • Cascading Look Ups - join two look up fields such that the values available in one look up are trimmed based on the value selected in another look up
    • Autocomplete - provide type ahead functionality in a text field based on values pulled from a field in another list on the same site
    • Lookup Detail (NEW!) - allows you to pull in additional fields from a lookup list based on the value selected in a lookup field.
    • Default to Current User (NEW!) - pre-populate a user field with the current user on the new form.
    • Star Rating Adapter (NEW!) - can be applied to numeric fields. Fields are displayed as five stars and edited by clicking on one of the stars.

Most of the things marked (NEW!) were actually released in the updates package to v2014.01. The Stack and Star Ratings Adapter are actually brand new. Other than that, most of what’s changed in v2015.01.beta is:

  1. Added a Client Side Rendering (CSR) hook to hide the form until SPEasyForms has done it’s work, making the page load less jumpy (SharePoint 2013/Online only).
  2. Configure the jQuery UI theme used at the list and/or site collection level.
  3. Nested containers. Drag and drop parts of containers to reorder tabs for instance or move a tab to an accordion page.
  4. No longer using the default master, the settings page is now a stand-alone AXPX. This allows the same interface in SharePoint 2010 as 2013/Online. Also, highly customized master pages no longer mess-up the UI.
  5. Significant performance improvements on the settings page, especially for intense redraw activities like drag and drop.
  6. Updated third party libraries to their latest stable release: jQuery, jQuery-UI, and SPServices. In the case of jQuery and jQuery-UI, that’s the latest 1.x release.

There is a full fledged user manual that explains this functionality in nauseating detail, but it's approximately 45 pages.  This document is intended to provide a lighter overview of this functionality to get you started with using SPEasyForms quickly. The full manual is installed with the solution and available in the editor from the help button on the ribbon.

Installation

Download the SPEasyForms.2015.01.beta release from https://speasyforms.codeplex.com and follow these steps to install it:

  1. Go to the root site of your site collection and go to Site Settings –> Web Designer Galleries –> Solutions.
  2. Click the Upload Solution button in the ribbon.
  3. Browse to the SPEasyForms.wsp file you downloaded from CodePlex and hit OK.
  4. When the upload finishes, click the Activate button from the ribbon. Note that activation will take quite a bit of time because of all the files being copied to the style library and there is no indication that anything is happening, so be patient.

Now that wasn’t too painful, was it?  To confirm that it appears to be working, go to a list in your site collection and look for a button in the Settings panel of the List, Library or Calendar ribbon:

image_thumb8

Click the SPEasyForms button and you should see the SPEasyForms Settings page, which looks something like this:

image_thumb1011

There is on gotcha’ that you should be aware of. SPEasyForms installs all of its scripts and resources in the SPEasyFormsAssets folder of the site collection Style Library. If this library has force checkout turned on, all of the files may come in checked out to you (this seems to only be a problem on SharePoint 2010).

If the scripts are checked out, nobody else can see them except you so nobody else will see the things you configure SPEasyForms to do but you. There are over 300 files in this directory, so checking them in manually is impractical. The easy solution is to delete the entire directory, turn off force checkout in the library, and then deactivate and activate the SPEasyForms again. The files should now come in checked in.

In general, if somebody else cannot see what you’ve configured SPEasyForms to do, the first thing to check is can they at least read the files in the Style Library. The next check to make is can they at least read the Site Assets library on the same site as the list you’ve configured. That’s where the configuration files are stored.

Now that you’ve got it installed, I'll take you through quick step-by-step instructions for configuring each of the three broad categories you can configure with SPEasyForms, starting with configuring layout.

Configuring Layout

I’m just going to dive in and start mucking with the layout of a form, in this case for a Calendar. So after going to my Calendar and clicking on the SPEasyForms button on the Calendar ribbon, to add tabs:

  • Click the Add Container button on the ribbon.

image_thumb11111

  • Select Tabs from the drop down list and click Add.

image

  • Enter tab names one per line and hit OK.

The settings page should now look something like this:

image

The left-hand side of the settings page, which is the properties panel, now shows a tabs container at the bottom with two tabs.  The right-hand side of the page, which is a WYSIWYG panel at least for basic form structure, shows what the form looks like, which is no different at this point because empty containers are not drawn.  Note also that the save button is now active because you have changes that need saving.  It becomes inactive whenever you save and active whenever you have pending changes.  At this point I’m betting you are more or less thinking “great, so I have 2 empty tabs that don't even show in the form, big whoop!”  You can fix that pretty quickly by dragging and dropping fields from the default form to the tabs.

All edits are initiated in the properties panel on the left side of the screen.  The WYSIWYG panel simply displays the configuration. 

image

You can drag and drop fields from any field collection to any field collection, or even reorder fields within a field collection by drag and drop (note that reordering fields in the default form has no real effect, those are drawn by SharePoint in the order they’re configured to use in SharePoint).  And as soon as you drop something, the WYSIWYG updates to reflect your changes.  If you were actually one of those people who were thinking “big whoop” a couple of seconds ago, I think at least an ooh aah would be in order about now.  Well…I thought it was cool anyway.

You can add as many containers as you want.  Below is an example of a four container form (the bottom 2 collapsed in the editor):

image

Admittedly, it is not the most realistic example, four containers for nine fields is probably overkill.  But I’m trying to demo SPEasyForms here, not win a blue ribbon for most aesthetically pleasing form. 

You may have noticed that the default form in the above picture is now at the bottom. You can reorder the containers by drag and drop too.  Or reorder the tabs on a tabs container. You can even drag a container onto another container, so for instance you can drag the columns container onto the tabs container, in which case it becomes a two column tab. In the picture below, I’ve done just that plus I’m in the process of dragging the accordion container onto the tabs:

image

Noticed that the name of the container becomes the label for the tab, so I’ll probably want to rename Columns and Accordion to something more meaningful, which I can do by hitting the gear icon on the container title bar. Once I’ve dropped the Accordion and saved my configuration, my form now looks like:

image

As you can see from the above screen shot, SPEasyForms works on forms that open in a dialog too. If the form is on a dialog, it resizes the screen after it’s done its work, and again on certain events that may change the size of the content like validation or a tab change.

Note that there are some restrictions on where a container can be dropped based on the type of container and where you’re trying to drop it. In general, if a container cannot be dropped in a spot the placeholder underneath the container you’re currently dragging turns red. If you drop it anyway, it is returned to its original position. The restrictions for what you cannot do are as follows:

  • A field collection cannot have children, nor can it be a top-level container. It can only exist on another container. That’s why it can only be added on the add or edit container dialog box.
  • An HTML Snippet container cannot have children. I’m not going to talk about these much in this document, but its sole purpose is to display some arbitrary HTML on the page; it has no logic to deal with children.
  • The default form can neither have children nor be a child. SPEasyForms does not muck with the default form. It just puts stuff above it or below it, and moves fields from it to containers. Since it puts stuff both above and below it, you can move it up and down, but you can’t indent it and drag it onto a tabs container for instance.

You don’t really have to remember all that though, just remember that if the placeholder turns red it’s not a legal spot for that container.

Because a lot of editing is done by drag and drop, and the properties panel can become pretty complex for a large form, it often helps to collapse stuff between the source and destination before you drag and drop. You can collapse all containers (hide the sub-containers) with the Collapse button (or expand with…Expand).  You can toggle individual containers collapsed status by clicking the the little triangle icon on the right side no the title bar. Lastly, you can toggle the collapsed status of a container and all of it’s sub-containers by double clicking on its title bar.

So what are all of those other little buttons on the containers?  They are:

Button Scope Description

image_thumb28

Container Configure the container. This brings up the same dialog you see when you add a container. You can change the container name/title and/or add field collections to the container.

image_thumb3711

Container Delete this container, all fields that were on the container (or a sub-container) are returned to the default form. There is no confirmation, but you can always undo.

image_thumb53

Field Configure field visibility rules for this field.

image_thumb60

Field Add or configure the field adapter for this field. If there are no field adapter types available for a particular field type, this button will be missing next to fields of that type.

The last two buttons will be described in their own sections below.  Anyway, I think you now have enough information to start using the danged thing.  Don’t forget to save, after which you can go and open the new form on the list you just configured and observe the fruits of your handiwork.

Conditional Visibility

Conditional visibility allows you to configure fields to be hidden or read-only or even highlighted based on a variety of conditions. To configure conditional visibility rules for a field:

  • Click the key icon image_thumb53 next to the field in the properties panel.

image

  • Click the plus button image on the dialog.

image

  • The only required field for a rule is the state, choose either Hidden, ReadOnly, or Editable (or one of 4 highlight colors). If that’s the only thing you fill in, the rule will apply to all users on all forms.  Choose hidden and click OK.

image

The conditional visibility dialog now shows the rules for the current field in a list.  The above rule will hide the field Title on all forms (display name is Last Name).  Since title is generally a required field, this rule probably isn't such a good idea, as nobody will be able to submit a new item because they will get a validation error (which won't even be displayed as the entire row is hidden in a form when you hide a field), so keep that in mind. There are a couple of other options on the add rule dialog, so lets create a more complex rule:

  • Click the plus button image on the dialog again.

image

  • Select ReadOnly for the state.

image

  • Applies to is a type ahead entity picker for SharePoint Site Groups.  Start typing the name of one or more SharePoint groups and select it from the drop down.  You can also check the box labeled author to apply this state to whoever created the item regardless of their group membership.
  • For forms, you can apply this rules for any combination of the new, edit, and display forms.  The default is all three, and I’m going to leave that alone for now.
  • Click OK.

That brings us back to the conditional visibility dialog, where there are now two rules:

image

When a user comes to a form, for each field for which there are conditional visibility rules configured, the first rule which matches the current user is the only rule that will be enforced for that field.  That means the order for the fields is very important, you want to go from very specific rules to very general rules.  It also means the above rules don’t make sense; the second rule will never be reached, since the first rule applies to everyone.  You can reorder the rules by drag and drop:

image

The other buttons next to each rule in the list are:

  • The  gear button image takes you to a dialog where you can edit the rule.
  • The  X button image deletes the rule.

Finally, you can get a list of all configured rules for all fields on the main settings form, by clicking the Conditional Visibility button in the ribbon.  This is a static list, nothing is sortable or editable, but you can double click a rule to launch the visibility rules dialog again.

image

Field Adapters

Field control adapters allow you to change the look and/or behavior of a field in the new, edit, and display forms. I'll quickly describe adding one of them and show what it does to get you started; the Autocomplete adapter, which is a pretty simple one. To add it:

  • Click the wrench icon image_thumb60 next to a field of type SPFieldText (I’m doing Title).

image

  • Choose Autocomplete from the list of available adapters.

image

  • Choose the list you want to reference for the Autocomplete field. There will be a slight delay as I get information about the list from the server. Then choose the field you want to reference (note: if the form column drop down is empty, click on cancel, click on "Clear Cache", and try again). I have a list of Standard meetings and the title field contains meeting titles so that's what I've chosen.
  • Once you've done that, the Field Adapters View will look like:

image

  • Once you've saved the configuration, open the new form of list and the Title field should have type ahead functionality starting at 2 characters (note: if you configured the field visibility rules in the last section, you probably have to remove them or add a rule before them so you can edit the title field before you can test this):

image

Note: If the wrench icon image_thumb60 does not appear next to a field, it's because there are no adapter implementations for that field type.

To remove adapter from a field, click the X button next to the adapter in the Field Adapters View.

Wrapping It Up

That’s pretty much it for an overview of SPEasyForms functionality.  Hope you find it useful.  Rate it, leave comments in the discussion board, add issues if you encounter bugs or to request feature enhancements etc.  If any of the above isn't clear, check out the corresponding section in the full blown user manual, and hit me up on the discussion board if it still isn't clear.

Last edited Jan 26, 2016 at 6:25 PM by mcsheaj, version 5