Ignore

Please note that your browser is not supported.

We recommend upgrading to the latest Firefox or Google Chrome.

Frontend: Endpoints

Endpoints let you define how a user will navigate through your application. They also provide helpers for determining whether a particular navigation element is in a current or active state.

Let's look at an example. Our application has two endpoints: one for viewing a list of messages and another for showing the details of a particular message. We can setup navigations between these two views using the endpoint attribute on the node:

Consider an app with two views: one for viewing a list of messages and one with more details for a single message. You can use endpoints to setup navigations between the two views. Let's start by setting up a link that lets a user navigate from the message list to the show view:

<h1>
  Here's a list of your messages:
</h1>

<article binding="message">
  <h1 binding="title">
    message title goes here
  </h1>

  <a href="/messages/show" endpoint="messages_show">
    View Message
  </a>
</article>

The messages_show endpoint value references a named endpoint within the application. When the view is rendered, Pakyow replaces the defined href with the path defined by the messages_show endpoint. Given a list of three messages, the rendered view will look something like this:

<h1>
  Here's a list of your messages:
</h1>

<article>
  <h1>
    Message 1
  </h1>

  <a href="/messages/1">
    View Message
  </a>
</article>

<article>
  <h1>
    Message 2
  </h1>

  <a href="/messages/2">
    View Message
  </a>
</article>

<article>
  <h1>
    Message 3
  </h1>

  <a href="/messages/3">
    View Message
  </a>
</article>

The endpoints are built based on the presented data, populating each link with a unique href. Clicking on the link for a message will direct you to the endpoint that represents messages_show—whatever that might be. As the frontend designer, you aren't required to know the particulars. Instead, you simply define the behavior you want and the connections are made for you.

Prototyped endpoints

The hardcoded href value from the above example is used to provide basic navigation within a prototype. We recommend setting default values that match the presentation paths defined in the frontend. These values will always be replaced in the final application.

Using endpoint states

It's often useful to style endpoints differently when a user is located at that endpoint. Pakyow handles this by rendering endpoints in one of two navigation states: current and active.

An endpoint is in a "current" state when its path fully matches the current url. These endpoints will receive a ui-current class.

When an endpoint path matches /part/ of the current url, the endpoint is considered "active". These endpoints will receive a ui-active class.

Specifying an endpoint action

In more complicated navigation interfaces, the navigation item may be different than the element that causes the navigation action to occur. Here's an example view template that defines a separate endpoint action:

<nav>
  <ol>
    <li binding="guide" endpoint="guides_show">
      <a href="/guides/show" binding="title" endpoint-action>
        Guide Title
      </a>
    </li>
  </ol>
</nav>

Adding the endpoint-action attribute to the a element separates the endpoint node from the action node. This causes the li endpoint node to receive the ui-current and ui-active classes, with the a endpoint action node receiving the href value.

Using delete endpoints

Delete endpoints are a bit different than standard navigation endpoints as they cause a destructive action to occur. However, Pakyow still handles delete endpoints in a similar way to other endpoints.

To create a link that triggers a delete endpoint just specify the name of the endpoint like you would for other endpoints:

<h1>
  Here's a list of your messages:
</h1>

<article binding="message">
  <h1 binding="title">
    message title goes here
  </h1>

  <a href="/messages/show" endpoint="messages_delete">
    Delete Message
  </a>
</article>

In normal cases, clicking a link causes the browser send a GET request to the server. Here Pakyow works some magic to turn delete links into a form that triggers the DELETE endpoint when submitted.

Since delete endpoints are turned into forms, the endpoint element should be capable of submitting a form when clicked. There are two approaches to choose from. The first approach is to use a submit button:

<input type="submit" value="Delete Message" endpoint="messages_delete">

If this doesn't work, the second approach is to attach the submittable component to the endpoint element:

<a href="/messages/show" endpoint="messages_delete" ui="submittable">
  Delete Message
</a>

The submittable component will automatically submit its parent form when clicked.

Confirming the delete action

Pakyow.js ships with a confirmable component that can be useful for destructive endpoints like delete. The component presents a confirmation dialog they must accept after invoking the delete endpoint. Without the confirmation, the endpoint will not be triggered.

To use the confirmable component, simply add it to the element:

<article binding="message">
  <a href="/messages/show" endpoint="messages_delete" ui="confirmable">
    Delete Message
  </a>
</article>

Form endpoints

You can set endpoints on forms as well. Pakyow will automatically setup a form with the correct action and method for submitting the form to the endpoint you define.

For example, say we have the following endpoints:

:messages_create          POST  /messages
:messages_replies_create  POST  /messages/:message_id/replies
:messages_show            GET   /messages/:id
:root                     GET   /

You can connect the form to the messages_create endpoints like this:

<form endpoint="messages_create">
  ...
</form>

The rendered version of the form will look like this:

<form action="/messages" method="post">
  ...
</form>

Defining an endpoint is usually better than hardcoding an action and method yourself, since the form will automatically adjust to handle any changes to the backend endpoints. The endpoint path or http method could be changed, but as long as the name of the endpoint is the same the form will continue to work.

Inspecting endpoint names

Endpoint names are part of the implicit contract that exists between the frontend and backend of an application. To see a full list of endpoints along with their names, run the info:endpoints command:

pakyow info:endpoints
:messages_create          POST  /messages                      pakyow/reflection
:messages_replies_create  POST  /messages/:message_id/replies  pakyow/reflection
:messages_show            GET   /messages/:id                  pakyow/reflection
:root                     GET   /                              pakyow/reflection
Next Up: Forms