INPUT /  OUTPUT /  LANGUAGE





Defining Your Own Tags

As your interfaces grow, you'll find yourself writing the same tag over and over with the same fields: every heading with the same size and colour, every card with the same border and layout. The class tag lets you define a new kind of tag of your own, and then use it as often as you like, just like a built-in tag.


A first class

<important:class *=<span bold=true color={orange}>>

This is <important {really}> worth knowing.</n>
And so is <important {this}>.
This is really worth knowing.
And so is this.

The first line defines a new tag type called important. After that, <important ...> works like any other tag.

The * field holds the definition: a single tag that each new important tag is made from. You saw the same * field in the chapter on arrays, and it works the same way. Here, the definition is a bold, orange span. Anything you put in an important tag's primary field goes into the span's primary field.

The name you give a class is the name of the new tag type. Like any other name, it can be used anywhere in the scope where you created it.

Building something bigger

A definition can be as complicated as you like, as long as it's a single tag on the outside. Here's a class for the profile card from the chapter on making things look good:

<card:class _=name job=job *=
    <box width=16,em border=2 borderColor=x2E8B57 margin=1,em spacing=0.5,em align={center} {
        <name:span size=18,pt bold=true color=x2E8B57 {}></n>
        <job:span italic=true {}>
    }>
>

<card job={Mathematician} {Ada Lovelace}>
<card job={Computer scientist} {Grace Hopper}>
<card job={Mathematician} {Alan Turing}>
Ada Lovelace
Mathematician
Grace Hopper
Computer scientist
Alan Turing
Mathematician

Three cards, each with three lines of code instead of eight. And if you decide the cards should be blue, you only have to change the definition.

This class has two new fields of its own, which need explaining.

Choosing what the outside world sees

The names inside a class definition, like name and job above, are hidden. Someone using a card can't reach inside it and see them. That's deliberate: it means the inside of a class can change without breaking the code that uses it.

To let users of your class get at something inside it, add a field to the class tag. The field's name is the name users will see, and its value is the path to the thing inside the definition that it stands for:

Class fieldMeans
job=jobthe card has a job field, which is the inner span called job
jobColour=job.colora jobColour field, which is the color field of that span
bg=backgroundColora bg field, which is the backgroundColor field of the outer box

The special _ field chooses what the class's primary field stands for. In the card, _=name means the text in a card's primary field goes into the name span. Without _, the primary field is the primary field of the outer tag in the definition, as it was for important.

Once a field is exposed, it works like any other field, both when creating the tag and afterwards:

<ada:card job={Mathematician} {Ada Lovelace}>
<ada.job {Mathematician and writer}>
<putLn ada>                       <! sends "Ada Lovelace" !>

Anything inside the definition that you don't expose stays hidden, even from code that reaches the card through a reference pointer.

Fields the class doesn't mention

An exposed field doesn't need to be in the definition already. The card's outer box isn't given a backgroundColor, but with bg=backgroundColor exposed, every card's box gains one, ready for <ada.bg {lavender}>. It's the same rule as for any tag: a field is there as soon as it's used.

You can also give an instance fields the class doesn't expose at all. They go to the instance's primary tag: the tag that _ points to, or the outer tag of the definition if there's no _. In the card, that's the name span:

<ada:card job={Mathematician} underline=true {Ada Lovelace}>   <! underlines the name !>
<ada.backgroundColor {yellow}>                                 <! highlights the name !>

As with any tag, it doesn't matter whether you give such a field when you create the instance or later, and each card has its own.

There's one exception. A field the definition already gives that tag belongs to the class, unless the class exposes it. The definition gives the name span a colour, so a card ignores color={red}, and <ada.color {red}> is an invalid reference. That keeps the class in charge of its own design. If you want people to change something the definition sets, expose it.

Settings that shape the whole tag

An exposed field doesn't have to be something you'd see. It can be a setting that the rest of the definition works things out from. Here's a heading class where you give a level, and the class decides the size:

<heading:class _=text level=level *=
  <span bold=true {
    <level:scalar 1>
    </p><text:span size=<sub 50, <mul 10, level>>,px {}></p>
  }>
>

<heading {Top level heading}>
<heading level=2 {Sub-heading}>
<heading level=3 {Minor heading}>
Body text
Top level heading

Sub-heading

Minor heading

Body text

How does a level 3 heading end up 20 pixels high, when the definition sets level to 1? The values you give when you create a tag take the place of the ones in the definition. For the third heading, the level scalar is created holding 3 instead of 1, and the size is then worked out from that. The 1 in the definition only matters when you don't give a level, which makes it the default.

What takes the place of the 1 is the value you gave, worked out where you wrote it. So a level can be calculated, or come from something of your own:

<depth:scalar 2>
<heading level=<add depth, 1> {Minor heading}>      <! level 3 !>
<heading level=depth {Sub-heading}>                 <! level 2 !>

Each heading gets the number depth held (or that number plus one) at the moment it was created. It doesn't keep any link to depth: change depth later, and the headings stay as they are.

The setting is called level both inside and outside the class, but it doesn't have to be. The class field level=level says "the class's level field is the scalar called level inside the definition", just as job=job did for the card.

One thing a class isn't is a spreadsheet. The size is worked out once, when the heading is created. If you give a heading a new level later, with <h.level 2>, the level changes but the size stays as it was.

That's only true of things worked out from a setting. A class field that stands for a field of a tag inside the definition, like jobColour=job.color on the card, is that field. Change it, and the job title changes colour straight away, just as if you'd changed the span's colour yourself. The span already knows what to do with a new colour. A scalar like level doesn't: it just holds a value, and does nothing when the value changes unless you tell it what to do.

The job span in the definition doesn't need a colour of its own for jobColour to work. Like any tag, it gains a color field when one is first needed.

To tell a setting like level what to do when its value changes, you could give it onSet code, which is carried out whenever the setting is assigned a new value. (Other event fields, like onPush and onClear, can react to other kinds of change.) Here's an example using onSet:

<status:class _=text ok=ok *=
  <span {
    <ok:scalar true onSet=<if ok then=<text.color {green}> else=<text.color {red}>>>
    <text:span color=<if ok then={green} else={red}> {}>
  }>
>

<web:status {Web server}></n>
<mail:status ok=false {Mail server}></n>
<mail.ok true>      <! the mail server turns green !>

The colour is set in two places, and each has its own job. The color field gives each status the right colour to begin with, and the onSet code keeps it right whenever ok changes afterwards.

Your names, not the class's

The card class has a hidden span called name. What happens if your program has something called name too, and you use it in a card?

<name:scalar {Grace Hopper}>
<card job={Computer scientist} {<name>}>

The card says "Grace Hopper". Everything you give an instance, whether values, code or content, is worked out where you wrote it, using your names. The names hidden inside the class never get in the way. Hiding works in both directions: you can't see into a class, and the class's insides can't take over the names you use.

The same goes for names you create in an instance's content. They belong to the instance, so you can reach them through its name:

<ada:card job={Mathematician} {<first:span underline=true {Ada}> Lovelace}>
<putLn ada.first>                 <! sends "Ada" !>

Here first is a span you made yourself and put in the card, so it's yours to use, even though it sits inside the card's hidden name span.

Classes with behaviour

A definition can include code fields too, so every tag made from the class also behaves the same way. Here's the "picking a box" example from the chapter on reference pointers again, with the repeated code moved into a class:

print('''
<selected:scalar null>

<choice:class _=label bg=backgroundColor fg=color *=
    <self:box width=100 height=60 border=1
        onClick=
            <if selected then=<selected.*.bg null>, <selected.*.fg null>>,
            <selected self.&>,
            <selected.*.bg {gold}>,
            <selected.*.fg {black}>,
            <putLn label>
        {<label:span {}>}
    >
>

<choice {A}> <choice {B}> <choice {C}> <choice {D}>
''')

while True:
    print('You picked ' + input() + '.</n>')
ABCD
You picked B.

Adding a fifth box now takes a few characters, rather than another ten lines. Some things to notice:

A code field can be exposed like any other. If it is, code you give that field when you create an instance replaces the definition's code for that instance. It isn't added to it. Instances that don't give the field keep the definition's code, which works as a default, just as the 1 did for the heading's level.

What can be a class?

A class definition can be any presentation tag, presentation container tag or persistent logic tag. It can't be a transient logic tag, since those don't leave anything behind to be an instance of the class.


Try it

  1. Make a warning class: a box with a red border and a bold "Warning:" before whatever text you give it.
  2. Add a colour field to the card class that changes the card's border colour.
  3. Turn the noughts and crosses square from the chapter on arrays into a class, and use it in the array's definition.
  4. In the picking example, expose the box's width as a field, and make one box twice as wide as the others.