In my last post, I covered what LiveView is at a high level. In this series, we’re going to dive deeper and implement a LiveView powered Markdown editor called Frampton. This series assumes you have some familiarity with Phoenix and Elixir, including having them set up locally. Check out Elizabeth’s three-part series on getting started with Phoenix for a refresher.

This series has a companion repository published on GitHub. Get started by cloning it down and switching to the starter branch. You can see the completed application on master. Our goal today is to make a Markdown editor, which allows a user to enter Markdown text on a page and see it rendered as HTML next to it in real-time. We’ll make use of LiveView for the interaction and the Earmark package for rendering Markdown. The starter branch provides some styles and installs LiveView.

Rendering Markdown

Let’s set aside the LiveView portion and start with our data structures and the functions that operate on them. To begin, a Post will have a body, which holds the rendered HTML string, and title. A string of markdown can be turned into HTML by calling Post.render(post, markdown). I think that just about covers it!

First, let’s define our struct in lib/frampton/post.ex:

Now the failing test (in test/frampton/post_test.exs):

Our render method will just be a wrapper around Earmark.as_html!/2 that puts the result into the body of the post. Add {:earmark, "~> 1.4.3"} to your deps in mix.exs, run mix deps.get and fill out render function:

Our test should now pass, and we can render posts! [Note: we’re using the as_html! method, which prints error messages instead of passing them back to the user. A smarter version of this would handle any errors and show them to the user. I leave that as an exercise for the reader…] Time to play around with this in an IEx prompt (run iex -S mix in your terminal):

Great! That’s exactly what we’d expect. You can find the final code for this in the render_post branch.

LiveView Editor

Now for the fun part: Editing this live!

First, we’ll need a route for the editor to live at: /editor sounds good to me. LiveViews can be rendered from a controller, or directly in the router. We don’t have any initial state, so let's go straight from a router.

First, let's put up a minimal test. In test/frampton_web/live/editor_live_test.exs:

This test doesn’t do much yet, but notice that it isn’t live view specific. Our first render is just the same as any other controller test we’d write. The page’s content is there right from the beginning, without the need to parse JavaScript or make API calls back to the server. Nice.

To make that test pass, add a route to lib/frampton_web/router.ex. First, we import the LiveView code, then we render our Editor:

Now place a minimal EditorLive module, in lib/frampton_web/live/editor_live.ex:

And we have a passing test suite! The ~L sigil designates that LiveView should track changes to the content inside. We could keep all of our markup in this render/1 method, but let’s break it out into its own template for demonstration purposes.

Move the contents of render into lib/frampton_web/templates/editor/show.html.leex, and replace EditorLive.render/1 with this one liner: def render(assigns), do: FramptonWeb.EditorView.render("show.html", assigns). And finally, make an EditorView module in lib/frampton_web/views/editor_view.ex:

Our test should now be passing, and we’ve got a nicely separated out template, view and “live” server. We can keep markup in the template, helper functions in the view, and reactive code on the server. Now let’s move forward to actually render some posts!

Handling User Input

We’ve got four tasks to accomplish before we are done:

1. Take markdown input from the textarea
2. Send that input to the LiveServer
3. Turn that raw markdown into HTML
4. Return the rendered HTML to the page.

Event binding

To start with, we need to annotate our textarea with an event binding. This tells the liveview.js framework to forward DOM events to the server, using our liveview channel. Open up lib/frampton_web/templates/editor/show.html.leex and annotate our textarea:

<textarea phx-keyup="render_post"></textarea>

This names the event (render_post) and sends it on each keyup. Let’s crack open our web inspector and look at the web socket traffic. Using Chrome, open the developer tools, navigate to the network tab and click WS. In development you’ll see two socket connections: one is Phoenix LiveReload, which polls your filesystem and reloads pages appropriately. The second one is our LiveView connection. If you let it sit for a while, you’ll see that it's emitting a “heartbeat” call. If your server is running, you’ll see that it responds with an “ok” message. This lets LiveView clients know when they've lost connection to the server and respond appropriately.

Now, type some text and watch as it sends down each keystroke. However, you’ll also notice that the server responds with a “phx_error” message and wipes out our entered text. That's because our server doesn’t know how to handle the event yet and is throwing an error. Let's fix that next.

Event handling

We’ll catch the event in our EditorLive module. The LiveView behavior defines a handle_event/3 callback that we need to implement. Open up lib/frampton_web/live/editor_live.ex and key in a basic implementation that lets us catch events:

The first argument is the name we gave to our event in the template, the second is the data from that event, and finally the socket we’re currently talking through. Give it a try, typing in a few characters. Look at your running server and you should see a stream of events that look something like this:

There’s our keystrokes! Next, let’s pull out that value and use it to render HTML.

Rendering Markdown

Lets adjust our handle_event to pattern match out the value of the textarea:

def handle_event("render_post", %{"value" => raw}, socket) do

Now that we’ve got the raw markdown string, turning it into HTML is easy thanks to the work we did earlier in our Post module. Fill out the body of the function like this:

If you type into the textarea you should see output that looks something like this:

Perfect! Lastly, it’s time to send that rendered html back to the page.

Returning HTML to the page

In a LiveView template, we can identify bits of dynamic data that will change over time. When they change, LiveView will compare what has changed and send over a diff. In our case, the dynamic content is the post body.

Open up show.html.leex again and modify it like so:

Refresh the page and see:

Whoops!

The @post variable will only be available after we put it into the socket’s assigns. Let’s initialize it with a blank post. Open editor_live.ex and modify our mount/3 function:

In the future, we could retrieve this from some kind of storage, but for now, let's just create a new one each time the page refreshes. Finally, we need to update the Post struct with user input. Update our event handler like this:

Let's load up http://localhost:4000/editor and see it in action.

Nope, that's not quite right! Phoenix won’t render this as HTML because it’s unsafe user input. We can get around this (very good and useful) security feature by wrapping our content in a raw/1 call. We don’t have a database and user processes are isolated from each other by Elixir. The worst thing a malicious user could do would be crash their own session, which doesn’t bother me one bit.

Check the edit_posts branch for the final version.

Conclusion

That’s a good place to stop for today. We’ve accomplished a lot! We’ve got a dynamically rendering editor that takes user input, processes it and updates the page. And we haven’t written any JavaScript, which means we don’t have to maintain or update any JavaScript. Our server code is built on the rock-solid foundation of the BEAM virtual machine, giving us a great deal of confidence in its reliability and resilience.

In the next post, we’ll tackle making a shared editor, allowing multiple users to edit the same post. This project will highlight Elixir’s concurrency capabilities and demonstrate how LiveView builds on them to enable some incredible user experiences.

Viget has helped organizations design and develop award-winning websites and digital products for 20 years. In that time, we’ve been lucky to create long-term relationships with clients like Puma, the World Wildlife Fund, and Privia Health, and, throughout our time working together, we’ve come to understand each others’ unique terminology. But that isn’t always the case when we begin work with new clients, and in a constantly-evolving industry, we know that new terminology appears almost daily and organizations have unique definitions for deliverables and processes.

Kicking off a project always initiates a flurry of activity. There are contracts to sign, team members to introduce, and new platforms to learn. It’s an exciting time, and we know clients are anxious to get underway. Amidst all the activity, though, there is a need to define and create a shared lexicon to ensure both teams understand the project deliverables and process that will take us from kickoff to launch.

Below, we’ve rounded up a few terms for each of our disciplines that often require additional explanation. Note: our definitions of these terms may differ slightly from the industry standard, but highlight our interpretation and use of them on a daily basis.

User Experience

Research

In UX, there is a proliferation of terms that are often used interchangeably and mean almost-but-subtly-not the same thing. Viget uses the term research to specifically mean user research — learning more about the users of our products, particularly how they think and behave — in order to make stronger recommendations and better designs. This can be accomplished through different methodologies, depending on the needs of the project, and can include moderated usability testing, stakeholder interviews, audience research, surveys, and more. Learn more about the subtleties of UX research vocabulary in our post on “Speaking the Same Language About Research”.

Wireframes

We use wireframes to show the priority and organization of content on the screen, to give a sense of what elements will get a stronger visual treatment, and to detail how users will get to other parts of the site. Wireframes are a key component of website design — think of them as the skeleton or blueprint of a page — but we know that clients often feel uninspired after reviewing pages built with gray boxes. In fact, we’ve even written about how to improve wireframe presentations. We remind clients that visual designers will step in later to add polish through color, graphics, and typography, but agreeing on the foundation of the page is an important and necessary first step.

Prototypes

During the design process, it’s helpful for us to show clients how certain pieces of functionality or animations will work once the site is developed. We can mimic interactivity or test a technical proof of concept by using a clickable prototype, relying on tools like Figma, Invision, or Principle. Our prototypes can be used to illustrate a concept to internal stakeholders, but shouldn’t be seen as a final approach. Often, these concepts will require additional work to prepare them for developer handoff, which means that prototypes quickly become outdated. Read more about how and when we use prototypes.

Navigation Testing (Treejack Testing)

Following an information architecture presentation, we will sometimes recommend that clients conduct navigation testing. When testing, we present a participant with the proposed navigation and ask them to perform specific tasks in order to see if they will be able to locate the information specified within the site’s new organization. These tests generally focus on two aspects of the navigation: the structure of the navigation system itself, and the language used within the system. Treejack is an online navigation testing tool that we like to employ when conducting navigation tests, so we’ll often interchange the terms “navigation testing” with “treejack testing”.

Learn more about Viget’s approach to user experience and research. 

Professional certifications have become increasingly popular in this age of career switchers and the freelance gig economy. A certification can be a useful way to advance your skill set quickly or make your resume stand out, which can be especially important for those trying to break into a new industry or attract business while self-employed. Whatever your reason may be for pursuing a professional certificate, there is one question only you can answer for yourself: is it worth it?

Finding first-hand experiences from professionals with similar career goals and passions was the most helpful research I used to answer that question for myself. So, here’s mine; why I decided to get Scrum certified, how I evaluated my options, and if it was really worth it.

A shift in mindset

My background originates in brand strategy where it’s typical for work to follow a predictable order, each step informing the next. This made linear techniques like water-fall timelines, completing one phase of work in its entirety before moving onto the next, and documenting granular tasks weeks in advance helpful and easy to implement. When I made the move to more digitally focused work, tasks followed a much looser set of ‘typical’ milestones. While the general outline remained the same (strategy, design, development, launch) there was a lot more overlap with how tasks informed each other, and would keep informing and re-informing as an iterative workflow would encourage.

Trying to fit a very fluid process into my very stiff linear approach to project planning didn’t work so well. I didn’t have the right strategies to manage risks in a productive way without feeling like the whole project was off track; with the habit of account for granular details all the time, I struggled to lean on others to help define what we should work on and when, and being okay if that changed once, or twice, or three times. Everything I learned about the process of product development came from learning on the job and making a ton of mistakes—and I knew I wanted to get better.

I was fortunate enough to work with a group of developers who were looking to make a change, too. Being ‘agile’-enthusiasts, this group of developers were desperately looking for ways to infuse our approach to product work with agile-minded principles (the broad definition of ‘agile’ comes from ‘The Agile Manifesto’, which has influenced frameworks for organizing people and information, often applied in product development). This not only applied to how I worked with them, but how they worked with each other, and the way we all onboarded clients to these new expectations. This was a huge eye opener to me. Soon enough, I started applying these agile strategies to my day-to-day— running stand-ups, setting up backlogs, and reorganizing the way I thought about work output. It’s from this experience that I decided it may be worth learning these principles more formally.

The choice to get certified

There is a lot of literature out there about agile methodologies and a lot to be learned from casual research. This benefitted me for a while until I started to work on more complicated projects, or projects with more ambitious feature requests. My decision to ultimately pursue a formal agile certification really came down to three things:

1. An increased use of agile methods across my team. Within my day-to-day I would encounter more team members who were familiar with these tactics and wanted to use them to structure the projects they worked on.
2. The need for a clear definition of what processes to follow. I needed to grasp a real understanding of how to implement agile processes and stay consistent with using them to be an effective champion of these principles.
3. Being able to diversify my experience. Finding ways to differentiate my resume from others with similar experience would be an added benefit to getting a certification. If nothing else, it would demonstrate that I’m curious-minded and proactive about my career.

To achieve these things, I gravitated towards a more foundational education in a specific agile-methodology. This made Scrum the most logical choice given it’s the basis for many of the agile strategies out there and its dominance in the field.

Evaluating all the options

For Scrum education and certification, there are really two major players to consider.

1. Scrum Alliance - Probably the most well known Scrum organization is Scrum Alliance. They are a highly recognizable organization that does a lot to further the broader understanding of Scrum as a practice.
2. Scrum.org - Led by the original co-founder of Scrum, Ken Schwaber, Scrum.org is well-respected and touted for its authority in the industry.

Each has their own approach to teaching and awarding certifications as well as differences in price point and course style that are important to be aware of.

SCRUM ALLIANCE

Pros

• Strong name recognition and leaders in the Scrum field
• Offers both in-person and online courses
• Hosts in-person events, webinars, and global conferences
• Provides robust amounts of educational resources for its members
• Has specialization tracks for folks looking to apply Scrum to their specific discipline
• Members are required to keep their skills up to date by earning educational credits throughout the year to retain their certification
• Consistent information across all course administrators ensuring you'll be set up to succeed when taking your certification test.

Cons

• High cost creates a significant barrier to entry (we’re talking in the thousands of dollars here)
• Courses are required to take the certification test
• Certification expires after two years, requiring additional investment in time and/or money to retain credentials
• Difficult to find sample course material ahead of committing to a course
• Courses are several days long which may mean taking time away from a day job to complete them

SCRUM.ORG

Pros

• Strong clout due to its founder, Ken Schwaber, who is the originator of Scrum
• Offers in-person classes and self-paced options
• Hosts in-person events and meetups around the world
• Provides free resources and materials to the public, including practice tests
• Has specialization tracks for folks looking to apply Scrum to their specific discipline
• Minimum score on certification test required to pass; certification lasts for life
• Lower cost for certification when compared to peers

Cons

• Much lesser known to the general public, as compared to its counterpart
• Less sophisticated educational resources (mostly confined to PDFs or online forums) making digesting the material challenging
• Practice tests are slightly out of date making them less effective as a study tool
• Self-paced education is not structured and therefore can’t ensure you’re learning everything you need to know for the test
• Lack of active and engaging community will leave something to be desired

Before coming to a decision, it was helpful to me to weigh these pros and cons against a set of criteria. Here’s a helpful scorecard I used to compare the two institutions.

For me, the four areas that were most important to me were:

• Affordability - I’d be self-funding this certificate so the investment of cost would need to be manageable.
• Self-paced - Not having a lot of time to devote in one sitting, the ability to chip away at coursework was appealing to me.
• Reputation - Having a certificate backed by a well-respected institution was important to me if I was going to put in the time to achieve this credential.
• Access - Because I wanted to be a champion for this framework for others in my organization, having access to resources and materials would help me do that more effectively.

Ultimately, I decided upon a Professional Scrum Master certification from Scrum.org! The price and flexibility of learning course content were most important to me. I found a ton of free materials on Scrum.org that I could study myself and their practice tests gave me a good idea of how well I was progressing before I committed to the cost of actually taking the test. And, the pedigree of certification felt comparable to that of Scrum Alliance, especially considering that the founder of Scrum himself ran the organization.

Putting a certificate to good use

I don’t work in a formal Agile company, and not everyone I work with knows the ins and outs of Scrum. I didn’t use my certification to leverage a career change or new job title. So after all that time, money, and energy, was it worth it?

I think so. I feel like I use my certification every day and employ many of the principles of Scrum in my day-to-day management of projects and people.

• Self-organizing teams is really important when fostering trust and collaboration among project members. This means leaning on each other’s past experiences and lessons learned to inform our own approach to work. It also means taking a step back as a project manager to recognize the strengths on your team and trust their lead.
• Approaching things in bite size pieces is also a best practice I use every day. Even when there isn't a mandated sprint rhythm, breaking things down into effort level, goals, and requirements is an excellent way to approach work confidently and avoid getting too overwhelmed.
• Retrospectives and stand ups are also absolute musts for Scrum practices, and these can be modified to work for companies and project teams of all shapes and sizes. Keeping a practice of collective communication and reflection will keep a team humming and provides a safe space to vent and improve.

Parting advice

I think furthering your understanding of industry standards and keeping yourself open to new ways of working will always benefit you as a professional. Professional certifications are readily available and may be more relevant than ever.

If you’re on this path, good luck! And here are some things to consider:

• Do your research – With so many educational institutions out there, you can definitely find the right one for you, with the level of rigor you’re looking for.
• Look for company credits or incentives – some companies cover part or all of the cost for continuing education.
• Get started ASAP – You don’t need a full certification to start implementing small tactics to your workflows. Implementing learnings gradually will help you determine if it’s really something you want to pursue more formally.

In my last post, I defined terms used by our UX team that are often confused or have multiple meanings across the industry. Today, I’ll share our definitions for processes and deliverables used by our design and strategy teams.

Creative

Brand Strategy

In our experience, we’ve found that the term brand strategy is used to cover a myriad of processes, documents, and deliverables. To us, a brand strategy defines how an organization communicates who they are, what they do and why in a clear and compelling way. Over the years, we’ve developed an approach to brand strategy work that emphasizes rigorous research, hands-on collaboration, and the definition of problems and goals. We work with clients to align on a brand strategy concept and, depending on the client and their goals, our final deliverables can range to include strategy definition, audience-specific messaging, identity details, brand elements, applications, and more. Take a look at the brand strategy work we’ve done for Fiscalnote, Swiftdine, and Armstrong Tire.

Content Strategy

A content strategy goes far beyond the words on a website or in an app. A strong content strategy dictates the substance, structure, and governance of the information an organization uses to communicate to its audience. It guides creating, organizing, and maintaining content so that companies can communicate who they are, what they do, and why efficiently and effectively. We’ve worked with organizations like the Washington Speakers Bureau, The Nature Conservancy, the NFL Players Association, and the Wildlife Conservation Society to refine and enhance their content strategies.

Still confused about the difference between brand and content strategy? Check out our flowchart.

Style Guide vs. Brand Guidelines

We often find the depth or fidelity of brand guidelines and style guides can vary greatly, and the terms can often be confused. When we create brand guidelines, they tend to be large documents that include in-depth recommendations about how a company should communicate their brand. Sections like “promise”, “vision”, “mission”, “values”, “tone”, etc. accompany details about how the brand’s logo, colors and fonts should be used in a variety of scenarios. Style guides, on the other hand, are typically pared down documents that contain specific guidance for organizations’ logos, colors and fonts, and don’t always include usage examples.

Design System

One question we get from clients often during a redesign or rebrand is, “How can I make sure people across my organization are adhering to our new designs?” This is where a design system comes into play. Design systems can range from the basic — e.g., a systematic approach to creating shared components for a single website — all the way to the complex —e.g., architecting a cross-product design system that can scale to accommodate hundreds of different products within a company. By assembling elements like color, typography, imagery, messaging, voice and tone, and interaction patterns in a central repository, organizations are able to scale products and marketing confidently and efficiently. When a design system is translated into code, we refer to that as a parts kit, which helps enforce consistency and improve workflow.

Comps or Mocks

When reviewing RFPs or going through the nitty-gritty of contracts with clients, we often see the terms mocks or comps used interchangeably to refer to the static design of pages or screens. Internally, we think of a mock-up as a static image file that illustrates proof-of-concept, just a step beyond a wireframe. A comp represents a design that is “high fidelity” and closer to what the final website will look like, though importantly, is not an exact replica. This is likely what clients will share with internal stakeholders to get approval on the website direction and what our front-end developers will use to begin building-out the site (in other words, converting the static design files into dynamic HTML, CSS, and JavaScript code).

If you're interested in joining our team of creative thinkers and visual storytellers who bring these concepts to life for our clients, we’re hiring in Washington, D.C. Durham, Boulder and Chattanooga. Tune in next week as we decipher the terms we use most often when talking about development.