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>
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.
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
When an endpoint path matches /part/ of the current url, the endpoint is considered "active". These endpoints will receive a
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>
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-active classes, with the
a endpoint action node receiving the
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>
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>
You can set endpoints on forms as well. Pakyow will automatically setup a form with the correct
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
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
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