Scanning Guides
"scanningGuides":
{
    "Web":     [ ... ],
    "Windows": [ ... ]
}

Scanning guides allow for extremly granular control of Ultralink options on a per-fragment or per-UI element basis. For instance, you might want one set of web page fragments to be filtered through a specific Ultralink Database and another set of fragments to be washed through a different one. This behavior is dictated by the scanningGuides object that you pass in as an Ultralink option. On the top-level of this object, you have either a Web entry, a Windows entry or both which control the specific targeting behavior in their respective environments.

Web-based Environments

"Web":
[
    { "URL": "webexample/dir/somewebpage.html", "description": "Sidebar Terms",
        "paths":
        [
            {
                "selector": "#layout_sample_drawer98Content",
                "options": { "noAnchorBan": "true", "includeSearch": "false", "hoverTime": "250", "database": "sidebardb" }
            },
            {
                "selector": "#layout_sample_drawer16Content",
                "options": { "noAnchorBan": "true", "includeSearch": "false", "hoverTime": "250", "database": "sidebardb" }
            }
        ]
    },

    { "URL": "webexample/dir/somewebpage2.html", "observeMutations": "div.bodyDiv", "description": "Value Controller",
        "paths":
        [
            {
                "selector":    "#attd\\.viewgrid .gridContent",
                "subSelector": ".gridRowTable td.gridCell[idx=0]:not(:has(uword))",
                "options": { "includeSearch": "false", "hoverTime": "250", "database": "detaildb" }
            },
            {
                "selector":    "#thirdGrid  .gridContent",
                "subSelector": ".gridRowTable td.gridCell[idx=5]",
                "options": { "includeSearch": "false", "hoverTime": "250", "database": "detaildb" }
            }
        ]
    }
]

For Web environments, you pass in an array of objects with the entries described below. Every object should correspond to a specific page (or set of pages) that you want behavior overridden on.

URLrequiredA partial URL that is used to match against and target the desired page.
pathsrequiredAn array of objects describing the exact location in the page to operate on.
descriptionoptionalA human-readable summary of the scanning guide.
additiveoptionalIf true, indicates that the scanning guide should be used in addition to the normal scanning process for the page instead of replacing it.
observeMutationsoptionalA selector indicating which elements to watch for modification that can potentially trigger a re-scan.
requiredURL
A partial URL that is used to match against and target the desired page.
requiredpaths
An array of objects describing the exact location in the page to operate on.
optionaldescription
A human-readable summary of the scanning guide.
optionaladditive
If true, indicates that the scanning guide should be used in addition to the normal scanning process for the page instead of replacing it.
optionalobserveMutations
A selector indicating elements to watch for modification which can potentially trigger a re-scan.

In each individual object within the paths array, there is a selector entry and an options entry. The selector value targets the exact portion of the web page to turn into a fragment. The options object contains specific Ultralink Options that you want to apply to the fragment (note: not all Ultralink options can be applied on a per-fragment basis).

If the elements you are targeting in the paths entry change often, or perhaps they not have loaded the content you want to target yet, you can use the observeMutations entry with a CSS selector which will tell the code to watch for changes on the specificed element(s). This element needs to contain all the elements described by the selector entries. When a change is noticed, it checks to see if it was any of the matched elements in the selector entries. If so, then it creates fragments using the subSelector value in the context of the selector and re-scans it.

Native Windows Applications

"Windows":
[
    { "name": "Some app", "module": "sumapp.exe", "company": "Some company, Inc.",
        "paths":
        [
            {
                "path": { "name": "Main Window", "type": "Window", "d": { "type": "ListItem", "d": { "type": "Text", "column": "Name" } } },
                "options": { "database": "somepeopledatabase" }
            },

            {
                "path": { "name": "Main Window", "type": "Window", "d": { "type": "ListItem", "d": { "type": "Text", "column": "Info ID" } } },
                "options":
                {
                    "database": "infodatabase", "includeSearch": "false",
                    "autogenUltralinks" : { "([a-zA-Z][a-zA-Z][a-zA-Z0-9])": { "links": { "examplelt": { "URL": "http://exampleurl.com" } } } }
                }
            },

            {
                "path": { "name": "Main Window", "type": "Window", "d": { "type": "ListItem" "d": { "type": "Text", "column": "Event" } } },
                "options":
                {
                    "database": "Mainline", "includeSearch": "false",
                    "autogenUltralinks" : { "(.*)": { "links": { "examplelinktype": { "URL": "http://exampleurl.com/nextexample" },
                                                                 "anotherlinktype": { "URL": "https://another.link.type/?AUTOGENDATA" } } } }
                },
                "autogenData": { "a": { "type": "ListItem", "d":
                                                            [
                                                                { "type": "Text", "column": "Description" },
                                                                { "type": "Text", "column": "Time/Date"   },
                                                                { "type": "Text", "column": "Priority"    }
                                                            ] } }
            }
        ]
    },
    { "name": "Another Application", "module": "another.exe", "company": "Some other company, Inc.",
        "paths":
        [
            {
                "path": { "name": "Specific Window", "type": "Window", "d": { "type": "Edit", "id": "4242" } },
                "options": { "database": "Mainline" }
            }
        ]
    }
]

The story for scanning guides in a Windows environment is similar, but there are differences in how content is identified in a Windows application. Instead of a URL, the scanning guide object can contain a name entry which corresponds to the name of targeted Windows application, a module entry for the name of the specific executable and must also include a company entry to match against the author of the exectuable.

Once the specified Windows application has been identified, there is a paths entry containing an array of objects that pinpoint the exact UI element(s) in the application. Each of those objects has a path entry which contains a nested set of element objects that describe which elements to target.

typerequiredDescribes the kind of UI element targeted (Window, ListItem, Text, etc...).
nameoptionalRestrict the sweep to only elements that match the specified name.
idoptionalRestricts matching to only elements with the specific ID.
columnoptionalA column name that restricts matching to only those elements in a table column of that specified name.
doptionalAnother element object. Indicates that the desired element is a descendant of the current element.

In this way, you construct a set of objects nested through the d entries that specifically target your desired UI elements. Ideally you should do this with the least number of element heirarchy descriptions as possible so that your structure will be robust against different UI changes, while still successfully targeting the correct elements. The options entry is the same Ultralink Options value as in the Web context where you can specifically override a subset of Ultralink behavior just for that Windows UI element.

Autogenerated Data

One of the options you can pass into the options in both Web and Windows environments is the autogenUltralinks option. This allows you to create Ultralinks on the fly from data in the content. It can be handy to create an Ultralink for specific situations, especially if you can create links on them that contain context specific information. That is what the autogenData entry is for (currently only supported in Windows scanning guides).

In autogenData, you specify a structure very similar to the one in the path entries to specifically identify individual Windows UI elements. Here you do the same thing except that you start at the matched element and then use a new a entry that tells the code to travel upward to the element's ancestors. For every element matched, it packages up it's textual value along with either the element name or column name and creates a set of key/value pairs in URI component form. This value is then substitued back in the autogenUltralinks entry inside links that have the AUTOGENDATA marker in their URL. This enables you to gather up the data around a targeted UI element and pass it by way of the generated link to the specificed webpage or Inline View logic.

Check out our Ultralink Autogeneration document for detail on exactly how you can create Ultralinks on the fly.

UI Element Lineage

To make the construction of path and autogenData objects easier, we have incuded a feature inside the Ultralink Windows app. If you right click on the Ultralink icon in the taskbar, a menu will pop up with an item called UI Element Lineage. If you select this, a new window will pop up that displays a JSON object of the complete UI element hierarchy for the last element that the Ultralink lookup trigger was activated on. From this object, you can easily craft the nested object heirarchy that smartly targets the elements you want to customize. Usually you will want to remove elements from this hierarchy that might make the matching too rigid or situation specific. For the same reason, you will probably want to remove many element attributes from the final object set as well.

PreviousPrev
Next