Creating a Frogans slide and viewing it

Update: The “align” attribute has changed for the latest version of Frogans Player for developers alpha (v0.2.1). The contents of this post and the downloadable resources have been updated accordingly. Click here for more info.

Introduction

This post covers the creation of the first slide of a Frogans site. Don’t hesitate to refer to the resources at https://www.frogans.org/en/resources/fsdl/access.html.

Frogans sites are created using the Frogans Slide Description Language (FSDL), version 3.0. FSDL is for Frogans sites what HTML is for Web sites, except that, unlike HTML, FSDL is the only language that is used for creating Frogans sites. This is a serious security advantage for Frogans site users.

FSDL 3.0 is still not fully implemented and its specification is still under development, but you can already create functioning sites with it, using the parts that already work. The sample site that comes with the Frogans Player for Developers download uses a few of these (you can view and modify its FSDL source in test/helloworld/home.fsdl).

Understanding the production chain

Before you start authoring in FSDL 3.0, it’s good to understand how the process works like an production chain.

FSDL uses a model of layers for presenting graphics on a Frogans slide. Each layer is the final step in an production chain of XML elements. Here are some examples showing how the XML elements are chained together:

  1. Example 1: For presenting a simple rectangle, your production chain looks something like this:

    1. <resdraw…> (this XML element is used to create the rectangle, or another form, as a resource)

    2. <layer…> (this element presents that rectangle as a layer on the slide)

  2. Example 2: For presenting an imported image file in a layer, your production chain looks something like this:

    1. <file…> (this creates a reference to the file)

    2. <resimage…> (this creates an image resource from that file)

    3. <layer…> (this presents that resource on your slide using the <layer> element.

These are just two examples of graphic resources that can be presented in layers. Other resources include vector graphics <respath>, blocks of text <restext> and gradient backgrounds <respixels>. (Additionally, settings can also be defined in the production chain, such as for image processing filters <setfilter>, typographic fonts <setfont>, shadows <setshadow> and groups of resources merged together <setmerge>, but these will be covered in other posts.)

To see in detail how these elements go together, let’s put them to work in FSDL 3.0.

Setting up your XML file.

FSDL 3.0 is written in XML. So you start with the XML declaration:

<?xml version='1.0' encoding='utf-8'?>

and then write the FSDL root element,

 

<frogans-fsdl version='3.0'>

 

</frogans-fsdl>

 

The FSDL root element will contain, as children, all of the elements that will make up your Frogans slide.

 

You now have an FSDL document that has no content.

Previewing in Frogans Player for Developers alpha

Before going further, let’s save the slide file for viewing in Frogans Player for Developers alpha. If you haven’t already downloaded and unzipped the software, there’s a tutorial here, and you can find the download page here. Go to the folder containing the Frogans Player software and create a new folder inside the “test” folder and name it “lab1.fsdl.”

 

Now, open Frogans Player, right-click (or ctrl-click for one-button Mac users) on the yellow ball and select “Open a Frogans” in the pop-down menu. Write “test*lab1” as your Frogans address, click “OK” and you should see something like this:

 

Capture

 

That’s right. Frogans Player is very good about telling you what it wants to see in an FSDL document. Let’s see what we can do to satisfy Frogans Player.

Presenting a rectangle in your slide

As shown above, we can create and present a rectangle using a chain of two elements, <resdraw> and <layer>.

 

Let’s start with the <resdraw> element:

 

<resdraw resid='rect1_res' figure='rect' stroke='off' size='640,480' color='#008800' />

This <resdraw> element contains a number of attributes:

  1. “resid” – The value of this mandatory attribute (“rect1_res”) is a unique identifier that can be referred to in one or more other elements, further down the production chain. In this case, it’s going to be referred to in a <layer> element.

  2. “figure” – The value of this mandatory attribute determines whether this is a rectangle (“rect”), a rectangle with rounded corners (“roundrect”) or an ellipse (“ellipse”).

  3. “stroke” – The value of this mandatory attribute determines whether this figure will be displayed as an outline stroke (“on”) or as a solid color (“off”).

  4. “size” – The value of this mandatory attribute determines the size, in pixels, of the rendered resource. 640 by 480 pixels is the maximum value accepted, as it is also the maximum size that a Frogans site may be rendered on a high-definition screen. On a typical desktop computer, or on an older touchscreen smartphone, the site will be rendered at 320 by 240 pixels.

  5. “color” – The value of this optional attribute is the rectangle’s color, expressed in hexadecimal format (Note: don’t forget the # symbol).

[Note that the values are shown using single quotes. At this time, Frogans Player does not accept the use of double quotes within elements.]

Now, let’s write a <layer> element that will present this rectangle:

<layer resref='rect1_res' layerid='rect1_layer' leapout='all' pos='320,240' align='center-middle' combine='add' />

The attributes for this layer are:

  1. “resref” – The value of this mandatory attribute, “rec1_res,” matches the “resid” value in the <resdraw> element above. This tells Frogans Player that this layer will contain and present the rectangle resource defined above.

  2. “layerid” – The value of this mandatory attribute is a string that can be used in Frogans site authoring software for managing layers in the user interface. It is a mandatory attribute, even when coding by hand, as we are doing here.

  3. “leapout” – This is a mandatory attribute. One of the more amazing things about Frogans sites is that each slide can be presented in two different ways, depending the size of the display designated by the user. That way, if the site is made smaller or larger by the user, certain visual elements can appear or disappear so as to optimize the layout for the display size. The “leapout” value of “all” means that the layer will be displayed, no matter what the size of the slide. The value of “lead” means that the layer will be displayed only when the slide is at a size of 50% or larger. Layers that are shown only when the slide is smaller than 50% will have a “leapout” value of “vignette” (although I would have preferred for it to be “rhythm”).

  4. “pos” – The value of this mandatory attribute is the position of the layer on a 640 by 480 grid. So, a value of “320,240” will position halfway across and halfway down the 640 by 480 surface (with respect to the layer’s alignment point – see “align.”

  5. “align” – The value of this optional attribute determines the alignment point from where resource the layer will be positioned. Here, “middle-center” means that the alignment point halfway down and halfway across the surface of the layer would be place on the slide at the coordinates in the value of the “pos” attribute. If it were “top-right,” on the other hand, the rectangle would be placed with its upper right-hand corner at the coordinates in the value of the “pos” attribute. (The default value is “middle-center.”)

  6. “combine” – The value of this mandatory attribute determines how the layer will be rendered with respect to the layers below it:

    1. “add” – When in doubt, use “add” as the value. This means that the layer will be simply be superimposed over the layers below it.

    2. “clip” – This value makes it so that the resource in the layer will be opaque only where there is one or more non-transparent layers below it. For instance, if you place a square image with this attribute value over a round shape, the square image will be cropped within the boundaries of the round shape.

    3. “cutout” – This value makes it so that the opaque areas of the resource in the layer will make the layer(s) below it transparent. It can be used to trim the edges or cut out holes in the lower layers.

    4. “inter” – This value causes this and the lower layer(s) only be seen where this layer is opaque, i.e., where this layer intersects with the others.

You should end up with an FSDL document that looks like this:

<?xml version='1.0' encoding='utf-8'?>

 

<frogans-fsdl version='3.0'>

 

<resdraw resid='rect1_res' figure='rect' stroke='off' size='640,480' color='#008800' />

 

<layer resref='rect1_res' layerid='rect1_layer' leapout='all'pos='320,240' align='center-middle' combine='add' />

 

</frogans-fsdl>

Save your file and reload it in Frogans Player by right-clicking on the Frogans Slide (NOT the yellow ball), and selecting “Reload.” You should see a big, happy green rectangle like this:

Capture2

Importing and presenting an image in your slide

To import and present an external image in your slide you will use a <layer> element, just like you did with the rectangle above. But first, you’ll need to make use of the <file> and <resimage> attributes.

To get the file used for this step click here. Place this file, “pooch.jpg” in the same folder as your FSDL file.

Now, let’s create the <file> element:

<file fileid='pooch_file' nature='static' name='/pooch.jpg' cache='on' />

This <file> element contains the following attributes:

  1. “fileid” – The value for this mandatory attribute (“pooch_file”) is a unique identifier that can be referred to in one or more other elements, further down the production chain. In this example, the other element will be <resimage> for creating an image resource. But the <file> element can be used for other kinds of files, notably other FSDL files for creating links to other slides in the same Frogans site.

  2. “nature” – The value of this mandatory attribute is either “static,” “dynamic” or “embedded.” A file that is “embedded” is embedded as text characters in the <file> element.

  3. “name” – The value of this mandatory attribute is the local path to the file, followed by the name of the file. For instance, if “pooch.jpg” is found in the same folder (or “directory”) as the FSDL file, the path is simply “/”. However, if it is found in a sub-folder, for instance called “images,” the value of the attribute would be “/images/pooch.jpg.”

Now, let’s create a <resimage> element for this image file:

<resimage fileref='pooch_file' resid='pooch_res' size='600,440' />

This <resimage> element contains the following attributes:

  1. “fileref” – The value of this mandatory attribute (“pooch_file”) matches that of the “fileid” attribute in the <file> element. This way, <resimage> knows what image file to use.

  2. “resid” – The value of this mandatory attribute (“pooch_res”) is a unique identifier that can be referred to in one or more other elements, further down the production chain. In this case, it’s going to be referred to in a <layer> element.

  3. “size” – The value of this mandatory attribute determines the size, in pixels, of the rendered resource.

Finally, let’s create a <layer> element for presenting this resource:

<layer resref='pooch_res' layerid='pooch_layer' leapout='lead' pos='20,20' align='left-top' combine='add' />

The attributes used here are the same as those used for the rectangle above. But their values have changed.

  1. “resref” – The value of this attribute (“pooch_res”) matches that of “resid” in the <resimage> element so that the <layer> knows which resource to use.

  2. “layerid” – he value of this attribute (“pooch_layer”) is a unique identifier that can be useful for managing layers in an authoring tool.

  3. “leapout” – The value of this attribute (“lead”) means that this layer will only be displayed when the slide is viewed at a minimum of 50% scale. So, when the slide is made smaller by the end-user, this layer will disappear.

  4. “pos” – The value of this attribute (“20,20”) means that the alignment point of this image resource in this layer will be positioned 20 units from the left edge and 20 units from the top edge (on a field of 640 by 480 units) of the slide.

  5. “align” – The value of this attribute (“top-left”) means that the alignment point for this image resource will be in the upper left hand corner of the image.

[Given that the size of the image in <resimage> is 40 pixels less wide and 40 pixels less high than the rectangle in the lower layer, and that it is positioned 20 by 20 pixels from the top left hand corner, it should be centered on the slide. To get the same result, we could have otherwise used the same “pos” and “align” attribute values as for the rectangle.]

Trying it out

Your FSDL 3.0 file should look like this (pretty small, given the length of this post):

<?xml version='1.0' encoding='utf-8'?>

 

<frogans-fsdl version='3.0'>

 

<resdraw resid='rect1_res' figure='rect' stroke='off' size='640,480' color='#008800' />

 

<layer resref='rect1_res' layerid='rect1_layer' leapout='all' pos='320,240' align='center-middle' combine='add' />

 

<file fileid='pooch_file' nature='static' name='/pooch.jpg' />

 

<resimage fileref='pooch_file' resid='pooch_res' size='600,440' />

 

<layer resref='pooch_res' layerid='pooch_layer' leapout='lead' pos='20,20' align='left-top' combine='add' />

 

</frogans-fsdl>

And your Frogans site should look like this:

Capture3

Test the “leapout” function clicking and dragging the edge of the slide (a zoom symbol should appear below the mouse pointer) or right-click on the site and select “Small size” from the pop-down menu. Your site should now look like this:

Capture4

The end

That’s all for today!

To download the FSDL file and accompanying image file for putting in your “test” folder, click here.

1 Comment

Leave a Reply

Your email address will not be published.


*