StippleUI.jl

StippleUI is a library of reactive UI elements for Stipple.jl.

together with

• Stipple.jl,
• StipplePlotly.jl and
• Genie.jl

it is part of the GenieFramework, a powerful and complete solution for building beautiful, responsive, reactive, high performance interactive data dashboards in pure Julia.

StippleUI provides over 30 UI elements, including forms and form inputs (button, slider, checkbox, radio, toggle, range), lists, data tables, higher level components (badges, banners, cards, dialogs, chips, icons), and layout elements (row, col, dashboard, heading, space) from the Quasar Framework.

News: Vue 3 / Quasar 2

From version 0.24 on StippleUI has upgraded the front-end libraries to Vue3 / Quasar 2, as Vue-2 has reached its end-of-life.

We have put lots of effort in making migration as easy as possible. Nevertheless, there are some places where advanced user interfaces might need a little tweeking.

Main Changes for version >= v0.24

Components

• General: Syncing of additional fields is no longer done with the syntax fieldname.sync but rather with v-model:fieldname. This is already taken care of by the components' API, e.g. paginationsync in table(). If you have manually added such fields you need to adapt your code.
• Quasars's Table component has changed the naming of the content attribute from data to rows. Accordingly, all references in templates should be changed to rows in the long run, e.g. table(:mytable, @showif("mytable.data.length")) should be changed to table(:mytable, @showif("mytable.data.length")). However, we have introduced a watcher that sets a second field named 'data' to the 'rows' field, which will keep old code running in most cases. The only disadvantage of that solution is that syncing the table content back to the server sends the double amount of data; so that helper might be deprecated in the future.

More Migration Support

• Stipple's README https://github.com/GenieFramework/Stipple.jl/blob/master/README.md
• Quasar upgrade guide: site: https://quasar.dev/start/upgrade-guide/
• Vue migration guide: https://v3-migration.vuejs.org/

Installation

pkg> add StippleUI

Usage

Quasar Components

StippleUI defines functions for most of the quasar vue components. Most functions are named like their Quasar counterparts, e.g. btn() for q-btn, tab() for q-tab, etc. Some functions have received different names for clarity, e.g. textfield() for q-input with text type and numberfield() for q-input with number type. Most functions have named positional arguments that are used for definition of common attributes, e.g. label or fieldname. Besides that all functions have a general calling scheme for unnamed arguments and keyword arguments:

• if a component supports content, the first non-named positional argument is passed as content to the components.
• any following non-array argument is passed as parameter to the components
• any non-named array argument is joined and passed as content
• if a component does not support content, e.g. btn(), all non-named arguments except arrays are passed as parameter. (Passing arrays can be used to define templates for a component. More details can be found in Vue.js docs.)
• keyword arguments are passed pretty much the same as the Julia expression, except that
  • __ is converted to -
  • ! in the middle of a keyword is converted to .
  • ! at the end of a keyword indicates that the argument should be treated as js expression
  • a Symbol as value of a keyword argument indicates that the argument should be treated as js expression
  • non-standard characters which are not allowed in Julia variable names can be used by employing the var""notation, e.g. span(var"v-html" = "My Text with <br>new lines")
  • most variable names that contain a dash in Vue-syntax are automatically replaced, e.g. "leftlabel" => "left-label". All standard mappings can be found in StippleUI.API.ATTRIBUTES_MAPPINGS

Examples

julia> btn("Just do it!", @click(:mybutton), loading = :mybutton) |> println
<q-btn :loading="mybutton" label="Just do it!" v-on:click="mybutton = true"></q-btn>

julia> textfield("Label", :mytext) |> println
<q-input label="Label" v-model="mytext"></q-input>

What if a component is missing?

If a quasar component is not yet covered by StippleUI, you can still use the quasar() function to make it available in your UI:

julia> quasar(:btn, label = "Action!") |> println
<q-btn label="Action!"></q-btn>

In a very similar way, you can also integrate vue components or any other html component:

julia> vue(:calender, date = "today", "This is still a dream!")
"<vue-calender date=\"today\">This is still a dream!</vue-calender>"

julia> xelem(:br)
"<br></br>"

Bindings

There are two ways of assigning component properties

• assignment of a string value: attribute = "lorem ipsum"

• assignment of a Javascript expression, by

  • assigning a Symbol attribute = :input
  • or by appending a !-character to the attribute attribute! = "input"

  In most cases this syntax is used to directly bind app variables, but you can also bind more complicated expressions, e.g. array elements (note that js has 0-based indexing): attribute = Symbol("data[0]") attribute = R"data[0]" attribute! = "data[0]" The R"" string macro is a convenient way of defining Symbols.

Helper macros

Vue.js has defined several short cuts which typically start with a @-character. In Julia the @-character is reserved for macros. So we decided to use macros to achieve a similar syntax. But we also provide macros to add attributes with other 'forbidden' characters like . or -. Have a look at the docstrings of @click, @on, @iif, @els, @elsiif, @recur, @text, @bind, @data and @showif to learn more. To try out whether rendering is correct enter the tentative expression at the REPL, e.g.

julia> span(@showif(true))
"<span v-show=\"true\"></span>"

julia> span(@click(:mybutton))
"<span v-on:click=\"mybutton = true\"></span>"

Quasar's Flexgrid

Quasar implements a grid system called "Flexgrid" that allows for easy definition of UIs by classes.

A grid can be either vertical (class = "column") or horizontal (class = "row"). The child elements receive their size within that container by setting the class "col" for equally spaced children, or "col-6" for a fixed multiple of 1/12 of the container size (here 6 so 50%). Moreover, Quasar allows for varying child sizes depending on the size of the container, by adding a size-condition after the col class, e.g. "col-md-3", or simply "col-md". In the StippleUI-API we define the attributes col, xs, sm, md, lg, xl to make this class definition more convenient, e.g.

row(htmldiv(col = 2, md = 4)) |> println
# <div class="row"><div class="col-2 col-md-4"></div></div>

Furthermore, spacings between child elements are added by setting the class="gutter-md". In case of children in flex containers (row or column) the setting needs to be class = "gutter-col-md". Again, we have defined an attribute that takes care of the difference and automatically choses the correct setting.

julia> row(gutter = "md", htmldiv(col = 2, md = 4), "Hello World") |> println
<div class="row q-col-gutter-md" Hello World><div class="col-2 col-md-4"></div></div>

Furthermore, children might badly display if they have a background setting, which is due to the way, Quasar sets margins and padding. The way out is to wrap the children in an extra div element, which can conveniently done by using the @guttermacro.

julia> row(gutter = "md", @gutter htmldiv(col = 2, md = 4, "Hello World")) |> println
<div class="row q-col-gutter-md"><div class="col-2 col-md-4"><div>Hello World</div></div></div>

More details can be found in the docstrings.

Javascript code

Vue.js offers the possibility of embedding javascript functions that are called ither manually (methods) or automatically when certain events occur, e.g. watch, mounted, created, computed. Such code can easily be defined by the respective macros @methods, @watch, @mounted, @created, @computed, e.g.

@methods """
logdemo: function(text) {
    console.log("Text from Stipple: " + text)
    return text
},
squaredemo: function(number) {
    console.log("The square of " + number + " is " + number**2)
    return number**2
}
"""

@created """"
    console.log('This app has just been created!')
"""

See the editable tree demo for more information. These macros also work for explicit models, e.g.

@created MyApp """"
    console.log('This app has just been created!')
"""

User-defined events

There is support for user-defined events by the macro @event.

@event :uploaded begin            
    println("Files have been uploaded!")
end

These lines define julia code that is executed when an event from the client is forwarded to the server. Typically, events at the client originate from certain vue components, e.g. q-uploader. They can be forwarded by calling the @on macro with two Symbol arguments.

julia> uploader("Upload files", url = "/upload" , @on(:uploaded, :uploaded))
"<q-uploader url=\"/upload\" v-on:uploaded=\"function(event) { handle_event(event, 'uploaded') }\">Upload files</q-uploader>"