Cell Properties

Note on 'property' terminology:

  • Because HFL supports both properties of cells in the cell tree and javascript object properties, there can be confusion as to which one is being referred to in this manual.

Cell Properties:

  • In HFL you can set cell properties using either HTML attribute syntax or CSS property syntax anywhere within code block bodies. Either syntax will have the same effect, and they can be used interchangeably, and in any order or combination.
  • One can use whichever syntax seems the most convenient. Some property assignments can be CSS-style, others attribute-style. Any attribute can be expressed in property syntax, and the converse is almost true. The exceptions are for properties that use the colon ':' qualifiers.
  • Setting cell properties using attribute syntax
  • Cell properties set using attribute syntax have the form of assignments, and must not have a terminating semi-colon.
  • The attribute values should be quoted. (Although HFL will accept unquoted values as well, quotes are a much safer way of expressing the value.)
  • SYNTAX
    • <attr> = <attr-value>
       
      where:
      <attr-value>
      :=
      <quoted-value> | <value> | <var-value>
      <quoted-value>
      :=
      "<value>" | '<value>'
      <var-value>
      :=
      $<var-name>
  • Attribute values can be references to variables, provided the variable name begins with a '$'.
  • Attribute values can be references to pseudo-variables. (See below.)
  • If double-quoted strings are used, any '$'-prefixed variable references will be expanded within the string.
  • Attribute values cannot however be arbitrary expressions, as the result would be indistiguishable from a normal assignment statement, and therefore ambiguous. If an expression value is needed, it must be first assigned to a '$'-variable, and the variable used in the attribute-assignment statement.
  • EXAMPLES:

    • color = "red"
      width = "100%"
      $hgt = $parent_hgt/2;
      height = $hgt;
      href="foobar.html"

  • Setting cell properties using CSS property syntax
  • Cell properties can be set using CSS property syntax, but the statement must have a terminating semi-colon.
  • SYNTAX
    • <prop-name>: <expression>;
  • Property syntax allows any valid arbitrary expression for the value. As such, it has fewer restrictions than attribute syntax.
  • EXAMPLES:

    • color:red;
      width:$width/2;                           // Halves the width
      href="$HREF_PATH/$href"                   // Prepend href with path  
  • Getting current property values
  • CSS and HTML provide a way for application code to set the value of properties, but not to get their current values. This is because they have no ability to do programatic actions, and thus do not have variables.
  • HFL is a programming language, it does use variables, and thus it has a need to be able to fetch the current values of properties.
  • Rather than require a function call or a dot-operator to fetch property values, HFL instead fetches property values using pseudo-variables, as discussed next.
  • Deleting property values
  • Properties can be completely removed from a scope using the deleteProp() function.
  • deleteProp (<prop-name-string>)
    • Deletes the cell property given by the property name string. The property must be specified as a quoted string or a value that evaluates to a string.
    • EXAMPLE:

      • page_next { deleteProp('title'); }

Pseudo-Variables

  • Pseudo-variables are language components that have the appearance and syntax of a variable reference, but in fact are accessing properties or internal state, often as function calls.
  • All pseudo-variable names begin with a leading '$'.
  • Pseudo-variables can be used anywhere a normal variable can used. In particular, because the variable names begin with a '$', references to pseudo-variables will be replaced with their property's value if used inside of double-quoted strings.
  • There are two types: property pseudo-variables and built-in pseudo-variables.
  • Property Pseudo-Variables
  • Most properties (e.g. color and width) can be accessed using pseudo-variables having the same name with a '$' in front, (e.g. $color and $width).
  • If the property has a hyphen in the name (e.g. margin-left), the corresponding pseudo-variable has an underscore in place of the hyphen (e.g. $margin_left).
  • The big advantage of the pseudo-variable syntax is that the property values can be expanded inside of double-quoted strings, which keeps the code clean and easy to read.
  • NOTE: Avoid creating or assigning to variables with leading '$' characters that have the same name as cell properties, as they will override and replace their usage as pseudo-variables.
  • EXAMPLES:

    • // Property pseudo-variables
      color:red; print("THE COLOR IS $color");  // Prints 'THE COLOR IS red'
      width:$width/2;                           // Halves the width
      href="$HREF_PATH/$href"                   // Prepend href with path  

      // WARNING: accidental override of pseudo-variable '$color'
      $color = 'blue';                          // Oops: '$color' is now a variable

  • Built-in Pseudo-variables
  • Built-in pseudo-variables return important internal state values. Most report the current scope engine state values, making it easier for code to know what is being processed.
    • Built-in pseudo-variables:
       
      $tag
      Returns the current cell's 'tag' value, if any
      $class
      Returns the current cell's .class value, if any
      $id
      Returns the current cell's #id value, if any
      $text
      Returns the current cell's own text content, if any
      $alltext
      Returns the current scopes's text content, including
      all of the content of child cells, if any
      $cell_num
      Returns the cell number of the first cell of the
      range of the current scope.
      $cell_num_last
      Returns the cell number of the last cell of the
      range of the current scope.
      $cell_range
      Returns the range of cells of the current scope
      as an array of two elements.
      $scope_count
      Returns the counter value of the current scope's innermost
      scope. This can be useful in debugging print statements.
      $page_num
      Returns the scope-start value of the parent page containing
      the current scope
      $page_filename
      Returns the output file name the parent page, if a name
      has been assigned
      $HFL_VERSION
      Returns the current HFL version number as a string
  • EXAMPLES:

    • if ($tag != 'div') { class='content' }    // Set class in non <div>s
      print("CURRENT CELL IS $cell_num");       // Print curr cell#
      $sz = substr($text, 1, -1);  text = $sz   // Trim quotes off string cell
      if (!$class) { class = "myclass" }        // Set class if none

Class Property Support

  • Classes are a bit of an unusual property, because a cell can have more than one class bound to it.
  • A single class binding is a single string.
  • If a cell has multiple classes, the class binding becomes an array of strings.
  • As a syntactic shortcut, and to preserve HTML syntax compatibility, multiple classes can be specified as a single string, and the parser will break them into individual strings, as would the browser.
  • But HFL uses classes as part of its scope specfications, which makes it important that they be as easy to set as are tags and ids.
  • Because HFL is a programming language, the class values are open to being manipulated, not just assigned one time as they would be in HTML. This requires some functionality that goes beyond the syntax used by HTML.
  • class = "<class-list>"
    • Sets the specified class for the cells of the current scope.
  • class += "<class-name>"
    • Adds the specified class to the list of classes bound to the cells of the current scope.
    • The reason for this operator (function) is to make it easy to add a class to possible existing classes of a cell.
    • The only reason this is even slightly difficult is that how that would be coded depends upon whether or not the cell already has a class.
      • For example, if cell p:1 has no class value yet, and we wish to add class "nav_parent", it would be a simple attribute assignment:

        • p:1 { class = "indented" }
      • But if the cell p:1 already had class "nav", we would have to insert a blank in front, as in:

        • p:1 { class = "$class indented" }
      • Instead, we can use the += operator. It works in both cases, and is clearer in intent:

        • p:1 { class += "indented" }

    • EXAMPLE

    • p:1{
        class="nav"
        print("CLASS IS |$class|");   // Prints: "CLASS IS |nav|"
        class += "nav_parent"
        print("CLASS IS |$class|");   // Prints: "CLASS IS |nav nav_parent|"
        class += "indented"
        print("CLASS IS |$class|");   // Prints: "CLASS IS |nav nav_parent indented|"
        }

  • hasClass (<class_name>)
    • Returns whether the cell of the current scope has the specified class as one of its classes. This function is often useful for detecting cells that are marked with temporary class names.
    • EXAMPLE:

    • // Mark nav bar by adding a temp class
      nav_bar { class+="__nav_bar_override" }

          ...

      // Later test if nav_bar was marked by testing for the temp class
      nav_bar {
        if (hasClass('__nav_bar_override')) {
          // Do something
          } }

  • removeClass ("<class-name>")
    • Removes the specified class from the list of classes bound to the cells of the current scope.
    • This function is the semantic inverse of the class '+=' operator.
    • EXAMPLE

    • p:1{
        // Assign 3 classes to the cell
        class="nav nav_parent indented"
        print("CLASS IS |$class|");   // Prints: "CLASS IS |nav nav_parent indented|"
        
        // Remove class 'nav_parent'
        removeClass("nav_parent");
        print("CLASS IS |$class|");   // Prints: "CLASS IS |nav indented|"
        }

Previous: Variables Next: Flow Control And Functions