GizmoTags and Templates

GizmoTags and templates provide a way to change the page layout and "look" of Metadot pages. GizmoTags are constructs embedded in the HTML templates, and are expanded during the page rendering process to insert content inline. The gizmo tags each correspond to a perl module, and it is the perl module which implements the generation of the inline content. The term `gizmo tag' is a bit of a misnomer: the gizmo tag module may and typically does generate content pertaining to a gizmo object, but it may also generate arbitrary content as well (for example, one gizmo tag inserts a "fortune" into the page).

The gizmo tags correspond to modules defined in <metadot>/metadot/GizmoTags . When a display request is received, a gizmo tag-enabled template is "expanded" by executing the `exec' method corresponding to each tag object, and inserting the resultant HTML in the template.

Templates and GizmoTags are activated by choosing "Style 4" in the Config->Style&Colors page. It is suggested that you start with the default templates shown there and modify them to suit your needs. As is described below, the gizmo tags embedded in the default templates are what determine the page content rendered using the templates, and therefore, as you edit the default templates, make sure that you do not inadvertently delete any gizmo tags which provide content that you want to retain.

The first template, `maintemplate ', is used for creating Metadot's front page. The second template, ` subtemplate ', is used for subcategory pages. The third template, the `utility ' template, is used to display the `detailed view' of all gizmos except Category. E.g., the utility template is the one used if you execute the ` show ' op for a Discussion object.

You can make your site look different by changing the places from where GizmoTags are called, by adding or removing GizmoTags, or by changing the HTML tables layout in the templates.

Gizmo Tags in Page Description Fields (Advanced)

While not documented further, it is possible to use gizmo tags in page description fields.

However, two important warnings must be noted:

Gizmo tags in a description field are NOT preserved if a page is edited using Windows IE. This is because in Windows IE, a WYSIWG HTML editor is used to edit the page's description field. (Thanks to interactivetools.com). This editor will remove any non-standard HTML. You will need to add and edit gizmo tags in a description field using a different browser.
Gizmotag processing does not currently guard against loops generated by using the "wrong" gizmo tags in a description field. For example, using a md_catdesc tag (see list below), which generates the page description, within a page description, will cause an infinite loop when you try to display the page.

Update: As of Metadot 5.5.2.1, it is now possible to use square brackets as well as angle brackets for specifying gizmo tags. This allows the gizmotags to be preserved in a page description field when using the WYSIWYG HTML editor. For example, this construction will now work: [gizmotag name="md_quota_meter"][/gizmotag]

To see GizmoTags in action, follow this simple tutorial:

Gizmotags Tutorial

The following set of steps will illustrate from a user standpoint how gizmotags work. Then, the subsections below describe in more detail how they are implemented.

1. From the main page, log in as "admin" and then Enable Editing

2. From the "Manage" menu go to "Style & Colors".

3. Select "Style 4" on the Global Look selector. This will make the system generate its pages from the templates that follow.

4. There are three templates in Style & Colors: `maintemplate', `subtemplate', and `utilitytemplate'. The first one is used for generating the front page. Let's work with that.

5. Cut and paste the Template for the Style & Colors page to the HTML or text editor of your choice. (This will make the template easier to edit than in the browser text area). .

6. Lets try moving the news column to the left side of the page. We assume that you are starting from the template that comes with Metadot's default content.

7. In the template file in your editor, search for the GizmoTag for rendering the news column, or `newscol'. The name of the GizmoTag is md_newscol (search for the `md_newscol' string). You'll see start and end markers in HTML like this:

 

These are just comments placed there to let you easily find GizmoTags in your template. The only requirement for GizmoTags to work is that the GizmoTag tags themselves be present, like follows:

<GIZMOTAG NAME="md_newscol"> </GIZMOTAG>

The tag element is GIZMOTAG; the `name' attribute is the name of the tag. This name must correspond to the name of some module in <metadot>/metadot/GizmoTags for the template to find and expand the tag.

Note that the template in the default metadot content also includes HTML between these two tags, similar to the content that will be rendered when the template is interpreted. This chunk of HTML between an open and close pair of gizmo tags is optional, and will be removed when the tag is "expanded" and the content from the expansion inserted. It can be useful to have this default HTML in the template in order to allow an HTML editor to render the template similarly to how it will look when all its tags are expanded. If the referenced gizmotag object (e.g. the "md_newscol" object in this example) does not actually exist, then the tag will not be expanded. In this case the default HTML will be retained and displayed.

8. For this example, suppose we want to move this gizmo tag so that it appears in the same place where the ` md_v_subnav ' GizmoTag is. ` md_v_subnav ' is the one in charge of rendering the vertical subcategories column. We need to create an html table around the ` md_v_subnav ' GizmoTag and move the ` md_newscol ' GizmoTag to a row in it. The layout that you should put in the template where ` md_v_subnav ' is should look like this:

<table>
    <tr>
        <td>
            <GIZMOTAG NAME="md_v_subnav">
            </GIZMOTAG>
        </td>
    </tr>
    <tr>
        <td>
            <GIZMOTAG NAME="md_newscol">
            </GIZMOTAG>
        </td>
    </tr>
</table>

For clarity we have left out the HTML comments and the default HTML within the gizmo tags.

After you do this change, copy the template back to the Colors & Styles page, save and return to the main page. That's it! You should now see that the newscolumn appears on the left side.

Changing Gizmotag Styles

Each GizmoTag is defined to have an associated CSS style class name . For the associated style class to have any effect when the gizmo tag is used, a style rule for the class must be defined in the HTML. With templates, the "Style Sheet" box in the Manage..->Styles & Colors config page is not used. Instead, any style rules used within a template must be defined in the template HTML itself. To do this, you must identify the style name for the GizmoTag you want to modify, and then define a style for it in your template (some gizmotag styles are already defined in the default templates). You will find GizmoTag style names listed in a column in the GizmoTag browser, accessed through the Gizmo Browser page mode. (See Section 10 for more information).

7.2.1 Example:

` md_date ' is a GizmoTag that will display today's date and time when rendered. To change the font style and color for the `md_date ' GizmoTag, go to Manage->Style&Colors and enter the following line inside the <style></style> section for the template you are modifying:

.tagDateClass { font-family: Helvetica, Verdana,Arial,sans-serif; font-size: 10pt; color: red;}

Make sure your Global Look style is set to 4, and save your template. You'll notice that the date now appears in red and with a smaller type.

Metadot Gizmo Tags

The following are the GizmoTags that come bundled with the Metadot distribution. Any of them may be embedded in a template via a GIZMOTAG as described in the examples above.

Some of these gizmo tags take additional attribute "arguments" in addition to the required name attribute. (For example, see the md_imagesrc gizmo tag below).

All gizmotags may be passed the optional attribute/value pair no_comments="1" . For example:

<gizmotag name="md_title" no_comments="1">...</gizmotag>

The `no_comments' attribute suppresses the comment lines that are normally placed around each expanded gizmotag in the html. Sometimes the comments are detrimental, for example if you wish to place the gizmotag expansion results in a <title>..</title> HTML element. The `no_comments' option works for any gizmotag.

md_adminbar : Will display a bar with two combos for adding gizmos to a page and for going to different management sections. It will also display a button to enable/disable Edit mode. The two combos will only show up when in Edit mode.

md_applicationlist : display Applications, the list of all the applications within the category

md_calendar_month : displays the month view of a calendar for navigation.

md_catlist : display categories, the list of all the sub-categories within the category.

md_catdesc : Will display the description field of the current category.

md_catname : Will display the name field of the current category.

md_catpath : Will display the path of clickable names from home to current category.

md_gizmopath : Will display the path of clickable names from home to current gizmo. A more general version of the md_catpath gizmotag.

md_clipboard : displays the clipboard interface

md_cat2col : Will display the categories and subcategories under the current category as a wide two-column list.

md_date : Will display today's date and time (e.g.. Sun Oct 7 16:55:57 2002).

md_discussionlist : display Discussions, the list of all the discussions within the category

md_editpanel : Generates the `edit panel' info for the current object -- the edit, permissions, cut, etc. icons.

md_fortune : Display a random (sometimes funny) message.

md_h_topcat : Displays a horizontal list with the topmost categories.

md_h_topnav : Displays a horizontal list with subcategories of the current category.

md_imagelist : Display list of all ImageItem children of the category

md_imagesrc : Given image name passed as an `image' attribute, generates full server path to image (as configured when the site was set up). You will want to use this gizmotag with the `no_comments' attribute as described above to suppress the extra comment output. For example:

<gizmotag name="md_imagesrc" image="xyz.gif" no_comments="1">..</gizmotag>

md_itemlist : Display list of all Item children of the category

md_gizmolist : Display the list of all the gizmos within the category by gizmo type (excepting Categories, Polls and News Gizmos).

md_newslist : Displays a list with all newsitems in the current category.

md_newscol : Display newsitems under the current category in column format.

md_newsitemlist : Display list of all News Item children of the category

md_poll : Displays all polls under the current category in vertical column format.

md_pollist : Display list of all Poll children of the category

md_scrollviewlist : Display list of all ScrollView children of the category

md_tablelist : Display list of all Table children of the category

md_title : Generates the name (title) of the current object. If you are using this gizmotag to generate the title for an html template page, call it with the `no_comments' attribute as described above to suppress the extra comment output.

md_username : Displays the name of the current logged in user.

md_quota_meter : Displays the remaining disk quota for file uploads of the current user.

md_v_subnav : Display a vertical navigation bar with subcategories of the current category.

md_v_subnav_flex: Display a parameterizable vertical navigation bar with subcategories of the current category. This tag supports the following parameters, passed as additional gimotag attribute/value pairs:

show_parents: tells the nav bar to show the parents of the current page
unconditional_expansion_depth: tells the nav bar how many levels should be unconditionally expanded.

md_v_subnav2 : Displays a vertical navigation bar with subcategories of the current category.

md_h_applist : Displays horizontally the applications list.

md_search : Displays the search box. Can take optional attribute img_src specifying an image to use for the search button. For example,
<gizmotag name="md_search" img_src="../images/search_button.gif">...</gizmotag> Of course, the image must be installed in the specified directory in the web server.

md_todays_events : displays the event listing panel for the current date

md_welcome : Displays the currently logged-in username and a link for signing in.

md_users_online : Indicate how many users are currently logged in, and have been active within the last 15 minutes.

md_links_panel : Displays a panel images linked to user functions. If the user is not logged in, the panel contains links for: ` register', `login', `my website', and `my page '. When the user logs in, the panel contains links for: ` logout', `profile', `my website', and `my page '.

md_gizmorunner : This tag allows displaying objects other than the current object inline. This is done by specifying the type (the `isa') and iid of the object that you wish to display inline, as so:
<gizmotag name="md_gizmorunner" isa="Table" iid="1234">...</gizmotag> You may optionally include an "op" attribute also; if this value is not specified, then `show' is used as the default. (To find the iid -- the unique id -- of the object, it is simplest to just display it in your browser and note the iid in the URL generated for the display operation).