sugarCRM文档翻译1

2018-3-9 14:42:14 星期五

本文分两部分:

第一部分是从index.php入口开始的代码执行的部分流程

第二部分是对官方文档的翻译

第一部分: 流程:

入口文件: index.php

->加载 include/entryPoint.php

entryPoin.php:

->加载配置文件 config.php ($sugar_config 数据库配置, 邮件配置, 语种, 日志配置, 默认module/action等等 )  config_override.php

->加载安全相关类, DB工厂类, autoloader, 本地化, 邮件, 日志

->加载权限认证类, 钩子, SugarApplaction类

->设置session_id, 实例化Localization, 获取管理员信息

->sugarApplication()->execute()

exectute():

-> 获取module名字

-> 加载controller.php 查找顺序:

　　custom/modules/moduleNameController/controller.php

　　modules/moduleNameController/controller.php

　　custom/include/MVC/Controller/SugarController.php::CustomSugarController.php

　　include/MVC/controller/SugarController.php

-> 检查权限认证信息, 设置主题, -> 设置数据库查询超时, 查询最大连接等资源

->controller->execute()

 注意:

action=index时, 默认是listView: SugarController->remap_action

加载模板:

以SugarController.php为例

SugarController->execute()->procesView()->ViewFactory::loadView()

loadview优先级(当action=index时):

1.当URL参数中有target_module时

custom/modules/{$target_module}/views/view.list.php > modules/{$target_module}/views/view.list.php

2.档URL参数中没有target_module时

　　custom/modules/{$module}/views/view.list.php

　　modules/{$module}/views/view.list.php

　　custom/include/MVC/View/views/view.list.php

　　include/MVC/View/views/view.list.php

loadView():

ViewFactory::_buildFormFile()-> new SugarView() (或者_buildClass()) -> ViewFactory::_loadConfig() -> process()

注意: view.list.php是一个公用的模板文件, 他最终的渲染内容是会根一些配置文件, 数据文件有关的

第二部分: 翻译:

Dashlets:

他就是首页页面上的一个功能模块(一个横条) 参考

自定义模块的相关文件:

custom/modules/xxx/Dashlets/xxx/xxx.meta.php : 定义一个数组变量, 里边有模块的名字,描述, 图标, 归属哪个模块

custom/modules/xxx/Dashlets/xxx/xxx.php : 定义一个类, 里边有显示模块内容的方法display()

custom/modules/xxx/Dashlets/xxx/xxx.en_us.lang.php : xxx.meta.php中的title, description使用(没有就直接使用xxx.meta.php数组中定义的值)

单个dashlets要继承自Dashlet.php,

list dashlets继承自DashletGeneric.php,

图表dashlets继承自DashletGenericChart.php

所有的dashlets信息存放在user_preferences表, 每个dashlets都有一个ID

dashlets种类:

1. 展示modules数据 2. 订阅其他网站的数据 3.图表展示 4. 工具(日历, 记事本, 时钟等) 5. 其他

javascript:

位置: ./include/JavaScript/Dashlets.js

功能: 提交表单(postForm), 请求数据(callMethod: 调用dashlet类的方法, 或者调用外部接口,如谷歌地图)

 Databases

支持MySQL和mssql, 高级版本还支持db2和oracle, 没有使用触发器和存储过程, 方便编码和抽象

索引: 放在系统模块或者自定义模块目录下的vardefs.php, 键名叫indices (注意vardef文件, 和metadata文件, 前者是描述数据库表的信息, 后者是描述html样式和布局的配置文件)

主键: sugar用create_guid()方法生成全局的唯一值(GUID)当做所有表的主键, 一共36位的字符串: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee, 没有使用自增值是为了防止在数据同步时产生主键冲突

Entry Point 入口文件

/cron.php  windows/linux 计划任务入口

/index.php  框架入口

/service/{v1版本号}/soap.php

/service/{v1版本号}/rest.php

./include/MVC/Controller/entry_point_registry.php

URL访问方式: http://{sugar url}/index.php?entryPoint={entry point name}

自定义入口: 分 6.3版本之前和之后

6.3之后: 入口文件写在/custom/Extension/application/Ext/EntryPointRegistry/中, 然后通过编译生成到: /custom/application/Ext/EntryPointRegistry/entry_point_registry.ext.php

6.3之前: 要创建/custom/include/MVC/Controller/entry_point_registry.php文件 定义入口(仍然兼容, 但不推荐)

入口信息是一个数组, 每一项是一个入口点, 每一项中包含两个值一个是入口文件的路径, 另一个是bool值,表示是否进行权限验证

File cache  文件缓存

主要缓存模板文件和语言字符串

默认放在/cache目录下边, 如果需要更改位置, 则需要需改 config.php 或者 config_override.php

打开文件缓存: 系统管理 > 系统 > 系统设置 > 高级 > 开发模式

Quick Search

Sugar QuickSearch (SQS)

Suagr Bean

数据库操作:

增:

$bean = BeanFactory::newBean($module);
$bean->name = 'Example Record';
$bean->save();
$record_id = $bean->id;

改:

$bean = BeanFactory::getBean($module, $id);
$bean->name = 'Updated Name';
$bean->save();

通过bean的fetched_rows 属性可以确认一条记录是新建的还是已经存在的 原文

 

Module Framework (module/下的代码结构, 与之对应的是 Application Framework 指application/下的代码结构)

一个module通常包含的文件:

1. Vardefs文件, 定义了数据库的表, 字段, 数据类型和关联关系的信息

2. SugarBean文件, 实现了增删改查的功能, 每个模块都继承自SugarBean, 并添加了适用本模块的方法和变量

3. MetaData文件, 定义页面布局和内容信息: (ListView, DetialView, EditeView, SubPanels(跟其他module的关系), Popups(跟其他记录关联的数据列表))

MVC

主要流程: SugarApplication -> ControllerFactory::getController() -> SugarController() -> SugarController::execute()::process()::processView() -> ViewFactory() -> view -> view::process -> SugarView -> SugarView::display()

Model:

SugarBean 以及其子类, 用来操作数据库, 许多普通的module也会继承自SugarObject

内置的六种SugarObject: Basic, Person, issue, Company, File, Sale

View:

Views, otherwise known as actions are typically used to render views or to process logic

或者叫Action, 他不仅可以输出HTML数据, 也可以输出json数据或其他结构的数据, 有一个内置的/默认的SugarView类, 他实现了很多view所需要的基础功能, 例如处理HTML头部和底部信息,

自定义的view文件, 应该放在 /your_module/views/view.<view_name>.php 而其类名应该是驼峰式命名: <Modulename>View<Viewname>, 首字母大写, 其余字母小写, 自定义视图文件可以继承自SugarView或其他View

view分类:

1. DatilView, 通常从ListView页面进入, 他显示了自身的一些数据以及关联的条目(子面板), 子面板是在详情页显示的与之有关的列表性质的信息

./<module>/metadata/detailviewdefs.php定义了详情页的布局  ./<module>/metadata/subpaneldefs.php定义了详情页显示的子面板

2, EditView, 新添加或者编辑都属于他, ./<module>/metadata/editviewdefs.php 中存放编辑页面的布局

3, ListView, 他包含了搜索表单, 搜索结果, 可以 删除, 导出, 批量更新数据, 也可以点击去查看详情

4, Save,

5, Delete

view 方法:

1, preDidplay() 当一个视图继承了其他视图的时候就可以使用这个函数了,

2, display()  展示数据, 将逻辑都写在这里边

加载视图:

ViewFactory 按照以下顺序去加载vew文件:

./custom/modules/<module>/views/view.<view>.php
./modules/<module>/views/view.<view>.php
./custom/include/MVC/View/view.<view>.php
./include/MVC/Views/view.<view>.php

视图的配置文件:

ViewFactory在渲染页面的时候, 会从下边文件中找到一些配置信息, 去控制视图的显示

./customs/modules/<module>/views/view.<view>.config.php
./modules/<module>/views/view.<view>.config.php
./custom/include/MVC/View/views/view.<view>.config.php
./include/MVC/View/views/view.<view>.config.php

Controller

Sugar主要的控制器是 SugarController, 如果想继承他, 就要在自己的模块中创建一个controller.php, 并把类名定义为<ModuleName>Controller, 而类的action的命名方式是 action_functionName

有许多细粒度的控制机制可以被开发者利用, 去重写controller的处理流程, 例如:

如果你想重写Save功能, 你可能要重写三个地方:

1, action_save: 处理保存的逻辑

2, pre_save: 处理来自表单的数据

3, post_save: 这里可以设置跳转链接, 或者保存后的一些处理逻辑, 或者展示一个新的view

自定义controller

自定义的controller要么继承自已经存在于/<module>/controller.php的类, 要么继承自SagurController, 但都要放在 ./custom/modules/<module>/controller.php 为了升级的时候不会被覆盖

包含控制器的文件:

./include/MVC/Controller/SugarController.php
./include/MVC/Controller/ControllerFactory.php
./modules/<MyModule>/Controller.php
./custom/modules/<MyModule>/controller.php

action

控制器中的方法可以直接写在控制器类中, 也可以通过 $action_file_map 去找到对应的代码文件去执行, $action_file_map的加载顺序如下, 后边的变量会覆盖前边的同名变量

./include/MVC/Controller
./modules/<module>
./custom/modules/<module>
./custom/include/MVC/Controller

自定义的 $action_file_map 文件需要放在 ./custom/modules/<module>/action_file_map.php 路径中, 确保安全升级

Controller执行流程:

1, 从index.php开始, 加载SugarApplication实例

2, SugarApplication实例化 SugarControllerFactory

3, SugarControllerFactory加载对应的Controller

4, 检查 ./custom/modules/<module>/Controller.php 是否存在

　　1, 如果不存在, 检查./modules/<module>/Controller.php是否存在

　　2, 如果还不存在, 就加载SugarController.php

5, 调用对应的action

　　1, 检查./custom/modules/<module>/<action>.php是否存在, 如果找到了, 并且./custom/modules/<module>/views/view.<action>.php不存在, 那就用这个view ???wtf

　　2, 如果不存在 ./custom/modules/<module>/<action> 就去查找 modules/<module>/<action>.php, 如果找到了, 并且./modules/<module>/views/view.<action>.php不存在, 就使用modules/<module>/<action>.php

　　3, 如果不存在 modules/<module>/<action>.php 就在控制器里查找 action_<action> 方法

　　4, 如果控制器中不存在这个方法, 就去加载 action_file_mapping, 并查找

　　5, 还是没有找到, 就报错"Action is not defined"

Metadata (用于页面布局的配置信息)

背景: Metadata定义为数据的信息 , 框架会利用这些文件去表达/抽象系统中页面怎么显示或者业务是怎样的逻辑, Metadata存在于定义性质的php文件中, 并由php进行处理, 这些处理通常包括, 1. Smarty 模板渲染页面, 2. JavaScript库处理(调用)一些影响显示的逻辑,或者对输入进行验证等

概念: Metadata是一个定义了嵌套数组的php文件, 他描述了视图中的按钮, hidden input标签, 字段布局等等的信息,

Application级别的Metadata

所有可用的应用模块都定义在 /include/moudules.php 其中:

$moduleList 定义了用于在界面顶部显示的tabs的名字, 他是个索引数组, 每一项的值都用复数形式 (so??)

$beanList 定义了可用的beans(modules), 他是一个关联数组, 键是复数形式, 值是单数形式, 值还跟$beanFiles关联

$beanFiles 定义了modules文件位置

$modInvisList 定义了可以在界面上显示的modues

$adminOnlyList 定义了在admin页面可以被admin看到的modules

Module级别的Metadata

路径: modules/[module]/metadata

additionalDetails.php	定义了当用户鼠标滑过listView的一行时的显示效果
editviewdefs.php	编辑页面如何渲染
detailviewdefs.php	详情页面如何渲染
listviewdefs.php	列表页面如何渲染
metafiles.php	重新定义详情, 编辑, 列表需要的metadata文件的路径
popupdefs.php	渲染搜索表单和列表页面时使用
searchdefs.php	显示modules的基础和高级搜索时使用
sidecreateviewdefs.php	在快捷面板上创建表单时使用
subpaneldefs.php	在详情页面的字面板展示

这些metadata文件的路径也可以在metafiles.php中被重新定义

搜索表单(Search Form)的Metadata

文件名是searchdefs.php, 里边是一个多维数组, 定义了某个模块的表单怎么显示

比如Accounts模块的表单( $searchDefs['Accounts']), 这个表单有多少列, 每一个表单项的文字宽度是多少百分比, input框多少百分比, input的name属性的值等等

其中$searchDefs['Accounts'] 中的Accounts是在 include/modules.php::$moduleList 变量中定义的键名

当一个模块的list视图被渲染的时候, 就会引入searchdefs.php文件, 在view.list.php中会检查modules中是否存在SearchForm.html

如果存在, 就会以Classic模式, 用include/SearchForm/SearchForm.php去处理搜索表单, (Classic Mode是指5.x版本之前, 目前是MVC/Metadata模式)

如果不存在, 就会用include/SearchForm/SearchForm2.php去处理搜索表单, 此时 就会在 custom/modules/[module]/metadata/ 和 modules/[module]/metadata 中依次寻找searchdefs.php文件

EditView 和 DetailView  的 Metadata

metadata文件也以通过studio interface(手工拖动?)去自动创建, 这种情况下, metadata会放在 custom/modules/[module]/metadata/目录下

当第一次访问一个view的时候, preDisplay()方法会去尝试加载正确的metadata文件, 通常情况下metadata文件会在/modules/[module]/metadata/目录下

metadata也可能放在其他路径下边, 他们的路径可以在metafiles.php中找到

生成html文件/渲染视图

当按照上边的约定加载完metadata后,  preDisplay()方法还会创建一个EditView object(以EditView为例), 检查是否需要根据metadata区构建一个smarty模板, EditView object会做大量的工作:

创建模板, 赋值, 权限等级判断等等,

在view代码中调用完preDisplay()方法后就会去调用display()->EditView object()::process()->EditView object()::display()->将生成的html数据放到buffer中输出

举例

加入有一个详情页的请求:  index.php?action=DetailView&module=Opportunities&record=46af9843-ccdf-f489-8833

1. 程序先去是否有一个 modules/Opportunity/DetailView.php 如果有就会去触发 Classic 模式的渲染方式

如果没有这个文件, 程序就会去找modules/Opportunity/views/view.detail.php

如果两个都没有, 程序就会加载include/DetailView/DetailView.php,  此时是 MVC模式,  include/MVC/View/views/views.detail.php 会创建一个DetailView的实例 -> 加载smarty -> setup() -> process() -> display();

2. 其中setup()会创建一个 TemplateHandler 实例, 他在创建最终的详情视图时会去检查加载哪个detailviewdefs.php, 如果setup()中传入了metadata参数就用这个参数, 没有的话, 就去做其他检查

TemplateHandler 实例 也会去做一些 ajax, javascript验证有关的事情

3. process()方法会根据metadata去计算页面展示时HTML元素之间的距离, 字段个数, 以及每列所占的百分比等等

4. display()方法会把变量赋值到Smarty模板上去, 并返回最终要输出的内容

5. 在输出前, TemplateHandler 实例会去检查缓存目录中有没有对应的文件(cache/modules/Opportunity/DetailView.tpl), 如果没有, 就会调用Sugar_Smarty::fetch()去生成缓存文件, 这一步很耗费资源, 另外, 通过 studio interface 方法生成的模板肯定会刷新缓存

Sugar Fields

sugar 根据metadata文件(例如listviewdefs.php)vardefs.php中定义的字段信息, 可以在include/SugarFields/Fields中找到sugar Fields文件

在 include/SugarFields/Fields/Base 中你会找到渲染  DetailView, EditView, ListView, 和 Search Forms 这些基础视图的模板(例如, DetailView.tpl)

目录结构:

./include/SugarFields/Fields/
./include/SugarFields/Fields/<Type>/DetailView.tpl  //Type: 比如Bool, Enum, Text, URL, Readonly... 
./modules/MyModule/vardefs.php
./modules/MyModule/metadata/defs.php

字段类型以及关联信息(比如是枚举类型, 他就会有多个值) 去自动生成HTML标签

Type: 也有group类型的比如 Address, Datetime, Parent, Relate

大多数的Sugar Field包含了一堆Smarty tpl文件

一些 Sugar Fields 还包含了 SugarFieldBase  的子类, 用来覆盖原有的方法去做一些额外的处理, 子类的名字要这样写: SugarField[Sugar Field Type] 其中后边的英文单词首字母要大写

例如:

enum类型的SugarField(会被渲染成 select 标签)的代码, 放在 ./include/SugarFields/Fields/Enum/SugarFieldEnum.php中,

这个代码中你可以看到, 枚举类型是是怎么使用6个Smarty模板中的一个取决于

1. view是什么(edit, detail or search)

2. enum vardef 的定义中是否有一个 'function' 属性去调用php函数去渲染字段的内容

例子, 添加一个视频input

Vardefs

他(Variable Definitions) 给Application提供了SugarBean的信息, 如果一个moudles包含了SugarBean, 那么就会有一个vardefs文件,

该文件用来描述表中的每个字段的信息, beans之间的关系, bean的索引信息, 关联表/字段信息等等

 

还有一页