Pliant documentation forum

Pliant documentation forum

On how to do Webpage styling in Pliant

Message posted by marcus on 2003/06/16 14:39:13
With respect to Pliant release 85 default.style, what is the (new) syntax and
semantics of the .page instructions (from 'alpha' to 'omega'). 

Message posted by hubert.tonneau on 2003/06/16 17:08:59
The syntax part:

most tags (HTML or XML) are now defined using 'html_tag' instruction
(see module /pliant/protocol/http/style/default.style for samples)

Sample 1:

  html_tag section name
    attr name Str encode

we define 'section' tag, and it requires a 'name' parameter (line 1)
'name' parametre has type 'Str'

So, a valid usage in a .page is

section "foo"

Now, the 'encode' section means that the argument will be automatically
HTML encoded.
I mean, if you write in your .page

section "foo!"

The 'name' argument will be tansmited to the styling machinery as
"foo!"


Sample 2:

  html_tag center
    body

the 'center' argument has no parameter, but has a body.
I mean a valid usage would be:

center
  [some text]

or

center
  text "some text"
  eol


Sample 3:

  html_tag font
    sequence font
      attr family Str -> face
      attr attributes Str
      attr size Float 12
    attr color ColorRGB888 (color rgb 0 0 0)
    body

Here you see 'sequence' which is a way to provide several arguments at once
without the identifier of each of them.

So,

font family "Helvetica" attributes "bold" size 16 color (color hsl 0 100 50)
  [sample text]

is the same as:

font font "Helvetica" "bold" 16 color (color hsl 0 100 50)


More details about where attributes identifiers must appear of be silent:
. when the instruction has some required parameters (listed on the first line),
  then the identifiers of the attributes must not be specified since the
  attributes are required
. when you specify the attribute of a sequence, then the value of all the
  attibutes in the sequenc will follow without the identifiers
. in other cases, the arguments are idenifier of the attribute followed by
  value for the attribute


Sample 4:

  html_tag image src -> img
    attr src Str

'-> img' means that in a .page, you have to write

image "foo.png"

not

img "foo.png"

but the low level part of the styling engine knows that the HTML tag name is 'img'
not 'image'

Same for:

  attr family Str -> face

the Pliant ID to use is 'family', but the HTML one is 'face'


Sample 5:

  html_tag note label
    attr label Str
    subpage target

the last line 'subpage target' means that there will be an all sub-page
provided idented, and the 'target' attribute will store the URL of the
subpage.

Sample usage of 'note' is:

note "my sample note"
  title "title of the sub-page"
  [here is the content]


Sample 6:

  html_tag row -> tr
    body
    newline

The newline means that the default tag handler will add a newline character
in the HTML stream at the end of the tag.

I mean

row
  [foo]
[bar]

(which is stupid from the semantic point of view)
would be translated to

<tr>foo</tr>
bar

not

<tr>foo</tr>bar


The special ColorRGB888 data type:
there are mainly two recommended ways to provide colors

color hsl 0 100 50

means hue=0, saturation=100, light=50, so red

color rgb 255 0 0

means red again.

The 'hsl' is not the same encoding with aguments inverted as the old 'lsh',
since the formulas to translate it to RGB are different.


Now, there are some special tags that are not declared though 'html_tag'
but still through plain metas:
input
text_input
select/option
file_upload
listing
they have not changed from earlier specifications.


Next, I will describe how Pliant tags translate to HTML (the rendering engine),
and introduce the special (style ...) attribute.
Message posted by hubert.tonneau on 2003/06/16 18:36:19
Introduction to Pliant styling mechanism.

Let's look at the 'title' tag:

  html_tag title label
    attr label Str encode
    attr logo Str
    attr link Str
    attr small
    sequence font
      attr family Str -> face
      attr attributes Str
      attr size Float 36
    attr color ColorRGB888 (color rgb 0 0 0)
    attr button Str
    sequence bsize
      attr bsize_x Float undefined
      attr bsize_y Float undefined
    sequence margin
      attr margin_left Float undefined
      attr margin_top Float undefined
      attr margin_right Float undefined
      attr margin_bottom Float undefined
    attr round Int 0
    attr bgcolor ColorRGB888 (color rgb 255 255 255) 

The content related attibutes is a small subset. I mean:

  html_tag title label
    attr label Str encode
    attr logo Str
    attr link Str

  'logo' is used to provide the URL of the logo that will be displayed at the
  right most part of the title, and 'link' is providing the URL you will get
  if you clic on the logo.

  Note: these two attributes probably don't work on release 85 experimental,
        but it's unrelated to this introduction to styling.

Now we have a large subset of attibutes that are purely styling related.

'font' provides the three informations required to decide the font to use
for drawing the title text.
Among these, 'attributes' is generally something like:
""
"bold"
"server"
"server bold"
"server italic"
'bold' and 'italic' are used to select the exact font within the familly
(see http://localhost/pliant/graphic/vector/font.html) for details about
available font familties and attributes.
Now 'server' means that the font will be server side rendered, then sent
to the browser as a bitmap, with antialising applied on server side.
This is very powerfull since it enables to use any font in your site (you
just need to install it on the server) and any resonable browser will
probably render it even if it's some not widely used one.

'button' attribute is used to define the 3D effect that will be applied
at the border of the title box.
Interesting samples are
  button "button.png"
or
  button "round.png" bsize 16 16 margin 7 7 7 7
So, 'button' attribute is used to select the .png image to use in the
/pliant/protocol/http/common/icon/ directory,
or alternatively, you could use:
  button "/pliant/protocol/http/common/icon/button.png"
and it could be used to specify an icon in any directory of your Pliant tree
provided the directory contains '/icon/' (for security versus simplicity
tradeoff)
Now 'bsize x y' means resize the image to x by y pixels (the default is to
rely on the resolution of the PNG file to compute it's exact size in milimeters,
then assume that the browser resolution is 72 pixels per inch)
and finaly 'margin left top right bottom' is used to specify what the central
part is. The central part is the one that will be extended to contain all the
content of the title, the margins will remain unchanged.

Then 'round' is a simpler alternative to 'button' where you specify only how
many rounded pixels you want in the corners, with no 3D effects.

'bgcolor' means the ground color of the box surrounding the title, so is
effective only if you use 'button' or 'pixel' to define the kind of box to
draw around the title text.


Now, back to the styling machinery, these are quite a lot of potencial parameters
for a title, so there is a machanism that will enable to omit most of these
most of the time. This is what I'm now going to express.

You can see the all set of tags and attributes values as a set of trippes
(tag, attribute, value)
Now, for each tag+attribute, we have a default value provided at tag definition
though the 'attr' instruction.
I mean

  html_tag title label
      ...
      attr size Float 36

means that the default value for title/size is 36.

Then, the 'style_setup' section of each style module can modify some of these
values according to the kind of browser issuing the request, the user rights,
the bandwidth load, and so one.

This will be done through instruction like:

push title size 24

The 'push' name of the instruction comes from the low level data structure
handling the value of each tag+attribute at any time.

It is a stack that has been implemented so that it's efficient for setting
a mark, then overwrite some of the tag+attribute values, and finally
rewind all the overwrites.

In a .page, if you write

para (style title size 24)
  [some code]

then it executes a bit like (this is not valid instructions set):
mark
push title size 24
[some code]
rewind

So, now, if you write instruction:

title "my title" logo "/myorg/mysite/mylogo.png"

the the instruction set in facts is:

mark
push title label "my title"
push title logo  "/myorg/mysite/mylogo.png"
execute title tag
rewind

So,

title "my title" logo "/myorg/mysite/mylogo.png"

is truely the same as

title "my title" (style title logo  "/myorg/mysite/mylogo.png")

In other words, when you write a tag instruction, you temporary overwrite
the values associated with the various attributes of the tag, and you can
even overwrite the values associated with other tags though using
(style tag attribute value)
instead of
attribute value

Also, 'style' will allow to overwrite several attributes:

para (style box button "button.png" bsize 64 64 hfont "Hobo" "bold server" 24)
  ...

Summary:
. each tag/attribute as a default value (defined in 'attr' intruction within
  'html_tag' bloc)
. it can be changed at page initialisation time by the 'style_setup' bloc
  of the various involved styles
. it can be changed at any time by a call to the tag, or even by the call
  to another tag through 'style' parameter
. backtracking is done automatically by the low level HtmlStack implementation
  defined in /pliant/protocol/http/stack.pli


Now, any tag will accept to carry usupported attributes:

if you write

para foo "a value"
  [here it is]

then even if 'foo' ID has not be defined in the 'html_tag' instruction defining
'para' tag, the foo="a value" will be stored in the HtmlStack data structure,
and the instruction will be accepted by Pliant compiler. The rendering part
of the 'para' tag is responsible for deciding what to do with the undefined
attributes.

As an example, if you write

cell width "100%"
  [the content]

then it works nicely, because the default style for 'cell' will decide to pass
unmodified the attributes it does not know, so you end with:
<td width="100%>the content<td>




Message posted by hubert.tonneau on 2003/06/16 20:22:44
Now the bottom part of the styling mechanism:

each tag defined through 'html_tag' as a hook set in the HtmlStack data
structure through 'style_tag' instruction in the 'style_setup' bloc of the
style module.

Here is an example:

  style_tag section
    write "<a name=[dq]"+name+"[dq]></a>"

'write' is used to send characters to the browser.

The attributes of the tag can be used as if they where local varibles thanks
to the styling meta programming layer, so 'name' is the value of the 'name'
attribute defined in:

  html_tag section name
    attr name Str encode

Now, for tags that have a body, such as 'small', we have to instructions:

  style_tag small
    write "<font size=[dq]-1[dq]>"
  style_close small
    write "</font>"

So, if you write

small
  [my text]

in a .page
you get:
<font size=[dq]-1[dq]>my text</font>
in your browser.

It is possible for a tag styling function to get the attributes of other
tags. As an example, the 'chapter' instruction get's the 'button' attribute
of the 'header' tag through:
attribute header button
instead of the shorter
button
we would use in the 'header' tag styling function.

We can also use 'push' instruction in the tag styling functions in order
to temporary overwrite the tag+attribute values so that the change will
be automatically rewinded when the tag ends.

As an example, in the styling function of header we find:
    push level level+1
and this is enough to get the 'level' attribute always specify if we have
a level 1, level 2 or level 3 header.

On the other hand, writing:
  level += 1
would have prevented the rewind mechanism of the HtmlStack data structure
to work properly.

Note: I wonder if I should not add some more meta programming to automatically
translate
  level += 1
to
  push level level+1
Anyway, the current status is that it's not done automatically.


Now, in a style tag function, we can not only know the value of each
attribute, but also know what attributes have been passed in the .page
instruction we are currently handling, and what attributes values have been
inherited from the outside.
This is the 'has' operator:
  if has:family
    ...
in the 'font' style function is used to test if 'family' attribute has been
explicitely passed.


Please read the various 'style_tag' functions in module
/pliant/protocol/http/style/default.style
and tell me what parts need more explainations.
Message posted by hubert.tonneau on 2003/06/16 21:07:50
I've forgotten one point about the way tag+attribute values are assigned:
. there is a default value provided though 'html_tag' instruction
. the site 'Style options' is parsed to overwrite default values
. the various .style 'style_setup' blocs are executed and can overwrite some more
. each tag can temporary overwrite some attributes while it's body is executed


I've also forgotten to specify that most of Pliant advanced styling features are
currently done through tables and bitmaps as opposed to using advanced HTML 4
features.

The bitmaps are created on request (with a cache mechanism implemented
in /pliant/protocol/http/common/cache.pli) in /pliant/protocol/http/common/virtual_tree.html

/common/corner... one rounded corner (old style)
/common/border... the borders of a 3D effect
/common/text... server side rendered text
/common/button... server side rendered buttons
/common/icon... server side rendered icons

In order to check server side rendering you can try the following code in a
.page (provided the 'Century Gothic' Type 1 is available to Pliant):

font font "Century Gothic" "server" 16
  [This is some server renderd text]

the Pliant HTTP server will output each word of the sentence through a bitmap.
The main limit is that it's bandwidth consuming, CPU power consuming, and
that the bitmaps cannot be baseline aligned since there is no such notion
in HTML, so if you use several faces or sizes on a single line, the vertical
alignment will not be perfect.


Server side rendered icons means the icon is server side rescaled put on top of
of button which is colored, and the transparency is applied according to the
background color.


You should also experiment with the server side rendered button (I assume
previous explainations about titles should be enough to set server side
generator parameters), and with the new 'box' button.

I've replace the old
note right 0.30
  [content]
note inline
  [the content]

with
box right width "30%"
  [content]
box
  [the content]
Once again, the 'box' tag basically uses the same set of attributes as 'title'
or 'button' to specify how to draw the border of the box.