Developing webform-based iParts (ASCX)

❗️

Deprecation Notice

This method of generating iParts has been deprecated and is no longer supported. Please see Developing a client-based iPart.

Another method is to create an ASP.NET webform-based (ASCX) iPart. You need file access to the web server where iMIS is installed to create webform-based iParts. Therefore, this method is only available with iMIS 2017, and is not supported in iMIS Cloud.

There are two distinct methods for adding new webform-based iParts in iMIS:

• Simple iParts consist of only an ASCX control.
• Complex iParts have multiple user controls and can also include logic in class libraries.

Any user controls and class libraries that you create must be copied to a file path that resolves to the same root-relative URL on all servers that host iMIS RiSE websites (iMIS_webroot).

The user controls can be placed in any folder below the iMIS_webroot. The class libraries must be placed in the bin folder below the iMIS_webroot, for example, iMIS_webroot/bin.

📘

Note

The class libraries should also be added to the c:\AsiPlatform\Asi.Scheduler_your instance\bin folder.

When specifying paths to controls, be sure to use a slash (/) instead of a backslash for the segment delimiters.

Guidelines for creating webform-based iParts

When developing a webform-based iPart, you should adhere to the following guidelines:

• Use SOA to access the database (REST or WCF).
• Use a meaningful, unique name for your iPart and any related classes.
• Use descriptive namespaces and class names.
• Check for nulls on properties.
• Check for null parameters.
• Don’t use static variables.
• Use existing styles or create new styles using cascading stylesheets (CSS).
• Keep them simple. Create separate iParts instead of making just one iPart.

Creating a simple webform-based iPart in iMIS

A simple webform-based iPart requires only that you have a web user control that you want to display in a RiSE website content record.

Do the following to create a simple webform-based iPart:

1. Place the *.ascx file in a folder under the root directory of the iMIS application, for example, ~/iParts/MyOrg. The file must be included in the same path on all iMIS application servers and RiSE websites in order to work properly.
2. From the Staff site, go to RiSE > Page Builder and add or edit a content record.
3. Select the Add content link.
4. In the Content Gallery, enter the relative path to the web user control. The path you enter should be from the root of the web server’s application directory, for example, ~/iParts/MyOrg/MyControl.ascx.

📘

Note

Simple webform-based iParts do not support any design-time configuration options. Your control must include any styles or formatting needed when the iPart is rendered.

Creating a complex webform-based iPart in iMIS

A complex webform-based iPart provides more detailed configuration options, allowing the iPart to actively participate in decisions about how the iPart is configured, rendered, and published.

Most standard iParts available in iMIS use base classes to provide a consistent runtime and design-time control. These base classes should be inherited by your iPart user controls and classes. By starting your iPart development using the Visual Studio iPart Template, you can save time since the template already includes two user controls and a common class that inherit from these controls. If you create additional controls, you might want them to inherit from one of these base classes.

Do the following to create a new iPart using the Visual Studio iPart Template:

1. In Visual Studio, create a new iPart project using the iMIS iPart template and name it with a unique iPartname. The iPart project will contain the following sample files:

• iPartnameCommon.cs
• iPartnameDisplay.ascx
• iPartnameConfigEdit.ascx

These files have TODO comments to guide you in completing tasks that might be required in order to get your iPart working. Only a few of these tasks will need to be completed for this initial process.

2. The first task requires that you create a new content type in iMIS with details from your iPart project. When a content type is created, iMIS registers the new iPart and adds it to the Content Gallery.

📘

Note

The path you enter should be from the root of the web server’s application directory.

a. From the Staff site, go to RiSE > Maintenance > Content types.

b. Create a new folder with a unique name, for example, Widget World. Select the Allow only the following types of objects in this folder option and select only Content Type from the list.

📘

Note

Create a folder with the name of your organization for organizing your custom iParts. This will prevent your iParts from being accidentally overwritten. The folder is also added to the Content Gallery.

c. Highlight the folder and select New > Content Type.

d. Select ASCX-based and enter a name and description for the content type. The name should be similar to your iPart class name but can contain spaces. This is the name of the content type as it will be displayed in the Content Gallery.

Webform-based iParts require several advanced properties that will allow RiSE to interact with the code in your compiled project after the project is uploaded to the webserver. Additional optional properties are available to support special case features but are not often used.

e. In the URL to the control or page that is used to display items of this type at runtime field, provide the relative path to where your iPart display control file will be copied, for example:

~/iParts/WidgetWorld/HelloWorldDisplay.ascx

f. In the Name of the .NET assembly that contains the class that implements this content type field, enter the Assembly name from your iPart project properties.

📘

Note

This value defaults to Asi.Web.iParts.Custom.iPartname, but you might want to change this default value before you copy Assembly name.

g. In the Name of the serializable class within the assembly that implements this content type. Fully qualified name with namespace field, enter Assembly name.iPartnameCommon (the name of your iPart's common class).

h. (required) In the Name of the .NET assembly that contains the IContentType class used to publish this content type field, you will generally leave this value as the default (Asi.Business.ContentManagement.ContentItem) unless you have written your own class library that implements the IContentType interface.

i. (required) In the Name of the IContentType class within the assembly. Fully qualified name with namespace field, you will generally leave this value as the default (Asi.Business.ContentManagement.ContentType.ContentTypeBase), unless you want to develop your own class to perform custom actions when your iPart is published or rendered.

📘

Note

If you do create any such class, it must inherit the base class (Asi.Business.ContentManagement.ContentType.ContentTypeBase), and you must enter the fully qualified class name, including namespace.

j. (required) In the URL to the control or page that is used to collect the properties of a new item of this type field, enter the relative path to where your iPart configuration control file will be copied, for example:

~/iParts/WidgetWorld/HelloWorldConfigEdit.ascx

k. (required) In the URL to the control or page that is used to edit the properties of an existing item of this type. This is often the same as the NewLink field, enter the relative path to where your iPart configuration control file will be copied, for example:

~/iParts/WidgetWorld/HelloWorldConfigEdit.ascx

This value is only needed if you create a separate control for configuring an existing instance of the iPart that is different from the one used when creating a new instance of the iPart. Otherwise, this value can be the same as the value in the URL to the control or page that is used to collect the properties of a new item of this type field, or it can be left blank.

l. (unused) Leave the URL to the control or page that is used to collect parameters for content items of this type field blank.

m. (optional) In the URL to the icon graphic that represents items of this type field, enter the relative path to the images that will identify your iPart when a RiSE content page is in Easy Edit mode, for example:

~/iParts/WidgetWorld/HelloWorldIcon.gif

The image file must be 16x16 pixels in size. If this field is left blank, a default Easy Edit icon is used (~/AsiCommon/Images/icon_con_usercontrol.gif).

n. (optional) In the URL to the configuration help page field, enter the relative path to an HTML page containing the configuration help for your iPart, for example:

~/iParts/WidgetWorld/HelloWorldHelp.htm

The visual look and feel of the Help page is based on the iMIS theme for the website in which the iPart is being configured. To be consistent with the rest of iMIS, you should only use basic HTML and allow RiSE to style the page.

o. Click Save.

At this point, the new iPart has been added to the Content Gallery, but it is not yet usable on a content record.

When you select your new content type from the list of ContentTypes, you will see two warnings indicating that files related to your new content type could not be loaded. This is expected since the assembly references do not yet exist on the web server.

3. From the list of ContentTypes, select your new content type to display its properties. The second property under Advanced Properties is The ContentKey of this content type. The implementation class must override the ContentTypeKey property and return this value. Copy the entire string of characters shown.

4. In your Visual Studio iPart project, open the Common class (for example, HelloWorldCommon.cs) to edit:

• Locate the ContentTypeKey property and replace the string value with the ContentKey you copied previously

Note: Retain the quotation marks.

• Remove the two TODO comments above the value.

5. In your Visual Studio iPart project, open the ConfigEdit control class (for example, HelloWorldConfigEdit.ascx.cs) to edit:

• Locate the AtomComponentName property and replace the string value with the Content Type property name value you entered, if different from the default value.

Note: Retain the quotation marks.

• Remove the two TODO comments above the value.

6. Open the properties for your Visual Studio iPart project and change the following:

• In the Application tab, change the Assembly name and Default namespace from the defaults to values that are more appropriate for your iPart. Remember that the Assembly name must match the value on your Content Type as defined in iMIS.
• In the Application tab, update the Target framework to match the current version (for example, .NET Framework 4.5)

📘

Note

You might need to update the path for the WEB_ROOT and SCHEDULER_BIN parameters specified in the Deploy_iPart.bat file to match the installation on your web server. The defaults in the template are:

C:\Program Files (x86)\ASI\iMIS15\Net
C:\AsiPlatform\Asi.Scheduler_iMIS\bin)

7. Test that your iPart is working:

a. Create a new content record.

b. Add your iPart to the content record, then publish.

c. Create a navigation item that points to the new content record, then publish.

d. The template iPart simply displays the user name of the currently logged-in user, so when you navigate to it, you should see your user name.

You can now build your iPart to provide the new functionality. Once you're finished, update the files on the web server and test the iPart.

If you will be deploying your iPart across multiple webservers, you can use the Package Installer to create a deployment package.

iPart base classes

The first two base classes require a reference to the Asi.Web assembly (iMIS webroot\bin\Asi.Web.dll)

• iPartDisplayBase.cs: Implements common functionality for the iPart runtime display control. Your display control should inherit from iPartDisplayBase.
• iPartEditBase.cs: Implements common functionality for the iPart design-time control. Your design-time control should inherit from iPartEditBase.

The other base class requires a reference to the Asi.Business.ContentManagement assembly (iMIS webroot\bin\Asi.Business.ContentManagement.dll)

• iPartCommonBase.cs: Implements common functionality for both the iPart runtime display control and the iPart design-time control. Your iPart Common class should inherit from iPartCommonBase.

The base classes currently implement the following functionality:

Configuration options (available at design-time and common to all iParts).

If your iPart does not need one or more of these, they can be hidden using this example

• (required) Name: A unique name for the iPart (required for every iPart).
• Title: The title to display above the iPart.
• Do Not Render In Design Mode: Prevents contact data from loading in the content editor.
• iPart CssClass: The iPart will honor this CSS class setting.
• ShowBorder: Adds a border to the iPart.
• Display content within a collapsible panel: The iPart will display in a collapsible PanelTemplateControl if this option is set.
• Show the content as collapsed: The content within the iPart will display in a collapsed state if set.
• Display on screen sizes (for responsive themes only): Options to select on which devices the content should display.

Properties (available to the run-time control):

• EntityManager (also available to the design-time control): The EntityManager can be used to execute SOA functions.
• UserId: Returns the currently selected user.
• IsProxied: Indicates whether the UserId is the logged-in user.
• IsAnonymousUser: Indicates whether the current user is authenticated.