diff --git a/docs/brickindex.md b/docs/brickindex.md new file mode 100644 index 0000000..01ac71d --- /dev/null +++ b/docs/brickindex.md @@ -0,0 +1,16 @@ +| 页面名称 | html文件 | js文件 | 说明文件是否完成 | +| ------------ | -------- | ------ | ---------------- | +| accordion | √ | √ | √ | +| audio | √ | √ | √ | +| aggrid | x | √ | x | +| button | √ | √ | √ | +| datagrid | √ | √ | x(html页面报错) | +| docs | √ | x | √ | +| editabletree | √ | √ | √ | +| error | √ | x | x(无html页面) | +| message | √ | √ | √ | +| tab | √ | √ | √ | +| toolbar | √ | √ | √ | +| tree | √ | √ | √ | +| video | √ | √ | √ | + diff --git a/docs/cn/.README.md.swp b/docs/cn/.README.md.swp new file mode 100644 index 0000000..dab2fc7 Binary files /dev/null and b/docs/cn/.README.md.swp differ diff --git a/docs/cn/README.md b/docs/cn/README.md index 4cd555e..b298e2a 100644 --- a/docs/cn/README.md +++ b/docs/cn/README.md @@ -10,3 +10,4 @@ ## [bricks安装](install.md) ## [控件介绍](widgets.md) ## [事件处理](events.md) +## [对后台服务器要求](server.md) diff --git a/docs/cn/descjson.md b/docs/cn/descjson.md index 877f4e8..8885db9 100644 --- a/docs/cn/descjson.md +++ b/docs/cn/descjson.md @@ -17,465 +17,15 @@ widgettype是一个字符串属性。其值为Bricks中的所有控件类型或" 参见widgetBuild函数的desc说明 ## binds -列表属性,定义控件的事件处理,在列表中的每一项,定义一个事件处理, Bricks支持5种事件处理方法,分别是urlwidget, method, script, registedfunction和event +列表属性,定义控件的事件处理,在列表中的每一项,定义一个事件处理, Bricks支持5种事件处理方法, +分别是urlwidget, method, script, registedfunction和event -每种事件处理类型都支持下述属性 -### wid -字符串类型或控件类型,绑定事件的控件,缺省是binds坐在的构造控件。 -### event -字符串类型,事件名称, 绑定针对的事件字符串名称 - -### actiontype -绑定类型,支持“urlwidget", "method", "script", "registerfunction", "event" - -### conform -对象类型,确认控件的options,如存在,则此绑定需要用户确认后再执行 - -### 获取实时数据作为参数 -绑定任务获取实时数据作为参数,需要给定以下属性: -* datawidget:字符串或控件类型,获取实时数据的控件 -* datamethod:字符串类型,控件的方法,使用params作为参数调用, -获取实时数据的方法 -* datascript:字符串类型, js脚本,使用return返回数据 -* dataparams:参数 -datamethod 优先datascript,从datawidget控件中通过datamethod - -### target -字符串或控件实例,目标控件实例,如果是字符串,使用”getWidgetById“函数获得目标控件实例 - -### conform -如果一个事件处理需要用户确认,可以在事件处理中指定一个conform属性来引发,当此事件发生时,会弹出一个确认窗口,用户确认后才会处理此事件,否则不处理 - -### urlwidget绑定 -urlwidget事件处理方法是从后台获取一个控件描述文件,动态生成bricks控件,并将控件添加(添加,添加或替换)到事件处理指定的控件中。 - -urlwidget绑定需要一个options属性和一个mode属性,在此属性中需要 -* url:字符串类型, 获取desc数据的url -* mehtod:字符串类型,url调用的方法,缺省”GET“ -* params:对象类型,调用的参数 -绑定创建的控件添加到target控件中 - -请参考[例子](../../examples/urlwidget.ui) -``` -{ - "widgettype":"VBox", - "options":{ - "width":"100%", - "height":"100%" - }, - "subwidgets":[ - { - "widgettype":"HBox", - "options":{ - "height":"40px" - }, - "subwidgets":[ - { - "id":"replace", - "widgettype":"Button", - "options":{ - "width":"80px", - "i18n":true, - "label":"replace mode" - } - }, - { - "id":"insert", - "widgettype":"Button", - "options":{ - "width":"80px", - "i18n":true, - "label":"insert mode" - } - }, - { - "id":"append", - "widgettype":"Button", - "options":{ - "width":"80px", - "i18n":true, - "label":"append mode" - } - } - ] - }, - { - "id":"main", - "widgettype":"Filler" - } - ], - "binds":[ - { - "wid":"replace", - "event":"click", - "actiontype":"urlwidget", - "target":"main", - "options":{ - "url":"{{entire_url('replace_text.ui')}}", - "params":{ - "text":"Insert before" - } - } - }, - { - "wid":"insert", - "event":"click", - "actiontype":"urlwidget", - "target":"main", - "options":{ - "url":"{{entire_url('insert_text.ui')}}", - "params":{ - "text":"Insert before" - } - }, - "mode":"insert" - }, - { - "wid":"append", - "event":"click", - "actiontype":"urlwidget", - "target":"main", - "options":{ - "url":"{{entire_url('subtext.ui')}}", - "params":{ - "text":"Append After" - } - }, - "mode":"append" - } - ] -} -``` -在上述例子中,我们使用了一个竖向排列的容器(VBox),并在此容器中添加了两个字控件,分别是一个横向排列的容器HBox,和一个填充器(Filler) -并在横向排列的子控件中添加了3个按钮控件, 每个Button定义了id, 分别是replace,insert,和append,在主控件(VBox)的binds中分别定义了三个事件处理,分别对应于3个Button的click事件,演示了三种子控件在target控件中插入的模式(替换所有子控件,插入在已有子控件之前,添加到已有子控件之后) - -### method -需要指定target参数和method参数, -* target:类型为字符串或控件类型, -如果是字符串,使用“getWidgetById”函数获取控件实例。 -* method:字符串,target实例的方法, -* params:传递给方法的参数 -method绑定方法,将事件绑定到target控件的一个方法,并用params传递参数 - -例子 -``` -{ - "widgettype":"VBox", - "options":{ - "width":"100%", - "height":"100%" - }, - "subwidgets":[ - { - "widgettype":"HBox", - "options":{ - "height":"40px" - }, - "subwidgets":[ - { - "id":"changetext", - "widgettype":"Button", - "options":{ - "dynsize":false, - "width":"80px", - "i18n":true, - "label":"Change text" - } - }, - { - "id":"smaller", - "widgettype":"Button", - "options":{ - "dynsize":false, - "width":"80px", - "i18n":true, - "label":"Small size" - } - }, - { - "id":"larger", - "widgettype":"Button", - "options":{ - "dynsize":false, - "width":"80px", - "i18n":true, - "label":"larger size" - } - } - ] - }, - { - "widgettype":"Filler", - "options":{}, - "subwidgets":[ - { - "id":"text_1", - "widgettype":"Text", - "options":{ - "dynsize":true, - "text":"original text" - } - } - ] - } - ], - "binds":[ - { - "wid":"changetext", - "event":"click", - "actiontype":"method", - "target":"text_1", - "params":"new text", - "method":"set_text" - }, - { - "wid":"smaller", - "event":"click", - "actiontype":"method", - "target":"app", - "method":"textsize_smaller" - }, - { - "wid":"larger", - "event":"click", - "actiontype":"method", - "target":"app", - "method":"textsize_bigger" - } - ] -} -``` -上述例子中,三个Button分别驱动app中textsize_smaller(),textsize_bigger()来改变bricks字符大小,从而影响到text_1控件的显示大小 - -### script -绑定脚本,此方法将事件绑定到一个脚本,支持以下属性 -* script:字符串,脚本正文 -* params:对象类型,脚本可以访问params变量来获取参数。 -脚本中可以使用以下变量: -* this 事件处理中target对应的控件实例 -* params:参数对象,datawidget获得的数据会添加到params中 - -例子 -``` -{ - "id":"insert", - "widgettype":"Button", - "options":{ - "width":"80px", - "i18n":true, - "label":"click me" - }, - "binds":[ - { - "wid":"self", - "event":"click", - "actiontype":"script", - "target":"self", - "script":"console.log(this, params, event);" - } - ] -} -``` -在上述例子中定义了使用“script”事件处理方法来处理Button的“click事件”, 在click后在控制台上把事件传过来的参数显示出来 - -### registerfunction -事件绑定一个注册函数, 参看[RegisterFunction](registerfunction.md) -支持以下属性: -rfname:字符串,已注册的函数名称 -params:对象类型,调用注册函数时作为参数传递给注册函数。 - -``` - - - - - - - - - - - - - - - -``` -在上述例子中,使用bricks.RF注册了一个setText函数, 并在主控件的binds区域定义了当changetext按钮点击后调用注册函数“setText”来处理 - -### event -绑定事件,需指定target,触发target对象的一个事件 -支持以下属性 -dispatch_event:需触发的事件名 -params:传递给事件的参数,处理函数可以使用evemt.params获得此参数 - -``` -{ - "widgettype":"VBox", - "options":{}, - "subwidgets":[ - { - "id":"btn1", - "widgettype":"Button", - "options":{ - "label":"press me" - } - }, - { - "id":"txt1", - "widgettype":"Text", - "options":{ - "otext":"I will dispatch a event when btn1 pressed", - "i18n":true - } - } - ], - "binds":[ - { - "wid":"btn1", - "event":"click", - "actiontype":"event", - "target":"txt1", - "dispatch_event":"gpc" - }, - { - "wid":"txt1", - "event":"gpc", - "actiontype":"script", - "target":"self", - "script":"alert('yield');" - } - ] -} -``` -上述例子中,在主控件的binds区域定义了btn1的按钮点击后使用event处理类型来处理btn1的click事件,即转而触发“txt1”正文控件的“gpc”事件,并定义了当”txt1“正文控件在gpc事件发生后使用script事件处理方法alert一个消息 - -## 定义需要确认的事件处理 -有时候我们需要客户确认后在处理事件,如果用户不确认,则放弃处理事件,比如在删除数据时我们通常需要用户确认一下 -例子 -``` -{ - "id":"insert", - "widgettype":"Button", - "options":{ - "width":"80px", - "i18n":true, - "label":"click me" - }, - "binds":[ - { - "wid":"self", - "event":"click", - "actiontype":"script", - "conform":{ - "title":"conformtest", - "message":"测试事件处理前的用户确认功能,确认码?" - }, - "target":"self", - "script":"alert('确认过眼神!')" - } - ] -} -``` -上述例子中定义了Button的click事件使用script事件处理方式来处理,但是在处理前需要显示信息,让用户确认是否继续,如果用户放弃则不处理事件,确认后正常的处理事件。 +在binds中这五种事件处理方法都可以定义,在同一个控件中可以灵活的使用不同事件处理方法来响应不同控件的不同事件, +支持: +* 可定义bings所在控件的事件处理 +* 可定义binds所在控件的子(孙)控件的事件处理 +* 可定义应用控件树上任何‘wid’对应的控件的事件处理 +* 同一个控件的同一个事件,使用多个处理方法按定义顺序依次处理 + +详细事件处理请参看[bricks的事件处理](event.md) diff --git a/docs/cn/event.md b/docs/cn/event.md new file mode 100644 index 0000000..a8b02bb --- /dev/null +++ b/docs/cn/event.md @@ -0,0 +1,478 @@ +# bricks的事件处理 +bricks的事件处理是在控件描述文件的binds区域中添加事件处理说明来实现的 +## bricks支持的事件处理类型 +* urlwidget +* method +* script +* registerfunction +* event +例外还支持一种混合型 +* actions + +## 事件处理定义数据要素 + +所有事件处理类型都有的数据要素有 +### wid +### event + +### actiontype +绑定类型,支持“urlwidget", "method", "script", "registerfunction", "event" + +### conform +对象类型,确认控件的options,如存在,则此绑定需要用户确认后再执行 + +### datawidget +### datamethod +### datascript +### dataparams + +### 获取实时数据作为参数 +绑定任务获取实时数据作为参数,需要给定以下属性: +* datawidget:字符串或控件类型,获取实时数据的控件 +* datamethod:字符串类型,控件的方法,使用params作为参数调用, +获取实时数据的方法 +* datascript:字符串类型, js脚本,使用return返回数据 +* dataparams:参数 +datamethod 优先datascript,从datawidget控件中通过datamethod + +### target +字符串或控件实例,目标控件实例,如果是字符串,使用”getWidgetById“函数获得目标控件实例 + +### conform +如果一个事件处理需要用户确认,可以在事件处理中指定一个conform属性来引发,当此事件发生时,会弹出一个确认窗口,用户确认后才会处理此事件,否则不处理 + +不同的事件处理方法也有部分不同的事件处理属性,一下分别说明: + +### urlwidget绑定 +urlwidget事件处理方法是从后台获取一个控件描述文件,动态生成bricks控件,并将控件添加(添加,添加或替换)到事件处理指定的控件中。 + +urlwidget绑定需要一个options属性和一个mode属性,在此属性中需要 +* url:字符串类型, 获取desc数据的url +* mehtod:字符串类型,url调用的方法,缺省”GET“ +* params:对象类型,调用的参数 +绑定创建的控件添加到target控件中 + +请参考[例子](../../examples/urlwidget.ui) +``` +{ + "widgettype":"VBox", + "options":{ + "width":"100%", + "height":"100%" + }, + "subwidgets":[ + { + "widgettype":"HBox", + "options":{ + "height":"40px" + }, + "subwidgets":[ + { + "id":"replace", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"replace mode" + } + }, + { + "id":"insert", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"insert mode" + } + }, + { + "id":"append", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"append mode" + } + } + ] + }, + { + "id":"main", + "widgettype":"Filler" + } + ], + "binds":[ + { + "wid":"replace", + "event":"click", + "actiontype":"urlwidget", + "target":"main", + "options":{ + "url":"{{entire_url('replace_text.ui')}}", + "params":{ + "text":"Insert before" + } + } + }, + { + "wid":"insert", + "event":"click", + "actiontype":"urlwidget", + "target":"main", + "options":{ + "url":"{{entire_url('insert_text.ui')}}", + "params":{ + "text":"Insert before" + } + }, + "mode":"insert" + }, + { + "wid":"append", + "event":"click", + "actiontype":"urlwidget", + "target":"main", + "options":{ + "url":"{{entire_url('subtext.ui')}}", + "params":{ + "text":"Append After" + } + }, + "mode":"append" + } + ] +} +``` +在上述例子中,我们使用了一个竖向排列的容器(VBox),并在此容器中添加了两个字控件,分别是一个横向排列的容器HBox,和一个填充器(Filler) +并在横向排列的子控件中添加了3个按钮控件, 每个Button定义了id, 分别是replace,insert,和append,在主控件(VBox)的binds中分别定义了三个事件处理,分别对应于3个Button的click事件,演示了三种子控件在target控件中插入的模式(替换所有子控件,插入在已有子控件之前,添加到已有子控件之后) + +### method +需要指定target参数和method参数, +* target:类型为字符串或控件类型, +如果是字符串,使用“getWidgetById”函数获取控件实例。 +* method:字符串,target实例的方法, +* params:传递给方法的参数 +method绑定方法,将事件绑定到target控件的一个方法,并用params传递参数 + +例子 +``` +{ + "widgettype":"VBox", + "options":{ + "width":"100%", + "height":"100%" + }, + "subwidgets":[ + { + "widgettype":"HBox", + "options":{ + "height":"40px" + }, + "subwidgets":[ + { + "id":"changetext", + "widgettype":"Button", + "options":{ + "dynsize":false, + "width":"80px", + "i18n":true, + "label":"Change text" + } + }, + { + "id":"smaller", + "widgettype":"Button", + "options":{ + "dynsize":false, + "width":"80px", + "i18n":true, + "label":"Small size" + } + }, + { + "id":"larger", + "widgettype":"Button", + "options":{ + "dynsize":false, + "width":"80px", + "i18n":true, + "label":"larger size" + } + } + ] + }, + { + "widgettype":"Filler", + "options":{}, + "subwidgets":[ + { + "id":"text_1", + "widgettype":"Text", + "options":{ + "dynsize":true, + "text":"original text" + } + } + ] + } + ], + "binds":[ + { + "wid":"changetext", + "event":"click", + "actiontype":"method", + "target":"text_1", + "params":"new text", + "method":"set_text" + }, + { + "wid":"smaller", + "event":"click", + "actiontype":"method", + "target":"app", + "method":"textsize_smaller" + }, + { + "wid":"larger", + "event":"click", + "actiontype":"method", + "target":"app", + "method":"textsize_bigger" + } + ] +} +``` +上述例子中,三个Button分别驱动app中textsize_smaller(),textsize_bigger()来改变bricks字符大小,从而影响到text_1控件的显示大小 + +### script +绑定脚本,此方法将事件绑定到一个脚本,支持以下属性 +* script:字符串,脚本正文 +* params:对象类型,脚本可以访问params变量来获取参数。 +脚本中可以使用以下变量: +* this 事件处理中target对应的控件实例 +* params:参数对象,datawidget获得的数据会添加到params中 + +例子 +``` +{ + "id":"insert", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"click me" + }, + "binds":[ + { + "wid":"self", + "event":"click", + "actiontype":"script", + "target":"self", + "script":"console.log(this, params, event);" + } + ] +} +``` +在上述例子中定义了使用“script”事件处理方法来处理Button的“click事件”, 在click后在控制台上把事件传过来的参数显示出来 + +### registerfunction +事件绑定一个注册函数, 参看[RegisterFunction](registerfunction.md) +支持以下属性: +* rfname:字符串,已注册的函数名称 +* params:对象类型,调用注册函数时作为参数传递给注册函数。 + +``` + + + + + + + + + + + + + + + +``` +在上述例子中,使用bricks.RF注册了一个setText函数, 并在主控件的binds区域定义了当changetext按钮点击后调用注册函数“setText”来处理 + +### event +绑定事件,需指定target,触发target对象的一个事件 +支持以下属性 +dispatch_event:需触发的事件名 +params:传递给事件的参数,处理函数可以使用evemt.params获得此参数 + +``` +{ + "widgettype":"VBox", + "options":{}, + "subwidgets":[ + { + "id":"btn1", + "widgettype":"Button", + "options":{ + "label":"press me" + } + }, + { + "id":"txt1", + "widgettype":"Text", + "options":{ + "otext":"I will dispatch a event when btn1 pressed", + "i18n":true + } + } + ], + "binds":[ + { + "wid":"btn1", + "event":"click", + "actiontype":"event", + "target":"txt1", + "dispatch_event":"gpc" + }, + { + "wid":"txt1", + "event":"gpc", + "actiontype":"script", + "target":"self", + "script":"alert('yield');" + } + ] +} +``` +上述例子中,在主控件的binds区域定义了btn1的按钮点击后使用event处理类型来处理btn1的click事件,即转而触发“txt1”正文控件的“gpc”事件,并定义了当”txt1“正文控件在gpc事件发生后使用script事件处理方法alert一个消息 + +## 定义需要确认的事件处理 +有时候我们需要客户确认后在处理事件,如果用户不确认,则放弃处理事件,比如在删除数据时我们通常需要用户确认一下 +例子 +``` +{ + "id":"insert", + "widgettype":"Button", + "options":{ + "width":"80px", + "i18n":true, + "label":"click me" + }, + "binds":[ + { + "wid":"self", + "event":"click", + "actiontype":"script", + "conform":{ + "title":"conformtest", + "message":"测试事件处理前的用户确认功能,确认码?" + }, + "target":"self", + "script":"alert('确认过眼神!')" + } + ] +} +``` +上述例子中定义了Button的click事件使用script事件处理方式来处理,但是在处理前需要显示信息,让用户确认是否继续,如果用户放弃则不处理事件,确认后正常的处理事件。 + diff --git a/docs/cn/widgetid.md b/docs/cn/widgetid.md new file mode 100644 index 0000000..c87fc57 --- /dev/null +++ b/docs/cn/widgetid.md @@ -0,0 +1,60 @@ +# 控件ID +在控件描述文件中,我们可以使用“id“属性能设置控件的id, 这个id会设置到控件对应的dom元素上 + +## 控件ID的作用 +像DOM体系,bricks使用控件ID用🐟标识控件,不一定要求唯一,但在使用时通常只会使用找到的一个控件 + +bricks的事件处理依赖控件id来确认事件的发起控件, 事件的目标控件以及事件的数据来源控件 + +## 控件查找开始位置 +从binds区域所在的控件开始查找,对于"."号分割的id,首先从当前位置查找到第一段id的控件,再用上一个找到的控件作为下一段id的开始位置,直到最后一段,并将最后一段找到的控件作为最终控件返回。如果任何一个位置的id没找到对应的控件,返回空。 + +## 控件ID书写规则 + +bricks事件处理中的控件ID, 通过“."号开分段,标识要分段查找相应的控件。 + +## 控件查找方向 +"-"号开始的id从当前位置向上查找控件 +否则从当前位置向下查找 + +## 预定于的id +预定义的id通常放在"."分割的第一段,用来改变控件查找的开始位置 + +### app +"app“ bricks.App属性,也是Body控件,对应于html的元素 + +### root +bricks前端应用只放一个控件在bricks.Body中,所有其他的控件都放在这个root控件之下, "root"ID用于查找这个控件 + +### self +binds区域所在的控件 + +## binds区域中和控件ID有关的属性 + + +### wid +字符串属性,定义事件发起方的id, 缺省为"self" + +### target +定义事件处理的控件, 下面对不同的事件处理方式分别说明 + +#### urlwidget +target控件是此事件生成的子控件的父控件,需要是个容器控件 +参看[控件表述文件](descjson.md) + +#### method +事件的method方法的控件。 + +#### script +script脚本可用this变量来使用target对应的控件 + +#### registerfunction +注册函数可以使用this变量来使用target对应的控件 + +#### event +定义触发事件的控件实体 + +### datawidget +定义事件的参数来源对象,如果找到此控件,则通过该控件的datamethod(如果定义)方法来获取参数,或者通过datascript脚本来获取参数 +获得的参数将会添加到binds事件处理定义中说明的参数中 +