Adcom is a set of JavaScript plugins and frontend styles
that are the foundation for admin sites at The New York Times.
The plugins serve common use cases on the internal sites we create day-to-day: rendering dynamic lists, standardizing form validation, maintaining state across page loads, persisting settings, and others.
The styles (view an example here) are a custom flavor of Bootstrap, and establish guidelines for what to include on each page, and where. A consistent visual language helps people feel more comfortable using our tools, and makes them easier for our developers to maintain.
Currently v0.1.0. Last updated April 19, 2015.
Adcom was built for our specific needs at The New York Times, but is based on a more general set of issues we identified as a large programming team.
Our internal websites are used by copy editors, reporters, web producers, developers and others, and we feel it's important for them to have a consistent workflow and visual framework. These tools should feel familiar and predictable, not dangerous. This is especially important when creating tools by developers using separate frameworks and codebases.
Adcom contains a boilerplate layout for how to structure our sites, with Bootstrap-based components and best practices for when and how to use them.
Long-lived admins encourage feature creep. They can grow over months or years to cover more needs and options, and development time can be lost reimplementing code to suit them.
We try to smooth out that process by providing foundational plugins that are quick to use for a 1.0, but flexible enough to grow with increased complexity.
For example, List.js helps you render simple tables for a first draft. When you need a more advanced templating engine, additional filtering or you need to change the data source, each change can happen independently, without having to start over with a new plugin.
Making our front-end code easier for newcomers to maintain and understand means keeping our code organized. Moving the JavaScript for common tasks into plugins, and moving the configuration into the HTML, keeps each page's JavaScript focused on it's unique business logic.
Like Bootstrap, Adcom's plugins encourage use and configuration in the View layer by setting data attributes directly on elements. This reinforces thinking of the document as driving development. The API tries to flatten the shared JavaScript and document layers, linking the physical map of a page to its source code and the JavaScript that enhances it:
We build our sites using different frameworks and languages. To make Adcom usable across it all, we focus on the document.
The document layer is the closest blueprint we have to the finished page that users access, making it a useful starting point into understanding and changing a page. It's design also tends to be the most resiliant across frameworks. So sharing code incresingly means sharing documents.
So we encourage configuring our plugins in the document and writing template partials inline.
Download the latest version from GitHub.
Adcom is also available over bower.
bower install adcom
The dist folder of the source code contains the following files:
adcom/
└── dist/
├── css/
│ ├── adcom.css
│ ├── adcom.css.map
│ └── adcom.min.css
└── js/
├── adcom.js
└── adcom.min.js
The adcom.css and adcom.min.css both include Bootstrap v3.3.4. adcom.js and adcom.min.js do not include the Bootstrap JavaScript plugins; if you require them, they must be included separately.
You can include all of the plugins or individual ones by loading either the distribution adcom.js file or any of the source files.
<!-- load all of plugins -->
<script src="dist/js/adcom.js"></script>
<!-- load list.js only -->
<script src="js/list.js"></script>
Plugins are also compatible with the Asynchronous Module Definition API:
<!-- using require.js -->
<script src="require.js"></script>
<script>
require.config({
paths: {
jquery: 'assets/jquery',
adcom: 'assets/adcom'
}
});
require(['adcom'], function() {
// all plugins are defined
});
</script>
Each assumes jQuery is available on the page or through RequireJS, and will install List.js to $.fn.list.
Most plugins have a set of primary options that can be specified in two ways:
.list({ "option": true }))For example, set the show option on a list with a data attribute on the element, or by passing a boolean to the initializer:
$(list).list({show: false})<list data-show="false"> ... </list>When a plugin is initialized, all data attributes on the element are converted into options that get passed into the initializer as defaults. You can also mix and match; options specified in the JavaScript initializer take precedence over those as data attributes. Multi-word options are expressed in camel case in JavaScript (currentPage), and with hyphens as data attributes (data-current-page).
Adcom includes CSS styles which are a compiled variation of Bootstrap. There are several modifications / additions Adcom makes to the following categories:
It also includes a boilerplate scaffold of the overall structure we use for admins at The New York Times.
<!-- load adcom.css in your head tag -->
<link rel="stylesheet" href="/assets/adcom.css">
To make changes to the plugins or styles, make sure you have npm installed on your system. Then, run npm install within the project's home directory to install dependencies.
You also need to have bower installed to load Bootstrap as a dependency. Run bower install.
Several grunt tasks are provided to make development easier:
grunt compiles the CSS and JavaScript, and updates the docs with the latest codegrunt watch listens for changes to the source files, recompiling the CSS or JavaScript when necessarygrunt jekyll:server boots up this documentation on localhost:8000/adcom/This repo is hosted on GitHub. Please use the Issues page to comment on the project and report any bugs or concerns you have.
To contribute pull requests, please fork the repository and create a pull-request against the develop branch.
Adcom is released under the Apache 2.0 License.