API x tag - noradle/plsql-print GitHub Wiki

基础 x(tag) API (被 o/xtag 替代)

take a glance

tag.p('<div#id.c1.c2 a1=v1,a2=v2, :1 :2>', '', st(...)) -- 空 div 标签
tag.p('<div#id.c1.c2 a1=v1,a2=v2, :1 :2>', 'some text', st(...)) -- 有内容的 div 标签
tag.p('<script src=:1,>','',st(url)); -- 空内容的 script
tag.s('<img src=:1,>', st(url)); -- 自关闭标签
tag.o('<div>') -- open
tag.c('</div>') -- close
tag.t('...') -- plain text, 不是必须放到 tag 中，除了带有参数外
tag.p('<li>', tag.p('<a href=:1,', ..., st(...)));
tag.t('<li>' || tag.p('<a href=:1,', ..., st(...))) || '</li>');
tag.p('<a href=:1,>', tag.s('<img src=:1,>', st(...)) );

tag.j('<li>',v_name,'</li>');
tag.j('<a href="', ..., '"</a>');

APIs table

common parameters

  1. inner|text: the content between tag, no default value
  2. para - replace :1 :2 ... :n with st(n), default to null
  3. cut - if true, output nothing, default to null

note:

  • x 是 tag 的 synonym, 用于减少代码长度(因为页面输出API往往是大量调用的)
  • 参数的基本顺序规律是 tag, inner|text, url|value, para, cut
  • 只有cut参数在没有para参数情况下需要写参数名，其他情况下都无需写参数名，代码视觉效果较好
  • 带输出内容踢的 x.x API 都包含 tag inner text 参数
  • a.href|img.src|script.src|link.href 等都需要 url 参数，经常使用，单独提出 API. 并且系统会自动对url参数调用u(url)来进行智能处理，见下一章URL部分。
  • 表单项经常需要带入动态数值，因此提供 x.v(tag,value[,para,cut]) API。
API stand for plsql output explain
x.p(tag,inner[,para,cut]) pair `x.p('
', '...')`
 `
...
`		 open/close tag pair
x.s(tag[,para,cut]) single `x.s('')` `` self-closed tag
x.o(tag[,para]) open `x.o('
')`
 `
`
 tag open
x.c(tag) close `x.c('')` `` tag close
x.v(tag,value[,para]) value `x.v(' `` input value
x.i(tag,src[,para]) `` `x.i('', 'url')` `` like ``, has src attr and self-closed
x.j(tag,src[,para]) javascript
`<script>`		 `x.j('http://xxx.js')` `<script src="http://xxx.js"></script>` gen `<script src=>` to load external url
x.l(tag,href[,para]) `` `x.l('http://xxx.css')` `` gen `` to load external css
x.a(tag,text,href[,para,cut]) `` `x.a('', '...', 'url')` `...` like `...`, has href attr and content
x.f(tag,action[,para]) `` `x.f('', 'url')` `...` like `...`, has action, tag open only
x.t(text[,para,cut]) text `x.t('a.:1,b.:2',st('node','oracle'))` `a.node,b.oracle` plain text with dynamic parameter to replace ":n"
x.r(text,dyna) around `x.r([[[@]]]', 'Noradle')` [Noradle] place header/footer around the string stand by "@"
x.e(text) escape `x.t(x.e('...'))` `<a>text</a>` function for escape `<` and `>`
x.w wrap `x.w('norale','b')` `noradle` wrap every letter in string with a tag name

attributes

x.o('<tag#id.class1.class2 battr1 battr2 attr1=value1,attr2=value2,^attr3=value3>');

produce

<tag id="id" class="class1 class2" battr1 battr2 attr1="value1" attr2="value2" data-attr3="value3">`

Note:

  • order must be "tag#id.class battr attr"
  • 关于 src/href 的值包含 =, 的问题，会被当前 attr=value, 被替换掉；请使用带url参数的API或使用变量值替换来安全处理
  • most API have param "cut", if cut=>true, 可以根据条件，直接忽略不输出
type plsql output explain
`#id` `x.o('
')`
 `
`
 must follow tag
`.classname` `x.o('')` `
`
 must follow tag/#id, can have multiple classnames
`attribute` `x.s('')` `` only have attribute name, no "=value" in it
can have multiple separated by " "
`attribute=value` `x.s('')` `` don't place "" around value
can have multiple separated by ","
`^attribute=value` `x.s('');` `` "^" will be replaced with "data-"

substitute in tag line

PL/SQL servlet will produce dynamic page that have database data in it, so it must bind dynamic variable data to page, by now, NORADLE can only bind data to

  1. x.x API's "text" parameter, like x.p('<span>', plsql_variable).
  2. x.x API's url parameter, like x.a('<a>','text',plsql_variable_for_url)
  3. x.v API's value parameter, like x.v('<input type=text>', plsql_variable_for_value)

all x.x API's first param can use subsitution ":n", replace with st(...) params with plsql variable value(not static string).

It provide another way to bind plsql variable value to HTML/XML page.
(The basic way it to fill x.x API param with variable like "text" param)

for example

	procedure substitute is
		v_id varchar2(30) := 'id1';
		v_c1 varchar2(30) := 'c1';
		v_c2 varchar2(30) := 'c2';
		v_b1 varchar2(30) := '';
		v_b2 varchar2(30) := 'disabled';
		v_a1 varchar2(30) := 'a1';
		v_a2 varchar2(30) := 'a2';
		v_a3 varchar2(30) := 'a3';
	begin
		h.content_type('text/plain');
		x.o('<tag#:1.:2.:3 :4 :5 attr1=:6,attr2=:7,^attr3=:8>', st(v_id, v_c1, v_c2, v_b1, v_b2, v_a1, v_a2, v_a3));
		x.t('content');
		x.c('</tag>');
	end;

will produce

<tag id="id1" class="c1 c2"  disabled attr1="a1" attr2="a2" data-attr3="a3">
content
</tag>

note: ":n" will be substitute with nth st parameter value.

boolean switch shortcuts

there are shortcut to switch regular boolean attributes below:

  • x.checked
  • x.selected
  • x.disabled
  • x.defer
  • x.async

for example:

x.j('<script :1 :2 attr=value>', st(x.defer(true),x.disabled(false));

will produce

<script defer attr="value">

note there is no "disabled" attribute print out, because x.disabled(false) have false param.

特性总结

  • 输出页面的源码保留标签开关<tag>看起来非常熟悉顺眼
  • 缩进书写支持(随PL/SQL缩进，或在标签前加前导空格)，页面层次更清晰，代码可读性更强
  • 支持 <tag> 的 escape，防止脚本注入
  • param(n) 替换 $n
  • <tag> 中的内容实现 <tag#id.c1.c2 b1 b2 a1=v1,a2=v2> 的缩写 否则就要写很长的
  • cut=>true, 可以根据条件，直接忽略，不再进行进一步的处理 这样可以省去 if then,end if 两行，并且和其他输出 API 调用语句排列整齐
  • 对于带 url 的引用
  • .t 不生成标签，只是输出文本，带式可以带入参数替换文本中的锚点
  • #id .class, attr=value, attr=:1px, checked 等，解决标签内属性书写过长，比较臃肿的问题，强调对css选择器id,class的特殊支持
  • a,i(mg) 等最常见带有url属性的输出，特别的对最常用的 javascript, stylesheet 的链接的支持
  • bulk: ths, tds, options, checks, radios 快速绑定分隔符分割数组，plsql数组，sys_refcursor 的数据源，性能考虑更多
  • tree: 快速绑定 sys_refcursor 生成树形结构标签
  • .w 对一组数据的每一个都套用(wrap)同一个模板

Todo

  • html header 中的简洁输出问题，需要自己根据应用的需要去写一个快捷 API，方便自己用
  • 自动结束 </body></html> 问题，Noradle 自动补全所有最后没有关闭的标签 [solved]
  • html5 data-xxx 属性名称过长，需要缩写问题 ^attr=value, 该特性会导致API性能下降，考虑用户自己包一层或者是增加参数
  • API 性能分析，希望能再快一点，虽然这个属于 CPU cache 级操作，性能不是瓶颈 tag#id.class1.class2 attr1=value1,attr2=value2, :1 :2 需要定位 intrb 和 substrb 多次，分别是 空格，.，# 。 如果使用 regexp，可能只需扫描一次 (\w+)(#\w+)(.(\w|.)+)( (\w+=\w,)+) 替换成 <$1 id="$2" class="$3" 不可能，因为没出现的部分会输出成 xxx="" 的情况，无法解决。
⚠️ **GitHub.com Fallback** ⚠️