Developing Web Components

Preface

Why We Wrote This Book

Web development has not stopped evolving since I stumbled into the field over 13 years ago. If anything, the rate at which it is evolving is increasing. If you take a look at the investment that Google has made in Polymer and web components, it is probably safe to bet that web components will play a large role in web development in the near future as browsers implement more support for them. There are still some issues that need to be addressed, such as search engine optimization (SEO) concerns, but I do not think web components are going away, and I don’t think this is bad. The introduction of web components (or a similar standard for extending, packaging, encapsulating, and importing discrete UI components) is long overdue in web development. Even if you do not put all your stock in web components—for example, lifting back the curtain and seeing how the Great Oz accomplishes his UI wizardry, making an element draggable—they can be very useful.

Glenn Vanderburg said, “Developers should always understand one layer of abstraction below their everyday work.” I agree with this statement, and I would argue that widget libraries, jQuery plugins, and even jQuery are the levels of abstraction at which most frontend engineers operate on a daily basis. The level just below that consists of the DOM manipulations these libraries perform, and the DOM and its native APIs. Understanding precisely what these libraries are doing will enable you to write more efficient code on a daily basis and prepare you for the great awakening.

Inevitably, there will come a time when one of these libraries does not fit nicely into the use case with which your product manager or information architect has gifted you—at which point, you either sink or swim. I for one would have preferred to have some swimming lessons before my day arrived, but I was not that fortunate.

I was tasked with making a fixed-width portal product fluid-width, and all of the portlets resizable. Sounds easy, right? I was informed that this had been attempted more than once before, and that previous developers had failed and said it was impossible. Well, that was encouraging. On top of this, Internet Explorer 9 had just hit the market, and due to technical debt we were running three different versions of jQuery and two different versions of jQuery UI, none of which worked well with IE9. So, before I could even start the resizing work I had to move to a single version of jQuery and jQuery UI that played nicely with IE9. You might think that moving to a single version of each library would be a simple process, but I quickly realized why we had accumulated the massive technical debt. We were running a myriad of jQuery plugins ranging from bad to awful in quality and old to ancient in web time. In addition to breaking our code, the upgrade broke the majority of these plugins. This required upgrading and patching several plugins, and replacing others. This in turn involved an intimate knowledge of the DOM, which I did not have. I console logged, reverse engineered, and consumed Stack Overflow until I had solved every problem. This was all before I could even get started on the column resizing and portlet changes.

Next, I got some ridiculous requirement that the portlet column resizing had to look precisely like a mock that had already been approved. It also had to behave just as the approved specification described. There was not a plugin in existence that would meet these requirements. Marvelous. I got to write my own.

Once I had that spaghetti code written, I had to make all the portlets and every widget resizable. All of these events had to be timed properly, and nothing could spill out of containers while resizing. setTimeout and I began a love affair that still continues to this day.

If you can relate to this story, then you likely have your own. If so, like me, you probably hacked something together that was a hodgepodge of Stack Overflow responses and miscellaneous jQuery plugins held together by some glue code you wrote that have 100 different branches to account for all the anomalies that occurred due to your lack of understanding. I have been there, and it is not fun. This experience is why I wrote this book.

In addition to not drowning, there are some other benefits to understanding how the lower-level parts of UI components function:

• It allows you to define an API that makes sense to you—jQuery plugins are not everyone’s cup of tea.

• It gives you full control over the entire stack, which makes debugging easier and allows you to decide at what layer a change should occur.

• It allows you to decide which features are important and to limit your footprint in cases where file size is of great concern (e.g., mobile applications).

• It allows you to make optimizations that fit your applications and use cases.

Lastly, I think that it is every frontend engineer’s job to understand the DOM and vanilla JavaScript. This understanding, and the ability to design solutions, is what sets frontend engineers apart from frontend developers.

What This Book Is

The primary goal of this book is to provide the foundational knowledge required to develop and deploy web components. It is intended to be an introduction and to inspire, not to be an exhaustive resource on the subject matter. This foundational knowledge has been divided into four parts, preceded by a general introduction to web components and the areas we will tackle in this book. Each of these sections and their chapters will build upon a working code example.

Part I, UI Core Concepts

The first part covers core concepts such as cloning nodes, rendering layers, stacking contexts, and z-index that are necessary for understanding how to properly position, drag, and resize elements. These concepts are often misunderstood or only partially understood, which can lead to poor design decisions and implementations. These poor decisions can have a significant impact on the performance and maintainability of your code. If you already have a firm grasp on these concepts, then feel free to skip ahead to Part II.

Note

The base class component and the dialog component that are used throughout the rest of the book are introduced in Part I. If you skip ahead and later decide that you would like to learn about the design and implementation details, then refer back to Chapter 2.

Part II, Building Our UI

The second part provides an introduction to concepts and patterns that are typically abstracted away from day-to-day frontend development by libraries such as Dojo, jQuery UI, Kendo UI, and Twitter Bootstrap. These concepts and patterns are used to implement UI components that you probably work with on a daily basis as a front-end engineer. The benefits that these abstractions and UI components provide cannot be understated. I highly recommend leveraging a base library such as jQuery UI that provides good life cycles, extension points, and access to utility functions and helper classes. If you need a more lightweight foundation you can explore using jQuery++, which provides APIs for dragging, dropping, resizing, etc. in a single 162 KB file. It also allows you to cherry-pick features, further reducing the file size.

A practical application of these concepts and patterns is illustrated by the continuation of the dialog component that was introduced in Part I.

If you are already familiar with these patterns or you would prefer to dive right into the meat of web components, then start with Part III.

Part III, Building HTML5 Web Components

The third section provides an introduction to web components as defined by the World Wide Web Consortium (W3C) and implemented by browsers. This section takes the working example built in and and converts it into a fully functioning web component.

Part IV, Testing, Building, and Deploying Components with Polymer

The fourth section covers how Google’s Polymer bridges the web component implementation gaps in today’s browsers and provides convenient APIs for creating extendable web components. It then guides you through converting your web component from Part III into a Polymer component. Finally, it shows how to package and deploy the raw web component and the Polymerized version using different package managers.

What This Book Isn’t

The intent of this book is not to be the definitive guide for developing web components across the entire spectrum of devices used to access the Internet. That would be an impossible endeavor, for two key reasons.

First, the capabilities of the browser have increased significantly in recent years, and the Internet has transformed from a document delivery mechanism into a quasi application platform. This transformation has made the browser a much more robust and feature-rich platform than I ever imagined possible back when I was using tables to lay out pages and testing them in Netscape 4. There are now many new techniques for achieving what would have been spectacular feats of JavaScript pixel pushing using CSS alone. These native features continuously evolve, but are adopted at differing rates by browser vendors. Implementation varies across browsers as well, because browser vendors base their implementations on their own interpretations of the W3C specifications. These features are very relevant to web component development, but this brave new browser world is a book topic in its own right. Inclusion of this level of detail is out of scope. While it is very relevant, it is not required for web component development.

Secondly, the number of device types and vendors—smartphones, tablets, phablets, etc.—has increased significantly over the past five years. This proliferation of new devices and manufacturers has reintroduced limitations that we assumed were issues of the past: limited processing power, limited memory, smaller form factors, poor network connectivity, etc. This influx of new devices has impacted web development in interesting ways, and introduced new concepts such as responsive design and adaptive design. They have also introduced new interaction patterns, such as the touch event and gestures. All the devices have their own sets of quirks. The new and expanding mobile market is a field of its own within the web development world, though, and too deep a topic to include here.

Trying to account for these complexities and others in web development when authoring a book of this nature is simply not feasible. The book would be larger than The Art of Computer Programming and out of date before the first chapter was complete.

Warning

In addition to issues relating to the number of devices on the market and varying device capabilities, it is equally import to note that the W3C Web Components specification is a working specification. As a result, information contained in this book will likely become dated and require the publication of new editions as the specification is finalized. A best effort will be made to follow the specification as closely as possible.

Conventions Used in This Book

The following typographical conventions are used in this book:

Italic

Indicates new terms, URLs, email addresses, filenames, and file extensions.

Constant width

Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.

Constant width bold

Shows commands or other text that should be typed literally by the user.

Constant width italic

Shows text that should be replaced with user-supplied values or by values determined by context.

Tip

This icon signifies a tip or suggestion.

Note

This icon signifies a general note.

Warning

This icon indicates a warning or caution.

Using Code Examples

Supplemental material (code examples, exercises, etc.) is available for download at https://github.com/webcomponentsbook.

This book is here to help you get your job done. In general, if example code is offered with this book, you may use it in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this book does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books does require permission. Answering a question by citing this book and quoting example code does not require permission. Incorporating a significant amount of example code from this book into your product’s documentation does require permission.

We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Developing Web Components by Jarrod Overson and Jason Strimpel (O’Reilly). Copyright 2015 Jarrod Overson and Jason Strimpel, 978-1-491-94902-3.”

If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [e-mail].

Safari® Books Online

Note

Safari Books Online is an on-demand digital library that delivers expert content in both book and video form from the world’s leading authors in technology and business.

Technology professionals, software developers, web designers, and business and creative professionals use Safari Books Online as their primary resource for research, problem solving, learning, and certification training.

Safari Books Online offers a range of plans and pricing for enterprise, government, education, and individuals.

Members have access to thousands of books, training videos, and prepublication manuscripts in one fully searchable database from publishers like O’Reilly Media, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, Course Technology, and hundreds more. For more information about Safari Books Online, please visit us online.

How to Contact Us

Please address comments and questions concerning this book to the publisher:

• O’Reilly Media, Inc.
• 1005 Gravenstein Highway North
• Sebastopol, CA 95472
• 800-998-9938 (in the United States or Canada)
• 707-829-0515 (international or local)
• 707-829-0104 (fax)

We have a web page for this book, where we list errata, examples, and any additional information. You can access this page at http://bit.ly/developing-web-components.

To comment or ask technical questions about this book, send email to [e-mail].

For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.

Find us on Facebook: http://facebook.com/oreilly

Follow us on Twitter: http://twitter.com/oreillymedia

Watch us on YouTube: http://www.youtube.com/oreillymedia

Acknowledgments

Jason Strimpel

First, I would like to thank my wife Lasca for her encouragement and understanding. I cannot imagine a better partner in life. I have never known a more intelligent, beautiful, and unique person. I love you. You are my favorite everything. Beep boop.

I would also like to thank my manager, Claude Jones, for his guidance and help. Without it, this book would not exist.

I would like to thank my coauthor Jarrod Overson for agreeing to step in and write Part IV. If you sometimes think you’re faking it, then I am doomed, as you are definitely a more gifted writer, speaker, and engineer than me.

Many thanks to Simon St.Laurent for hearing out my half-baked idea, and providing the feedback that shaped it into an acceptable book proposal. Also, my editor Brian Anderson is the most patient person I have ever known. Without him this book would be nothing more than the inner workings of my mind without context and would not be understood by anyone expect myself. Thank you Brian.

Finally, I would like to thank all the silent partners—the engineers who write much better code than I ever will and have taught me innumerable lessons. They choose to remain out of the public eye, but if you are lucky enough run across one of them in your career—trust me, you will know it— then listen to them. It is because of these silent partners that I am even passable at best for an engineer and that I am able to share what little knowledge I do posses.

Jarrod Overson

None of my work would have been possible without the support and patience of my wife, Kate Lane. For years now she has accommodated my ramblings about JavaScript, particles, and physics simulations while always being supportive and motivating. Thank you for giving me the opportunities to speak abroad, code into the night, and spend far too much time organizing community events. Without your support none of what I have now would have been possible, including my two beautiful children.

Thank you Finn, for bringing so much joy into my life. All of your great ideas leave me amazed and thrilled to be your father. Thank you Norah, for always being able to put a smile on my face. Both of you have been my motivation to be a father and person that you can be proud of.

Finally, thank you, Jason, for thinking of me when putting this book together. You’re one of San Diego’s best developers and it’s always an honor working with you. I hope to be able to work with you many more times in the future.