News

Keechma author Mihael Konjević on

Keechma Developer Tools Preview

Keechma is getting close to v1 release. Most of the work is done, what's left is documentation update and the release of the developer tools.

Here's a short screencast that shows off some of the features built into the dev tools. If you're missing some context around the example application make sure to check the walkthrough.

Keechma author Mihael Konjević on

Announcing Keechma Forms Library

Today, I’m excited to release the Keechma Forms library. Although it’s released under the Keechma brand, you don’t have to use it with the rest of Keechma ecosystem, it can be used with any Reagent based application.

What is Keechma Forms and why does it exist?

Keechma Forms is a library that will help you build forms with delightful UX. It is UI agnostic (as long as you use Reagent), but it gives you a way to display validation errors in the right time.

If you want to learn more about the validations and when they should be rendered I can recommend these links:

Although some of these articles are pretty old, I still encounter these kind of problems on a daily basis. Implementing forms is hard.

Keechma Forms solves two of the hardest problems when dealing with forms:

  • Validation of arbitrarily nested data
  • Keeping track of dirty key paths in arbitrarily nested data

Data Validation

Most form libraries push the data validation to the component level, which is great for simple use cases, but it starts to fall appart as soon as you have anything remotely complex.

Keechma Forms take a different approach, and validation is always performed on the data. Validators take in the data and return the nested map with the errors.

Example:

;; Define a value validator - first element is validator name, second is the
;; validator function
(def not-empty [:not-empty (fn [v] (not (empty? v)))])

;; Define a form validator. Each attribute takes a vector of value validators
(def user-validator (forms.validator/validator {:username [not-empty]
                                                :password [not-empty]}))

;; Define a form validator with nested fields
(def article-validator
  (forms.validator/validator {:title [not-empty]
                              :user.username [not-empty]}))

;; Define a form validator which validates a list of objects
(def team-validator
  (forms.validator/validator {:name [not-empty]
                              :players.*.name [not-empty]
                              :players.*.number [not-empty]}))

Go to the API documentation to see more examples. Validator API can handle any kind of document structure you throw at it.

Dirty key paths tracking

This feature is crucial if you want to build forms with the great UX. Badly implemented live validation is worse than validating the whole form on submit.

The “before and while” method not only caused longer completion times, but also produced higher error rates and worse satisfaction ratings than the other inline validation variations we tested.

from the Inline Validation in Web Forms article

Keechma Forms allows you to avoid these problems by keeping track of any changes user made to the form. That way you can show the right error messages at the right moment.

Demo

I've implemented a demo to showcase the features of Keechma Forms. These are the features I've implemented:

  • Form should have input fields for: username, password, name and email
  • Form should allow user to add any number of social network accounts
    • User should add at least one account
    • Each account should have a select dropdown for the network and input for the username
  • Form should allow user to add any number of phone numbers
  • If the field is in valid state, validation should be performed on blur
  • If the field is in invalid state, validation should be performed on change (keypress) so the error message is removed as soon as possible
  • When the user submits the form, all fields should be validated
  • If the user adds a social network account or phone number after they tried to submit the form, new fields should be in valid state

Check out the demo to see how it looks. I think this is the form with the best UX I've ever implemented. Although you can feel differently, the important thing is that this kind of heavily customized behavior is possible with Keechma Forms. Check out the annotated source code here.

Conclusion

Building forms with delightful UX is possible and easy with Keechma Forms, and I hope you'll find it as useful as I do. As always if you have any questions you can ping me on Twitter or you can send me an email

Keechma author Mihael Konjević on

Road to v1.0.0

Today I’m releasing the new Keechma site and I wanted to use this opportunity to share my plans for v1.0.0.

Keechma is now slightly older than three months, and in this time I talked a lot with the people who were trying it out, did a lot of experimentation and built a number of smaller apps with Keechma. This gave me some ideas on things that need to be improved before a solid v1 release.

One of the first things I did with Keechma was extracting EntityDB and Router from the main project. Although this allows usage of these libraries in the non-Keechma projects, it created some logistic problems. The biggest problem was that the build system (and design) were created with a single repo in mind. That’s why the new site was the first and most important step to v1.0.0.

New site is built with bunch of tools (Marginalia, Codox, Make, NodeJS), but the final build is performed by the Lektor CMS which allows me to build the site both from the content generated by the documentation tools, and to add custom content (like this news) in one system. Expect more articles, news and content around Keechma in the future.

Future of Keechma

Convenience layer

When designing and building the first version, I was very careful to avoid adding stuff to Keechma just for the sake of convenience. I believe that adding a convenience layer too early makes it easy to design a bloated system. It resulted with clean, tight core, but it also resulted with an API that is more verbose than necessary.

In the future, I want to add a convenience layer on top of Keechma that will remove a lot of boilerplate code from the typical app. This convenience layer will be completely optional and contained in a separate package. I want to keep the amount of code in the main Keechma project minimal. I will share more news about this project when I start working on it, but please let me know if you have any ideas or feedback.

Documentation

Another area I want to focus on is documentation. Keechma is a new project and the community around it is starting to form. I believe that the best thing I can do to kickstart the growth of the community and Keechma adoption is to create more documentation, more tutorials, more content around Keechma. Right now, writing documentation will have bigger impact than writing code, and that's something I'm ready to embrace.

To be able to write great docs and tutorials, I need your help. I have some ideas about the improvements that can be made, but more feedback is always welcome.

How You can help me:

  • Try Keechma - you will have questions, and by answering these questions I'll be able to see which parts need better docs
  • Ask questions - you can find me on Clojurians Slack (in #keechma channel), on Twitter or you can send me an email.
  • Show me examples of interfaces that were hard to architect - If you have an example of the interface that is hard to architect, send it to me and I'll try to replicate it with Keechma and write a blog post about it. It doesn't matter if it's implemented in a different framework, or if you found it somewhere in the wild.

I want to make Keechma really easy to use, and it all starts with good documentation. Your feedback and questions will allow me to write it.

Tangential projects

Keechma solves a small subset of problems we encounter while building apps. There is a lot of stuff that could be solved in a nicer way, and I'll work on it as need arises.

The first project that will be released in the near future (after I write the documentation) is Keechma Forms. It will allow you to model and validate complex forms with ease. Until the documentation is written you can check out the tests to see how the API will look.

Like EntityDB and Router, the Forms library is in no way coupled with Keechma. It can be used with any Reagent project but also with any ClojureScript project (with a little effort).

Conclusion

I believe that Keechma has sound fundamentals, and in the future, I want to make it the easiest to use and the best-documented framework out there (at least in the ClojureScript world). To do that, I'll need your help, so please let me know if you have any feedback. You can ping on Twitter or you can send me an email.