UI fragments

A fragment is a snippet of UI markup used to insert, remove, or modify components in a UI template. Use fragments for small customizations on top of built-in layouts.

For larger layout changes and device adaptation, see Appearance and layout template.

Simple example

The code below uses fragment configuration to remove the comment-tab component from mobile and desktop/tablet layouts. Click Run and use Chrome DevTools device mode to preview mobile and tablet.

<script>
    var CustomAppearance= UIExtension.appearances.AdaptiveAppearance.extend({
        getDefaultFragments: function() {
            var isMobile = PDFViewCtrl.DeviceInfo.isMobile;
            if(isMobile) {
                / mobile 设备端的 Fragment 配资。
                return [{
                    target: 'comment-tab',
                    action: 'remove'
                },{
                    target: 'comment-tab-li',
                    action: 'remove'
                }, {
                    target: 'comment-tab-body',
                    action: 'remove'
                }];
            } else {
                / desktop/tablet 设备端的 Fragment 配资。
                return [{
                    target: 'comment-tab',
                    action: 'remove'
                }, {
                    target: 'fv--comment-tab-paddle',
                    action: 'remove'
                }, {
                    target: 'hand-tool',
                    config: {
                        callback: {
                            around: function(callback, args) {
                                try{
                                    console.info('before callback');
                                    var ret;
                                    if(callback instanceof UIExtension.Controller) {
                                        ret = callback.handle(...args);
                                    } else {
                                        ret = callback.apply(this, args);
                                    }
                                    console.info('after callback');
                                    return ret;
                                }catch(e) {
                                    console.error(e, 'an error occurred');
                                } finally {
                                    console.info('');
                                }
                            }
                        }
                    },
                }];
            }
        }
    });
    var libPath = window.top.location.origin + '/lib';

    var pdfui = new UIExtension.PDFUI({
            viewerOptions: {
                libPath: libPath,
                jr: {
                    licenseSN: licenseSN,
                    licenseKey: licenseKey
                }
            },
            renderTo: document.body,
            / 根据设备类型提供不同的 appearance。
            appearance: CustomAppearance,
            addons: []
    });
</script>

{
    "iframeOptions": {
        "style": "height: 500px",
        "injectCss": [
            "/lib/UIExtension.vw.css"
        ]
    }
}

Fragment configuration parameters

• target: Unique component name.
• action: How the fragment is applied; default is UIExtension.UIConsts.FRAGMENT_ACTION.EXT:
  • UIExtension.UIConsts.FRAGMENT_ACTION.EXT: Extend the target component.
  • UIExtension.UIConsts.FRAGMENT_ACTION.BEFORE: Insert before the target.
  • UIExtension.UIConsts.FRAGMENT_ACTION.AFTER: Insert after the target.
  • UIExtension.UIConsts.FRAGMENT_ACTION.APPEND: Append inside the target (target must be a container).
  • UIExtension.UIConsts.FRAGMENT_ACTION.FILL: Clear the target’s children and replace them (target must be a container).
  • UIExtension.UIConsts.FRAGMENT_ACTION.REPLACE: Replace the target.
  • UIExtension.UIConsts.FRAGMENT_ACTION.REMOVE: Remove the target.
• template: XML template; used when action is BEFORE, AFTER, APPEND, FILL, or REPLACE.
• config: Component configuration; ignored when action is REMOVE.

  • config.target: Name of a component in the template; used when action is BEFORE, AFTER, APPEND, FILL, or REPLACE.

  • config.attrs: HTML attributes for the component.

  • config.callback: Business logic. Three forms are supported:

    • function: Invoked for component events and replaces the built-in callback. Only xbutton, dropdown-button, and context-menu-item support a plain function. To wrap the built-in behavior, use a controller class or decorator below.

    • controller class: Listen to lifecycle and handle more events:

      {
          target: 'hand-tool',
          config: {
              callback: class extends UIExtension.Controller {
                  mounted() {
                      super.mounted();
                      this.component.element.addEventListener('hover', e => {
                          console.info('mouse over', this.component)
                      })
                  }
                  handle() {
                      console.info('hand-tool clicked')
                  }
              }
          }
      }

    • decorator object: Hooks around the controller handle method: before, after, thrown, and around.

      {
          target: 'hand-tool',
          config: {
              callback: {
                  before: function() {
                      / 在controller handle 方法调用之前执行的函数， 它可以接收到 handle 函数的所有参数。
                  },
                  after: function(returnValue) {
                      / 在 controller handle 方法调用之后执行的函数，它可以接收到 handle 函数返回值以及调用参数。
                  },
                  thrown: function(error) {
                      / 在 controller handle 方法抛出异常之后执行的函数，它可以接收到异常对象以及调用参数。
                  },
                  around: function(callback, args) {
                      / 接收 controller handle 方法引用以及调用参数，在 around 回调中，可以对 handle 方法运行前后以及在捕获异常的代码块中执行代码。并且还可以决定是否执行 handle 方法。
      
                      try{
                          console.info('before callback');
                          var ret;
                          if(callback instanceof UIExtension.Controller) {
                              ret = callback.handle(...args);
                          } else {
                              ret = callback.apply(this, args);
                          }
                          console.info('after callback');
                          return ret;
                      }catch(e) {
                          console.error(e, 'an error occurred');
                      } finally {
                          console.info('');
                      }
                  }
              }
          }
      }

Notes

Use fragments for small UI tweaks. For major layout changes, see Appearance and layout template.