Usage

What it does, how it works, why it is what it is.

Adcom consists of 1) a collection of JavaScript plugins, and 2) styles for rendering common items. You can use them separately or together.

JavaScript

Adcom includes several jQuery plugins, configured via data-attributes, that streamline rendering common page elements.

Consistency and iteration

Some things are common in admins: rendering lists, editing records, searching a collection. They're so easy to do, it's often faster to reimplement them each time they come up. But this presents a few problems, especially when working as part of a large team across many admins.

  1. Each time you jump into someone else's codebase, you must relearn how the code is organized. Various methods of sorting and filtering tables and rendering JavaScript templates is mixed in with complex domain-specific JavaScript.
  2. Component complexity outgrows first-draft architecture. Rendering a sortable table of items might be simple at first, but those simple solutions may need to work with more specific needs later on. You may need to combine your original features with others: adding search, or the ability to update records on the backend. When these needs make your original solution obsolete, iteration can become an opportunity to duplicate work.

Adcom's plugins are designed to let you handle simple things in the same way every time. For example, the list-rendering plugin, List.js, lets you render a first draft of a collection in seconds, but provides hooks to override specifics without changing architecture. Complex pieces like server-side search or plugin-powered filtering can be swapped in without changing how you initialize or render content.

Grounding interaction in HTML

Adcom's iteractions are modeled after Bootstrap's, in that they are designed to integrate directly into your rendered HTML without having to write JavaScript yourself by using data-attributes. This helps keep your page's DOM as the starting point for understanding how your site works, giving it a more consistent grounding than one of the infinite JavaScript-first methods.

Styles

Interactive websites, particularly admins, need to clearly convey direction to the user, both in representing what they're looking at and what they're supposed to do.

Adcom addresses this by providing Bootstrap-like classes for displaying common types of information in consistent ways. When possible, rendering attributes like a record's status or metadata should be done in the same way so users understand what they're looking at. Distinct components are also provided, such as Actions which are an alternative to buttons. They let you build visual cues into destructive or constructive actions in your site, such as editing or deleting records.