CSS flex usage note

Flex can be used to solve most ui layout requirements in regular business applications if each items need to have equal height. 

Flex consists of flex container and flex items, each of them supports different css styles. It is important to understand which css style works on flex container or flex items.

Flex container:

For any container html element, when setting the below css style to it, the element becomes a flex container, and any direct sub elements become flex items.

.myform {

  display: flex;

}

The flex container has the below css styles:

.myform {

  display: flex;

  flex-wrap: wrap;  //control whether wrap the elements when page shrinks

 justify-content: center; // control where to shall all flex item in flex container in main axis: center, flex-start, flex-end, space-around, space-between

align-items: stretch; // control how each flex item is aligned in cross axis direction: stretch, flex-start, flex-end, center and baseline

align-content: normal: //control how all flex items are align in flex container in cross axis direction, not used very often.

}

Flex elements

Any direct sub elements of flex container element can be styled by flex item css styles. The styles controls the element itself and its sibling elements' behavior. The styles include:

flex: define how the element will grow or shrink when the page width changes. It can be used to define how item grows and shrinks related to other elements. For example, a growing input text box with a button with default width can be defined as below

   input[type="text"] {

      flex: 1 0 auto

  }

  button[type="submit"] {

    flex: initial 0 initial

  }

Sample usage 1

A growing field and a fix width item, the growing field occupies all remaining line

  .search-form {

    display: flex;

    flex-wrap: wrap;

  }

  growingitem {

    flex: 1 0 auto

  }

 fixeditem {

    flex: initial 0 initial

  }

Sample usage 2

Two fields occupy left and right end of the line by setting justify-content: space-between

  .search-form {

    display: flex;

    flex-wrap: wrap;

    justify-content: space-between;

  }

  input[type="search"] {

    flex: 1 0 initial

  }

  button[type="submit"] {

    flex: 1 0 initial

  }

Expanding item to occupy all its container's space 

When setting the below display style to any item within a container, the item becomes a flex container, and by default, flex container will expend and stretch to all available space in container.  

display: flex

Difference between React useCallback and useMemo

React useCallback and useMemo hooks look similar, and both of them take a callback function, and dependent array as parameters. But their returns different values to the callers.

useCallback hook returns a memorized callback function, if the dependencies are changed. So the type of the variable assigned by useCallback is a function object. The function object itself is memorized, so when rendering the parent react function component, the function object will not be created again and again as new function objects. The function object body will not be invoked until in the project someone calls the function.

useMemo hook returns a memorized object, so the type of the variable assigned by useMemo may be any type depends what is returned from the callback method body in useMemo's first parameter. If nothing is returned, then the variable assigned by useMemo hook is undefined. Different from useCallback hook, when assigning a variable by useMemo hook, the callback method of useMemo hook will be called immediately, no matter whether the variable is used or not by the application. 

Since both useMemo and useEffect will automatically execute their callback method when page loads or when dependency parameters change, so their functions look similar. But useMemo is executed during DOM rendering. while use Effect is executed after DOM rendering, for the time consuming operation such as remote network requests. 

In practice, it is important in many times, the cost of using useCallback and useMemo may be bigger than the benefit bringing by it, and requirement of setting the proper dependent array parameter may introduce new bugs to the logic, so they should be used with caution in the real project.

Set dependent array parameter in useCallback (and other react) hooks

React callback hook creates memorized callback function, the memorized callback function gets created once, but will be invoked later for many times. If the callback function uses any values returned by useState() hook, then those values must be included in the useCallback's dependent array parameter. The reason is when useCallback is created, it captures all the closure variables as a snapshot for future usage. After that, if some values are updated by calling set method of useState() hook, the updated values will be not reflected in the closure snapshot captured by useCallback hook when it was created, so when the callback hook method is called after its creating, it will still use the original out-of-date values it captured when it was created. 

So as a simple rule, when defining hooks with dependent parameters, always including all values controlled by useState() in its dependent parameter.

Guidewire Jutro DataTable Usage (ver 4.1.1)

Jutro DataTable component is a major UI element when creating jutro pages, DataTable includes build-in pagination, searching, editing and no-data function, understanding how to use and configure jutro DataTable with metadata.json5 is very important.

1. Data source

DataTable metadata json5 definition has a data property, which accepts an array of item. Datatable's column is based on the item's attribute name. If you need to implement your own customized filter function, you can create a function to filter the data first and then feed the filtered data to the Datatable' data property.

2. search/filter 

For Jutro datatable, search and filter means the same. 

ShowSearch property controls whether to show a search input textbox on top of the datatable. If showSearch is set to true, then you can also specify a string on "filterPlaceholder" property to set a placehold text on the search input field. 

By default, when a search text is changed by user, the search criteria will check all records' all columns to get the matched records. However, you can customize the search behavior by specify DataTable's onFilter property to a custom function, and this function will be called whenever user changes the input of search input textbox field. A sample code is shown below:

      {

        "id": "myDataTable",

        "type": "container",

        "component": "DataTable",

        "componentProps": {

          "noDataText": {

            "id": "datatable.nodatatext",

            "defaultMessage": "No data found ...."

          },

          "expandOnRowClick": false,

          "defaultPageSize": 10,

          "pageSizeOptions": [

            10

          ],

          "filterPlaceholder": "",

          "rowIdPath": "publicID",

          "showSearch": true,

          "filterPlaceholder":"Search name, state, or population",

          "headerMultiline": true,

          "onFilter": "filterRow"

        },

    const filterTable = (filterValue) => {

        const filterNumber = parseInt(filterValue, 0);

        return (row) => {

            return row.claimNumber === filterValue;

        };

    };

  const resolvers = {

        resolveCallbackMap: {

            filterRow: filterTable

        }

    };

3. pagination

Pagination is supported by DataTable as build-in feature. The related settings include:

defaultPageSize : 10

pageSizeOptions : [10, 25]

showPagination: true

4. handle row click

When user clicks on a row, a custom callback function can be set to onClickRow property to handle the click, the input parameter is the row clicked.

  {

        "id": "ClaimSummary",

        "type": "container",

        "component": "DataTable",

        "componentProps": {

          "onRowClick": "onClickRow",

          "selectOnRowClick": true

        },

    resolveCallbackMap: {

            filterRow: filterTable,

            onClickRow: onClickRow

    }

    const onClickRow = (row) => {

        console.log(row);

    };

5. defaultSorted

Set datatable's default column for sorting

6. columnsConfigurable

true or false. Decide whether to show the three-bar button on right side of search bar for configuring columns.

7. Table column

Columns in DataTable are defined as an array under datatable's content property. Each column object's component property specify the column type, for example, DisplayColumn. The column object has below properties

header: specifying the header text

path: specify which datatable date object's field is for this column.

sortable: whether to show and support sort on this column

renderCell: specify a callback method to render the cell, the callback function has parameter of row item and row index

Guidewire Jutro notes

1. How to get all available properties for a component

Just opening project's framework/packages/components/widgets/folder, and then open the specific component you want to check.

2. Component settings in metadata definition

For object's component settings in metadata json5 file, it will first try to match the jutro component with the same name. If no match found, then it will match the html build-in element. For example, 

"component": "button"

will map to jutro button component, instead of html button element. But

"component": "label"

will map to html label element.

3. Content setting

The jutro framework will do its best to put the content into the mapped html element, for example, button will show the content string as its text. div will just show the content between the open and close tag. 

4. Add custom page/component

To add a new custom page, first create the page component and metadata json5 file. 

Then import the component in app.js file and also add the component into componentMap object.

In app.routes.metadata.json5, add a new path to load the page component for the specific route url path.

Actually this is the same change when running the below generate page command:

jutro-cli generate page

5. Enable guidewiree jutro capability buildin page

In addition to import the page component into app.js and componentMap, as well as updating the app.routes.metadata.json5, you also need to update config.json5's capabilitiesConfig section to set the capability's value to true. Otherwise the page/component jsx file will not be loaded.

6. Dynamic update UI with override in renderContentFromMetadata

When defining UI content with Metadata json5 format, all the values are hardcoded in json5 files. In order to dynamically change the values (for example, set element visible property based on server side response), the jsx file can set override parameter in renderContentFromMetadata method. For example, the below code sets claim element's visible property based on the return value of isClaimVisible()

       Claim: {

            data: claimDataTable,

            visible: isClaimVisible(),

}

Note, the method will only be called once when the UI is rendered from metadata, once the rendering is finished, even if the function returns a different value, it will not be called again automatically.

In order to be sure UI will reflect the underling data change, in the data change handler function, it should call useState() method to notify react to refresh the UI, so the metadata will be evaluated again. 

Basically, values set in override parameter is same as other react component properties, and they are read only when passed to child component for initialization. 

7. Difference between to and href for Link component

When href attribute is set for Link component, it will cause to reload the page on that url, which will download the full index.html and js files.

When to attribute is set for Link component, it will stay in the current html page, and only reload the component based on app.js router configuration. So it is much fast and user friendly.

Guidewire jutro metadata json5 object types

When defining objects in Jutro with metadata json 5 schema, there are 5 types available. Since there are only 5 types, so the exact html tag type of the object depends on both object's type and component setting, and Jutro will make the best guess based on those information.  

1. Elements

This type is for static object that do not offer a user input, like label or badge. Element type object does not have content property. 

2. Container

Container object contains array of elements, other containers, fields, iterables. Container object always has a content property to define its content.

3. Field

Field object is used to describe user input elements. Field type usually do not have content property, but have a label property depending on its component setting.

4. Action

Action object is used to describe interactive or action components. For button component, its content property sets the button text.

5. Iterables

Iterable type mainly used with Accordion, tabset and table to show repeated items. It also has build-in support for empty content.

6. layout

layout type is used for setting the elements layout.

Guidewire Jutro metadata: how to set property to json5 component

1. Set component prop in metadata json5 file

When creating component using Guidewire Jutro metadata json5 format, for simple element, for example, label component of element type, the label text is set by "content" attribute, and other attributes are set by componentProp attribute as below:

 {

        id: 'myLabel',

        type: 'element',

        component: 'label',

        content: 'mylabel name',

        componentProps: {

          for: 'myfor',

        },

        selfLayout: {

          component: 'div',

          componentProps: {

              someattr: 'mycustattr',

          },

        },

      },

This indicates jutro (4.1.1)  just puts whatever componentProps settings into the element's html without validation whether the attributes actually exist or not.

Note the selfLayout node defined in the metadata creates a new wrapping element for the current element. if the node is deleted, then <div someattr='mycustattr'> element will also be deleted.

2. Set component in jsx with override and resolver

In many cases, we need to set component properties dynamically in jsx files for example, set the callback method for button element. This can be done by passing resolver parameter in jsx's renderContentFromMetadata method. For example, if metadata sets button's callback to a string, the string needs to map to a method defined in jsx file as below

      {

        id: 'btnFileCLaim',

        component: 'button',

        type: 'element',

        content: 'button name',

        componentProps: {

          size: 'small',

          type: 'primary',

          onClick: 'clickme',

        },

      },

in component jsx file:

const MyTestComponent = () => {

  const onclickme = () => {
    console.log('button clicked');
  };

  const override = {
  };

  const resolvers = {
     resolveClassNameMap: styles,
     resolveCallbackMap: {
      clickme: onclickme,
    }
 };

 return renderContentFromMetadata(uiMetadata.viewClaimList, override, resolvers);
};

export default MyTestComponent;


When overriding property values, the id is used as key, and there is no need to specify componentProps. For example, in above sample, the below code can be used to override the button's label and type property

const MyTestComponent = () => {

    const onclickme = () => {

        console.log('button clicked');

    };

    const override = {

        codelessCardTitle: {

            content: 'myoverridecontent',

        },

        btnFileCLaim: {

            content: 'mybuttonoverridename',

            type: 'secondary',

        },

    };

    const resolvers = {

        resolveClassNameMap: styles,

        resolveCallbackMap: {

            clickme: onclickme,

        }

    };

    return renderContentFromMetadata(uiMetadata.viewClaimList, override, resolvers);

};