Ignore

Please note that your browser is not supported.

We recommend upgrading to the latest Firefox or Google Chrome.

Hello, Web: 5-Minute App

Welcome! We're glad you're interested in learning learning about Pakyow. The best way to get a feel for everything is to build something yourself. This guide will take you through the entire design-first process, starting with a frontend prototype and then turning the prototype into a complete application.

You'll be building a simple messaging app that lets users create messages and send replies to each other. There's nothing you need to know before going through this guide. It's intended to be approachable by anyone, even if you've never built a web app before. If you do get stuck, feel free to reach out to the community. We're happy to help!

The full source code for this example is available on Github for you to reference, and you can see it running live at the following url:

Before you start

If you haven't already, take a minute to install Pakyow. We'll wait here.

Once Pakyow is installed, generate a project using pakyow create from the command line:

pakyow create example

Pakyow creates a brand new project structure for you and gets it ready to run.

From the command line, move into your new project folder:

cd example

You're ready to start building!

Prototyping the message list

You'll start by prototyping your app's first feature: a list of messages for users to see. Since you'll be prototyping, go ahead and boot your project into prototype mode. Run this command from your project folder in the command line:

pakyow prototype

Prototype mode lets you see a navigable, frontend-only version of your project right in your web browser. It's the best place to start designing and building the interface for a new feature. You can boot back into prototype mode at any point in your project's development, giving you a consistent place to do all of your design work from.

Okay, let's create our first frontend view template. Each view template defines part of the interface for your project using plain html. Pakyow composes your templates together into what the user sees and interacts with in their web browser. Our first view template will present a list of messages for the user.

Define the following template in the frontend/pages folder:

frontend/pages/index.html
<article binding="message">
  <p binding="content">
    Message content goes here.
  </p>
</article>

Make sure the file is saved, then visit localhost:3000 in your favorite web browser. You'll see the root index page displayed just as you defined it:

Pakyow Example: Message List Prototype

Looks like you're off and running! Note that your pages may look a bit different, since the screenshots in this guide are pulled from the example app. Feel free to copy those assets to your project 😃

Thinking ahead, it would be helpful to tell the first user of the app what to do when no messages have been created. You can define an empty message by adding a new version of the message element to the same index.html page as before:

frontend/pages/index.html
<article binding="message">
  <p binding="content">
    Message content goes here.
  </p>
</article>

<p binding="message" version="empty">
  No messages yet. Try creating one!
</p>

Reload your web browser and you'll see both versions:

Pakyow Example: Message List Prototype with Empty Version

In just a minute we'll see how Pakyow handles these two versions of our message elements. But first, we need a way for our users to create new messages. You can do this by defining a form at the top of your index.html page:

frontend/pages/index.html
<form binding="message">
  <div class="form-field">
    <input type="text" placeholder="Type your message..." binding="content">
  </div>

  <input type="submit" value="Create">
</form>

<article binding="message">
  <p binding="content">
    Message content goes here.
  </p>
</article>

<p binding="message" version="empty">
  No messages yet. Try creating one!
</p>

Reload your web browser once again and you'll see the form at the top of the screen:

Pakyow Example: Message List Prototype with Form

Nice, you've prototyped your first feature! We could add more to the prototype, such as improving how it looks with stylesheets. For now let's move on and see how Pakyow turns our html view templates into a usable app.

Going from prototype to application

The view template you defined in the previous section tell Pakyow everything it needs to build in some basic behavior to your project. To see the app in action, restart the project by pressing Ctrl-C to stop the current process and boot into normal development mode:

pakyow boot

Reload your web browser and this time you'll see just the empty message view and form:

Pakyow Example: Message List

Pakyow understands that no messages are available to present, so it automatically renders the empty version. Helpful, right? Let's explore some other behavior that Pakyow has added for us.

Try using the form to create a new message. You'll find that submitting the form causes a new message to be created, which is then presented in the list:

Pakyow Example: New Message

And that isn't all—there's some other behavior going on behind the scenes. To see it, open two browser windows side by side, then create a message in one of the windows:

Pakyow Example: Realtime UI

Changes made by one user are instantly available to other users! Pakyow handles everything about these updates for you.

Okay, at this point we have some of the basic behavior of our app working. And all we had to do was define a single html view template to make it happen. The UI could use some more features to make it more user friendly, so we'll take care of that next.

Improving the form

Right now users can create messages without typing any content. This makes for a pretty poor user-experience, so let's add some validation and error handling to our form. First, attach additional behavior to your form by adding the ui attribute:

<form binding="message" ui="form">
  ...
</form>

...

Pakyow ships with a form view component that handles things like submitting in the background and handling errors that occur.

Next, make the message content required by adding the required attribute to the text field:

<form binding="message" ui="form">
  <div class="form-field">
    <input type="text" placeholder="Type your message..." binding="content" required>
  </div>

  ...
</form>

...

Finally, add an unordered list for presenting errors in your form:

<form binding="message" ui="form">
  <ul class="form-errors" ui="form-errors">
    <li binding="error.message">
      Error message goes here.
    </li>
  </ul>

  ...
</form>

...

Reload your web browser and you'll find that it's no longer possible to create a message without first writing some content. What you're seeing here is the built-in browser validation, but Pakyow has also attached validation to your app. To see it, simply add the novalidate attribute to the form:

<form binding="message" ui="form" novalidate>
  ...
</form>

...

This tells the web browser to skip validation and let the application take care of it instead. Reload your web browser and use the form to create a message without any content. Now you'll see errors presented in the list:

Pakyow Example: Form Errors

Let's continue improving our application by adding the ability to reply to messages. We'll do this in the next section.

Adding the replies feature

Users need a way to reply to messages that have already been created. We'll add this new feature using following the same design-first process as before. Start by hitting Ctrl-C and booting back into the prototype:

pakyow prototype

Let's start by defining another page template that presents a message along with its replies. Create this template in a new frontend/pages/messages folder. This tells Pakyow what requests should use the new template and helps keep your frontend organized. Here's the html for the new show template:

frontend/pages/messages/show.html
<article binding="message">
  <p binding="content">
    Message content goes here.
  </p>

  <hr>

  <article binding="reply">
    <p binding="content">
      Reply content goes here.
    </p>
  </article>

  <p binding="reply" version="empty">
    No replies yet.
  </p>

  <hr>

  <form binding="reply" ui="form">
    <ul class="form-errors" ui="form-errors">
      <li binding="error.message">
        Error message goes here.
      </li>
    </ul>

    <div class="form-field">
      <input type="text" binding="content" placeholder="Leave a reply..." required>
    </div>

    <input type="submit" value="Reply">
  </form>
</article>

Navigate to http://localhost:3000/messages/show in your web browser to see the new page. Just like before, you'll see everything just as you defined it:

Pakyow Example: Message Show Prototype

Next, let's setup some links to give users a way to navigate between pages. Start by adding the following link to the top of the show message page:

frontend/pages/messages/show.html
<a href="/">
  Go back home
</a>

<article binding="message">
  ...
</article>

Users also need a way to view messages. Do this in the index page by adding the following add a link to the message element:

frontend/pages/index.html
...

<article binding="message">
  <p binding="content">
    Message content goes here.
  </p>

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

...

Reload your web browser and you'll be able to navigate between pages in your prototype!

Okay, this feature seems pretty solid, so let's see it in action.

Hit Ctrl-C and boot back into normal development mode:

pakyow boot

Reload your web browser and play around with the app for a bit. You'll be able to create messages, click on the link to view them, and then add replies. Pakyow has hooked everything up for you and attached behavior to your interface. The app offers a nice user-experience out of the box, with both pages updating to show new messages and replies as they're created.

Ordering the dataset

You may notice that messages are displayed oldest at the top. This doesn't make a whole lot of sense with the form being at the top, so let's change this. Add the following dataset attribute to the message binding on the index page:

frontend/pages/index.html
<article binding="message" dataset="order: created_at(desc)">
  ...
</article>

...

Reload the page and the messages will be presented with the newest at the top:

Pakyow Example: Ordered Message List

Reflection lets you configure certain aspects of the presented dataset right in the view where it's used. In addition to the order, you can also set a limit to the amount of data presented, as well as specify the underlying query to use for fetching data.

Setting page titles

Right now both pages in our project use the page title specified in the layout. Let's set a custom page title on the message show page to differentiate it. We'll add some configuration, called front-matter, to the top of the page template:

frontend/pages/messages/show.html
---
title: "View Message"
---

...

Reload the page and you'll see that the new page title is used for the message page. Dynamic values are also supported. For example, you can present the message content in the title like this:

---
title: "{message.content} | View Message"
---

...

Conclusion

There you have it—you were able to build a complete app with just a few lines of HTML. Pakyow uses a built-in tool called reflection to understand the semantic intent of your view templates and then bootstraps a working backend for your interface. From here, you can extend the reflection to add any custom features that you might need.

We covered a lot of ground in this example, introducing several concepts including view composition, data bindings, and reflection. Use the links below to learn more about the parts of the framework that we covered here:

  • Frontend: Are you a frontend designer or developer? Start here to learn about view composition and data bindings, as well as topics we skipped such as the asset pipeline.

  • Backend: More of a backend developer? Start here to learn about the various backend aspects such as routing, data sources, and presenters.

  • Reflection: Intrigued by reflection? Start here to learn more about how it works, then move on to the frontend or backend documentation.

Thanks for reading! We can't wait to see what you build.

Next Up: Frontend