Parsing Props for UXPin Merge Controls – A How-to Guide
Our friend from PayPal, Anthony Hand, decided to share how to make designers’ lives easier using parsing props with UXPin Merge.
Merge is UXPin’s revolutionary technology that helps you import and sync your dev’s UI components from the component library in the design tool.
You can bring the components via Storybook integration or Git repository. You can also use NPM integration for importing and components without engineer’s help. Either way, you don’t need to worry about trading off between time and robust prototypes – you can have both.
It’s possible to design fully interactive prototypes extremely fast because the UI elements you use during the design process are live code. Discover more about UXPin Merge.
Prop Parsers for UXPin Merge Controls
As any UI developer knows, parsing and validating user inputs is as much of an art as a science. While most of the users most of the time may enter the expected values, we must always be prepared to do a little graceful massaging and tweaking, as well as error handling.
In my days as a Sr. UX Designer on a DevOps team at PayPal and all of my projects are internal web-based tools, we used UXPin Merge. After we settled on the Microsoft Fluent UI library for our next generation of web apps, we embarked on the process of importing the UI library into UXPin using their Merge technology. The process was straightforward enough, though it did have a little learning curve.
One of our first learnings with UXPin Merge was that standard parsing and validation needs applied. The Properties Panel in UXPin is, after all, just a fancy user input form. We developed a few standard parsing utilities for basic user inputs like colors and dates, for example.
As we got deeper into the UXPin Merge preparation, we soon realized that more complex UI controls would need complex JSON in the underlying control. However, surfacing raw JSON to non-technical people in UXPin would quickly kill user adoption.
JSON is a complex data model expressed as a string, created for computers, not humans. As a result, one of our most important innovations was to create an advanced multi-use parser that allowed us to gather plain text user inputs to configure complex UI controls like dropdowns, navigation lists, and data tables.
Basic Parsing
We created a few basic parser functions in JavaScript to handle the validation for common user inputs around colors, dates, and numbers, for example. Although these were primarily created to make it easier to configure UI controls in UXPin, some of these utilities have found wider use internally.
Parsers converted the string “50” to an integer and validated the hex color, adding back in the required # mark. Our Merge wrapper also trimmed leading and trailing whitespace from the icon name. (UXPin Editor and Props Panel view)
Color Parsing & Formatting
The Microsoft Fluent UI controls want hex values, such as “#0078d4” (a lovely shade of blue), but we wanted to allow users to use both hex values and easier to remember theme tokens (such as “themePrimary”). Plus, we wanted to support semantic tokens (e.g., “success”) and a handful of basic colors (e.g., “white”, “transparent”).
As for gracefully handling errors, we trimmed input text of whitespace and accepted valid hex values, even if they didn’t start with a # mark.
Our custom color parser gives a huge range of freedom to users and accepts all of those types of values, returning either a validated hex value for use by the UI control, or “undefined” as an error flag.
The color parser checked to see whether “themePrimary” was a color token in the theme, then retrieved its hex value for use by the icon object.
Similarly, the color parser looked up the special semantic color token, “success,” and converted it to a hex, as well. “Success” is easier to remember than an arbitrary hex value.
Complex Parsing
As mentioned previously, many of the underlying UI controls use complex JSON for configurations, like menus, navs, and dropdowns. However, JSON is hard to read for humans, and easy to break. So instead of JSON, we invented an innovative syntax that’s much easier for regular humans to use. In addition to plain text, the syntax tokens we developed include:
- icon(Icon_Name | color): Any icon in Microsoft’s icon library
- link(Display Text | URL)
- Divider or —-: To display a divider in a list
- * : To mark a child in a section, like in a nav or menu
- CSV Parsing: For table rows or when commas are needed in plain text in certain controls
Note: In most cases, this special syntax is only for use within UXPin to help designers and (typically) non-technical people easily build prototypes. To build the actual web apps, developers would set up these UI controls in the standard way with JSON, event handling, etc.
Icons & Text in Menus
Let’s look at how a user would add popup menu items to a CommandButton control in UXPin. In this example, the user clicks on the button with the text “New” to display a popup list of the types of objects the user could add, such as various file types, a folder, a user, etc.
In the UXPin Editor, the user clicks on the Menu Items prop to view a large text editor. Our improved parser now looks ahead to determine whether a string like “File” is a regular menu item or a section heading. The star ( * ) indicates that “Document” is a child, so “File” must be a section heading. Note the usage of the icon() token, and two intuitive ways to indicate a divider.
This is the view of the same CommandButton as rendered in the UXPin Prototype Preview mode.
This powerful, innovative syntax was reused across nearly a dozen other UI controls that supported a list-style view: Dropdown, Combobox, Pivot (tab strip), Nav, ChoiceGroup (radio buttons), GroupButton, SplitButton, Breadcrumb, and more.
Although support for icons, dividers and groups varied between controls, once UXPin users became familiar with this basic approach, they are able to easily apply the same approach across a ton of controls to create rich, interactive prototypes without knowing a lick of JSON.
Data Tables
As you might imagine, internal web apps are data intensive and data tables are extremely common. So, one of the main drivers for developing this advanced parsing engine was to help us easily create realistic — and modestly functional — data tables in our prototypes.
To create rich prototypes with reasonably advanced functionality, our workflow starts off with Excel. We first develop a model of the view in Excel, using the link() and icon() syntax mentioned above within each cell. Then we export that worksheet as a CSV file.
Using any text editor, we can open the CSV file and copy just the headers, or the row data, into the Headers and Rows props in UXPin, respectively. Compare this streamlined workflow to what we used to do to create tables in other prototyping tools!
The UXPin Editor view for the DetailsList’s Rows prop showing the comma-delimited cells (CSV format) with our innovative link() and icon() syntax.
Designer’s Perspective on Parsing
As you look through the source code for our parsers, you may have some opinions on some of the design decisions in the code, and how (relatively) inefficient or verbose the code is. You may even notice some errors. I accept responsibility for these decisions.
Keep in mind that I’m a UX designer, not a professional programmer. More importantly, I explicitly decided to optimize for readability, modularity and ease of maintenance over efficiency, per se, given my limited knowledge of JavaScript. This is open source code, so you’re welcome to borrow some or all of the code, make modifications, or offer updates and bug fixes.
On Optimizing UXPin Merge
UXPin’s Merge technology lets any company import the exact same UI component library that they use for development into UXPin so that anyone on the team can create rich, interactive prototypes. It’s a powerful technology that can dramatically increase the velocity of design for user feedback and stakeholder reviews, and can improve developer handoff.
However, as our team learned, there needs to be a modest investment in setting up the end user experience for success in UXPin. We made an explicit decision to optimize the UXPin user experience with smart parsing that brings maximum power while minimizing errors.
We recently ported our proprietary Microsoft Fluent UI library to an open source library which your team are welcome to experiment with and gain inspiration from. And feel free to liberally modify and/or borrow any of our parsers for your own UXPin Merge projects!
