前言

本手册提供了 CUBA Studio IDE 以及其功能的参考信息,CUBA Studio IDE 有助于提高基于 CUBA 框架的应用程序的开发效率。

CUBA Studio 基于开源的 IntelliJ Platform,并通过以下 CUBA 特有的功能对其进行扩展:

  • 创建 Gradle 构建脚本的脚手架代码。

  • 创建数据模型、数据库架构和 CRUD UI 的脚手架代码。

  • WYSIWYG 界面布局设计工具。

  • 对开发人员友好的功能,加快编码过程,包括:动作(action) 、 推断(intention) 、 检查(inspection)、 引用(reference)。

  • 轻松支持国际化。

  • 为现有的(或遗留的)数据库创建数据模型和 UI 界面。

  • 热(重新)部署。

  • 使用 CUBA 框架和扩展的版本升级更加容易。

IntelliJ Platform 为 CUBA Studio 提供了强大的基础。包含很多可以提升 CUBA 开发者生产力的功能,比如非常人性化的用户界面,智能代码补齐,安全的代码重构,后台代码检查,内置的版本控制以及对 Gradle 的集成。如果您之前没有使用过 IntelliJ IDEA,我们强烈推荐您访问其网站的 学习 & 支持 部分,快速了解其基本功能。

发行说明

版本 13

界面设计器的布局重新排布了,主要为了以下目的:

  • 高效的使用 IDE 窗口的空间。

  • 便于在 XML 描述源码和布局预览之间切换。

  • 允许熟练的开发者在查看和编辑 XML 代码时使用设计器的功能。

对界面设计器做了如下变更和改进:

  1. 界面设计器的面板修改为独立的 IDE 工具窗口。Component Hierarchy 展示在 IDE 的右上角,与之前一样。Component Palette 展示在 IDE 的右下角。Component Inspector 展示在 IDE 的左下角并包含属性和处理器标签页。

    当在编辑器打开界面描述时,这些工具窗口会自动打开。当在编辑器切换界面描述文件时,工具窗口的内容会随之改变。有时当您打开其他的 IDE 工具窗口(比如 Gradle、Persistence 等),设计器的面板会被隐藏,可以通过点击位于左右的 IDE 工具窗口按钮重新打开。

    保留在左下角展示 Component Inspector 是为了满足熟悉之前布局的开发者们。如果需要将该面板移至右侧,点击面板标题的 Move to Right Bottom 即可。

    v 13 sd tool windows
  2. 布局预览面板现在与界面描述的源码编辑面板共享编辑器的空间。去掉了原来的 TextDesigner 标签组。现在在界面描述的右上部添加了四个按钮用于切换界面预览模式:

    1. Editor only - 在编辑器只显示源码。

    2. Editor and Preview - 编辑器空间分割,包含源码和预览。

    3. Preview only - 只显示预览(与之前版本的界面设计器布局类似)。

    4. Preview in Window - 源码在编辑器展示,但是预览通过单独的窗口展示,可以将预览窗口移至其他显示设备。

  3. 当编辑 XML 代码时会激活设计器面板,面板会与编辑器同步交互。熟练开发者们通过编辑 XML 源码切换和修改界面描述,他们现在也能获得界面设计器的编辑功能帮助:

    1. 当编辑器的光标从一个 XML 标签移至另一个标签时,会在 Component HierarchyComponent Inspector 面板自动选中对应的组件。

    2. 在层级面板点击元素会将源码编辑器的光标移至对应的 XML 标签。

    3. 可以从工具箱拖拽新组件至层级树,当编辑器只显示源码时,也可以在左下角的探查面板修改组件的排序和编辑组件属性。源码会直接同步所有改动。

  4. 界面编辑器现在能在 Component Hierarchy 树中展示表格(或数据网格)的列。作为这个改动的一部分,删除了之前的几个用来编辑列和操作的弹窗。现在可以在 Component Inspector 面板直接查看和编辑列、操作属性以及事件处理器。添加新的列或者操作也变得更加容易了。当选中一个表格、表格的一列或者操作, Component Inspector 会显示 + Add 按钮。点击该按钮可以添加列或者操作。

  5. 界面设计器还添加了组件创建向导对话框。添加数据容器、表格、网格、表格的列、表格操作以及表单的字段组件变得更加容易了。

    当为界面添加上面提及的任何一个组件时,会弹出一个对话框用来指定最重要的组件属性。比如,当为界面添加数据网格时,可以选择已有的数据容器或者创建新的数据容器,能设置组件 id 并且为网格选择一组标准操作和按钮。

    v 13 datagrid wizard
  6. 界面设计器的 Component Hierarchy 面板添加了可以铜鼓输入文字查找组件的功能:

    v 13 search hierarchy
  7. Component Hierarchy 面板的右键菜单也添加了额外的转换功能。现在可以快速的将 TextField 组件转换为 TextArea 或者其他组件:

    v 13 text field conversions
  8. Component Hierarchy 面板右键菜单的 Inject to Controller 操作现在支持可以同时注入多个选中的组件。

其他功能和改进:

  1. 添加了对 Kotlin 编程语言的支持。在项目创建向导中,如果选择的平台版本为 7.2.0 或更新版本,则可以选择 Kotlin 为项目的编程语言。CUBA 项目的所有元素:实体、界面、服务都可以用 Kotlin 生成。Studio 的可视化设计器、智能自动补全、自动检查以及热部署也都支持 Kotlin。

  2. 对于使用平台 7.2.0 或更新版本的项目,对 Hot Deploy 机制做了重写(支持所有语言),主要是为了支持 Kotlin。如果在 Java、Groovy 项目中遇到了热部署的问题,可以切换至之前的机制,通过关闭这个设置:CUBASettingsProject SettingsHot deploy compiled classes

  3. 扩展了 CUBA 项目创建向导。在几个步骤之间重新安排了各个字段,并且添加了新的字段:模块前缀、支持的语言、地区、主数据存储属性。

  4. CUBA Application 运行配置添加了两个额外的配置:Command line arguments - 命令行参数Environment Variables - 环境变量。这些设置会在 Tomcat 运行调试模式 CUBA 应用程序的时候生效。比如,通过设置命令行参数,可以配置非默认时区:-Duser.timezone=Europe/London 或者增加内存:-Xmx1500m

    v 13 run configuration
  5. 为登录界面设计了新模板,新的布局和设计可以在基于 CUBA 7.2.0 或最新的版本的项目中使用。新的登录界面样式可以查看 GitHub 了解。如需在项目中添加新的登录窗口,可以在 NewScreen 向导中选择 Login screen with branding image 模板。

  6. Project Properties 对话框中添加了修改项目工件版本的功能:

    v 13 artifact version
  7. 在服务和 Spring bean 源码的编辑器顶部操作面板中添加了 Inject 操作。之前只能在通用菜单(Alt+Insert)使用。

  8. Data Store Properties 窗口添加了方便配置数据库连接的对话框。为 Connection params 字段添加了一个 “铅笔” 按钮,点击这个按钮,会弹出一个窗口用于配置连接参数。Studio 会考虑数据库特定的分隔符将参数转换为连接字符串:

    v 13 connection params
  9. Locales 对话框现在能根据可用的语言给出提示并根据选择的语言自动填充地区代码:

    v 13 locales dialog
  10. 扩展了 Attribute is not included into the view - 属性未包含在视图中 的代码检查。现在还会检查关联了持久化属性的非持久化属性,这种关联是通过 @MetaProperty#related 注解参数指定的。

  11. 改进了 Studio 处理 Gradle 项目同步失败的行为。现在 CUBA 主菜单会一直显示,并包含附加的菜单项:

    1. Re-Import Gradle Project 菜单项,可以用来处理一次性的网络访问故障。

    2. Restore Project to the Latest State 菜单项,能将 Gradle 构建脚本恢复到上次成功导入的状态,这可以放置无意的或者错误的脚本修改。

      v 13 menu import failed
  12. 独立版 Studio IDE 升级到 IntelliJ Community Edition 2019.2。 之前下载的独立版 Studio IDE 不会自动升级,需要从 CUBA Platform 网站下载新的版本。

  13. 很多其他的小改进和问题修复:

版本 12
  1. 使用原生 IntelliJ UI 组件重新实现了界面设计器。新的设计器响应更快,打开也更快。 设计器有了很多改进,下面会提到一些。

    v 12 screen designer
  2. 为设计器添加了一个新的 Handlers 标签页,放置在 Palette 和 Properies 标签页旁边。 展示已有的方法以及所有可以使用的事件监听器和选中组件的代理方法。 如要生成处理方法,只需双击相应的条目即可。

    v 12 sd handlers
  3. 在界面设计器的顶部操作面板添加了 Preview 操作。 能打开一个正在编辑的界面的预览窗口。该预览窗口的画布能跟踪 XML 编辑的改动,按照其布局变化自动更新预览界面。

    v 12 sd preview
  4. 在界面设计器的层级树的右键菜单中,添加了 Inject to controllerGo to XML 操作。

  5. 在层级树和组件工具箱的右键菜单中添加了 CUBA Documentation 操作。这些操作能打开 CUBA 开发者手册中相应的组件章节。

  6. Form 组件的 Properties 标签页添加了 Add Column 按钮。

  7. ValidatorFormatter 界面设计器对话框中,添加了 class 字段类名的自动完成功能。

  8. 添加了各种应用程序事件监听器的脚手架代码功能。可以通过两种方式使用:

    1. 打开已有的 Spring Bean,在源码编辑器顶部的操作面板中点击 Subscribe to event

    2. 右键点击 CUBA 项目树的 Middleware,选择 NewEvent Listener

      v 12 event listeners
  9. 添加了项目级别的界面生成选项支持。这些设置会被用在 NewScreen…​ 界面向导中。 如要修改这些设置,可以打开主菜单的 CUBASettingsScreen Generation Settings 进行修改。 目前支持下列界面设置:

    1. 表单组件的字段宽度(默认 450px),在实体编辑界面使用

    2. 编辑器的操作按钮在界面底部,在 “全屏” 模式(非对话框模式)打开的实体编辑器中使用

    3. 强制以模态窗打开编辑界面,以对话框模式打开的实体编辑器使用

  10. 在界面创建向导中可以设置该界面的菜单项名称。

  11. 可以为没有 id 的组件添加处理器脚手架代码。Studio 会在需要的时候要求开发者输入组件 id。

  12. 为界面控制器的操作面板添加了 Main Menu 操作。该操作可以将当前界面添加至主菜单或者配置导航至主菜单。

    v 12 main menu action
  13. 优化了 CUBA 项目树中 Deployment 部分的构建 WAR 和 UberJAR 的 UI。如果启用了相应的构建配置,现在只需通过双击 Build WARBuild UberJAR 条目直接构建 WAR 或 UberJar。并且在项目树的 WAR/UberJAR Settings 元素旁边显示相应工件的配置文件(single-war-web.xmllogback.xmljetty-env.xml 等),方便访问。

    v 12 uber jar
  14. 添加了能创建新的数据库创建、更新脚本的操作。在 CUBA 项目树的 Data StoresMain Data Store 右键菜单中:

    1. 初始化脚本: NewDatabase init script

    2. 更新脚本: NewDatabase update script

  15. 在从界面控制器调用的 Install Delegate 对话框中,现在可以为表格的列生成 formatter、自定义列生成器或者 value provider。

  16. 为界面 XML 描述中的 icon 属性添加了自动提示,并在侧边糙提供图标预览。

    v 12 icon gutter
  17. LookupField 组件的 XML 属性 optionsEnum 添加自动提示。

  18. UI 组件的 Quick Documentation 弹窗现在提供了至 CUBA 文档的链接:

    v 12 quick doc
  19. 实体设计器中的本地化语言对话框现在能为 Bean 验证自动生成消息键值,比如 "playground_Rank.queueSize.validation.Digits" 或 "playground_Tariff.taxType.validation.NotNull"。

  20. Microsoft SQL Server (2012+) 数据库类型添加了 Integrated Security 选项的支持。注意,只对基于 CUBA 7.1.0+ 的项目有效。

  21. 大型项目的性能进一步提升(数据模型设计,view.xml 静态分析,CUBA 项目树)

  22. 最低支持的 IntelliJ IDEA 版本提升到了 2019.1。意味着如果您使用更早版本的 IDEA(或者 CUBA Studio),将无法升级 CUBA 插件至新版本。

  23. 很多其他的小改进和问题修复:

版本 11
  1. 添加了 "CUBA Add-ons" 界面,可以通过该界面管理项目中的扩展插件。 可以在 CUBA 项目树双击 ProjectAdd-ons 或者从主菜单的 CUBAMarketplace…​ 打开该界面。 关于该界面的详细描述请参阅此章节

    addons market small
  2. 添加了 欢迎界面。简化了访问通用项目设置和操作的流程,并带有文档和社区网页的链接。

  3. 添加了管理第三方依赖库的 UI。在 Project Properties Editor 可以使用。

  4. 实体设计器已经使用 IntelliJ UI 组件进行了重构。新设计器有如下好处:

    1. 更好的响应体验,打开速度更快

    2. 对实体和其属性的改动会立即反馈到源代码

    3. 集成了 IntelliJ 智能重构技术,比如 安全删除 实体属性

      v 11 entity designer
  5. 实施了实体属性的 安全删除 重构技术。 如要开始重构,从实体设计器删除属性或在源码中右键点击该属性选择 RefactorSafe Delete…​。该重构动作会在视图、界面和其他的配置文件里面搜索此属性的使用情况。并能自动删除安全的地方,对需要手动修复的地方给出警告。

    v 11 safe delete attr
  6. 数据存储配置已经从 Project Properties 界面移出。现在数据存储配置可以在 CUBA 项目树的 Data Stores 部分查看和编辑。主数据存储的设置可以从主菜单 CUBAMain Data Store Settings…​ 打开。请参考 管理数据存储 章节了解细节。

  7. 能使用 HSQLDB InMemory 作为附加数据存储。

  8. 支持使用 MariaDB 作为主或附加数据存储。

  9. 支持使用 Amazon Redshift 作为附加数据存储。

  10. 在实体源码编辑器的操作面板添加了 Add attribute

    v 11 add attr
  11. 支持 EntityChangedEvent 监听的操作也添加到了实体源码编辑器的操作面板。可以用来创建新的监听器或者导航至已经存在的监听器方法。

    v 11 entity changed action panel
  12. 添加了 创建 CUBA EntityChangedEvent 监听器 脚手架代码的对话框。现在可以在一个类里面创建多个监听方法并选择两个额外的事件。

    v 11 new entity changed dialog
  13. 在实体设计器中支持更多的 BeanValidation 2.0 注解:@NotEmpty@Positive@PastOrPresent 以及其它。

  14. 当为实体添加属性时,实体设计器能自动识别属性名称是否能作为实体名称显示(namecaptiontitle 等),如果此时还未有实体名称的话,会自动生成 @NamePattern 注解

  15. 视图设计器现在可以为已经存在视图更名,并对使用该视图的地方进行名称替换。

  16. IDEA 的 Inject 'xxx' 快速修复提示现在可以根据变量名注入 bean - 扩展了其实现,可用于界面控制器和 Spring bean 的上下文中。使用该快速提示的方法示例:

    v 11 inject before
    v 11 inject after

    要使用该功能,在 Spring bean 或者 CUBA 界面控制器中输入需要注入的 bean 的变量名。然后按下 Alt+Enter,在提示框选择 Inject 'beanName'。bean 的类名根据变量名自动关联,所以变量名必须跟 bean 接口的名称一致。比如:dataManagerfileStorageServicemessageBundleclusterManagerAPI,这些变量名会被识别并成功注入对应的 CUBA bean。

  17. 添加了 Java 代码检查器,检查使用 getMessageformatMessage 方法指定的本地化字符串是否存在。

    v 11 message quick fix

    MessageBundleMessagesAbstractWindow(旧界面)类的 getMessageformatMessage 会使用该检查。如果指定键值的消息在指定的消息包中不存在,消息键值会高亮为红色。

    如果按下 Alt+Enter 并选择 Create message in the message bundle 进行快速修复,Studio 会打开 Localization Message 对话框,用来为所有配置的项目 locale 输入本地化消息。

  18. Studio 中独立的 IDE 版本已经升级至 IntelliJ Community platform 2019.1。之前下载的独立版本不会自动升级,您需要从 CUBA Platform 网站重新下载。

  19. 包含该版本的 IntelliJ IDEA 的 CUBA 插件已经上传至主插件(稳定)频道。所以不需要单独设置额外的插件仓库了。如果您使用的是之前版本的 CUBA Studio 插件,现在可以从 Custom Plugin Repositories - 自定义插件仓库 列表中移除 https://plugins.jetbrains.com/plugins/haulmont/list 了。 自定义仓库列表在这里:FileSettingsPlugins → "gear" icon → Manage Plugin Repositories

  20. 其它很多小的改进和缺陷修复:

版本 10
  1. 实体、界面控制器和界面描述的代码编辑器顶部现在提供了一个工具栏,通过这个工具栏可以快速访问 CUBA 提供的操作、在相关文件之间快速跳转:

    v 10 actions panel

    通过面板的按钮可以很快的切换到相关的 DDL 脚本、视图和界面。另外,还可以创建新视图、新界面以及JPA生命周期回调方法。

    这些操作在 IDEA 的 “intentions” 菜单也同样提供了,这个菜单可以通过快捷键 Alt+Enter (Option+Enter) 调出:

    v 10 actions menu
  2. 实现了为 EntityChangedEvent 监听器创建脚手架代码的功能。在 CUBA 项目树选择一个实体类、包、或者最外层的 Middleware 节点,然后点击右键菜单中的 New > EntityChangedEvent Listener。Studio 会在 core 模块创建 Spring bean,带有两个监听器方法:分别在事务提交前和后收到通知。

  3. 实现了为 JMX bean 创建脚手架代码的功能。在 CUBA 项目树选择 Middleware 节点或者 Beans 节点下的一个包,然后点击右键菜单的 New > JMX Bean

  4. 实现了为配置接口生成脚手架代码的功能。在 CUBA 项目树选择 Project > Config Interfaces 节点,然后点击右键菜单的 New > Configuration Interface

  5. Inject 对话框现在包含了 Project bean 的选择区域,这里可以注入任何项目中可用的 Spring bean。

  6. 使用 Groovy 编写的界面控制器也能使用 Inject 对话框了。

  7. 提升了依赖注入的体验:现在如果将光标放在方法体内并调出 Inject 弹窗,注入的字段定义会自动生成在类的顶部,而字段名会自动复制到光标处。

  8. 将组件注入控制器 的行为现在也能在组件的 XML 内做了。试试将光标放在XML中一个组件的元素上,然后按下快捷键 Alt+Enter (Option+Enter)。

  9. 实现了添加实体索引和唯一约束的可视化编辑器。可以在实体编辑界面的底部找到新的 Indexes 标签页。

  10. 实现了检查重复实体名称和表名的功能。如果为多个类定义了相同的实体名或者表名,则会在实体类显示提示。

  11. 实现了在实体的字段添加正确 JPA 注解的功能。简化了手动编写实体属性的工作:您在可以添加实体字段并生成 getters/setters 之后在该字段按下 Alt+Enter (Option+Enter),即可看到相关选项。

  12. 在界面控制器代码中,如果注入了界面 XML 中不存在的组件,则会显示提示信息:

    v 10 warn nonexisting
  13. 在实体类代码里,如果实体类没有 @NamePattern 注解的话,也会显示警告信息:

    v 10 warn namepattern

    可以在类名处通过按下 Alt+Enter (Option+Enter) 快捷键修复问题或者屏蔽这个警告。

  14. 视图设计器现在使用了主从布局,视图列表在左边,选中的视图编辑在右边。

  15. 对基于 CUBA 7.1 以上版本的项目,添加了如下功能:

    1. 能使用带侧边菜单和响应式侧边菜单的主界面模板。

    2. 支持向声明式打开的界面和 fragments 传递属性参数。

    3. 支持 REST API 扩展组件。

  16. 所有解决的问题:

版本 9
  1. 破坏性更改:Studio 现在使用 HSQL 2.4.1。当打开一个使用 HSQL 数据库的项目时,Studio 会提示升级项目文件 build.gradle 中的 HSQL 版本。如果同意,项目可以正确的用 Studio v.9+ 继续工作。但是,要注意以下问题:

    1. 带有新 HSQL 驱动的应用程序如果在带有旧 HSQL 驱动的之前版本 Studio 打开的话,有可能启动不了。

    2. 基于 CUBA 7.1 之前的使用 HSQL 的项目,计划任务会失效,因为之前版本的数据库表有一列叫 PERIOD,现在在 HSQL 2.4.1 中已经是保留字了。在 CUBA 7.1 里面重命名了该列。

      Tip

      如果您使用的是 CUBA 7.0 或者更低的版本,而且在开发阶段需要使用 HSQL 和计划任务,可以按照下面的步骤在 Studio 使用 HSQL 2.2.9:

      1. 退出 Studio。

      2. 复制 cuba-studio 目录:

        • Windows 系统:从 C:\Program Files\Haulmont\CUBA Studio 2018.3\plugins\ 复制到 %userprofile%\.CubaStudio2018.3\config\plugins\

        • MacOS 系统:从 /Applications/CUBA Studio.app/Contents/plugins/ 复制到 ~/Library/Application Support/CubaStudio2018.3/

      3. 在拷贝的 cuba-studio/lib 目录中,使用 hsqldb-2.2.9.jar 替换 hsqldb-2.4.1.jar。可以在 这里 下载。

      4. 启动 Studio 并打开项目。

      5. build.gradle 中使用 def hsql = 'org.hsqldb:hsqldb:2.2.9' 替换 def hsql = 'org.hsqldb:hsqldb:2.4.1'

      至此,Studio 和项目都会使用 HSQL 2.2.9,基于 CUBA 7.0 和更低版本的应用程序便能在 HSQL 使用计划任务了。

  2. 热部署机制现在能同时部署更改的类依赖的所有类,这样不会在打开修改了的界面时弹出 ClassCastException

  3. 当选择 MySQL 或者 Oracle 数据库时,Studio 会展示一个对话框,这里可以点击链接到供应商网站下载 JDBC 驱动,然后可以上传驱动至项目和 Studio。上传驱动结束后,需要重启 Studio。

    可以使用 CUBA > Database Proprietary Drivers 配置页移除上传的驱动。

  4. Create CUBA Screen 向导中可以在浏览界面和主从界面模板的 Table type 字段选择 DataGridTreeDataGrid

  5. Create CUBA Screen 向导 添加了 Extend an existing screenEntity fragment 模板。

  6. 在可视化编辑器中 Undo/Redo 操作能正常工作。

  7. 在界面设计器中,数据加载器的查询语句添加了自动完成功能。

  8. 界面设计器在画布右上角添加了一个按钮,用来切换至界面控制器。

  9. 在基于新 API 的界面 XML 描述中使用 invokedatasource 属性时,会给出警告。

  10. 如果在 Project Properties 窗口添加了 Groovy 支持,则可以在 Create CUBA Screen 向导中的 Advanced > Controller language 字段选择 Groovy。

  11. Groovy 写的 Services 能在 CUBA 项目树中显示。

  12. 项目打开时会弹出有框架新版本的提示。

  13. 微调了代码编辑器中侧边栏的图标。

  14. 不管有没有重构,都可以在实体设计界面自由更改实体属性的类型。

  15. 添加了枚举类型设计界面。

  16. 视图设计器使用原生 IntelliJ UI 重写。

  17. 数据模型生成器包含使用新 API 的界面模板。

  18. 所有解决了的问题:

版本 8
  1. 现在第一次打开项目是通过导入向导来做了。参阅打开现有项目了解细节。

  2. 项目模型现在保存在 .idea 文件夹的一个文件内,所以不会每次在打开项目时进行 Gradle 同步。

  3. 通过 Run/Debug Configuration 编辑器现在可以选择运行应用程序服务的 JDK 版本。在 Configuration 标签页有 JVM 字段。默认使用 JAVA_HOME 环境变量的值。

  4. 可以通过标准的 Refactor > Rename 操作来对视图进行重命名。在 CUBA 项目树中可以在视图元素上调用这个操作,也可以在 views.xml 文件的视图 XML 定义中的 name 属性调用这个操作或者在界面 XML 描述中任何引用该视图的地方调用。

  5. 可以在界面设计器中数据容器的 view 字段调用视图编辑器。

  6. 实现了在界面描述的 <fragment> XML 元素中对 screen 属性的自动完成功能以及使用参考功能。

  7. 为菜单标题实现了本地化名称编辑器。在 CUBA 项目树中点击 Generic UI > Web Menu,切换到 Structure 标签页,选择一个菜单项然后在 Caption 字段点击 edit 即可。

  8. 如果枚举值没有本地化名称,编辑器则会出现警告。如果发现该警告,可以使用 Create message in the message bundle 快速修复来创建默认名称。

  9. 实现了在配置接口中声明应用程序属性时,能自动完成其名称。当定义 app.propertiesweb-app.properties 内的属性时,按下 Ctrl+Space 即可。

  10. 所有解决了的问题:

版本 7
  1. 如果你的项目基于 CUBA 6.10 ,并使用了 BPM 、图表 、全文搜索或报表等高级扩展组件,则需要在 ~/.gradle/gradle.properties 文件中设置 premium 仓库的访问凭据,如 开发人员手册所述。 Studio不会将凭据传递给Gradle。

  2. 所有解决了的问题:

1. 安装

在安装 CUBA Studio 之前,确保系统满足 CUBA 开发人员手册 安装 部分中说明的要求。

有两种不同的安装 CUBA Studio 的形式:作为操作系统上独立的 IDE 安装或者作为已经安装的 IntelliJ IDEA 的插件安装。独立的 Studio IDE 是 IntelliJ IDEA 社区版的特殊版本,包含了 CUBA 插件。如果之前没有用过 IntelliJ IDEA,推荐使用独立 IDE 版本。

IDE 版本对应于使用的 IntelliJ IDEA 的版本,比如,2019.2。CUBA 插件有自己独立的版本号,从 13 开始。

可以从 https://www.cuba-platform.cn/tools/ 下载适用于 Windows、macOS 和 Linux 的独立 IDE 的安装程序。插件可以通过 IntelliJ 插件仓库下载(参考下面)。

在 Windows 上安装
  1. 下载 cuba-studio-VERSION.exe 安装程序。

  2. 运行安装程序并按照其说明操作:选择安装位置、启动器类型、文件夹名称,然后完成安装。

  3. 启动已安装的应用程序,参考这里了解更多信息。

在 macOS 上安装
  1. 下载 cuba-studio-VERSION.dmg 安装程序。

  2. 双击安装程序,然后将 CUBA Studio.app 拖放到 Applications 文件夹。如果有以前版本的 Studio 并且想保留它,请在出现的对话框中选择 Keep Both

  3. 启动 CUBA Studio 应用程序,参阅这里了解更多信息。

在 Linux 上安装
  1. 安装所需的依赖:

    $ sudo apt-get install libgconf-2-4
  2. 下载 cuba-studio-VERSION.tar.gz 存档。

  3. 将存档移动到适当的文件夹,例如 ~/lib 并将其解压:

    $ tar -xvf cuba-studio-VERSION.tar.gz
  4. 转到 bin 目录并启动应用程序:

    $ cd ~/lib/cuba-studio-VERSION/bin
    $ ./cuba-studio.sh
首次启动 IDE

当第一次启动独立的 CUBA Studio IDE,Studio 会询问一些问题:

  • 在第一个 Complete Installation 对话框中,选择 Do not import settings 然后点击 OK

  • 在下一个 Customize CUBA Studio 对话框中,可以点击 Skip Remaining and Set Defaults 以使用默认设置。因为之后随时可以自定义这些环境。

  • 参阅 入门 部分了解如何启动一个新项目或者打开已有项目。

IntelliJ IDEA 插件安装
  1. 启动 IntelliJ IDEA 2019.1 或者更新的版本。

  2. 打开 Plugins 对话框。

  3. 切换到 Marketplace 标签页

  4. 在搜索栏输入 "CUBA",可以在搜索结果看到 CUBA 插件。

  5. 点击 Install ,之后按照 IDE 的步骤继续安装。

1.1. 使用代理

如要配置 CUBA Studio 通过代理服务器访问网络,需要按照下列步骤配置:

  1. 配置 IntelliJ IDEA (或 CUBA Studio)

  2. 配置 Gradle

  3. 配置 Git(可选)

配置 IDEA(CUBA Studio)代理
  • 打开 Settings 对话框:主菜单 → FileSettings

  • 选择 Appearance & BehaviorSystem SettingsHTTP Proxy

  • 设置必要的参数值,然后点击 Check connection 进行测试:

proxy idea

请参考 IDEA 代理配置 了解更多内容。

配置 Gradle 代理
  • 在用户主目录找到 ~/.gradle/gradle.properties 文件

  • 编辑该文件,按照 Gradle 文档 配置代理参数:

systemProp.http.proxyHost=192.168.57.1
systemProp.http.proxyPort=3128
systemProp.http.proxyUser=developer
systemProp.http.proxyPassword=Df887..33
systemProp.http.nonProxyHosts=*.nonproxyrepos.com|localhost
配置 Git 代理(可选)

也许您想要配置 Git 版本控制软件的代理,比如需要从 CUBA GitHub 仓库 下载示例项目:

运行该命令:

git config --global http.proxy http://proxyUsername:proxyPassword@proxy.server.com:port

参考 Git 文档 了解更多细节。

1.2. 离线模式

可以在没有联网的情况下使用 Studio 开发项目,前提是所有项目所需的依赖已经下载过,比如,项目已经打开并且使用当前的 Studio 进行过装配(assemble)。离线模式下,Studio 的部分功能将无法使用,比如无法修改 CUBA 平台的版本或者浏览 CUBA 的插件市场。

要使用里面模式,打开 IDE 右边的 Gradle 工具窗口,然后点击 Toggle Offline Mode 按钮:

gradle offline mode

在离线模式中,Gradle 使用缓存的依赖执行所有的项目构建任务。并且不会尝试访问网络下载新的依赖。如果所需的依赖在缓存中不存在,构建执行则会失败。

1.3. 非标准 Studio 版本

有时需要在 IDE 中使用一个非标准的 Studio build。想试用最新的 Studio 功能或者参与 Beta 版本的测试。使用非标准的 Studio build 需要在 IntelliJ IDEA 中安装特定的插件版本。

Tip

非标准的 Studio 版本在商业订阅的需求上与稳定版一样。

Beta 发布版

Beta Studio 发布版会在下一个 Studio 的主版本发布之前的几周发布。这些版本也已经测试过,但是还可能包含一些未解决的问题。Beta 版本主要是为了:

  • 为感兴趣的用户提供新 Studio 功能的前期试用。

  • 帮助 CUBA 团队在更广泛的工作区和项目基础上测试即将发布的新 Studio 版本并提供反馈。

如需试用 Beta 版本,需要按照以下步骤操作:

  1. 打开主菜单 → FileSettingsPlugins 对话框。

  2. 点击 齿轮 图标,然后选择 Manage Plugin Repositories

  3. 点击 + (Add) 然后在仓库 URL 地址字段输入: https://plugins.jetbrains.com/plugins/beta/list

  4. 切换至 Marketplace 标签页。您应当能看见 CUBA 插件升级至 BETA 版本的请求。

  5. 点击 Update

  6. 根据提示重启 IDE。

如果需要切换会稳定的插件版本,按照以下步骤:

  1. 打开主菜单 → FileSettingsPlugins 对话框。

  2. 卸载 CUBA 插件。

  3. 点击 齿轮 图标并选择 Manage Plugin Repositories

  4. 从列表移除 “beta” 仓库。

  5. 重新安装 CUBA 插件,会从稳定版的仓库安装。

夜间版本

Nightly Studio builds 会作为持续集成流程的一部分每天晚上发布。这些版本包含最新改动。如果想做第一个吃螃蟹的人,可以切换到夜间版本,获得最新的功能、提升以及支持即将发布的新 CUBA 平台版本。

Warning

夜间版本包含一些未经 QA 测试的改动。因此这些 build 可能包含严重的功能性缺陷。

如需用夜间版本,需要按照以下步骤操作:

  1. 打开主菜单 → FileSettingsPlugins 对话框。

  2. 点击 齿轮 图标,然后选择 Manage Plugin Repositories

  3. 点击 + (Add) 然后在仓库 URL 地址字段输入: https://plugins.jetbrains.com/plugins/haulmont_nightly/list

  4. 切换至 Marketplace 标签页。您应当能看见 CUBA 插件升级至 NIGHTLY 版本的请求。

  5. 点击 Update

  6. 根据提示重启 IDE。

由于夜间版本是每天晚上发布,您会每天都收到 IDE 发出 “有插件可更新” 的提示。

如果需要切换会稳定的插件版本,按照以下步骤:

  1. 打开主菜单 → FileSettingsPlugins 对话框。

  2. 卸载 CUBA 插件。

  3. 点击 齿轮 图标并选择 Manage Plugin Repositories

  4. 从列表移除 “nightly” 仓库。

  5. 重新安装 CUBA 插件,会从稳定版的仓库安装。

从硬盘安装插件

Studio 插件的任何发布版,包括之前的一些版本,都能从插件仓库网站手动下载然后安装到 IntelliJ IDEA。按照下列步骤:

  1. 在 JetBrains Plugin 仓库打开 CUBA 插件 页。

  2. 选择需要下载版本的通道(稳定版、Beta 版、夜间版)。

  3. Version History 列表中找到需要下载的 build 版本。

  4. 点击 Download 开始下载。

  5. 在 IDEA 中打开主菜单 → FileSettingsPlugins 对话框。

  6. 点击 齿轮 图标并选择 Install Plugin from Disk…​

  7. 选择刚下载的 zip 文件,并点击 OK

  8. 根据提示重启 IDE。

2. 更新

更新独立 IDE

可以从 网站 下载新版的独立 Studio IDE 然后覆盖安装。会保留之前所有的 Studio 设置。

也可以从插件仓库安装 CUBA 插件的自动更新,这样就不用下载和安装整个 IDE 应用程序:

  1. 打开 Plugins 对话框。

  2. 切换到 Updates 标签页。

  3. 如果有可用的更新,就可以在列表中看到。点击 CUBA 插件的 Update ,IDE 将会下载这个插件。

  4. 下载完成后,需要重启 IDE 来应用新版的插件。

更新 IntelliJ IDEA 插件
  1. Windows 和 Linux 操作系统上点击 Help > Check for Update,MacOS 上点击 IntelliJ IDEA > Check for Updates

  2. 如果有可用的更新,会在列表中看到。选择 CUBA 插件 然后点击 Update 。IDE 将下载这个插件。

  3. 下载完成后,需要重启 IDE 来应用新版的插件。

3. 入门

本节介绍如何在 Studio 中创建新项目或打开现有项目并启动应用程序。

3.1. 创建一个新项目

CUBA Studio 提供了一种从零开始创建新 CUBA 项目的简单方法。只需使用 New Project 向导,然后按照以下步骤操作:

  1. Welcome to CUBA Studio 窗口中,单击 Create New Project 或使用主菜单 FileNewProject

  2. 选择 CUBA Project.

  3. 指定 Project namespace,该命名空间将会作为实体或者数据库表的前缀。命名空间只能由拉丁字母组成,并且尽可能短。这里需要仔细考虑该名称,因为之后如果想修改会需要很多手动操作。

  4. 如果需要,可以修改 Root package。这是 Java 类的根包名。也可以之后再调整,但是项目创建阶段生成的类还会使用当前的包名。

  5. 如果需要,可以修改 Module prefix。CUBA 项目的模块名称会添加这个作为前缀。模块名前缀可以稍后修改。

  6. Project SDK 字段,选择对应环境中设置 JAVA_HOME 的 JDK。如果看到 <No SDK> 这样的值,点击 New 然后选择 JDK 安装的目录,比如在 Windows 是 C:\Java\jdk8u202-b08,macOS 是 /Library/Java/JavaVirtualMachines/jdk8u202-b08/Contents/Home

  7. 选择默认仓库配置,或为项目 自定义 仓库配置。

  8. 选择项目中使用的 Platform version。如果没有特别需求,使用最新的发布版本。

  9. 为了做 beta 测试或尝试使用新的 CUBA 平台功能,您也许需要使用一个不稳定的 CUBA 版本,即,以 BETASNAPSHOT 结尾的版本。需要勾选 Show unstable versions 复选框,才能在 Platform version 的下拉框中看到这些版本。注意,SNAPSHOT 发行版只在 repo.cuba-platform.com 仓库发布。

  10. Languages support 下拉框字段选择项目使用的编程语言,或者使用默认的 Java 语言。

  11. 使用 Available locales 字段打开 Locales 编辑器对话框,可以为项目添加多地区支持。也可以稍后再修改该配置。

  12. 点击 Next

  13. 向导的第二步中,可以配置主数据存储属性,比如,为新项目选择本地的 PostgreSQL 作为数据库。这些属性也可以稍后修改。

  14. 点击 Next

  15. 如果需要,可以修改 Project name 字段的值。该名称只能包含拉丁字母、数字和下划线。

  16. Project location 配置新项目的路径。可以输入其他的值或者点击省略号按钮修改这个路径。

  17. 单击 Finish。空项目将在指定目录中创建,之后 Studio 会自动通过 Gradle 文件开始构建项目信息并为项目建立索引。

  18. 项目同步和建立索引过程完成后,将在 Project 工具窗口中看到 CUBA 项目树。

  19. 打开 Gradle 工具窗口,默认固定在右边栏。点击“扳手”图标(Gradle Settings)然后在 Gradle JVM 字段选择 Use JAVA_HOME。如果在下拉列表中没有看到该选项,请确保按照 CUBA 开发者手册中 安装 部分配置了正确的开发环境。点击 OK

  20. 现在可以开始项目的工作了。

3.2. 打开现有项目

打开已导入的项目

如果在此计算机上已经通过 CUBA Studio 打开过该项目,请执行以下操作:

  1. 使用最近项目列表或单击 Open,在文件系统对话框中选择 _ 项目目录 _,然后单击 Open 按钮。

  2. 等待 Gradle 同步和项目索引过程完成。只要 CUBA 项目树出现在 Project 工具窗口中,就可以开始使用该项目了。

首次打开项目

如果还没有在此计算机上通过 CUBA Studio 打开该项目,例如,只是通过 VCS 下载了代码,请执行以下操作:

  1. 在欢迎窗口,点击 Import Project。如果已经打开了另一个项目,则在主菜单点击 File > New > Project from Existing Sources

  2. 在文件系统的窗口,选择项目的根目录(包含 build.gradle 文件),然后点击 Open 按钮。

  3. Import Project 窗口,选择 Import project from external model 单选按钮并在下面的列表中选择 CUBA,然后点击 Next

  4. 在导入向导的下一页点击 Finish

    • 等待 Gradle 同步和项目索引过程完成。CUBA 项目树会出现在 Project 工具窗口中。

  5. 在主菜单点击 File > Project Structure

    • 确保 Project SDK 字段的值跟环境中设置的 JAVA_HOME 一致。如果看到 <No SDK> 值,点击 New 然后选择 JDK 安装的目录,比如在 Windows 是 C:\Java\jdk8u202-b08,macOS 是 /Library/Java/JavaVirtualMachines/jdk8u202-b08/Contents/Home

    • 确保 Project language level 字段的值跟 JDK 的版本一致。比如,如果 JDK 是 1.8 语言等级必须是 8 - Lambdas, type annotations, etc.

首次打开基于 CUBA 6.10 的项目

CUBA Studio 支持基于 CUBA 6.10+和 7.0 的项目。可以打开在旧版本的 Studio 中创建的项目,并将其导入到新 Studio 中,进行以下操作:

需要记住 CUBA 6.10 只支持 Java 8,所以 JAVA_HOME 环境变量必须指向 JDK 8 的安装目录。在迁移到 CUBA 7 之后,如果需要可以使用新版本的 JDK。

如果是第一次打开已有的 CUBA 6.10 项目,需要按照下面的步骤:

  1. 如果项目使用了 premium 扩展组件(Reports、BPM 等)并且已经有了许可,需要按照 文档 的描述在 ~/.gradle/gradle.properties 文件内设置 premium 仓库的访问凭证。

  2. 在命令行使用 gradlew cleanIdea 任务删除旧的 IntelliJ 项目文件。

  3. 如果项目使用 Git 做版本控制,将 .idea 行添加到项目根目录下的 .gitignore 文件中。确保本地 IDE 设置不会在项目的所有开发人员之间共享。

  4. 按照上面 首次打开项目 部分所述导入项目。

3.3. 升级项目

本节介绍将项目升级到较新版本 CUBA 的过程。

Tip

建议使用版本控制对项目进行管理,并在升级之前提交所有未提交的改动。这样的话,如果由于某种原因导致升级失败,可以通过版本控制查看执行了哪些更改并快速回滚到以前的版本。

  • 按照前一节中的描述打开项目。

  • 单击主菜单中的 CUBA > Project Properties,或双击 CUBA 项目树中的 Project > Properties

  • CUBA Project Properties 对话框中,在 Platform version 字段中选择所需的 CUBA 版本。

  • 为了做 beta 测试或尝试使用新的 CUBA 平台功能,您也许需要使用一个不稳定的 CUBA 版本,即,以 BETASNAPSHOT 结尾的版本。需要勾选 Show unstable versions 复选框,才能在 Platform version 的下拉框中看到这些版本。

    Tip

    只有使用了 repo.cuba-platform.com 仓库才能看到 SNAPSHOT 版本。

    Warning

    强烈建议不要在生产环境使用 BETASNAPSHOT 版本。

  • 单击 OK,然后确认。

  • 如果要升级到较新的功能版本(例如,从 6.10.X 升级到 7.0.X 或从 7.0.Y 升级到 7.1.Y),则会出现 Migration Required 弹窗,包含将由 Studio 自动执行的数据库迁移的信息。查看信息确认数据库迁移内容,然后单击 Migrate,注意,此时并不会执行数据库更新脚本,只是列出更新步骤。

  • Studio 会自动执行迁移,更新脚本(如果需要)并运行 Gradle cleanundeploy 任务。

  • 如果升级到新的功能版本,可能有新的改动使得项目不能运行,请查看 Release Notes 中的 Breaking Changes 部分,并相应地对项目进行修改。

  • 如果您的项目包含 CUBA Add-ons,您也许需要升级到兼容当前 CUBA 版本的合适扩展插件版本:

    • 打开 CUBA 项目树的 ProjectAdd-ons

    • 选择 Updates 标签页。

    • 选择所有能升级的插件。

    • 点击 Apply & Close.

    • 等依赖下载完成并且项目重新建立索引。

  • 尝试通过执行 CUBA > Build Tasks > Assemble 来组装项目。如果编译不通过,可以按照日志输出来修复代码。

  • 执行 CUBA > Update Database 将框架中可能新引入的数据库结构更改合并到项目的数据库中。

3.4. 启用应用程序

当 Studio 导入了一个 CUBA 项目之后,会创建为 CUBA 特定修改的 Run/Debug 配置,目的是用来运行部署了应用的本地 Tomcat 服务。所以为了运行应用程序并能用调试器进行连接,只需要在主工具栏点击选中的 CUBA Application 配置边上的 debug 按钮即可。

app start 1

Debug 工具窗口的 Console 标签页可以看到状态。能通过点击打印在 Server started at 消息之后的链接地址在默认浏览器打开应用程序的图形界面。

app start 2

也可以通过 CUBA 树部分的 Runs At…​ 在浏览器打开运行的应用程序:

runs at

如果要查看应用程序服务的输出,切换到 catalina.out 标签页:

app start 3

如果要停止应用程序,可以通过在主菜单选择 Run > Stop 'CUBA Application' 或者点击 Debug 工具窗口的按钮:

app start 4

推荐在开发中使用 Run/Debug 配置来启动应用程序,但是通过 Studio 的 CUBA 主菜单项也可以控制本地 Tomcat 应用程序服务:

cuba menu appserver

当从 Start Application Server 主菜单命令启动服务时,在 Windows 系统能看到一个控制台窗口显示服务器日志。在 Linux 或者 macOS 系统,不会显示控制台,但是可以在 Terminal 工具窗口通过执行 tail -f deploy/tomcat/logs/app.log 命令查看服务日志。Stop Application Server 命令通过发送 SHUTDOWN 信号给停止端口来停止 Tomcat 服务,停止端口是通过项目属性设置(默认是 8005)。

运行/调试配置

Tomcat 服务中 CUBA Application 运行/调试的配置是能调整的。使用下列方式打开配置对话框:

  • 在工具栏中点击 CUBA Application 元素然后在菜单中选择 Edit Configurations…​

  • 或使用主菜单 → RunEdit Configurations…​

run configuration toolbar

会弹出 Run/Debug Configuration 对话框。您或许希望调整下列配置:

  • JRE - 启动调试 Tomcat 服务的 Java 运行环境。可以选择和项目 JDK 不同的 JRE,但是需要考虑二进制文件的兼容性需求(比如使用 Java 11 编译的应用程序不能在 Java 8 运行)。

  • Command line arguments - 传递给调试服务的 JVM 参数。例如,指定 -Xmx1500m 提高服务使用的最大内存数量。

  • Environment Variables - 调试服务进程可以使用的环境变量。

run configuration settings

3.5. 使用非默认 JDK

IntelliJ IDEA 和 Gradle 默认都会使用由 JAVA_HOME 环境变量定义的 Java Development Kit (JDK) 来装配和运行 Java 项目。如需使用非默认的 JDK,又不想修改全局的配置,需要额外几步操作。

我们假设有这样的环境配置:

  • 开发机器的 JAVA_HOME 环境变量指向 JDK 8,但是由于某些原因,您没有办法修改这个配置。

  • 项目中想使用 JDK 11。

  • 您希望能使用新的 Java 11 API,因此项目需要使用 JDK 11 来编译和运行。

请按照以下步骤进行配置:

  • 为 IDEA SDK 添加 JDK 11,如已添加,请忽略这步。点击主菜单 FileProject Structure。在左侧菜单选择 SDKs。点击 + 按钮 → 选择 JDK → 选择 JDK 11 安装目录。点击 OK 保存更改。

  • 当创建新的 CUBA 项目时,在 Project SDK 字段选择 “11”。

  • 对于已有项目,打开主菜单 → FileProject Structure 窗口,然后修改 ProjectProject SDK 值。

  • 切换到项目根目录,并创建 gradle.properties 文件,包含以下内容:

# Path to JDK 11
org.gradle.java.home = C:/Java/jdk-11.0.5.10-hotspot
  • 修改项目根目录的 build.gradle 文件。并在 configure([globalModule, coreModule, webModule]) 块最后添加:

configure([globalModule, coreModule, webModule]) {
    ...
    sourceCompatibility = '11'
    targetCompatibility = '11'
}
  • 刷新 Gradle 项目配置:Gradle 工具窗口 → Reimport All Gradle Projects

  • 修改 CUBA Application 运行配置中的 JRE。打开主菜单 → RunEdit configurations…​CUBA Application → 修改 JVM 字段的值。

当这些修改完成之后,项目将会使用 JDK 11 进行编译和运行,而不需要修改全局系统配置。

4. Studio 用户界面

本节介绍 CUBA 特有的 IDE 元素的用户界面。有关 IntelliJ IDEA 的所有功能,请参阅 文档

4.1. CUBA 项目树

CUBA 项目树用于展示项目结构及其重要元素,通常在 IDE 左侧的 Project 工具窗口中打开。可以使用 CUBA > Project Tree 主菜单命令或在 Project 工具窗口的顶部下拉列表中选择 CUBA 来切换到项目树。

项目树包含以下元素:

cuba tree
  1. Project

    • Properties - 允许配置项目的基本设置。

    • Add-ons - 打开界面配置项目中用到的 CUBA 扩展。

    • Build Script - 包含两个主要项目脚本: build.gradle (定义构建配置)和 settings.gradle(定义项目名称和模块组)。

    • Modules - 显示所有项目模块。

    • Data Stores - 显示并管理项目所连接的 数据存储 列表。默认情况下,只有 Main 数据存储。

    • Deployment - 允许定义项目部署选项。

  2. Data model - 显示并管理项目的数据模型。

  3. Middleware - 显示并管理中间件服务和托管 bean。

  4. Generic UI - 包含与项目的用户界面相关的所有内容,例如界面、主题等。

  5. REST API - 允许配置 REST API 功能。

  6. Runs At…​ - 允许在外部或嵌入的 Web 浏览器中打开运行中的应用程序。

右键点击树元素能打开右键菜单,可以执行针对当前元素的特定操作。例如,使用 Data Model 项的右键菜单,可以从模型生成数据库脚本、从数据库生成模型以及创建新实体或枚举:

cuba tree context menu

4.2. CUBA 菜单

CUBA 主菜单可以快速访问 IDE 中的 CUBA 特有功能。某些菜单项功能与CUBA 项目树 及其右键菜单功能相同。

cuba menu

可以通过右击工具栏并选择 Customize Menus and Toolbars,将常用菜单项添加到主工具栏。在弹出的 Menus and Toolbars 窗口中,展开 Main Toolbar 项并使用 Add Action 按钮添加 Main Menu > CUBA 树中的条目。

4.3. 欢迎界面

在新项目创建时,欢迎 界面会自动在工作区打开。也可以通过主菜单 CUBAWelcome 来打开。

该界面提供主要项目设置、常用操作、文档和社区网页链接的快捷入口。 也会显示项目中用到的 CUBA 版本信息和 Studio 版本信息以及商业订阅信息。

welcome screen

4.4. CUBA 设置

如果单击 CUBA > Settings 主菜单项,可以看到在 IDE 的设置中选中了 CUBA 部分。

CUBA 部分包含对所有在 Studio 实例中打开的项目都通用的设置。

  • Ask before saving DB scripts with DROP statements - 建议不要自动执行包含 DROP 语句的更新脚本。

  • Show warning if application server port is in use - 打开项目且 Tomcat 端口被占用时显示警告。

  • Use embedded browser to open application - 如果选中该选项,则双击 Runs At 项目树中的应用程序 URL 时将使用内嵌 Web 浏览器打开项目地址。

  • Visual designer and embedded browser zoom percentage - 界面设计器的布局预览默认缩放。也可以通过预览面板顶部的一个操作按钮稍后调整。

  • Enable integration - 如果要将此 IDE 实例与旧的 Studio SE 或 Studio Browser Edition 集成,选中此复选框。这样就可以在新的 IDE 中打开旧 Studio 的项目。另外,这个复选框也会启用与前端生成器命令行工具的通信。

  • Listening port - 用于集成旧 Studio 的端口。确保这个值与旧 Studio 的 IDE Port 字段中指定的值相同。

项目设置

下一级的 Project settings 部分包含当前打开的项目的设置。所有非默认值都存储在项目根目录的 studio-intellij.xml 文件中,可以将其添加到版本控制系统,以便在团队中的所有开发人员之间共享项目设置。

  • Check compatibility between data model and database scheme - 在启动应用程序服务时,如果数据模型的当前状态与数据库架构不一致时显示警告信息。

  • Generate DROP statements in separate update scripts - 为删除实体、属性或更改属性的数据类型的操作生成更安全的更新脚本。这些脚本分为两部分:在第一部分,列或表被重命名为 *__UNUSED,在第二部分对这些对象执行实际的删除操作。

  • Use NVARCHAR when generating scripts for MS SQL Server -如果启用此选项,对于 Microsoft SQL Server 数据库,使用 NVARCHAR 列类型存储所有 String 属性。

  • Generate script name in format - 指定 yyMMddHHmm 可以将当前时间添加到生成的数据库更新脚本的名称中,这有助于确保在团队工作中脚本的正确顺序。

  • Do not delete columns started with - 此字段允许为表列指定一个前缀,Studio 将不跟踪具有此前缀的列。一般情况下,如果向映射到实体的表添加了一列,而不将列映射到一个实体属性,Studio 将生成删除此列的更新脚本。如果想避免丢失表中的列,可以在 Database Scripts 对话框中不包含此脚本,这个脚本也不会再次生成。或者通过 Do not delete columns started with 字段为此类列设置一个公共前缀,并相应地命名列。例如,在字段中输入 NOT_MAPPED_ 并将列命名为 NOT_MAPPED_CODE

  • Column length for enums with ID of String type - 此字段允许设置数据库列的长度,该列映射到具有 String 类型标识符的枚举类型的属性。例如,如果始终使用只由一个字符组成的短标识符,则可以将此字段设置为 1,以节省数据库空间。

  • Make plural forms - 根据英语语法构造名词的复数形式。

  • Repeat entity parent package for screens - 当 Studio 根据模板生成通用 UI 界面时,如果实体位于比 entity 包更深的一个包中,Studio 将为界面添加此包名。例如,如果 Customer 实体位于 com.company.sample.entity.crm 中,则其界面的默认包将是 com.company.sample.web.crm.customer

  • Use underscores in generated package names - 如果选中,包名称将包含以下划线分隔的单词,这些单词是根据以驼峰命名法命名的相应实体名称生成。例如,当为 com.company.sample.CustomerGrade 实体生成界面时,界面的包将是 com.company.sample.customer_grade。如果该选项关闭,则包名称为 com.company.sample.customergrade

  • Default parent package name for screens - 当根据与实体无关的模板生成通用 UI 时,可以在这里指定使用的默认包名替代"screens"(默认)。如果模板关联了实体,还会在包之前添加实体名称。例如,如果将此字段设置为"ui"并创建一个空白界面,则包的默认值为 com.company.sample.web.ui

  • Default entity attribute access modifier - 设置 Studio 在生成实体字段时使用的默认字段修饰符。

  • Generate entity name with underscore symbol - 如果选择,实体名称将具有 namespace_ClassName 格式,例如 sales_Customer。否则它将是 namespace$ClassName

  • Show module prefix migration dialog - 在项目打开时,显示模块定义迁移的弹窗,其中会建议将构建脚本中的模块定义改为新格式 - 用变量定义模块名称前缀。

  • Instant hot deploy - 此复选框允许关闭热部署。如果启用了热部署,则 Studio 会在应用或保存对视图、界面、消息或主菜单的更改时动态更新已部署的 Web 应用程序的 UI。

  • Scaffolding language - 在支持 Kotlin 的项目中选择使用何种编程语言生成代码。可选项为:KotlinJavaAlways Ask。如果您的项目混合了 Java / Kotlin 的内容,然后您想控制每次生成实体、服务、界面的脚手架代码,可以选择 Always Ask。该选项只有在项目支持 Kotlin 时才会出现。

  • Hot deploy compiled classes - 为基于 CUBA 7.2+ 的项目启用新的热部署机制。旧的机制需要复制 Java 源码到 Tomcat 配置目录并使用自定义的类加载器编译这些文件。新的机制会在 IDE 端编译这些文件,因此能热部署 Kotlin 代码。如果在使用新的热部署机制中遇到问题,可以尝试关闭该设置。

  • Hot Deploy Settings - 打开对话框来自定义热部署目录。例如,可能希望将 Web 门户的 HTML 文件和 JavaScript 文件所在的文件夹添加为部署目录。当更改这些文件时,Studio 会将它们复制到 Tomcat 中的各自对应的目录。因此,只需重新加载 Web 门户页面即可查看更改。

  • Screen Generation Settings - 影响界面生成的选项。这些设置在 NewScreen…​ 向导中使用。可用设置有:

    • Default form field width - 实体编辑器使用

    • Keep editor actions at the bottom - 实体编辑器以“全屏”模式打开时使用。

    • Force modal open type for editors - 实体编辑器以“对话框”模式打开时使用。

  • Fold messages in - 允许控制界面描述和界面控制器中的消息折叠。选中的话,消息键将替换为相应消息包中的实际值。

  • Message folding locale - 折叠(folding)消息时要使用的本地化消息文件。

5. Studio 功能

这部分文档描述了所有能帮助开发 CUBA 应用程序的 Studio 功能。主要是根据能在项目树中看到的项目元素组织相关信息。

5.1. 项目

本节介绍可用于管理项目基础设施的编辑器和命令。

5.1.1. 项目属性编辑界面

Project Properties 编辑界面允许对项目进行配置。可以从 CUBA 主菜单中打开它,也可以通过双击项目树的 Project > Properties 项来打开。

基本设置

Main 选项卡显示基本设置。

  • Module prefix 字段显示项目模块的名称前缀。后面加上模块的名称决定了项目攻坚的名称,比如 sales-global 模块装配成 sales-global-0.1.jar 工件。如果要重命名模块,可以修改模块名前缀。例如,使用 wages 模块名前缀的基本 CUBA 项目有 wages-globalwages-corewages-web 模块。

  • Artifact version 字段可以修改项目工件的版本。如果是 final build,可以不勾选 Snapshot,snapshot(快照版本)是可以被同名构建覆盖的版本。

  • Repositories 表格显示当前在项目中使用的仓库。Studio 扫描这些仓库以寻找可用的平台版本。使用该字段旁边的按钮配置对仓库的访问。有关详细信息,请参阅 文档。还可以在 build.gradle 中手动注册包含应用程序组件的其它仓库,并且仓库数量不受限制。

  • Platform version 选择平台的版本。如果选择了较新版本,则会根据需要决定是否会执行版本的自动迁移。

  • Show unstable versions 复选框可以选择显示不稳定的 CUBA 版本,是指带有 BETASNAPSHOT 的版本。

  • Groovy support 复选框可以在应用程序内启用 Groovy 代码,比如,在界面控制器类中。

  • 如果需要更改应用程序服务的路径,请在 Tomcat path 字段中指定新路径。下一次执行 gradlew deploygradlew start 会将 Tomcat 安装到该位置。

  • Tomcat ports 分组允许为通过 快速部署 安装在 deploy/tomcat 文件夹中的 Tomcat 应用程序服务分配非标准端口。

  • 需要特别留意 HTTP port 字段,该字段 Tomcat 监听的 HTTP 连接端口,以及 cuba.webPortcuba.webAppUrlcuba.restApiUrlcuba.connectionUrlList 应用程序属性。

  • AJP port 字段中,可以设置 AJP 连接器的端口。

  • Shutdown port 字段中,可以设置 Tomcat 监听的 SHUTDOWN 命令端口。

  • Debug port 字段中,可以设置 Tomcat 监听的 Java 调试器连接端口。如果更改了此端口,还应在 IDE 的调试配置中进行同步更改。

  • Available locales 字段允许设置应用程序可用的 本地化语言。单击该字段旁边的按钮打开语言环境编辑界面。位于编辑界面窗口中的 Locale select visible 复选框控制 cuba.localeSelectVisible 应用程序属性的值。 编辑界面还可以为 解析和格式化数据定义新的或覆盖已有的格式化字符串。

5.1.2. 项目依赖

Project Properties 对话框的 Dependencies 部分展示并管理项目的第三方依赖(库)。

dependencies

项目依赖在表格中按照模块分组展示,根据项目中选择模块的不同,一般有三个或更多的模块分组。 如果类库是添加到 global 模块,则在整个项目的范围内全局能用,因为其他的 CUBA 项目模块依赖于 global 模块。

表格中的 Type 列展示依赖的类型:

  • compile - 在编译和运行时使用的库

  • provided - 只在编译生产版本的应用程序时使用,不能包含在运行时的 classpath 中(比如 JDBC 驱动,Servlet API 的实现等。)

  • runtime - 只在运行时使用的库

  • testCompile - 在编译和测试时使用的库

  • testRuntime - 只在运行时测试使用的库

Text 列以 Gradle 依赖字符串的格式展示库的坐标:"group:name:version"

依赖管理的操作在依赖列表的右侧显示:

  • Add dependency - 添加新的项目依赖。指定 Maven 依赖声明或 Gradle 依赖坐标。对话框会自动验证依赖声明是否正确。

  • Remove dependency - 从项目中移除依赖。

  • Edit dependency - 修改依赖声明的内容。

参阅 Gradle 文档 了解更多关于第三方依赖的内容。

添加新的第三方依赖

添加新的第三方依赖需要以下步骤:

  • 找到需要类库的 Maven 依赖声明或者 Gradle dependency string for the required library.

newdep gradle
newdep maven
  • 复制依赖声明至剪切板

  • 打开 Project Properties 对话框

  • 选择需要添加依赖的模块,或者用 global 模块声明项目全局依赖。

  • 点击 Dependencies 表格右边的 + 按钮打开 Dependency Editor 对话框。剪贴板的依赖声明会自动粘贴到这里。

  • 点击 Dependency Editor 对话框的 OK 按钮,如果有声明验证错误的话,请手动修复。

  • 点击 CUBA Project Properties 对话框的 OK 按钮应用修改。Studio 会在项目的构建脚本添加必须的声明,并刷新项目配置。

  • 现在可以在代码中使用库中的类了。

Tip

Gradle implementation 'a.b.c' 依赖类型目前还不支持,请使用 compile 'a.b.c' 代替。

添加 JAR 文件依赖

有时您需要添加一个 JAR 文件作为项目的依赖,但是此文件不在任何公共的或内部的 Maven 仓库。此时,需要手动修改 build.gradle 脚本文件。

  • 在项目的根目录创建 lib 文件夹;

  • 将 JAR 文件复制到该文件夹,比如, <my-project>/lib/custom-lib.jar

  • 打开 Gradle 构建脚本:CUBA 项目树 → Build Scriptbuild.gradle

  • 修改 build.gradle 文件,为 repositories 部分添加 flatDir

    repositories {
        maven {
            ...
        }
        flatDir {
            dirs "${project.rootDir}/lib"
        }
     }
  • 修改 build.gradle 的 configure(globalModule) 部分,添加指定的 JAR:

configure(globalModule) {
    ...
    dependencies {
        compile(name: 'custom-lib')
    }
}
  • 刷新 Gradle 项目配置;Gradle 工具窗口 → Reimport All Gradle Projects

  • 现在可以在代码中使用该库的类。

5.1.3. 管理扩展插件

扩展插件是公共发布的全栈类库,用来对项目进行扩展使用其提供的附加功能。 可以参阅 CUBA 开发者手册 了解更多关于扩展和应用程序组件的知识。

CUBA Add-ons 对话框可以用来管理 CUBA 项目中引入的扩展插件。 可以通过下面的方式打开这个对话框:

  • 在 CUBA 项目树双击 ProjectAdd-ons

  • 从主菜单项: CUBAMarketplace…​

该对话框有三个标签页: MarketplaceInstalledUpdates

Marketplace 标签页

Marketplace 标签页展示发布的扩展中那些能与项目 兼容 的扩展插件。

addons market small

扩展按照类型分组。可以用过滤器查找需要的扩展,比如,"email" 或 "category:Translation"。

点击扩展的标题可以跳转到扩展的详情页,包括概览、兼容性、许可等信息:

addon details

如果需要安装扩展,可以在需要的扩展下点击 Install,然后点击 ApplyApply & Close 按钮。 在确认之后,Studio 会对项目的构建脚本和配置文件做必要的修改、下载新的库并刷新 Gradle 项目的配置。

使用坐标安装扩展

扩展的坐标其实就是 Gradle 的依赖字符串,即 "com.mycompany.cuba-addons:myaddon:0.1.5" 类型的串。这个字符串可以在 CUBA 平台的网站上发布或者扩展插件的作者自己发布。 如果该需要使用坐标(或使用 Gradle 依赖字符串)进行安装,点击 Updates 标签页标题右边的 "Install Add-on Manually" 图标:

addon by coords
Installed 标签页

Installed 标签页展示已经安装的关联到当前项目的扩展插件。

addons installed

已安装的扩展插件按照两种分类进行分组。 Marketplace Add-Ons 是从 CUBA 市场安装的扩展。 Custom Add-Ons 是由第三方开发、发布在第三方仓库或者 Maven 本地仓库的扩展。

如果要在项目中移除关联的扩展,可以选中相应的扩展点击 Delete,或者右键点击扩展,选择 Uninstall。 然后在弹出框选择 Apply。Studio 会从项目的依赖移除该扩展并更新项目的配置。

Updates 标签页

Studio 会自动检查项目中引入的扩展是否需要升级。 Updates 标签页显示可以升级的扩展的相关信息。

addons updates

如果要升级扩展,点击 Update 按钮,然后点击 ApplyApply & Close 按钮。 Studio 会自动升级依赖、下载需要的类库并更新项目配置。

另外,在打开项目之后,也会在界面的右下角显示可用的升级信息:

addon update notification

5.1.4. 模块管理

Studio 允许创建、编辑和删除项目的可选模块: coreguiwebweb-toolkitportalfront。可以使用 CUBA > Advanced > Manage Modules 主菜单或从项目树的 Project > Modules 项的右键菜单中执行此操作。

项目树的 Modules 部分显示项目中当前使用的模块。创建新项目时,默认包含 globalcoreweb。对于每个模块,Studio 也显示位于此模块中的配置文件。

5.1.5. 管理数据存储

主数据存储

Main Data Store Properties 窗口展示主数据存储的配置。 可以通过以下方式打开该窗口:

  • 在 CUBA 项目树双击 ProjectData StoresMain Data Store

  • 从主菜单点击: CUBAMain Data Store Settings…​

数据存储属性

下列属性可以为主数据存储和附加数据存储配置:

  • Define JDBC DataSource in - 决定使用哪个组件创建数据库连接池(需要项目基于 CUBA 7.2+)。可选值为:ApplicationJNDI

    • Application - 通过 CUBA 平台使用 HikariCP 库创建和管理连接池。推荐使用该模式。

    • JNDI - 通过应用程序服务器创建连接池并放入 JNDI。CUBA 应用程序使用 JNDI 名称从 JNDI registry 获取数据源。

  • Database type - 数据库服务的类型。Studio 开箱支持 PostgreSQLMicrosoft SQL ServerOracleMySQLMariaDBAmazon RedShift 以及 HSQLDB。如果需要,也可以集成其他数据库,参阅 本章节 了解细节。

  • Database URL - 指定主机、端口以及数据库名称。

  • Connection params - 指定其他连接参数。连接参数的格式依赖所选的数据库。字符串需要在数据库名称和参数之间包含一个分隔符。 比如,指定一个 Microsoft SQL Server 2008+ 实例名称,在该字段使用下列字符串:

    ;instanceName=myinstance

    可以使用 Connection params 字段旁边的 “铅笔” 按钮方便的输入连接参数。此时,Studio 会使用特定数据库的分隔符将参数组成连接串。

  • Custom database URL - 指定一个自定义的数据库连接 URL。这里需要提供 HostDatabase 名称,单独用于创建数据库。

  • Database userPassword - 数据库连接凭证。

  • Integrated Security - 当连接至 Microsoft SQL Server 2012+ 数据库时,启用相应的验证选项。

如果是 HSQLDB,Studio 本身会提供数据库服务,并将数据文件保存在 build/hsqldb 文件夹。

add store settings
附加数据存储

如需在项目中创建 附加数据存储,在 CUBA 项目树右键点击 Data Stores,选择 NewAdditional Data Store。 项目中注册的附加数据存储作为 Data Stores 部分的子项展示:

additional stores

右键单击附加数据存储,会弹出右键菜单:

  • Delete Data Store - 从项目中移除该附加数据存储

  • Edit Data Store - 打开对话框编辑附加数据存储设置

  • Generate Model…​ - 从选中的附加数据存储生成数据模型

创建或编辑附加数据存储时,会显示 Data Store 对话框,其带有以下字段:

  • Data store name - 数据存储的名称。只能包含字母和下划线,并且不能与项目名称相同。

  • Data store type - 数据存储的类型:RdbmsStoreCustom,参阅 文档 了解细节。

  • DataSource JNDI name - Studio 基于数据存储的名称自动设置。

  • 对于 RdbmsStore,需要指定下面描述的附加的属性。

数据库初始化和更新脚本

主数据存储 可以使用 数据库初始化和更新脚本 ,这些脚本显示在数据存储之下:

db scripts
  • Init 脚本包含重新创建数据库的 DDL 和 DML 语句,建立数据库以匹配当前的数据模型状态。

  • Update 脚本包含更新数据库的脚本,可以对之前任意状态的数据库进行更新,以匹配当前的数据模型状态。

Studio 会根据数据模型的更改自动维护初始化和更新脚本,阅读 数据库迁移 部分了解更多细节。

如果需要,也可以创建附加的数据库脚本。只需在 CUBA 项目树的 Data StoresMain Data Store 部分使用下面的操作:

  • init → 右键菜单 → NewDatabase init script

  • update → 右键菜单 → NewDatabase update script

new update script

5.1.6. 部署设置

Studio 中有一些与部署相关的编辑界面,用于对构建部署工件的 Gradle 任务进行设置。可以通过 CUBA > Deployment 主菜单打开这些编辑界面,也可以通过双击项目树中的 Project > Deployment 项来打开。

deployment settings
WAR 设置

WAR Settings 编辑界面允许设置 WAR 文件的构建配置。完成设置后,会在 build.gradle 中创建 buildWar 任务。

  • Build WAR - 如果选中,buildWar 任务会被配置在 build.gradle 中。

  • Include JDBC driver - 是否应将 JDBC 驱动程序包含在 WAR 文件中。

  • Single WAR for Middleware and Web Client - 是否构建将中间件和 Web 客户端应用程序 block 打包到一起的单个 WAR。

  • Custom web.xml path 指定用于单 WAR 的特定 web.xml 文件。单击 Generate 可自动创建此文件。

  • Logback configuration file - logback.xml 配置文件相对于项目根目录的路径。单击 Generate 以自动创建此文件。

  • 对基于 CUBA 版本 7.2 及以上版本的项目:

    • Custom data store configuration - 可以指定 WAR 工件要使用的自定义数据存储配置。

  • 对基于 CUBA 7.1 及以下版本:

    • Include Tomcat’s context.xml - 是否需要再 WAR 文件中包含 context.xml(Tomcat 部署描述文件)。

    • Custom context.xml path - 相对于项目根目录指定 context.xml Tomcat 部署描述文件。如果勾选了 Include Tomcat’s context.xml,则启用该配置。点击 Generate 自动创建该文件。

  • App properties - 要为此部署定义的一组应用程序属性。这些属性会添加到 WAR 内的 /WEB-INF/local.app.properties 文件中。

如果在设置中开启了相应的属性,则会显示 Build WAR 子元素。点击会执行 gradlew buildWar 任务。

Uber JAR 设置

UberJAR Settings 编辑界面允许对 Uber JAR 的构建进行设置。完成设置后,会在 build.gradle 中创建 buildUberJar 任务。

  • Build Uber JAR - 如果选中,buildUberJar 任务会被配置在 build.gradle 中。

  • Single Uber JAR - 如果选中,buildUberJar 任务会将所有应用程序模块打包到一起,创建一个 Uber JAR。

  • Logback configuration file - logback.xml 配置文件相对于项目根目录的路径。单击 Generate 可自动创建此文件。

  • 对基于 CUBA 版本 7.2 及以上版本的项目:

    • Custom data store configuration - 可以指定 UberJAR 工件要使用的自定义数据存储配置。

  • 对基于 CUBA 7.1 及以下版本:

    • Custom Jetty environment file - 嵌入式 Jetty 服务使用的 jetty-env.xml 配置文件路径,相对于项目根目录。单击 Generate 可自动创建此文件。

  • App properties -要为此部署定义的一组应用程序属性。这些属性将被添加到 Uber JAR 内的 /WEB-INF/local.app.properties 文件中。

  • Core port、 Web port、 Portal port 字段允许为相应应用程序块的嵌入式服务设置端口。如果选中 Single Uber JAR,这些字段就不设置了。默认端口值在 文档 中有描述。在运行 JAR 时可以使用 -port 命令行参数设置端口。

如果在设置中开启了相应的属性,则会显示 Build UberJAR 子元素。点击会执行 gradlew buildUberJar 任务。

5.2. 数据模型

在本节中,我们将介绍如何使用应用程序的数据模型。

5.2.1. 使用实体

创建新实体
  1. 在项目树中选择 Data Model 部分或它下面的包,然后从右键菜单中选择 New > Entity

  2. 出现 New CUBA Entity 对话框。在 Entity name 字段中输入实体类的名称,选择实体及其 ID 的类型。

  3. Studio 将创建实体类,根据实体类型的不同在 persistence.xmlmetadata.xml 中进行注册。创建的类会在源代码编辑界面中打开。编辑界面底部会显示三个选项卡:

    • Text 包含源码。

    • Designer 显示实体设计界面,可以使用图形界面配置实体及其属性,而不用编写 Java 代码。

    • DDL Preview 包含相应表及其参考约束的只读 DDL 代码。

创建实体属性

有多种方法可以向实体添加属性。

  • 使用实体设计器的图形化界面:切换到 Designer 选项卡,单击 Attributes 表下方的 New 并填写 New Attribute 窗口中的必填字段。

    Name 字段右边的地球仪按钮用于直接设置属性的用户友好名称。友好名称存储在 messages.properties 文件中,UI 组件默认使用这个文件来获取实体属性名称。如果为应用程序定义了多种语言,可以为所有语言指定本地化名称。

    attribute l10n
  • 使用从源码打开的独立窗口。在源码中将光标定位在最后一个字段下方,然后按下 Alt+Insert (Cmd+N)。在 Generate 菜单中,选择 Add Attribute。Studio 将显示 New Attribute 窗口,和从图形界面打开的一样。在代码编辑器的操作面板,也可以点击 Add attribute 按钮打开同样的窗口。

    new attribute 2
  • 还可以手动编写属性字段,生成 getter 和 setter 方法,然后在 Generate 菜单中选择 JPA Annotations,这样可以使用默认参数添加 JPA 注解。

Studio 可以帮助将新增的属性添加到为此实体创建的 UI 界面。将光标定位到包含该属性的行,然后按 Alt+Enter(Option + Enter)或单击灯泡图标并选择 Add entity attribute to screens

add attribute to screens

按 Enter 键,Studio 将打开一个对话框,其中包含使用了被编辑实体的界面列表。可以选择一个界面,Studio 会将该属性添加到此界面的相应 UI 组件中,例如添加到表格或表单中。

创建实例名称

可以用作另一个实体的引用属性的实体(例如 Customer 可以是 Order 的属性)需要一个模式(pattern)来生成实例的有意义的名称。此模式(pattern)由实体类上的 @NamePattern 注解定义。将光标定位在类名称上,即可在 Studio 中创建实体的名称模式,按 Alt+Enter(Option+Enter)并选择 Add name pattern(仅当实体没有 @NamePattern 注解时才显示此项):

create name pattern

按 Enter 键,Studio 将显示实体的所有属性列表。选择一个或多个属性,然后按 Enter 键。Studio 将在实体类上生成 @NamePattern

为新属性创建消息

手动创建新的实体属性时,其名称会高亮突出显示,以提醒在相应的消息包中创建用户友好的属性名称:

create message 1

在突出显示的属性上点击 Alt+Enter(Option+Enter),然后选择 Create message in the message bundle

create message
移除实体

要移除实体,使用 Safe delete 选项查找并清理对实体的引用:

remove entity

对实体的一些引用会被自动删除,比如在 persistence.xmlmetadata.xml 文件中对实体的引用。如果存在对实体的引用,将会弹出一个对话框显示这些引用。 点击对话框上的 View Usages 按钮, 可在 Find 工具窗口中查看这些引用,这时可以根据情况点击 CancelDo Refactor 按钮。

5.2.2. 使用枚举

Studio 提供一组操作和可视化设计器帮助在应用程序中使用 枚举

枚举与实体一并在 CUBA 项目树的 Data Model 部分展示。

创建新的枚举
  1. 在项目树中选择 Data Model 或者其下面的一个包名,右键点击后选择 New > Enumeration

  2. 弹出 New CUBA Enumeration 对话框。在 Class 字段输入枚举类的名称,选择包名,Id 类型(推荐 String)。

create enum
  1. Studio 将会创建枚举类,创建的类会在源码编辑器打开。编辑器的底部会显示两个标签页:

    • Text 包含源代码。

    • Designer 显示枚举设计器,这里可以使用图形界面配置枚举和值(常量),避免写 Java 代码。

enum designer

使用 Values 表格和关联的按钮设置枚举值常量。

  • Name 列用于输入代码中使用的常量名称。这个名称可以后期修改而不影响数据库已经存在的数据。

  • Value 列用于输入枚举常量的 id。这是数据库保存的实际值。

  • 地球按钮用于为选中的常量设置本地化名称(用户友好名称)。

设计器也提供将枚举的 Id type 从 String 修改为 Integer(或反过来)的功能。只需要打开枚举设计界面然后切换 Id type 的值。Studio 会自动在代码中对使用该枚举的地方做代码迁移。之后,您可以修改已有的枚举常量。注意,这种改动不会对数据库表格已存在的枚举值做改动,需要手动做数据迁移,比如可以通过一个数据库的更新脚本来实现。

5.2.3. 使用视图

要为实体创建新的 视图,请在项目树中选择实体,然后在右键菜单中点击 New > View

create view

视图设计界面会被打开。它包含以下字段:

  • Entity name - 要创建视图的实体的名称。

  • Name - 新视图的名称。

  • Extends - 内置或自定义视图,新视图会扩展其属性。任何实体都有三种内置视图:

    • _local 包含实体的所有本地属性(不引用其它实体的属性),

    • _minimal 包含名称模式中列出的属性,

    • _base 包括所有本地非系统属性和由 @NamePattern 定义的属性(实际上是 _minimal +_local)。

  • Configuration file - 用于存储此视图的 视图配置文件。默认情况下,Studio 在 global 模块中生成一个 views.xml 文件。

当前实体的完整属性列表显示在字段下方的树中。可以通过选中属性前面的复选框来选择要包含在视图中的属性。

如果视图继承另一个视图,则会选中所有继承的属性,并禁用相对应的复选框。

如果选择引用属性,则右侧面板中会显示以下属性:

  • Entity - 引用的实体名称。

  • View - 加载引用实体的可选视图。建议使用已命名视图而不是临时指定视图属性,因为这样可以更容易地维护复杂视图。此外,即使指定了视图名称,仍然可以通过选择属性树中的复选框来添加视图中未包含的属性。

  • Fetch - 用于引用属性的可选设置,指定如何从数据库中获取相关实体。有关详细信息,请参阅 文档

单击 OK 关闭设计界面后,可以在实体下的项目树中找到新视图:

create view 2

如果双击项目树中的视图项,Studio 将在代码编辑界面中打开 views.xml 并将光标定位在视图定义上。代码编辑界面底部有两个选项卡:TextStructure。后者显示此配置文件中定义的视图列表。

在 XML 中编辑视图定义时,使用 Ctrl+Space 自动完成属性名称:

view edit 1

要留意高亮突出显示的属性,它们很有可能不存在:

view edit 2

可以通过多种方式打开视图的图形设计界面:

  • 在项目树中选择视图,然后单击 Edit View 右键菜单项。

  • 将光标定位在配置文件代码中的视图元素上,按 Alt+Enter(Option+Enter),在弹出菜单中选择 Edit view,然后按 Enter 键。

  • 切换到配置文件代码编辑界面的 Structure 选项卡,选择视图并点击 Edit 按钮。

5.2.4. 数据库迁移

Studio 能够创建 DDL 脚本,以使数据库架构与项目的数据模型保持同步。生成的脚本可以从 Studio 直接执行,也可以由 Gradle 任务 执行,还可以在应用程序本身 启动时 执行。

要生成 DDL 脚本,请在主菜单中单击 CUBA > Generate Database Scripts,或在项目树中选择 Data Model,然后在右键菜单中单击 Generate Database Scripts

Studio 将打开 Database Scripts 窗口,窗口上有以下选项卡:

Updates

Updates 选项卡上显示出用来将数据库更新为数据模型当前状态的脚本。更新脚本保存在 modules/core/db/update 目录。这些脚本具有自动生成的名称,通过前缀定义执行顺序。包含 DROP 语句的脚本以红色突出显示。

可以通过单击 Create 按钮添加任意脚本,添加的脚本后续将与自动生成的脚本一起保存并执行。

单击 Remove 按钮可以编辑或完全删除新生成的脚本。

如果单击 Exclude selected(排除),这时会两个选项:

  • 将脚本移动到手动执行的脚本目录:modules/core/db/update-manually。然后当运行 Update database 时,脚本不会自动被执行,但可以在需要时手动运行它。此选项对于用于删除先前重命名为 *__UNUSED 的表或列的脚本非常有用。

  • 排除脚本:排除的脚本不会保存到 modules/core/db/update 目录中,而是记录在项目文件夹中的 studio-intellij.xml 文件中。再次生成脚本时,Studio 将忽略与排除脚本相对应的更改。这样就允许数据库架构和实体模型之间存在差异。

    例如,可能希望在对应项目实体的一个表中添加数据库字段,但不将其映射到实体属性。当 Studio 生成了从数据库中删除该字段的脚本时,只需将其排除,Studio 将不再生成同样的脚本。

Init Tables

执行 Create Database 时,Init Tables 脚本会在 Init constraintsInit data 脚本之前执行,并创建所有的表。开发人员可以编辑脚本,但要需要保留分隔表的注释。该脚本保存在 10.create-db.sql 文件中。

Init Constraints

Init Constraints 脚本在 Init tables 脚本之后执行,创建完整性约束。开发人员可以编辑该脚本,但需要保留分隔表的注释。该脚本保存在 20.create-db.sql 文件中。

Init Data

Init Data 脚本允许插入额外的数据或数据模型中不存在的数据结构信息。在初始化结束时执行。该脚本保存在 30.create-db.sql 文件中。

如果项目包含应用程序组件(扩展),但是此组件不为当前数据库提供 DDL 脚本,Studio 会为组件生成脚本,并在 Init {component} tablesInit {component} constraints 选项卡中显示。脚本分别保存在 01.{component}-create-db.sql02.{component}-create-db.sql 文件中。

单击 Save and close 以保存所有生成的脚本。可以在 Project > Data Stores > Main Data Store 项目树部分中找到脚本。

要运行更新脚本,先停止应用程序服务器(如果在运行),然后从 CUBA 主菜单执行 Update Database。如果要使用初始化脚本从头开始重新创建数据库,请执行 Create Database

5.2.5. 生成数据模型

Studio 允许为现有数据库创建数据模型和标准 UI 界面。单击 CUBA > Advanced > Generate Model 主菜单项或在项目树中选择 Project > Data Stores,然后在右键菜单中点击 Generate Model。如果有多个数据存储,Studio 会显示一个对话框,可以选择其一。

然后 Studio 打开 Generate Model from Database 向导。

步骤 1

这是模型生成向导的第一步。

generate model step1

可选步骤:单击 Settings 以设置创建的新实体的 Java 包位置以及实体的系统属性与数据库列的默认映射。

例如,如果数据库中的所有或大多数表包含 ModifiedModifiedBy 列,则可以将它们映射到被创建的实体的 Updatable.updateTsUpdatable.updatedBy 属性。在这种情况下,无需为每个表单独映射它们。

使用 Exclude columns from mapping 列表可以为所有表设置不需要映射到属性的列。

向导中会列出在项目数据模型中没有对应实体的表。可以使用上面的过滤器字段按名称查找表。

选择要映射到数据模型的表。某些表通过外键依赖于其它表,因此当选择这些表时,它所依赖的所有表也将被选中。如果取消选择一个表,则也会取消选择所有依赖它的表。

可以通过单击右侧的复选框来选择或取消选择所有可用表。

单击 Next

步骤 2

在此步骤中,可以查看和编辑为所选表的自动生成的映射。

generate model step2

Status 列描述自动映射的结果:

  • OK - 自动映射成功,所有列都映射到新实体。

  • Join table - 识别出实体之间的关联,会被映射为多对多关系的连接表。

  • There are unmapped columns - 某些列无法映射到新实体。

  • New PK will be created - 该表没有主键。将创建一个新的 UUID 类型的主键。

  • Composite PK will be replaced - 该表具有复合主键,但没有其它表引用它。复合主键将被替换为 UUID 类型的主键。

  • Composite PK referenced by other tables - 该表有一个复合主键,一些表引用它。Studio 无法映射此类表。

  • Unsupported PK type - 该表具有不支持的主键类型。Studio 无法映射此类表。

  • Choose primary key for DB view - 它是一个数据库视图,应该选择适合作为实体标识符的一列或一组列。在这种情况下,单击 Choose PK 按钮并选择主键的列。

Refresh mapping 按钮允许重新运行所选表的自动映射。例如,可以切换到数据库 SQL 工具,对数据库架构进行一些更改,然后返回到向导并再次执行映射过程。

Edit mapping 按钮打开一个包含映射详细信息的对话框窗口。在这里,可以更改实体名称和实体类要实现的系统接口。根据实现接口的不同,为了兼容 CUBA 的实体,会影响数据库列的创建数量。

generate model step2 2

当选中的是数据库视图并且需要选择用于实体标识符的列时,将显示 Choose PK 按钮而不是 Edit mapping

通过单击 Back,可以返回到上一步以选择或取消选择表。

单击 Next 转到下一步。

步骤 3

在此步骤中,可以指定应为新实体创建哪些 UI 界面。

generate model step3

如果取消选中 Create standard screen 复选框,Studio 将不会为新实体生成 UI。

使用 In modulePackageMenu 字段指定界面源代码的位置以及在主菜单中它们的显示位置。

使用 Standard screens 列中的下拉列表选择要生成的界面类型。

可以安全地跳过此步骤,并在完成模型生成过程后为实体生成 UI 界面。

单击 Next 转到下一步。

步骤 4

这是模型生成向导的最后一步。

Import scripts 表包含将在数据库上执行的脚本列表,查看这些脚本,以确认其符合要创建的实体。

在此之前,项目中不会创建任何内容,甚至也不会保存到磁盘中。Studio 实际上只会在点击 Run all scriptsRun script 时生成实体和界面并保存脚本。

可以在此页面上查看和编辑脚本,然后运行它们,或者仅保存脚本,稍后通过数据库管理工具来运行。导入脚本保存在 modules/core/db/import 目录中。

5.2.6. 集成自定义数据库

文档 中所述,框架允许使用 EclipseLink ORM 支持的任何 DBMS 作为项目数据库。Studio 可以帮助创建此类集成所需的文件。

在菜单中选择 CUBA > Advanced > Define Custom Database

在打开的窗口中可以设置新自定义数据库的属性。根据这些属性,Studio 会针对数据库生成设计时和运行时的支撑代码。

  • DB type id - 用于 cuba.dbmsType 应用程序属性的数据库类型标识符。

  • DB type name - 要在 Studio 中显示的数据库类型的用户友好名称。

单击 OK 后,Studio 会在 com.haulmont.cuba.core.sys.persistence 中生成 Java 类,并在项目的 com.haulmont.studio.db.{db_id} 包中生成 Groovy 类。自动生成的示例实现适用于 Microsoft SQLServer 数据库,需要适当地对其进行一些修改。

首先,修改 com.haulmont.studio.db.{db_id}.{db_id}DbProperties 类。当此类适配了新的数据库时,将能够在 Studio 中将项目切换到此数据库。重新打开项目在数据库类型下拉列表中查看新数据库。

要在运行时连接到新数据库,请修改 com.haulmont.cuba.core.sys.persistence 包的 {db_id}DbmsFeatures{db_id}DbTypeConverter 类。{db_id}SequenceSupport 类仅用于生成整数标识符和唯一编号。

最后,修改 com.haulmont.studio.db.{db_id}.{db_id}DdlGenerator 类,以便在需要时可以由 Studio 正确生成 initupdate 数据库脚本。如果不需要为此数据库生成 DDL 脚本,可跳过此步骤。

如果将自定义数据库用作主数据存储,则在生成数据库脚本时,Studio 将为所有应用程序组件(包括 CUBA)创建 init 脚本。这些脚本不包含一些必须的初始化数据,因此必须将以下内容添加到项目的 Init data 脚本中(30.create-db.sql):

insert into SEC_GROUP (ID, CREATE_TS, VERSION, NAME, PARENT_ID)
values ('0fa2b1a5-1d68-4d69-9fbd-dff348347f93', current_timestamp, 0, 'Company', null)^

insert into SEC_USER (ID, CREATE_TS, VERSION, LOGIN, LOGIN_LC, PASSWORD, NAME, GROUP_ID, ACTIVE)
values ('60885987-1b61-4247-94c7-dff348347f93', current_timestamp, 0, 'admin', 'admin',
'cc2229d1b8a052423d9e1c9ef0113b850086586a',
'Administrator', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', 1)^

insert into SEC_USER (ID, CREATE_TS, VERSION, LOGIN, LOGIN_LC, PASSWORD, NAME, GROUP_ID, ACTIVE)
values ('a405db59-e674-4f63-8afe-269dda788fe8', current_timestamp, 0, 'anonymous', 'anonymous', null,
'Anonymous', '0fa2b1a5-1d68-4d69-9fbd-dff348347f93', 1)^

5.3. 中间层

项目树集中在一个地方显示所有中间层服务和托管 bean。在下面的章节中,我们将介绍如何创建新服务和 bean。

5.3.1. 创建服务

服务 是容器管理的组件集,它们构成中间层边界并为客户端层提供接口。服务可以包含业务逻辑本身,也可以将执行委托给托管 Bean

要创建新服务,请选择 Middleware 项目树区域,然后在右键菜单中单击 New > Service

create service

输入服务接口的名称时,将自动生成相应的 bean 名称和服务名称常量:

create service 2

之后,将在 global 模块中创建服务接口,并在 core 模块中创建其实现。此外,新服务将自动注册在 web-spring.xml 配置文件中。

可以从代码编辑器边栏上的标记轻松地从接口切换到服务 bean 并返回:

service interface

一旦在服务接口中创建了方法,Studio 检查器就会建议在 bean 类中进行实现:

service interface 2

5.3.2. 创建托管 Bean

Studio 在项目树的 Middleware > Beans 部分显示中间层(包括实体和事务监听器)的所有 托管 Bean

studio beans

要在 core 模块中创建托管 bean,选择项目树的 MiddlewareBeans 节点,并在右键菜单中选择 New > Bean

create bean

当输入 bean 类名的时候,会自动生成对应的 bean 名称。

也可以在项目的其他模块中手动创建托管 bean:在项目树中选择一个包,右键菜单中点击 New > Java Class。然后按照上面例子所示,为类添加 @Component 注解。为了尽量避免命名冲突,特别是如果在开发一个应用程序组件,需要在注解中提供一个 bean 的特殊名称。

5.3.3. 创建事件监听器

事件监听器是指,在 Spring bean 中,有一个或者多个监听器方法,接收 Event 对象作为参数,并包含对该事件响应的代码。可以在 开发者手册 中了解更多关于事件和事件监听器的内容。

Studio 可以为多种应用程序事件创建监听器的脚手架代码:

可以生成新的监听器类或者为已有的类添加监听器。

新建监听器类

要创建新的监听器类,在 CUBA 项目树的 Middleware 部分点击右键,选择 NewEvent Listener 条目。

create event listener

对话框中可以选择监听器类所在的模块。事件监听器可以位于 web 模块,但是此时只有有限的事件可以使用。选择事件类型,按照向导提供所需的参数并点击 Finish 按钮生成类代码。

为已有类添加监听器方法

打开已有的 Spring Bean,在代码编辑器顶部的操作面板点击 Subscribe to event

add listener method

5.4. 通用 UI

Studio 提供了许多有助于在应用程序中使用 通用 UI 的功能。

在项目树中,可以看到 Generic UI 的以下元素:

  • Web Menu 打开主菜单的图形编辑界面。

  • Main Message Pack 部分包含主菜单项和通用 UI 元素的消息。

  • Screens 部分显示已有的应用程序界面。

  • Themes 用于管理应用程序的可视化展现。

5.4.1. 创建和移除界面

要创建新的 Generic UI 界面,请在项目树中选择 Generic UI,然后在右键菜单中选择 New > Screen。如果要为实体创建 CRUD 界面,请在项目树中选择此实体或其中一个视图,然后在右键菜单中点击 New > Screen

create screen

Studio 将显示可用模板的列表。该列表分为两部分:Screen TemplatesLegacy Screen Templates。 前者包含框架版本 7 以上可用于新界面 API 的模板,而后者包含也可用于版本 6 的界面模板。

create screen 2

如果为在项目树中选中的实体或视图创建界面,则 EntityEntity view 字段会自动填充:

create screen 3

Advanced 部分允许修改自动生成的界面描述和控制器名称以及界面 ID。当某个实体有多个界面时,这很有用。

单击 Finish 时,将创建并打开界面 XML 描述和 Java 控制器文件。对于没有使用 UiDescriptor 和/或 @UiController 注解的旧版界面,其界面描述被注册在 web-screens.xml 文件中。

移除界面文件时,使用 Safe delete 选项查找并清理对这个界面的引用:

safe delete screen 1

对界面的一些引用会被自动删除,比如在 web-menu.xmlweb-screens.xml 文件中对界面的引用。如果存在对界面的引用,将会弹出一个对话框显示这些引用。 点击对话框上的 View Usages 按钮, 可在 Find 工具窗口中查看这些引用,这时可以根据情况点击 CancelDo Refactor 按钮:

safe delete screen 2

5.4.2. 使用界面描述

界面 XML 描述 编辑器与 Screen Designer 集成在一起。界面设计器展示一组操作面板和工具窗口,可以用来开发界面的布局并以所见即所得的形势设置 UI 组件的属性。您可以直接编辑 XML 或使用设计器的面板生成代码。

Screen Designer 由下列元素组成:

  • Source code editor - 展示并编辑 XML 源码。

  • Top actions panel - 提供一些便于访问的操作。

  • Layout preview panel - 展示交互式的界面布局架构。

  • Component Hierarchy - 以层级树的形势展示界面元素。

  • Component Palette - 展示可以添加到当前界面的组件。

  • Component Inspector - 展示并编辑组件的属性和事件处理器。

Tip

界面设计器面板和工具窗口只有购买了 CUBA Studio 商业订阅才能使用。

screen designer
顶部操作面板

操作面板位于代码编辑器的顶部。提供下列操作的访问:

  • Controller - 导航至界面控制器。

  • <entity class name> - 如果当前界面是实体浏览器或者编辑器时会显示。可以导航至关联的实体。

也可以用侧边栏的标记在界面描述和其控制器之间切换。

工具窗口

Component HierarchyComponent PaletteComponent Inspector 面板是 IDE 中独立的工具面板。当在编辑器打开界面描述时,会自动打开这些工具窗口。如果在编辑器中切换界面描述文件,工具窗口的内容也会同步更新。有时候,当打开其他工具窗口时(比如 Gradle、Persistence 等),设计器的某些窗口会被隐藏,可以通过点击 IDE 窗口左右的相应按钮重新打开。

保留在左下角展示 Component Inspector 是为了满足熟悉之前布局的开发者们。如果需要将该面板移至右侧,点击面板标题的 Move to Right Bottom 即可。

设计器面板会在编辑 XML 代码时激活。熟练开发者们通过编辑 XML 源码切换和修改界面描述,他们现在也能获得界面设计器的编辑功能帮助。可以从工具箱拖拽新组件至层级树,当编辑器只显示源码时,也可以在左下角的探查面板修改组件的排序和编辑组件属性。源码会直接同步所有改动。

布局预览面板

Layout Preview - 布局预览面板 展示交互式的界面布局架构。与界面描述的源码编辑面板共享编辑器的空间。现在在界面描述的右上部添加了四个按钮用于切换界面预览模式:

  • Editor only - 在编辑器只显示源码。

  • Editor and Preview - 编辑器空间分割,包含源码和预览。

  • Preview only - 只显示预览。

  • Preview in Window - 源码在编辑器展示,但是预览通过单独的窗口展示,可以将预览窗口移至其他显示设备。

layout preview modes

面板在右上角有一些控制按钮:

layout preview controls
  • 100% x 100% 下拉框可以选择固定的 画布大小。画布的大小可以比预览面板大,此时会添加额外的滚动条。例如,如果在开发一个复杂的界面,带有很多控制组件,如果想预览,可以选择 1920 x 1080 画布大小,然后查看布局在大屏上如何展示。

  • Refresh 按钮重新加载预览界面的内容。

  • Zoom InZoom OutZoom Reset 按钮更改预览界面的缩放。

  • 最右边的按钮展示自动界面布局问题检测的结果。移动光标至这个图标可以看到发现的问题。

Layout Preview 面板中,也可以排布组件以达到需求的布局。组件可以用控制进行缩放和对齐:

  • 水平延展,

  • 垂直延展,

  • 水平、垂直对齐组件。

layout component controls
组件工具箱

Component Palette 工具窗口展示在 IDE 的右下角。显示可用的界面组件:

  • Containers - 容器;

  • Components - 组件;

  • Data Components - 数据组件:containers - 数据容器 和 loaders - 数据加载器;

  • Non-visual - 非可视化组件:actions - 操作、 dialog mode settings - 对话框模式设置,timers - 定时器以及其他辅助的界面元素;

  • Main window - 主窗口: 主界面特定的组件。

可以通过在搜索框输入名称的方式在工具箱搜素组件。

要在布局中添加一个组件,可以直接从工具箱拖拽组件至 Component Hierarchy 面板。

在工具箱右键点击组件,可以使用下列操作:

  • Add to Design - 添加选中的组件至界面,放置位置通过在层级树中选中元素决定。

  • CUBA Documentation - 打开组件在开发者手册中的文档页。

component palette
组件层级树

Component Hierarchy 工具窗口展示在 IDE 的右上角。以树的方式展示布局中的组件结构。

可用拖拽的方式修改树中元素的位置。

右键点击层级树中的元素,可以使用下列操作:

  • Convert 将组件转换为类似的其他组件。

  • Wrap 将组件放入建议的容器中。

  • Go to XML - 切换至源码中相应的 XML 标签。

  • Inject 将元素注入界面控制器或者导航至已经注入的声明。

  • DeleteCopyCut Paste 删除、复制、剪切、粘贴组件。

  • CUBA Documentation 打开选中组件的文档。

component hierarchy
组件探查

Component Inspector 工具窗口显示在 IDE 的左下角。展示并编辑选中组件的属性:

  • Properties 面板展示可视化组件的属性。

  • Handlers 面板展示可以与选中组件关联的事件监听器和组件委托。如要生成所需的处理器方法,只需双击相应的条目。

可以在搜索字段中输入文字快速定位属性:

component inspector

对于某些选中的元素会显示 + Add 按钮,提供添加子元素的一个快捷方法,比如添加表格操作、列、表单字段。如果所选组件是:

  • TableGrid 或其操作和列之一 - 可用:AddColumn, AddGroup, AddAction

  • Form 或其列和字段之一 - 可用:AddColumn, AddField

  • DataLoadCoordinator - 可用:AddonScreenEvent trigger 以及其它触发器

component inspector add button
源码检查

Studio 会检查界面布局是否存在错误和不一致,并且检查内部和外部引用。出现下列情况,会用警告或高亮显示 XML 元素的方式进行提醒:

  • 由于 XML 错误,无法组装界面布局。

  • 组件属性路径和名称与应用程序数据模型不对应。

  • 组件大小冲突: widthheightexpand 属性值的冲突。

  • dataContainerdataLoader 属性没有引用任何现有的数据容器或数据加载器。

  • form 中的字段没有显式定义 property XML 属性:此时,id 将被隐式地用作 property

  • form 元素语义错误:字段重复或位于 column 元素之外。

  • gridLayout 中的列数与指定的数字不匹配。

  • 在扩展界面中出现重复的元素属性,比如父界面和扩展界面中同时定义了完全一样的属性时。

  • 扩展界面中的元素的命名与父界面中不同,或者放置位置不正确。

  • messagesPack 属性指定的值不是一个有效的包,这个包要至少包含一个 messages_xx.properties 文件。

  • 过时的 XSD 引用。

  • id 值在界面内不是唯一的。

  • 其它问题。

可以在 Settings 窗口中配置 CUBA 检查器(CUBA > Settings > Editor > Inspections)。

源码意图和生成菜单

意图操作(Intention action)是一个上下文敏感的操作,开发者可以在源码编辑器通过按下 Alt+Enter(Option+Enter)调用。意图操作可以帮助代码重构、代码生成、导航和其他任务。可以在 https://www.jetbrains.com/help/idea/intention-actions.html 阅读更多关于意图操作的内容。

Generate - 自动生成 菜单包含上下文敏感的操作,可以帮助生成各种代码结构。可以通过按下 Alt+Insert(Cmd+N)调出。参阅 https://www.jetbrains.com/help/idea/generating-code.html 了解更多。

Studio 中包含的意图和生成菜单条目提高了使用界面组件的效率。使用 Alt+Insert(Cmd+N)和 Alt+Enter(Option+Enter)查看对于特定 UI 和数据组件的功能。

  1. 例如,要为 表单 组件添加一个新字段,可以将光标移入 form 元素然后执行下列操作的一项:

    • 按下 Alt+Insert (Cmd+N),选择 Add field,然后选择 property 属性的值,

      gui Form add
    • 输入 field 然后按下 TAB 键,然后选择 property 属性的值。

      gui Form add tab
  2. 另一个例子是为一个组件添加新的本地化语言标题。可以在源码中输入还未创建的消息键值。则引用的元素会高亮红色。然后按下 Alt+Enter(Option+Enter)并选择 Create message in the message bundle

    intention add localized message

5.4.3. 使用界面控制器

本节介绍 Studio 为 界面控制器 提供的功能。

利用源码编辑器的边栏图标可以快速切换到相应的 XML 描述文件、定位到注入组件的 XML 定义以及其它导航功能。

controller
顶部操作面板

操作面板位于控制器代码编辑器的顶部。展示下列操作:

  • <entity class name> - 切换至当前浏览界面或者编辑界面关联的实体。

  • Descriptor - 切换至对应的界面描述文件

  • Main Menu - 可以将当前界面加入主菜单或者切换至主菜单配置

  • Inject - 帮助在控制器类中注入依赖,下面有详细介绍

  • Subscribe to Event - 可以订阅各种事件,下面有详细介绍

  • Install Delegate - 可以生成组件的委托,下面有详细介绍

依赖注入

依赖注入是在界面控制器代码中获取对可视化组件和 API 端点(api endpoint)的引用的主要方式。当然,也可以编写所需类型的字段并手动进行注解。但是 Studio 提供了一个专用的窗口,这个窗口允许从列表中选择一个对象并自动创建合适的字段。窗口可以通过下列方式打开:

  • 点击顶部操作面板的 Inject 操作,

  • 按下 Alt+Insert(Cmd+N)键,在弹出的 Generate 菜单中选择 Inject…​

controller injection

以下对象可以被注入到控制器中:

  • 界面 XML 描述中定义的可视化组件和数据组件,

  • 界面 API 接口,

  • 基础设施接口,

  • 中间层服务,

  • 项目中定义的其他 Spring bean,

  • 配置接口,

  • SLF4J Logger 实例。

事件处理

通过创建事件处理程序,可以在界面生命周期的各个点执行代码并对用户操作做出响应。处理程序是一个用 @Subscribe 注解的控制器方法,使用事件作为输入参数。通过下列方式创建:

  • 点击顶部操作面板的 Subscribe to Event 操作,

  • 按下 Alt+Insert(Cmd+N)键,在弹出的 Generate 菜单中选择 Subscribe to Event

subscribe dialog

每个事件在窗口右侧都提供了描述,这个描述是从事件的 Javadoc 中提取的。

打开的窗口中提供以下事件:

  • 表示界面生命周期的控制器事件。

  • 可对按钮点击、表格选择、操作等做出响应的组件事件。

  • 表示此界面的外部框架的生命周期的框架事件(Frame Events)。

  • 允许对数据上下文更改做出响应,并在数据提交之前和之后执行代码的数据上下文事件。

  • 允许接收有关数据容器和实体状态更改通知的数据容器事件。

委托

使用委托,可以为各种界面机制提供代码来代替其标准实现。例如,可以提供自己的函数来提交数据或选择表格行的图标。

委托是具有特定签名的控制器方法,并使用 @Install 进行注解。通过下列方式添加:

  • 点击顶部操作面板的 Install Delegate 操作,

  • 按下 Alt+Insert(Cmd+N)键,在弹出的 Generate 菜单中选择 Install Delegate:

install dialog

每个委托都在窗口右边提供了描述,该描述是从框架的 Javadocs 中提取的。

5.4.4. 使用应用程序菜单

菜单设计器允许定义应用程序主菜单并将其存储在 web-menu.xml 配置文件中。Structure 选项卡显示图形设计器,可以在 Text 选项卡上编辑菜单的 XML 代码。

web menu

菜单可以以两种模式创建:

  • Single mode 中,菜单仅包含当前项目的 web-menu.xml 文件中的菜单项。在这种情况下,需要创建所有菜单项,必要时还需要将应用程序组件中的菜单项也定义进来,这种方式有点麻烦,但好处是可以完全控制菜单结构。

  • Composite mode 中,菜单除了包含当前项目的 web-menu.xml 中的菜单项,还包含所有应用程序组件的菜单配置文件中的菜单项。这种模式可以很方便地包含所有继承的菜单项,可以在菜单结构的任何位置插入当前项目需要的菜单项。继承的菜单项不能被修改。

    此外,在 Text 选项卡上,可以为菜单项定义 insertBeforeinsertAfter 属性。这两个属性定义了当前菜单项的插入位置。在 Composite 模式下,这两个属性有助于将当前项目菜单项与继承的应用程序组件菜单项组合在一起。

    例如,如果要将当前项目的菜单结构放在 Administration 菜单项的左侧,可以为当前项目的菜单树的根菜单项设置属性 insertBefore="administration"

菜单配置文件列表通过 cuba.menuConfig 应用程序属性定义,选择菜单模式时会更新此属性。

要添加菜单项,选择已有的菜单项(或配置文件以创建顶级菜单),然后单击 +。菜单项编辑窗口会在模式窗口中打开。

可以创建以下类型的菜单项:

Screen - 界面
web menu create

用于打开应用程序界面的菜单项。

应该为 Screen 项指定以下属性:

  • Screen - 这个菜单项打开的界面的非唯一 ID。

  • Id - 为菜单项指定任意唯一 ID。

  • Open type - 定义界面打开的方式,可以在新的选项卡打开,或者以模态窗的方式打开(NEW_TABDIALOG)。默认使用 NEW_TAB

  • Shortcut - 用于打开界面的快捷键。可选的组合键(ALT、CTRL、SHIFT)用“-”分隔,例如 ALT-C。

  • Style name - 定义菜单项的样式名称。有关详细信息,请参阅 主题

Menu - 菜单
web menu create 2

包含其它菜单项(子菜单)的菜单项。

需要为 Menu 项指定以下属性:

  • Id - 为菜单项指定任意唯一 ID。

  • Style name - 定义菜单项的样式名称。

Bean
web menu create 3

调用 托管 Bean 方法的菜单项。

需要为 Bean 项指定以下属性:

  • Id - 为菜单项指定任意唯一 ID。

  • Bean - 可以通过 AppBeans 获取到的 bean 的名称(例如 cuba_Messages)。

  • Bean method - 要调用的 bean 的方法名称。

  • Shortcut - 用于方法调用的快捷键。可选的组合键(ALT、CTRL、SHIFT),用“-”分隔,例如 ALT-C。

  • Style name - 定义菜单项的样式名称。

Class - 类
web menu create 4

执行给定类的 run() 方法的菜单项。

需要为 Class 项指定以下属性:

  • Id - 为菜单项指定任意唯一 ID。

  • Class - 一个类的完全限定名,这个类需实现 Runnable 接口。

  • Shortcut - 用于方法调用的快捷键。可选的组合键(ALT 、CTRL 、SHIFT),用“-”分隔,例如 ALT-C。

  • Style name - 定义菜单项的样式名称。

Separator - 分隔符

分隔菜单项的水平线。

5.4.5. 使用主题

Studio 可以帮助在项目中创建 主题 扩展和自定义主题。

theme extension

创建主题扩展或自定义主题时,会创建特定目录结构并修改 build.gradle 文件。

创建的主题会显示在项目树的 Themes 部分中。

halo ext

扩展或创建主题后,可以在 SCSS 文件或可视化编辑器中手动修改其变量: 在新主题的右键菜单中,选择 Open Variables File。此文件也可以通过 CUBA 主菜单:选择 Advanced > Manage themes > Edit theme variables

theme variables

6. 与 IntelliJ IDEA 终极版集成

IntelliJ IDEA Ultimate Edition(终极版)是商业 IDE,包含了很多对开发 CUBA 应用程序有用的附加功能:支持 CSS、JavaScript、JPA、Spring、Docker、数据库访问等等。

在终极版中,CUBA Studio 也可以与普通插件一样进行安装。并且能集成一些终极版的功能提升开发体验。

6.1. 关闭有冲突的功能

有些 Studio 的功能会跟 Intellij 终极版或者第三方插件的功能冲突。

比如,为了避免 CUBA Studio 提供的侧边栏图标和 IDEA 终极版中 Spring 插件图标的冲突,可以按照下面的步骤:

  • 在 IDEA 菜单中选择 Settings > Editor > General > Gutter Icons

  • 反选 Injection pointsProducers for Disposer methods 选项,

  • 应用更改。

6.2. 启用 JPA 支持

对 JPA (Java Persistence Annotation) 的支持通过 Java EE: EJB、JPA、Servlets 插件提供。

Warning

下面描述的功能不在标准的 CUBA Studio 或者 IntelliJ IDEA 社区版中提供。

JPA 支持提供以下功能,对于开发 CUBA 应用程序能提供帮助:

  • JPQL 语法高亮、自动补齐以及语法检查,

  • JPA 控制台(基于 CUBA 7.1+ 的项目),

  • 实体源码中的代码检查,

  • 实体关系图,

  • 其他功能,参阅 JetBrains 网站.

如需使用这些功能,在项目中做以下配置:

  • 为主数据存储配置数据源(Data Source)

  • 为所有的项目模块添加 JPA 切面

Studio 支持快速配置以上几点。下面的介绍是针对 IDEA 2019.2 版本的。

6.2.1. 配置数据源

可以通过 IDE 右侧的 Database 工具窗手动设置数据源。Studio 在项目打开时提供了自动数据源检测:

datasource notification

如果不小心错过了这个消息提示,也可以通过 Event Log 工具窗口访问记录的消息,只需点击屏幕右下角的事件日志按钮即可打开。

点击 Configure 打开已经预填写的 Data Sources and Drivers 对话框。

add ds dialog

数据源检测机制会根据主数据存储的设置自动发现配置参数,用来填写驱动和其他连接相关属性。但是也可以手动在 "Data Sources and Drivers" 窗口配置数据库驱动:

  • 点击对话框底部的 Download missing driver files 连接,驱动文件会自动下载。

  • 点击 Test Connection 测试自动发现的连接参数是否正确。如果需要可以修改参数。

  • Save 字段的值设置为 Forever。否则 IDE 重启之后会不记得密码。

  • 点击 OK 按钮关闭对话框。

如果 JPA 切面已经创建,可以通过 Persistence 工具窗口为其分配新建的数据源。在每个切面上点击鼠标右键,选择 Assign Data Sources…​ → 修改数据源 → OK

6.2.2. 配置 JPA 切面

项目中的每个模块都需要一个 JPA 切面,否则此模块不能使用 JPQL 语言相关的功能。

JPA 切面自动检测

Studio 能自动检测切面。当第一次打开新项目时,会在 IDE 的右下角提示 Frameworks Detected

facet detection

如果项目中已经配置 JPA 切面,则不会弹出此消息。如果想要看到此消息,可以通过主菜单 FileProject Structure 打开对话框移除已有的切面。然后重新打开项目,执行 Gradle 刷新操作(Gradle 工具窗 → Reimport All Gradle Projects 按钮)。

如果不小心错过了这个消息提示,也可以通过 Event Log 工具窗口访问记录的消息,只需点击屏幕右下角的事件日志按钮即可打开:

event log

点击 Configure 链接,会出现 Setup Framework 对话框。

反选 Web 分组内的条目,然后点击 OK

setup frameworks

如需检查切面的配置,打开 IDE 左边的 Persistence 工具窗口。然后展开其中一个节点,比如,app-global 模块匹配的那个节点,然后展开 Entities 子节点。此时能看到项目中定义的实体或者从应用程序组件继承的实体:

persistence tool window
JPA 切面手动配置

也可以通过 FileProject Structure 对话框手动配置 JPA 切面。

  • 打开 Project Structure 对话框,

  • 在左侧菜单选择 Facets

  • 移除所有已经存在的 JPA 切面,

  • 对项目中的所有模块:global、core、gui、web、portal - 做下面的操作:

  • 点击 "+"(添加)图标,

  • 选择 JPA 切面类型,

  • 选择以 “main” 结束的子模块,比如,"sample-sales.app-global.main"。 点击 OK

  • 在对话框的右下角,修改 Default JPA ProviderCUBA EclipseLink

  • 对其他模块重复上述操作。

Tip

别忘了设置底部的 Default JPA Provider 字段为 CUBA EclipseLink,否则 JPA 控制台不会有效。

add facet manually

6.2.3. 功能示例

在配置了 JPA 切面的模块的 Java 和 XML 文件里,JPQL 语法高亮,自动补齐和自动检查:

jpql highlighting
jpql java

实体关系图(ER 图)可以从 Persistence 工具窗口打开:右键点击任何模块,选择 EntitiesER Diagram。可以取消顶部 Superclasses 的选择,这样就不会显示通用的基类:

er diagram
JPA 控制台
Tip

注意,JPA 控制台只有在 CUBA 7.1+ 项目才能使用。

JPA 控制台可以从 Persistence 工具窗口打开:展开任何模块 → 选择 Entities 然后点击 Console 按钮:

jpa console button

会打开控制台窗口。现在可以在开发数据库上执行任何 JPQL 查询操作了:

jpa console