Moya Widgets is a libarary of widgets for common user interface elements. Using this widgets library is a good way of establishing a common look and feel across your libraries, and is used by many of the built in libraries.

Installation ¶

Moya Widgets is built in to Moya and may be installed as follows:

<import py="moya.libs.widgets" />

Moya Widgets does not need to be installed, to make the tags available for use. Althouge, there is a test page which you may want to have a look at. You can mount the test with the following:

<install name="widgets" lib="moya.widgets" mount="/widgets/" mountpoint="tests" />

Namespace ¶

Moya Widgets uses the namespace http://moyaproject.com/widgets. For brevity, the namespace prefix is typically set to w:.

Introduction ¶

This widgets library is a repository for common user interface elements, such as alerts, links, dialogs etc. and more advanced widgets such as pagination. They use markup targeted at Twitter Bootstrap, but can be customized if you are not using Bootstrap.

Alerts ¶

Alerts are simple container widgets with no parameters. The create a color coded panel containing a text message. Here's an example:

<w:success>Everything went according to plan!</w:success>

The following is a list of available alert widgets:

<success>

The operation completed successfully.

<info>

Some additional information for the user.

<warning>

Inform the user of potentially destructive consequences.

<danger>

Alert the user that their action didn't succeed.

<error>

Alert the user of an error.

Wells ¶

Wells are a simple container that draws attention to their contents. The following is a list of the available wells:

<well>

The default well.

<small-well>

A well with less padding.

<large-well>

A well with more padding.

Check ¶

Displays a green check (tick). Here's an example:

<w:check if="product.stock gt 0">

No Wrap ¶

Disables wrapping of text for its children. Essentially this wraps content in a div with the css property white-space set to nowrap. This widget is particularly useful in tables. Here's an example:

<w:no-wrap>This text won't be wrapped, even if the table is quite small.</w:no-wrap>

Links ¶

The <link> tag creates a link to a url on the site. This widget wraps a <a> tag around content with a generated url, optional class, and icon. The following link widgets are available:

<link>

Renders a simple link, see <link>.

<button-link>

Renders a link styled as a button, see <button-link>.

Buttons ¶

The <buttons> tag renders links tags as buttons. Here's an example take from the Moya Admin library:

<w:buttons>
    <w:link from="moya.admin" name="admin_new_object" with=".url">Add Another</w:link>
    <w:link from="moya.admin" name="admin_table_edit" with=".url" let:pk="obj.id">Edit</w:link>
</w:buttons>

URL ¶

The <url> tag renders a hyperlinked URL. For instance if you want to display a URL such as http://moyaproject.com, and you also want it to link to the same URLS. Here's how you could do that in a content definition:

<w:url url="http://moyaproject.com"/>

This would generate the following markup:

<a href="http://moyaproject.com">http://moyaproject.com</a>

Dialogs ¶

The <dialog> tag defines a dialog, used to render a container with a message and buttons.

Dialogs may contain a <dialog-buttons> tag which is a container for buttons.

The following is an example of a dialog, take from the Moya Blog library:

<form libname="form.deletepost" legend="Delete Post" xmlns="http://moyaproject.com/forms">
    <w:dialog>
        <moya:markdown>Are you sure you wish to delete post *${post.title}*?</moya:markdown>
        <w:dialog-buttons>
            <submit-button class="btn-primary" name="delete" text="Delete" clicked="delete" />
            <submit-button class="btn" name="cancel" text="Cancel" clicked="cancel" />
        </w:dialog-buttons>
    </w:dialog>
</form>

Paginate ¶

The <paginate> tag paginates a list of items, such as results from a database query, in to smaller pages and render a navigation control with numbered pages and forward / backward links.

The widget handles large queries quite elegantly. It will show the first few page numbers, the last few page numbers, and page numbers surrounding the current page. Other page numbers are replace with ellipsis so as not to render too many buttons. For example, if you are on page 16 of 100 pages you will see something like [prev] [1] [2] ... [15] [16] [17] ... [99] [100] [next] .

Here's an example taken from the Moya Blog library:

<w:paginate src="posts" dst="post">
    <blog:post post="post"/>
</w:paginate>

The src attribute should be the query results, in this case a query set of post objects from the db. The <paginate> iterates over each item, storing the current item in a value specified in dst, and rendering it with the enclosed content tags. That is literally all that is required to enable pagination.