Newspack Elections

Newspack Elections is a free and easy “no code” way to build a voter guide on your Newspack site that includes dynamic profiles of public officials and provides readers quicker access to more information about them.

This tool allows newsrooms to create and upload hundreds of candidate profiles at once by generating customizable “profile blocks” you can easily insert into voter guides or stories. The profiles you build with Newspack Elections can include key candidate information, giving voters easy access to campaign websites, social media profiles, and other relevant details.

You can see a walkthrough of the new features of Newspack Elections on Loom.

Get started

You can download a beta of the plugin via its “Releases” page on GitHub.

Collect all of the information that will feed your Newspack Elections profiles in a spreadsheet.

Start by cloning the Google spreadsheet import template; there are more than 50 columns of information that the plugin supports. Do not change the text in the column headers. You can delete the columns you don’t need without affecting the plugin’s performance. As long as you don’t change the text inside the column headers, you can do common spreadsheet tasks like freezing rows and using filters, etc. 

The candidate information that Newspack Elections supports falls into five distinct categories: 

1. Basic information
2. Demographic information
3. Biography and endorsements
4. Contact information
5. Social media information

For a guide to what should go in each category, read the “what to include” section.You’ll then activate Newspack Elections on your site via Newspack -> Connections.

Upload your spreadsheet

Once your spreadsheet contains all of the information you’d like to include in your profiles, download the spreadsheet as a CSV. Go to the “File” menu, then choose “download” and “Comma Separated Values (.csv).”

Upload it to your site by going to Elections –> Import in the left rail of your site’s dashboard. Click the blue “choose file” button, and select the .csv file you downloaded from Google Sheets.

Click “Upload.” Though it might take a minute to begin, you should see a count of all the profiles you’re uploading, and a progress bar as the profiles import.

Upon completion, click the link to see your imported profiles.

You can edit each profile individually and add or change information if necessary. You can see and edit all of the main information in the Newspack Elections profile in the right rail (Election Profiles –> Profiles)

Scroll down to see the entire list of category information populating that profile.

If there is information you want to add, remove or edit after the CSV is uploaded, you can do that here. 

If there are fields you would like to hide from the profile page, you can make those changes under the “block” tab. Click the main profile to highlight it, then click the “block” tab. 

NOTE: The changes you make in field visibility in this screen affect the individual candidate profile pages. When you add profiles to voter guide pages, you can make different decisions about what information to display or hide.

You can customize how these profiles look, including adding tints, toggling fields on and off, and choosing whether to show the field labels or not.

Publish your voter guide

When you add a profile, it’s saved in draft mode until you click “publish.” You can publish profiles individually by opening them and clicking the “publish” button, or publish every profile at once.

To bulk publish, click the open square next to the “picture” header to select all of the profiles on the current page, select “publish” from the “bulk actions” menu, and click “apply.”

Create voter guide pages

Once you upload and publish your profiles, they’re visible to anyone who happens across them (generally through search). We suggest embedding the profiles into individual voter guide pages for increased visibility and usefulness.

Types of profiles

There are three variations of profiles available in Newspack Elections. They include an “elections profile,” “inline profile,” and “mini profile.” 

Full Profile: This is a default option that includes a variety of commonly-used fields. Because it’s so wide, it’s best used on its own and not in columns with other profiles.

Profile: This is the do-it-yourself option, suitable for most voter guide layouts where you’d like to include a wide variety of information.

Inline Profile: This is a slimmer version of the full profile, best for embedding into stories.

Mini Profile: This is a tiny version of a profile with limited fields. This version is best if you have several candidates and only want to include basic information about each. This version also includes an option to change the candidate’s name to a URL that will direct to their more detailed profile page.

How to use patterns for your voter guide

The latest version of Newspack Elections has many customization options. But if you want to avoid building each profile from scratch (a process that can be very time-consuming for voter guides with dozens or even hundreds of candidates), create a pattern. 

Depending on the information you’d like to include in your guide, you may need more than one pattern. Perhaps you want to include the same information for every candidate — if so, one pattern may suffice. Maybe you want to include certain fields for Senate candidates, and different fields or styling for judges. In that case, consider creating a “Senate” pattern and a “Judge” pattern. And maybe it makes sense to do one pattern (perhaps with a red tint) for Republicans, and another (blue-tinted) for Democrats. In that case, create a “Republican” and “Democrat” pattern.

Follow the steps below for each pattern you’d like to create.

Decide what you want in your pattern

Build a pattern from an existing candidate profile. Keep in mind, you may not have the same information for all candidates. Start with all of the fields you want to include, if available. For example, you can include all personal and campaign accounts on X, Facebook, and Instagram. Build them into the pattern, and the plugin will display the ones that are available for each candidate. 

NOTE: We’ve created some patterns to fit some common situations and to save you time; you can find a rundown of those patterns in Appendix 2.

Create a profile to use as a pattern

Create your first profile block to use as your pattern for the rest of the blocks. Here’s what this means:

• The formatting you use in this pattern profile will carry through for every profile that uses the same pattern. Carefully consider the colors, font size, bolding, and whether you want the field labels to appear.
• The fields you use in this pattern profile appear in every profile that uses the same pattern, as long as the information is in the system. For example, if you always want the campaign address to appear if it’s available, make sure to include the “campaign address” field in your pattern profile. 
• If you include a paragraph block, the tool will replicate it in the pattern. For example, if you use the paragraph block to enter customized candidate information, you will manually update it every time you use the pattern for a different candidate. 

Open a blank post on your Newspack site. 

We optimized Newspack Elections to work with columns, so insert a column block and select the 50/50 layout.

Now, add your pattern profile. Click the “+” and choose the “Elections Profile” block.

Then, select a profile to use for the pattern. (We recommend choosing a candidate for the pattern that has information in most or all of the fields you want to include.) 

In the following tutorial, we’ll assume you’re using the “Profile” block as a pattern.

By default, the plugin will load the candidate’s name, picture, political party, and status.

Adding profile fields

Click the bottom of the profile block, and click the “+.” Select a “Profile Field” block. (You may have to type this into the search for it to appear.)

Note: Don’t click the smaller “+” you may see initially under the profile. That will add an entirely different block outside of your profile.

Click the same “profile field” icon that now appears in the toolbar; you’ll see the universe of options here, including the data you have saved for this candidate. 

Choose the field you’d like to add to the profile. Then, repeat the steps to add additional profile fields (except for social links, which you will add in the next step). These fields will load unstyled; we will style them in a subsequent step.

Decide how you’d like social media links (as well as links to other sites like Ballotpedia and Wikipedia) to appear. You could group them all together, or separate them by personal, official, or campaign accounts. 

When you’re ready to add social media profiles, click the “+” in the pattern profile. Select “profile social links.” (You may have to type this into the search bar for it to appear.)

Then, click the smaller “+” that appears and choose the social links you’d like to insert.

(If you decided to break up the social links into groups that would benefit from a label, insert a paragraph block into the desired spot on the profile and create your own label.)

NOTE: Though you may see them on the backend, only the social icons linked to data will appear on the published profile. In the above example, the campaign YouTube icon is faded to indicate that it won’t appear on the front-end. But if you’re creating a pattern, the campaign YouTube site will appear for candidates that have one. 

To include links to sites that will help voters do even more research about the candidates, use this same “profile social links” block. Those sites include Ballotpedia, LinkedIn, Open States, OpenSecrets, the FEC, Wikipedia, and Vote Smart (more information on these sites in the Appendix).

Repeat these steps of adding profile fields and profile social links until the profile has all of the fields you’d like to include in your profile pattern. If there’s a field you want to include for which the current candidate doesn’t have any information, it will appear as a “hidden field” in both the pattern profile and any other profiles that use the pattern and lack the information. 

Use the arrows to arrange the profile fields in the desired order.

Formatting and design

This version of Newspack Elections offers several ways for users to customize the design of the profile blocks. 

To change the entire profile, click the “Document overview” icon at the top of your post, then select the main profile block instead of one of its many components.

Click on the circular “styles” icon in the right-hand block menu. 

Here, you can make changes that affect the entire profile block. They include:

• Changing the style from “default” to a red, blue, or yellow tint, or a solid red, blue, or yellow.
• Changing the text color, size, and spacing.
• Change the background color of the profile
• Change the padding on the top, bottom, and sides of the profile

Once you have made your profile-wide changes, you can format the individual data blocks inside the profile. Click on the white space between the label and data to select the entire block.

The formatting options will appear in the right sidebar under both the “settings” and “styles” menus. They include:

• Showing/hiding the field label
• Changing the text justification
• Changing the font or color of the text
• Changing the text size
• Changing the social media icon size

You can click on one component of the data block to apply changes (such as bolding or italicizing) to either the field label or data. It’s also possible to add regular Newpack blocks to the profiles, such as paragraph blocks or separators. 

You can customize the appearance of links as the label or as the URL. For example, a phone number appears like this by default (with the text linking to the number):

Click on the block that says “Official Phone Number,” and the menu below appears in the right sidebar. 

You can keep as-is, or select another option. Selecting “number” will look like this:

If you want to give readers an easy way to click through to a candidate’s full profile, there are several options:

• Click on the candidate’s name, and choose “make title a link” in the settings menu on the right rail. 
• Click on the candidate’s picture and choose “link to Election Profile” in the settings menu on the right rail.
• Manually add a link into the profile block. (Note: This isn’t a good option if you are creating a pattern you will use for multiple candidates.)

Save your pattern

Once everything is exactly as you want, save your pattern. Click the “Document overview” icon at the top of your post, then make sure you’ve selected the main profile block instead of one of its many components.

Then, click the three dots at the top of the profile and select “create pattern.”

Name the pattern something descriptive (“Candidate default,” “Senate profile pattern,” etc.)

Untoggle the “Synced” option. (This is very important!)

Build your voter guide

Once you have your profile pattern, lay out your profiles on the page. (If you’d like to build each profile manually, you can do that, as well.)

The most visually-appealing layout for these profile blocks is in columns, either two- or three-across. 

Insert a column block and select either the 50/50 or 33/33/33 layout, depending on the number of candidates in the race. 

Click the “+” and begin typing the name of the pattern you saved. It should bring up that pattern as an option. Select the pattern.

Repeat the step in the adjacent column. Now, you should have two identical profiles side-by-side.

To change the candidates, select “choos another profile,” denoted by a pencil icon at the top of the profile.

It will bring up the list of all of your published profiles. Select another candidate.

You’ll notice that the profile is replaced with the new candidate’s information, but retains all of the fields and stylings of the pattern. If you included fields in the pattern where there is no data, it will appear as a hidden field. You can view it on the back end, but not in the preview or published version. (The only exception to this is if you have entered a custom paragraph block. For example if your pattern has a block that says “personal social media” and the candidate has no personal links, the paragraph block will still appear even while the links do not.)

You can make changes to individual profiles without affecting the overall pattern.

Other useful elements to consider

Detail blocks

If your voter guide is long, consider using Detail blocks so readers can decide what information to view.

On the published page, the information included in Detail blocks appears like this:

You can also style them via the block settings on the right, and change the block’s text or background color.

Here are two examples of what that could look like:

Users can click the triangle (or anywhere in the header) to expand the menu, and you can insert the Newspack Elections blocks into the collapsible section. 

Anchor links

Anchor links are very helpful when you have a lot of information on a page, and you want to provide an easy way for users to navigate.

First, figure out where you would like users to be able to jump to via a link. In the example below, you want them to be able to navigate directly to the “key dates” section.

Click on the block above the target section. In this case, that’s the block that contains information about how to find your polling place. In the block settings, click “advanced” and enter the word or words you’d like to use for your anchor tag. For example, “key-dates.”

Go to the place in the text where you’d like to use this anchor link. Here, it’s a “table of contents”-like block used at the top of voter guides. You can then insert the anchor tag over words or into a button by using the “link” option, and entering it as “#ANCHOR_NAME.” In this example, “#key-dates.”

Pattern blocks for different races

While you’ve already created a profile pattern block, you can also create patterns for different races. These kinds of pattern blocks are useful when you want to group Newspack Elections profiles (for example, all the candidates for a certain race) and insert that same group of profiles into multiple voter guide posts or pages.

Click on the block of profiles, and click the three dots on the right of the menu that appears. Then choose “Create pattern.”

Name the pattern, and click “Add.”

The next time you want to use this pattern, you can call it up like any other block. Type a “/” and start typing in “/NJ District 39.” It should bring up that pattern, and you can select it to insert the block. If you opt to have the pattern synced, you can update it once and have that update reflect every time the pattern is used.

Appendix 1: What information can you include in Newspack Elections?

There are more than 50 possible fields of data to collect via the import template. You can collect as many or as few as you want and delete any irrelevant columns.

Note: Do not rename the column headers because the import function won’t work properly if you do.

Here’s more about what information each field should include:

Basic information

Spreadsheet column	Meaning
name	This is the way the candidate’s name will appear at the top of their individual profile page. If you have a candidate, for instance, who goes by “Dr. John ‘Doc’ Smith Jr.,” that’s the way you should identify them in this column.
name_prefix	This is rare, but if you have a candidate running as a doctor, general, etc., you can indicate that title in this field.
name_first	Candidate first name
name_middle	Candidate middle name
name_last	Candidate last name
name_suffix	If they have a suffix to their name — for example, Sr., Jr., or III, you can indicate that here.
nickname	Candidate nickname, if any.
office_status	A place to indicate whether the candidate is an incumbent or a challenger, or any other way you’d like to indicate their status.
office_state	The state where the candidate is seeking office. This field will likely be unnecessary unless you include candidates from multiple states.
office_name	The office the candidate is seeking. Some examples include “U.S. President,” “Montana Governor,” “Circuit Court Judge,” or a legislative body such as “West Virginia House of Delegates.”
office_title	This may be redundant with the above, but it’s best to fill it out anyway. If the office_name is “U.S. Senate” the title would be “U.S. Senator,” for example.
party	The candidate’s political party.
bio	You can insert any text into this field, such as biographical information. It appears under the profile block on the candidate’s individual profile page.
image	This is an important column. For aesthetic reasons, every candidate in Newspack Elections should have a picture. Populate this field with a link to a .jpg or .png file. (Note: this shouldn’t be an attachment, but rather the URL of a picture file, which you can get by right-clicking a web image. If you don’t have a picture, you can upload the profile without it and either add it later or add a generic blank profile picture.) Once these images are imported, the tool will automatically add them to your website’s media library.
district	The specific district in which the candidate is seeking office, if applicable. This might be something like “Tennessee State Senate District 5” or “New Jersey Family Court, 4th Judicial Circuit.”
endorsements	Any relevant endorsements of the candidate you’d like to include.
occupation	The candidate’s occupation.
education	The candidate’s education, training, or degrees.

Demographic information and key dates

Spreadsheet column	Meaning
gender	The candidate’s gender, if it’s relevant to include. Note: You can include this information and choose not to display it publicly, which may help with newsroom analyses into candidate demographics.
race	The candidate’s race, if it’s relevant to include. You can enter whatever categories your newsroom decides to use for this field. Note: You can include this information and choose not to display it publicly, which may help with newsroom analyses into candidate demographics.
ethnicity	The candidate’s ethnicity, if it’s relevant to include. You can enter whatever categories your newsroom decides to use for this field.
date_of_birth	Candidate date of birth. Must be in a YYYY-MM-DD format.
date_of_death	Probably not relevant for inclusion in voter guides, but if you’re maintaining these profiles after the election, it can be a relevant field to include. Must be in a YYYY-MM-DD format.
date_assumed_office	The date the candidate assumed office. Must be in a YYYY-MM-DD format.
appointed_by	If relevant, the person who appointed the candidate.
appointed_date	If relevant, the date the candidate was appointed. Must be in a YYYY-MM-DD format.
confirmed_date	The date the candidate was confirmed. Must be in a YYYY-MM-DD format.
term_end_date	The date the candidate’s term ends. Must be in a YYYY-MM-DD format.
congress_year	If relevant, you can include the congressional year.

Contact information

When you include information in many of these columns, you can choose to group it together under “campaign,” “official,” and “personal” headers and appear as an icon (for example, a Facebook logo for a Facebook link, or a telephone icon for a phone number).

Spreadsheet column	Meaning
email_official	If the candidate is an incumbent, their official email address.
email_district	The email address of the candidate’s district office, if any.
email_campaign	The candidate’s campaign email address.
email_other	Any other non-official or non-campaign email address for the candidate.
contact_form_url	The link to a contact form if that’s a preferred way of getting in touch with a candidate.
address_official	For incumbents, their address is at the state or U.S. Capitol building, or wherever their official office is.
address_district	For incumbents, their address is in their home district.
address_campaign	The candidate’s campaign address (generally, the address they use to file their candidacy paperwork).
phone_official	For incumbents, their official Capitol (or other building) phone number.
phone_district	For incumbents, the phone number for their district office.
phone_campaign	The phone number the campaign listed when filing for office.
fax_official	For incumbents, their official fax number.
fax_district	For incumbents, their district office fax number.
fax_campaign	A candidate’s campaign fax number, if any.

Social media information

When you include information in many of these columns, you can choose to group it together under “campaign,” “official,” and “personal” headers and appear as an icon (for example, a Facebook logo for a Facebook link, or a telephone icon for a phone number).

Spreadsheet column	Meaning
website_official	If the candidate is an incumbent, their official website. Use full URL, including “http://www…”
website_district	The candidate’s district website, if any. Use full URL, including “http://www…”
website_campaign	The candidate’s campaign website, if any. Use full URL, including “http://www…”
website_personal	The candidate’s personal website, if any. Use full URL, including “http://www…”
x_official	For incumbents, their official Twitter/X account. Include a full URL to the page, rather than the @ username.
x_campaign	The candidate’s campaign Twitter/X account, if any. Include a full URL to the page, rather than the @ username.
x_personal	The candidate’s personal Twitter/X account, if any. Include a full URL to the page, rather than the @ username.
facebook_official	For incumbents, their official Facebook account, if any.  Use the full URL.
facebook_campaign	The candidate’s campaign Facebook account, if any. Use the full URL.
facebook_personal	The candidate’s personal Facebook account, if any. Use the full URL.
instagram_official	For incumbents, their official Instagram account, if any. Use the full URL.
instagram_campaign	The candidate’s campaign YouTube channel, if any. Use the full URL.
instagram_personal	The candidate’s personal Instagram account, if any. Use the full URL.
youtube_official	For incumbents, their official YouTube channel, if any. Use the full URL.
youtube_campaign	The candidate’s campaign YouTube channel, if any. Use the full URL.
youtube_personal	The candidate’s personal YouTube channel, if any. Use the full URL.
linkedin	The candidate’s LinkedIn profile, if any. Use the full URL.
gab	The candidate’s Gab page, if any. Use the full URL.
rumble	The candidate’s Rumble page, if any. Use the full URL.

Other useful candidate information

The fields in this section allow you to display icons that redirect users towards third-party sites that include useful information about candidates and incumbent politicians. 

Spreadsheet column	Meaning
wikipedia	A link to the candidate’s page on Wikipedia, the online user-maintained encyclopedia. Find the page on the site (https://www.wikipedia.org/) and include the full URL in the spreadsheet.
opensecrets_id	A link to the campaign spending information gathered by OpenSecrets. Find the page on the site (https://www.opensecrets.org/) and include the full URL in the spreadsheet.
ballotpedia_id	A link to the candidate’s page on Ballotpedia, the “encyclopedia of American politics.” Find the page on the site (https://ballotpedia.org/) and include the full URL in the spreadsheet.
openstates_id	A link to the candidate’s profile on Open States, a tool from Plural. It includes both Congressional and statehouse incumbents, and provides basic contact information, sponsored bills, and recent votes. Find the page on the site (https://open.pluralpolicy.com/) and include the full URL in the spreadsheet.
fec_id	The FEC collects campaign finance information for candidates for U.S. president, Senate, and the House of Representatives. Find the page on the site (https://www.fec.gov/data/candidates/) and include the full URL in the spreadsheet.
votesmart_id	Vote Smart collects information for local, state, and federal candidates, including biographical information, votes, ratings, and even speeches and press releases. Find the page on the site (https://justfacts.votesmart.org/) and include the full URL in the spreadsheet.

• Get started
  • Uploading the data
  • Publishing
• Creating voter guides
• Useful tips
• What information to include