Widgetfinger Tags

Widgetfinger is driven primarily by templates. These templates are not-evaluating (meaning they don’t execute arbitrary code) and they have a simple syntax, making it easy and safe for you to use in your pages.

Displaying Content

{% section name %}

To display a section of content on a page, use the section tag. It takes one parameter, which is the name of the section to display (e.g. home, main, or sidebar) without quotes.

{% global_section name %}

To display a section of content on a page, use the global_section tag. It takes one parameter, which is the name of the section to display (e.g. home, main, or sidebar) without quotes. The content that is created with a global section tag will be the same on every page. The global_section tag is useful for menus, sidebars, etc. that are the same on every page of the site.

Contact Form

The contact form tag puts a form on the page that allows website visitors to submit a message.

The simplest contact form you could possible make is

{% contactform :to email@example.com %}
{% endcontactform %}

The above tags would result in the following contact form

As you can see, the contact form automatically includes a message box for the website visitor to type their message in.

You can also add additional fields to the contact form, with the use of the field and checkbox tags, like so

{% contactform :to email@example.com %}
{% field :email_address %}
{% field :phone, Phone Number %}
{% checkbox :valid %}
{% endcontactform %}

Which results in the following contact form

As you can see in the above form, we now have additional fields for email address, phone number, and newsletter. We’re also customizing the field labels. By default, Widgetfinger will label the field with the name you give it. If the name has underscores, it’ll convert those to spaces. If you want a more complex label, just include it after the field name, like the “Subscribe to NewsLetter” label, above.

Finally, if you don’t want the message field automatically included, you can include :without_message like this

{% contactform :to email@example [:without_message] %}

The navigation tag outputs an unordered list of links that can be used for a navigation menu. The tag detects which page the visit is currently on, and applies a special class to the corresponding menu item.

An example of a basic navigation menu is

{% navigation %}
{% link About %}
{% link Services %}
{% link Contact %}
{% endnavigation %}

The above tags will create the following navigation HTML.

<ul id="navigation">
  <li class="about"><a href="/about">About</a></li>
  <li class="services"><a href="/services">Services</a></li>
  <li class="contact"><a href="/contact">Contact</a></li>
</ul>

In the above example of a navigation tag, in its basic form, you only need to supply the text of the navigation element. From that text, widgetfinger infers the class name of the menu item, and the page that the menu item will link to. With sensible page names, this will be all you need to make a robust navigational menu.

Also, the currently viewed page, and any subpages, will cause a “current” class to be added to the corresponding menu item. For example, if a web site visitor was viewing the Services page, the generated HTML for the navigation would be as follows.

<ul id="navigation">
  <li class="about"><a href="/about">About</a></li>
  <li class="services current"><a href="/services">Services</a></li>
  <li class="contact"><a href="/contact">Contact</a></li>
</ul>

In addition, any page whose path also starts with services will cause the services menu item to highlight.

Also, it may be necessary for the Name and URL of the navigational item to not match. The link tag provides additional flexibility through additional parameters.

If you need to override the URL, do this by providing a second parameter, as shown below.

{% navigation %}
{% link Home, / %}
{% link About %}
{% link Services %}
{% endnavigation %}

In the example above, the Home page has a URL of /, and therefore the standard naming does not apply. Its also possible to provide a full URL for a menu item, which leads to another site altogether, such as

{% navigation %}
{% link Home, / %}
{% link About %}
{% link Services %}
{% link Blog, http://blog.example.com %}
{% endnavigation %}

Finally, if you should need to add an additional class name, for styling particular menu items in certain ways, you can do this with a third parameter to the link tag, as shown below.

{% navigation %}
{% link Home, / %}
{% link About %}
{% link Services %}
{% link Blog, http://blog.example.com, subnav %}
{% endnavigation %}

The above widgetfinger tags will result in the following HTML.

<ul id="navigation">
  <li class="about home"><a href="/">Home</a></li>
  <li class="about"><a href="/about">About</a></li>
  <li class="services"><a href="/services">Services</a></li>
  <li class="blog subnav"><a href="http://blog.example.com">Blog</a></li>
</ul>

Liquid

For those of you who are little more technical, you may be interest to know that the templating language used by Widgetfinger is http://www.liquidmarkup.org/.