Adcom is a set of JavaScript plugins and frontend styles
that serve as the foundation for admins at The New York Times.
The plugins serve common use cases on the many internal sites we create day to day: rendering dynamic lists, standardizing form validation, maintaining state across page loads, persisting user settings, and so on.
The styles are a custom flavor of Bootstrap, and includes a set of guidelines for what to include on each page, and where. Ensuring that admins from all of our teams have a consistent visual language helps users feel more comfortable using the sites, and makes it easier for our developers to maintain.
Adcom is available over bower:
bower install adcomThe 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.jsThe adcom.css and adcom.min.css both include Bootstrap. adcom.js and adcom.min.js do not include the Bootstrap JavaScript plugins.
- List.js takes a list of items and renders them using a template
- Form.js standardizes cross-browser form validation and serialization
- Session.js stores individual user settings in localStorage or sessionStorage
- Persist.js creates "sticky" element attributes that can persist across page loads
- Message.js displays alert and snackbar-style messages to readers
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 require, and will install List.js to $.fn.list.
Most plugins have a set of primary options can be specified in two ways:
- As an object to the plugin's initializer function (such as
.list({ "option": true })) - Adding data-attributes to the plugin's element (initializers are normally called on a single DOM element)
For example, set the show option on a list by passing a boolean to the initailizer, or with a data attribute on the element:
$(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 hypens 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">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.
Run grunt to compile the CSS and JavaScript, update the docs, and watch for new changes to the source files to re-run itself.
Run grunt jekyll:server to boot up this documentation on localhost:8000.
Please use the Issues page to comment on the project and report any bugs or concerns you have.
Adcom is released under the Apache 2.0 License.
Created by Michael Strickland for the Interactive News team at The New York Times.