XMReport-快速开始

设计器产品界面

上图所示，设计器界面主要有下面几个部分：

顶部状态栏

顶部状态栏主要有保存，预览，退出按钮，显示当前正在编辑的模板文件的名称，以及设计器语言选择下拉框。

工具栏

工具栏包含了一系列编辑功能的按钮，用户可以在上面设置控件的位置，大小，样式以及数据绑定脚本等。

控件工具箱

控件工具箱上显示有当前设计器支持的控件类型，其中指针样式的按钮表达进入控件编辑模板，选中其它控件按钮进表示进入此类型控件的创建模板。用户可以通过下面的步骤在模板上创建一个控件：

1. 在工具箱上点击需要创建的控件，比如文本框。
2. 在界面上点击，拖拉出一个框。
3. 松开鼠标，一个文本框控件就创建出来了。

字体样式选择框

用户可以在字体样式选择框中对控件的字体进行调整（如果控件支持字体样式的话）。后面我们看到，这些按钮是从字体属性面板中部分抽取出来的。

控件位置，大小

显示和输入当前选中控件的位置，大小的数值信息。

1. X, Y 分别表示控件距父容器的左边界和上边界的距离，单位是0.1mm
2. W, H分别表示控件的宽，高，单位是0.1mm
3. Z表示控件的叠加层次，它跟CSS中的z-index类似，多个控件重叠的时候，Z数值越大的控件将会显示在越上面。
4. 横向充满，表示将当前控件的宽度设置成跟父容器的宽度一样。
5. 纵向充满，表示将当前控件的高度设置成跟父容器的高度一样。
6. 自适应高度，表示控件高度在打印输出时根据控件的内容自动调整高度（注意在高度自适应选中的情况下，H表示的是控件的最小高度）
7. 吸附，这是一个与控件无关的设置按钮，用于开启/关闭模板编辑器的吸附辅助功能，吸附功能用于帮助用户设计精确对齐的模板。
8. 打印/不打印，表示控件是否在输出打印时不显示，比如一些预置好的纸张上面可以已经有公司的Logo了，那么Logo图片可以设置成不显示 。
9. 每页出现 ，表示控件将会在每页打印输出，比如一些水印，Logo，表头位置等。
10. 允许跨页，表示允许控件在内容过长时，截断内容并在多页上显示

控件编辑区

控件编辑器主要是控件的ID，控件的复制剪切粘贴，操作的撤消与回退，以及文本的横向与纵向对齐样式。

控件ID

控件的唯一标识 ，这个ID在模板中是唯一的。它主要用于脚本，以及一些依赖控件的属性配置上面。

复制剪切粘贴，操作的撤消与回退

对应剪切板的复制剪切粘贴，另外，撤消与回退可以回退上一步的操作/重做下一步的操作，

属性面板

属性面板上包含一系列公共的样式，以及控件自有的属性面板按钮，点击它们将会弹出相应的面板设置对话框。

页面编辑区域

XMReport在页面编译区域预览模板的效果，用户也可以在这里对模板的控件通过拖拽的方式进行定位，调整大小，选择，复制剪贴删除等操作。

1. 单击控件：选中对应的控件，如未选中控件，则取消现选中的。
2. 拖拽：移动选中的控件的位置。
3. 双击：如果选中的控件是一个容器（如页眉，页脚，正文，单元格等），那么将进入容器编辑状态，点击容器外则退出窗口编辑状态。
4. 拖动选中控件上的锚点：可以调节控件大小，旋转角度，位置。
5. 右键单击：弹出控件的编辑功能菜单，包含剪贴，复制，删除等功能。
   

组件结构

组件结构面板中用于显示模板的组件大纲，它是一颗树，我们可以一层层展开，找到任意任意控件并选中，另外我们可以在控件上点击右键，呼出组件的编辑菜单，我们还可以通过上面的搜索框，搜索相应的控件。

数据源

包含了系统中的数据源模板列表，数据源是一种辅助设计的手段，它并不包含具体数据，也不包含数据库的连接信息，它仅仅是描述生成报告时，用户程序传递进来的数据有那些字段，以及字段的表达式。
用户可以拖拽，或者双击的方式将字段绑定到控件上面，方便实施人员对模板进行设计/修改。

模板管理

对系统中的模板进行管理，包含了常见的复制，剪切，粘贴，删除等功能。

1. 双击模板，对该模板进行编辑，编辑区域会刷新并显示此模板。
2. 右键，可以呼出模板的编辑按钮。

公共脚本

用户在这里可以添加自定义的脚本，然后在 “数据源/脚本” 属性面板中使用load函数加载脚本，比如 load(’/xxx.js’)，然后下来就可以使用脚本里面定义的函数/变量了。

数据与脚本

数据与脚本是XMReport的核心概念之一，每个控件都可以绑定一个数据对象，在生成报表的时候，数据脚本将被执行，脚本的最后一行的执行结果将被作为结果绑定到控件上。

脚本

在XMReport中，脚本采用JavaScript ES5语法编写，脚本将会通过解释执行的方式在JVM中运行。

数据脚本

默认情况下，“数据源/脚本” 属性面板中，"数据"输入框中的内容是直接被当作一个字符串对象绑定到控件上面的，如果需要把它当作一段脚本来执行，有以下几种方式：

1. 第一行加上//javascript注释前缀（斜线和javascript之间没有空格），脚本的最后一行将作为结果绑定到控件上面。
2. 为了方便用户的使用，你也可以采用等于号开头的写法，等于号后面的写法将会作为结果绑定到控件上面。
3. 使用类似于$variableName这样的占位符的方式，点位标记${}中的内容将会被当作脚本来执行，脚本执行的最后一行的结果会替换对应的占位符。

另外，子控件的脚本中可以访问到父控件绑定的数据中的属性，比如下面的例子，子控件可以访问到父控件绑定的数据中属性a和b，result的结果为25。脚本中访问一个变量时，如果脚本当前的作用域（scope）没有定义该变量时，它将一层一层往父级控件找到，直到根数据（生成报表时应用传递进来的数据），如果仍然查找不到，那么返回null。

//javascript Body's data script
var data={
	a: 12,
	b: 13
};
data;

//javascript Child's data script
var result=a+b;
result;

前置脚本

前置脚本是XMReport引擎在执行控件前运行的一段脚本，用户可以在前置脚本中做一些自定义操作，比如设置一些控件执行行为的一些属性。

后置脚本

后置脚本是XMReport引擎在执行控件后运行的一段脚本，用户可以在后置脚本中做针对执行结果做一些自定义的修改，比如修改文本控件的内容，宽高等。

结束脚本

结束脚本是整个模板执行完成之后回调运行的一段脚本，一些信息，比如总页数，汇总等，在整个模板输出完才能获取到的，可以在结束脚本中获取，并相应对控件的内容做一些修改。

可循环扩展的对象

XMReport中，有多种控件可以循环扩展的对象，比较常用的有Template，Page和Row，比如给表格的行绑定一个"数组/List"对象时，它将根据所绑定的数组/List对象的大小，扩展成多行。给Page绑定一个数组/List对象时，它将扩展成多页，Template同理。

集成示例工程

集成的示例工程为前端设计器提供了 预览，以及/数据源/模板/公共脚本的增删改查管理接口。用户可以根据自己的需要在自己的项目中实现对应的接口。

集成示例工程采用了SpringBoot + JPA的技术框架来实现，数据库方面采用了内嵌的Derby，用户可以根据自己的需求进行相应的修改，或者改成自己熟悉的技术来实现相应的接口。

编译示例工程前，需要使用以下命令将XMReport引擎包安装到本地maven库中：

mvn install:install-file -Dfile=web-report-engine-1.1.jar -DgroupId=org.mosmith -DartifactId=web-report-engine -Dversion=1.1 -Dpackaging=jar

如果客户操作系统为Linux/Unix/Mac OS X，那么需要在系统中安装SimSun.ttc字体（可以从Windows操作系统中复制），或者通过系统属性设置默认的字体：

System.setProperty("org.mosmith.tools.report.engine.output.pdf.PdfFontMapper.default", "simsun");

src/main/resources/static XMReport报表设计器前端静态资源文件。

src/main/resources/META-INF/persistence.xml 示例工程JPA配置文件（包含数据库连接配置），如下，用户可以根据需求修改数据源的连接信息：

<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.1" xmlns="http://xmlns.jcp.org/xml/ns/persistence" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd">
  <persistence-unit name="TemplateStorage" transaction-type="RESOURCE_LOCAL">
    <provider>org.hibernate.jpa.HibernatePersistenceProvider</provider>
    <properties>
      <property name="javax.persistence.jdbc.url" value="jdbc:derby:testdb;create=true"/>
      <property name="javax.persistence.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver"/>
      <property name="javax.persistence.jdbc.user" value="admin"/>
      <property name="javax.persistence.jdbc.password" value="admin"/>
      <property name="javax.persistence.schema-generation.database.action" value="create"/>
      <property name="hibernate.cache.provider_class" value="org.hibernate.cache.NoCacheProvider"/>
      <property name="hibernate.dialect" value="org.hibernate.dialect.DerbyDialect" />
    </properties>
  </persistence-unit>
</persistence>

ReportController 设计器预览接口，同时它是一个调用引擎生成报表文件的接口，如下，将模板，填充的数据，和选项传递进ReportHelper相应的接口，即可生成相应的PDF文件。

File file=new ReportHelper().toPdf(templateDataReader, previewData, previewOptions);

TemplateManagerController 设计器使用的模板增删改查接口。

ShareScriptManagerController 公共脚本的增删改查接口（可选集成）。

DataSourceTemplateController 数据源模板的增删改查接口（可选集成）。

内置函数

用户可以添加自定义的函数，如下代码，控件的脚本中可以直接访问到对象的方法。由此用户可以集成自己的数据查询方法等。

        // 生成报表文件前通过ReportHelper.setBuiltIn方法设置内置方法对象，可以设置多个。
        ...
        ReportHelper reportHelper=new ReportHelper();
        reportHelper.setBuiltIn("testBuiltInMethods", new TestBuiltInMethods());
        reportHelper.toPdf(xxx)
        ...
        
        class TestBuiltInMethods {
        	public String sayHello(String name) {
        		return "Hello " + name;
        	}
        }
        
        
        // 控件的脚本上可以直接调用TestBuiltIn里面的方法
        ...
        var message=sayHello('Mosmith');
        ...
        

内置变量

同样，用户也可以添加自定义的内置蛮一，如下代码，控件的脚本中可以通过内置变量名访问到对象，并可以调用对象上面的方法或者获取对象的字段：

        // 生成报表文件前通过ReportHelper.setProperty方法设置内置变量，可以设置多个。
        ...
        ReportHelper reportHelper=new ReportHelper();
        reportHelper.setBuiltIn("testBuiltIn", new TestBuiltIn());
        reportHelper.toPdf(xxx)
        ...
        
        class TestBuiltIn {
        	public String field;

        	public String sayHello(String name) {
        		return "Hello " + name;
        	}
        }
        
        
        // 控件的脚本上可以通过内置变量名访问到内置变量的方法和字段 
        ...
        var message=testBuiltIn.sayHello('Mosmith');
        var field=testBuiltIn.field;
        ...