Moya Links

Moya Links provides a way for libraries to advertise hyper-links for a particular purpose. This is typically used to add links to a menu or sub-menu of some kind.

Installation

Moya Links is built in to Moya and may be imported with the following:

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

The following will install Moya Links:

<install name="links" lib="moya.links" />

There is no need to mount this library, as there are no views, just custom tags.

Namespace

Moya Links uses the namespace http://moyaproject.com/links. Link tags in this document are assumed to have the XML prefix links: declared.

Introduction

The moya start command uses the Moya Links library to define which links are displayed on the top navbar (menu at the top of the page); it writes following file in your site application (site/logic/data.xml):

<moya xmlns="http://moyaproject.com"
      xmlns:links="http://moyaproject.com/links">

    <links:link text="About" from="pages" name="showpage" with="{'pagename': 'about'}"
        if=".apps.pages"/>
    <links:link text="Blog" from="blog" name="list"
        if=".apps.blog" />
    <links:link text="Contact" from="pages" name="showpage" with="{'pagename': 'contact'}"
        if=".apps.pages"/>
    <links:link text="Feedback" from="feedback" name="feedback"
        if=".apps.feedback" />
    <links:link text="Debug" from="debug" name="intro"
        if=".apps.debug and .debug" />
    <links:link text="API" from="site" name="jsonrpc"
        if=".apps.jsonrpc" />

</moya>

The above file sets the navbar links, but only if the relevant application is installed. Otherwise there would be broken links – and you wouldn't have a very good impression of Moya.

The start command also writes the following file (site/logic/content.xml):

<moya xmlns="http://moyaproject.com"
      xmlns:links="http://moyaproject.com/links">

    <content libname="content.base">
        <links:get dst="navlinks" />
    </content>

</moya>

This contains the base content definition which is inherited by all <content> tags in your project. The call to <get> retrieves a value called navlinks which contains a list of links, which is ultimately used to render the navbar in your base template.

See the rest of the document for the details on using the links tags.

Tags

Moya Links supplies two tags; <link> which defines links, and <get> which retrieves a list of those links.

Link Tag

The <link> defines a link to a page installed in your project. The following example defines two links; to the login page and about page:

<links:link from="moya.auth" name="login" text="Login to Sushi Finder" />
<links:link from="sushifinder.shop" name="cart" text="Shopping Cart" />

You can also add the URL explicitly, which might be necessary if you want a link to an external page. For example:

<link:link url="http://moyaproject.com" text="Moya"/>

Link tags also have a purpose attribute which allows you to categorize links. You may have a category for a main menu / sub-menu / footer links etc. The following example defines links for typical footer:

<links:link purpose="footer" from="moya.pages" name="about" text="About" />
<links:link purpose="footer" from="moya.pages" name="contact" text="Contact" />
<links:link purpose="footer" from="moya.pages" name="terms-and-conditions" text="Terms and Conditions" />

Get Tag

The <get> tag can retrieve a collection of links.

<links:get dst="links" />

This will retrieve the link tags and extract a list of dictionaries containing the following information:

url
The URL for the link.
text
Text associated with the link.

You could use the links list in a template such as the following:

<div class="menu">
{% for link in links %}
    <a href="${link.url}">${link.text}</a>
{% endfor %}
</div>

You can set a purpose attribute on <get> which gathers only <link> tags with the same value for purpose. For example, the following would get the footer tags defined previously:

<links:get dst="footer_links" purpose="footer"/>