KoalaRainbow :: Tags


Don't forget to check the examples if you want to see these things used practically.

Top-Level Tags

The following tags may be used anywhere in MovableType templates (or in the visualization lab).  Currently, this is just the MTKRVisualization tag, but at some point the ability to use KRQL for textual purposes will probably be implemented.

MTKRVisualization

Creates a visualization, producing a .png image file as output.  Note that when used inside the visualization "lab", the resulting image will always be written to "krtvis.png" in the root of the blog against which you were authenticated.  Since the visualization lab just looks for the first blog where you have permission to edit templates, there's no guarantee of which blog that will be (if you have multiple blogs), although it will presumably be consistent.

When all and said and done, all that this tag will output to the template that encloses it is an img tag pointing at the generated visualization image.

Concept

The MTKRVisualization tag serves as the container for all of the drawing nodes.

Filename Concerns

Unfortunately, the current implementation of MT makes it impossible to determine the name of the file that will result from the generation of the current template instance, at least in a sane fashion.  Automatic mechanisms to attempt to reverse engineer the information are a lost cause because the only context information available to us is the same information that MTEntries would set.  As such, the most intuitive approach is to have you, the user, just explicitly state the name of the file with some help from MT's date formatting mechanism.

So here's how it works.  If there is a timestamp context at the time of the MTKRVisualization tag, the filename will be run through the MT date formatter using the current timestamp.  (The timestamp will be set to the creation date of an entry if it's a specific entry, or to the start of the range associated with a given archive, etc.  I provide reasonable idioms below.)  If there is no timestamp context, the filename is used as is.  Processed or not, this filename (which may include path info) is appended to the current blog's base location to figure out where to save the file.

Of course, it's not completely that simple.  Specifically, you may find that you want to generate a bunch of visualizations at once, at which point you need the ability to generate the filename using KRQL.  Our solution is then that we provide two attributes you can use.  If you use "filename", we treat it as a string, not a KRQL query.  We do the date magic described above, then use it.  If you use "filename_dyn" then we know it is a KRQL query, and we evaluate it to get the string that we then pass to the date-transform, and then we use it.  When using filename_dyn you will probably want to use the concat function that allows you to concatenate things together.  For example, you could do "concat('images/foo-', position(), '.png')" if generating a visualization for every item in a set.  If there was date formatting involved, just put the fancy % codes in one of the string literals.  If you are going to do a visualization on a per-entry basis, you will probably need to use filename_dyn; see below.
 
For a description of the MT date tag formats, please see the MT Tag Manual Date Tags Section.  For your leisure, I include the following suggestions.  Note that "archives/" is a configurable variable on a per-blog basis.  I assume most people will follow this idiom, but if you put them somewhere else, be sure to change archives/ appropriately.  If you put them somewhere that is not directly beneath the blog's root, you're either going to need to use relative paths involving "..", or perhaps come up with a good solution and let me know.  (I'm developing this part last, and under time pressure, so it's distinctly not the best solution.)

Also keep in mind with these that the default archive mappings map all date-based archives to a single template.  If you're going to be generating more than one type of date-based archive, as things stand, you will probably need to bind each one to a separate template instance.  Them's the breaks.  Do this by going to the 'templates' page and 'create new archive template'.  Once you make this template (just copy over you existing template...), you can then go to your 'weblog config', and on the 'archive files' page, 'create a new template/archive type association' between the given archive type and your new template.

Attributes

Note that all of the following attributes are actually KRQL queries, but that there is no implied context, so if you choose to work with a set, you will need to fetch it via a global set query or via a function call (such as mtenv()).  This allows for dynamically setting the width or height of an image, if desired.

Visualization Data/Control Tags

The following tags may only be used within a KRVisualization tag.

MTKRVsetset

All of the attributes of a MTKRVsetset tag are evaluated as KRQL queries in a set context, and their values are saved to the KRQL global environment using the attribute name they are associated with.  For example, the <MTKRVsetset foo="/entries[days_old(created_on) { 4"> will save the set of all entries less than 4 days old to the variable foo.  This can then be accessed later via $foo.

It is important to note that the values are not saved to the environment until after all the queries have been evaluated.  This means that the queries in a single MTKRVsetset tag cannot depend on a value assigned in the same tag.  If you need to derive a value from another variable, it needs to have been set in a previous tag.

MTKRVsetval

All of the attributes of a MTKRVsetset tag are evaluated as KRQL queries in a value context, and their values are saved to the KRQL global environment using the attribute name they are associated with.  For example, the <MTKRVsetval bar="add(1, 3)"> will save 3 to the variable bar.  This can later be retrieved via $bar.

It is important to note that the values are not saved to the environment until after all the queries have been evaluated.  This means that the queries in a single MTKRVsetset tag cannot depend on a value assigned in the same tag.  If you need to derive a value from another variable, it needs to have been set in a previous tag.

MTKRVloop

MTKRVloop takes a set and iterates over the contents of the set resulting from the execution of the contents of the query attribute.  For each object in the set, it creates a new singleton set that becomes the 'current set' for the body of the loop.  Additionally, it assigns this singleton set to the variable name found in the name attribute.  This allows the value to be accessed explicitly, without depending on the 'current set' (which quickly can become impossible to get to.)

MTKRVloop is a container tag, and evaluates its entire contents for each iteration of the loop.  Nominally the contents of the loop will just be other tags described in this document, but if you can think of a useful way to use other tags and actually get values from them, feel free to use them.  Keep in mind that MTKRVisualization only returns an img tag, so no text output is going to show up from this.

Loops may be nested to your heart's content.  To help increase clarity (and simplify text searching), I have created additional tag definitions like "MTKRVloop#" for 0, 1, 2, 3, and 4.  You can use these if you want, or you can just use the normal MTKRVloop for all of your nesting needs.  They're all the same inside.

Attributes

MTKRVif

A conditional tag that evaluates the query found in the 'test' attribute in a boolean context.  If the result of the test is true, the contents of the conditional tag are evaluated.  If it is false, they are not.  I honestly don't know if the MTElse tag works with this.  My impression is that it should because we define it as a conditional tag, but I could be wrong.

Attributes

Visualization Draw Tags

A quick hard-coded teaser:


<MTKRVisualization width="200" height="200" bg="rgb(230, 230, 230)">
  <MTKRVsquare x="50" y="50" edge="50" fillcolor="color('blue')" edgecolor="color('black')" layer="1">
  <MTKRVrect x="50" y="75" width="20" height="40" fillcolor="color('#eeeeff')" edgecolor="color('black')" layer="2">
  <MTKRVcircle x="100" y="100" edge="100" fillcolor="color('red')" edgecolor="color('black')" layer="0">
  <MTKRVcircle x="100" y="100" edge="140" fillcolor="color('pink')" edgecolor="color('black')" layer="5" startang="0" endang="60">
  <MTKRVellipse x="135" y="100" width="70" height="40" startang="180" endang="360" fillcolor="rgb(190, 240, 200)" edgecolor="color('black')" layer="3">
  <MTKRVline x1="10" y1="190" x2="100" y2="100" layer="10" edgecolor="hsv(0.8, 0.8, 0.6)">
</MTKRVisualization>

The following tags may only be used within a KRVisualization tag.

common attributes (all)

common attributes (shapes, not lines)

Take care not to try and apply contradicting position/size information.  It'll be consistent, but possibly not what you'd expect.  Note that all of these attributes are evaluated (in a value context.)

MTKRVsquare

Draws a square.

Attributes (those not already found in common attributes):

MTKRVrect

Draws a rectangle, which is technically referred to as a "square that someone sat on, and then possibly rotated by 90 degrees; 270 degrees is theoretically possible, but takes 3 times the turning, and my wrist hurts when I try to do that."

No new attributes.

MTKRVcircle/MTKRVellipse

Draws a circle or an ellipse.  They're actually the same thing.  It's a secret though, so keep it on the down low. A circle is defined by the square in which it is circumscribed (same deal for the ellipse.)

Attributes (those not already found in common attributes):

MTKRVline

Draw a line!  fun fun fun!

Attributes (those not already found in common attributes):

MTKRVfilter

This mechanism allows you to apply filters to your drawing to help provide a more natural feel.  At this time there really aren't so many filters, but... some day!

It is important to note that 'layers' as implemented do not result in separate images that are then composited together.  Layers are just a mechanism to allow a different drawing sequence to be used than the order in which nodes are added to the image.  This has been further extended by associating filters with a layer so they are applied after the nodes in that layer is drawn.  This allows neat tricks like drawing your image twice, once on layer 0 and once on layer 1 and then having a blur happen on layer 0.  This creates a nice (to me) soft effect behind the image, with your true drawing then laid overtop.  Clearly it would be nice to have the flexibility to do all kinds of crazy image processing, but the key idea right now is intuitive-ness and not enough time.

Attributes For KRVfilter

Supported Filters and their attributes:

Copyright 2004, Andrew Sutherland