2023.1:Grooper Scripting - CSS Utilities

This article is about an older version of Grooper. Information may be out of date and UI elements may have changed.
2025	2023.1

Gain familiarity with the Grooper object model by scripting real world examples and see how commonly used namespaces and their members are leveraged.

You may download the ZIP below and upload it into your own Grooper environment (version 2023.1). It contains a folder to be imported into the "Projects" folder in the node tree. There are two Projects in this folder: an "incomplete" version for use in following along with the walkthrough of this article, and a "complete" version you can use if you want to quickly test the end result. The complete version has a compiled solution with the appropriate .dll and .xml files attached to the Object Library. If you are going to follow along with the walkthrough, delete the "complete" version. If you want to test the results of the completed Object Library you will need to recycle the "GrooperAppPool" in IIS after import for the object command to be available. Media:2023.1_Wiki_Grooper-Scripting-CSS-Utilities_Projects.zip

About

IMPORTANT

Before we begin, it is highly recommend to review the contents of the Remote Scripting Setup article. In that article you will learn how to configure your environment so that you can debug on your local machine, and not need to be on the "Grooper Server" in order to do so. You will also see how the Grooper SDK is used to push the files of your local solution to the target object in Grooper so that it may be properly compiled within the application.

---

The purpose of this article is to walk you through an example of creating a simple object command that will set CSS styling in the Style Sheet property of "DataFieldContainer" objects. In so doing we will get exposure to the powerful Object Library object and its useful solution template functionality. This solution will then be used in Visual Studio 2019 to write the necessary code to accomplish the desired task. This will reveal namespaces and their members that are commonly used to expand the capabilities of Grooper via scripting.

The script we create will be fairly simple, but it will give you a foundation upon which you could very easily expand to increase it's capabilities and usefulness. In so doing you can make a powerful and easy to use tool you may end up using in your regular Grooper designing.

Getting Started

In this section we will get the necessary components created from Grooper to begin setup for our object command.

Import Project Files and Create Object Library

The system this work will be done on is configured appropriately to debug and push files to Grooper via the Grooper SDK. Given that, the following is true:

• Grooper is installed
• Grooper Config has been run and pointed at a "Grooper Repository"
• An Active Directory account has been created and configured with the appropriate permissions to be leveraged by the Grooper Web Client
• IIS has been installed and appropriately configured
• The Grooper Web Client is installed and is using the aforementioned AD account for its application pool identity
• Visual Studio has been installed with the ASP.NET and web development workload
• The Grooper SDK extension has been added to Visual Studio

1. Open a compatible web browser (in this case Google Chrome is being used)
2. In the URL box type:

   localhost/Grooper/Design

3. Select the "Projects" folder in the node tree
4. Click the "Upload" button
5. In the "ZIP File Import" dialog box click the "Choose File" button
6. Browse to where you downloaded the Grooper ZIP file provided for this article, select the file, and click "Open"
7. Back in the "ZIP File Import" dialog box click the "Upload" button to complete the upload

A "completed" version of the work we'll be doing is provided. It contains a compiled version of the solution attached to the Object Library we will create. If you wanted to use this you could simply refresh the "GrooperAppPool" in IIS and the object command would be available. However, for the purposes of this walkthrough it will be removed.

8. Expand the folder of the imported object
9. Right-click the 'completed' Project and select "Delete"
10. In the "Delete" dialog box click the "Execute" button

11. Expand the folder provided from the ZIP import
12. Right-click the "Object Libraries" folder
13. In the pop-out menu select Add > Object Library
14. In the "Add" dialog box use the name:

    CssUtilities

15. Click the "Execute" button

16. With the Object Library added we can see it in the node tree

Create and Download C# Solution Files

Moving forward in this walkthrough we will be using C# for our .NET coding language as it by far the most popular choice. If enough requests for VB variations of the code come in we could update this walkthrough to have both.

1. Select the newly created Object Library
2. Click the "Scripting" tab.
3. Click the "Create" button.
   • This button will be grayed out if you are not using "localhost" in your URL.
   • Refer to the Remote Scripting Setup article for information on setting up your environment if you are working from a computer that is not the computer where Grooper and the Grooper Web Client is installed.
4. Choose C# from the drop-down menu.

5. Executing the previous command will create several files from a template that will be the foundation of the solution we will edit in Visual Studio.
6. You can select individual files and view their contents in the Document Viewer.
7. You can download individual files or even make edits here, although this may not be the best interface for doing edits.
8. The "ScriptingSession.cs" file has a couple of important comments.
   • Please note that compiling this script from Visual Studio will not add/update the ObjectLibrary DLL in Grooper. To add/update this DLL in Grooper and make the functionality in this project visible to Grooper, the Compile button must be used from the Script tab of the Grooper node in the Grooper Web Client.
   • You can debug with the GrooperSDK. Find the GrooperSDK in Visual Studio by going to Extensions..Manage Extensions..Online and searching for 'Grooper'. In addition to debugging, the GrooperSDK exposes commands such as Save, Save and Compile, and Get Latest.

The solution files that were just created are attached to the "CssUtilities" Object Library in the "Grooper Filestore". In order to properly edit this solution in Visual Studio we need to download a local copy of these files.

9. Click the "Advanced" tab.
10. Here you can see the files made are attached to this object in the "Grooper Filestore". We need to download local copies of these files to edit them.

11. Click back on the "Scripting" tab.
12. In the "Working Directory" dialog box, enter a path. The default path provided will suffice.

    C:\GrooperScripts

13. Click the "OK" button.
14. In the "Edit Script" dialog box a message confirms the files were saved and put in a sub-directory named after the selected object.
15. Click the "OK" button.

While we're still in Grooper let's download an image that will be used as an "IconResource" in our solution.

16. Expand the "Resources" folder and select "CssBadge.png".
17. Right-click the image in the Document Viewer and select "Save image as".
18. Choose a directory to save. The "Downloads" folder will suffice.
19. Name the file:

    CssBadge.png

20. Click the "Save" button.

Coding

Now for the fun part! In this section we will be writing the code for our "CssUtilities" namespace by defining the class and methods that will execute our object command.

NOTE: It's a good idea, when you can, to run Visual Studio with elevated permissions.

IconResource

We will start by adding our first piece of Grooper code: an attribute class called "IconResourceAttribute", but we'll call it simply as "IconResource".

Definition

The "IconResourceAttribute" is a class that allows you to decorate classes, methods, or properties with metadata specifying an icon resource. This icon can be used in various parts of an application to visually represent the annotated element.

Key Components

• Namespace: Grooper
• Assembly: Grooper.dll

Attribute Targets

• Targets: Class, Method, Property

Enum: IconStyle

• Normal: Standard icon without any overlay.
• OverlayOnFolder: Icon overlaid on a folder image.
• Add, Delete, Edit, Error, Go, Back, Lightning, Link, Save, GreenDot, RedDot, Search, Check, Folder, Archive, Wrench, Refresh: Various predefined styles for the icon.

Fields

• IconResource: string - The name of the image resource.
• Style: IconStyle - The style of the icon.
• AssemblyName: string - The name of the assembly where the resource is located (optional).

Properties

• ErrorImage: Bitmap - A static property that returns an error image if the specified icon resource is not found.

Methods

• Constructors:
  • IconResourceAttribute(string IconResource, IconStyle Style = IconStyle.Normal)
  • IconResourceAttribute(string AssemblyName, string IconResource, IconStyle Style = IconStyle.Normal)
• GetBitmap(Type tpe): Returns the bitmap image of the icon for the given type.
• GetBitmap(Assembly Assembly): Returns the bitmap image from the specified assembly.
• CreateIcon(Type tpe): Creates an icon handle from the bitmap.
• GetIconKey(Type tpe): Generates a key for the icon based on type.
• GetIconStream(Type tpe): Returns a stream of the icon image.
• Static Methods:
  • GetBlankIcon(): Returns a blank icon.
  • GetBlankStream(): Returns a stream for a blank icon.
  • GetIconKey(Assembly Assm, string IconResource, IconStyle Style): Generates a key for the icon based on assembly and style.
  • GetBitmap(Assembly Assm, string IconResource, IconStyle Style): Retrieves the bitmap image from the assembly with specified style.

Caching

• IconCache: A dictionary that caches icon images to avoid redundant loading.

Private Helpers

• NamedAssembly: Returns the assembly based on the AssemblyName field.
• GetAssembly(Type Type): Returns the assembly for the given type or the named assembly.
• GetIconInternal(Assembly Assm, string IconResource, IconStyle Style): Retrieves the icon internally, considering the style.
• GetOverlayIcon(Assembly Assm, string IconResource, string OverlayName): Retrieves an overlay icon.
• GetIcon(Assembly Assm, string IconResource): Retrieves the icon from the assembly.
• LoadResource(Assembly Assm, string IconResource): Loads the resource from the assembly.
• GetResourceStream(Assembly Assm, string IconResource): Gets a stream for the resource.
• OverlayIcon(Bitmap BgImage, Bitmap FgImage, int X, int Y): Overlays one icon on another.

Usage

This attribute can be used to decorate classes, methods, or properties, providing a way to associate them with a specific icon resource. The icons can be used in UI elements, documentation, or any other place where a visual representation of the code element is useful.

Example

<syntaxhighlight lang="csharp"> [IconResource("MyIconResource", IconResourceAttribute.IconStyle.Normal)] public class MyClass {

   // Class implementation

} </syntaxhighlight>

This example specifies that MyClass should be represented by the MyIconResource icon in its normal style. The second argument, however, is optional, and "Normal" is the default, so it could be written simply as:

<syntaxhighlight lang="csharp"> [IconResource("MyIconResource")] public class MyClass {

   // Class implementation

} </syntaxhighlight>

Applying IconResource to our Code