A Deeper Look at Adding Custom Fields in SalesLogix Mobile

We looked previously at adding custom fields to the SalesLogix Mobile client. It was easy enough to do, but as I’ve mentioned before, one of the hardest parts about customizing the mobile product is that you have to know what to type. Let’s take a look at just what’s available when adding custom fields in an customization module so you’ll have all the knowledge you need.

When we looked at adding custom fields to the mobile client previously, we used a “registerCustomization” function and passed in some values. We didn’t really discuss in that post how to know what parameter values are available to pass into this function. That can make it hard to know exactly what to type and what you can and can’t do there. We’re going to examine every part of that statement so you understand how it works, what’s available, and where to look to figure all this out for yourself.

The registerCustomization Function

The registerCustomization function is implemented in the Application.js file in the Argos-SDK. Well, what you’re actually using in your ApplicationModule is the registerCustomization function in the ApplicationModule.js in the Argos-SDK, which is the base code your own custom ApplicationModule extends, but the function there only passes the details along to registerCustomization in the Application.js, so the ApplicationModule base code doesn’t really do any of the work. Why is this important? Because you can look at the code in the Argos-SDK to find out everything you need to know about using this function to add custom fields. The fact that you have all the source code available to you is helpful. So use it. In a sense, it’s like some additional documentation (although source code doesn’t really count for as much as real documentation, but at least it’s something). Let’s look in the Application.js file (located in the argos-sdksrc folder) to see what the registerCustomization function does. The most useful thing you’ll find there is the comment preceding the function itself. It says the following:

Registers a customization to a target path.

A Customization Spec is a special object with the following keys:

“at”: “function(item)` – passes the current item in the list, the function should return true if this is the item being modified (or is at where you want to insert something).

“at”: “{Number}” – May optionally define the index of the item instead of a function.

“type”: “{String}” – enum of “insert”, “modify”, “replace” or “remove” that indicates the type of customization.

“where”: “{String}” – enum of “before” or “after” only needed when type is “insert”.

“value”: “{Object}” – the entire object to create (insert or replace) or the values to overwrite (modify), not needed for remove.

“value”: “{Object[]}” – if inserting you may pass an array of items to create.

Note: This also accepts the legacy signature: “registerCustomization(path, id, spec)” Where the path is “list/tools” and “id” is the view id

All customizations are registered to “this.customizations[path]”.

@param {String} path The customization set such as “list/tools#account_list” or “detail#contact_detail”. First half being the type of customization and the second the view id.
@param {Object} spec The customization specification

So, here’s what we know so far about what you pass to registerCustomization:

It can take either 2 or 3 parameters (we can tell this by looking at the function signatures in Application.js and ApplicationModule.js, as well as the comment):

path: A path is in the form of something like “edit#account_edit”. Alternatively, you can pass these separately as “edit”, “account_edit”.

spec: The “spec” is the set of parameters that define the customization we’re adding. We’ll outline these parameters next.

The Customization Specification

The customization specification, or “spec” is what describes the WHAT YOU ARE DOING part of the customization. “I want to add a customization here”. The spec parameter options are:

“at” which describes where you want the customization. This can be an index, but usually is a function that evaluates to true when for the row you want to look for. This function is passed the current row item. As the view is built and as each row is created, the row item is passed to this function. You can then check properties of that row, usually the row.name to see if it’s the one you want. So, if this function evaluates to true, then it looks at the “type” and “where” parameters to see what to do next.

“type” which is the type of customization. This indicates what action to take when the “at” evaluates to true. So, when the “at” function finds the right row, this tells it what to do. The choices are:

“insert”

“modify”

“remove”

“where” only applies if the “type” is an insert. If we’re inserting a new element, do we want it before of after the located row in the “at” param. Obviously, the choices are:

“before”

“after”

“value” is the parameter that contains what you’re customization contains. This is the actual “customization”. All the properties to set for the customization are wrapped up in this object. Optionally, you can pass an array of values, meaning an array of customizations, you’re adding. This parameter is the most important part. However, this sort of looks like a black hole. How do we know what choices are available? Let’s look at that next.

All in all, we’ll end up with something that looks like this. This sample, adds a customization to the account_detail view:

OK, let’s move on and see what choices there are for the value (or customization) object.

The Customization Object (The Values)

The customization values is the set of properties and values that describe the WHAT YOU ARE ADDING for the customization. This is the important part. This is what you actually want added to the view. The spec above outlines the what you are doing, “I want to add a customization here”, and the values object outlines what you’re actually adding.

So, how do we know what is available for this set of values? What are the available properties for this? Well, we have to think for a minute about *what* exactly we are adding. We’re adding a text value, or a picklist, or a lookup, or something. In short, we’re adding a field. It just so happens that there is a defined base “field” in the Argos-SDK (the actual object is named “_Field”). All fields start from this base field object. There’s also a specific field object for each of the different field types. For example, the “_Field” object is extended by the implementation for a picklist. The reason this is important to understand is because looking at the implementation for these field types will show up what the available properties are. What we’re actually setting in this values object that we pass to registerCustomization is a set of the properties for this field.

Let’s start by opening up the _Field.js file (located in the argos-sdksrcfields folder). This is the base type for any field. We can scroll through that and see the available properties. These are some of the properties we can set for our values object for our customization. We can see properties such as:

owner

disabled

hidden

‘default’ (to set a default value

name

label

property (the SData property to bind to)

type

validate

clearValue()

setValue()

and so on…

Luckily, these properties all have comments with them that describe what each of the properties & functions are for. Next, we can look at the implementation of the specific field type we’re adding. For example, open the LookupField.js (located in the argos-sdksrcfields folder). We can look through this and see even more properties we can set if the customization is adding a lookup field. There are properties such as:

widgetTemplate (if we want to define a new look for the control)

dependentErrorText

emptyText

completeText

cancelText

lookupText

view

keyProperty

textProperty

valueKeyProperty

valueTextProperty

requireSelection

resourceKind

where

orderBy

to list only some of the available properties…

Now we’re getting a more complete picture of what the available choices are for our values object. Sweet.

We can see even more field types (the SalesLogix specific ones) implemented in the argos-saleslogixsrcfields folder. We can see the picklist, address, name fields, etc. We can open those just the same to see what’s available and even better, we can override the default behavior easily as well and provide our own implementation for this. For example, a common request is how to customize the name parts dialog, or the address dialog. It couldn’t be easier in mobile. The template for these are located in these files and you can provide your own template for them by just setting the property with the new template (we’ll look at templates later on in a future article).

Conclusion

I guess the point I am trying to make with all of this, besides trying to outline exactly what you’re doing when you add registerCustomization in an ApplicationModule, is to point out that while there isn’t tons of documentation for the mobile platform, we can learn just about everything we need by looking at the source code. Good luck.

Ryan Farley is the Director of Development for Customer FX and creator of slxdeveloper.com. He's been blogging regularly about SalesLogix, now Infor CRM, since 2001 and believes in sharing with the community. He loves C#, Javascript, web development, open source, and Linux. He also loves his hobby as an amateur filmmaker.