Largo Project DocumentationRelease 0.5

Institute for Nonprofit News

June 03, 2015

Contents

1 Installation And Setup 31.1 Pre-Launch Checklist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 General Documentation 72.1 The WordPress Settings Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Theme Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.3 Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.4 Sidebars and Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.5 Series Landing Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.6 Taxonomies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.7 Post Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.8 Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.9 Contact Forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.10 Advertising . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3 For Developers 293.1 For Developers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293.2 Largo Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.3 Feedback on these docs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

i

ii

Largo Project Documentation, Release 0.5

Largo is a responsive WordPress starter/parent theme built specifically with the needs of news publishers in mind andis built and maintained by the news apps and technology team at the Institute for Nonprofit News (INN).

Questions? Comments? Get in touch with us.

Project Repository: https://github.com/INN/Largo/

Technical Issues (Bugs, Feature Requests, etc.): https://github.com/INN/Largo/issues

Help Desk (Support Requests): http://jira.inn.org/servicedesk/customer/portal/4

Knowledge Base: http://confluence.inn.org/display/LKB/Largo+Knowledge+Base

Twitter: http://twitter.com/largoproject

Mailing List: http://eepurl.com/yu0bT

Contents 1

Largo Project Documentation, Release 0.5

2 Contents

CHAPTER 1

Installation And Setup

1.1 Pre-Launch Checklist

Banner Images - To accomodate a number of screen sizes, the Largo theme requires three image sizes for the topbanner and automatically chooses the correct image size based on the size of a user’s browser window.

• 1170 by 120 px - for most desktop/laptop computers

• 980 by 150 px - for small desktops, most tablets, large phones

• 768 by 200 px - for most mobile phones

If your image is on a white or transparent background we recommend putting the content (logo, etc.) flush against theleft side of the image. For the smallest of the three images (768x200) the content should take up the full-width of theimage so it fills the header on small screens.

Optionally you can elect to not use images and display a text-only header instead. It will use the site title and taglinefrom your WordPress settings. (In the WordPress admin left sidebar, click on Settings and then General Settings tochange these).

Note with Largo 0.4 header images only display on the homepage and not single posts or pages.

Square Image In addition you’ll need to create a square thumbnail image (200 by 200 px is ideal) that is used asa fallback when you share posts on Facebook or Twitter for which you have not set a featured image. In addition,a small version of this image is created automatically by WordPress/Largo for use in the site navigation. Since thisimage needs to be optimized for a small size (60x60 px is the smallest it appears) the best square images should notcontain any text and you should avoid adding significant margins or padding within the image.

Sticky Header Logo - This image should be 100 pixels tall and at least 100 pixels wide. It will appear in the stickynavigation bar that is seen as people scroll, and on mobile.

Site Title, Tagline and Description - Before you launch your site you will need to write a title, tagline and a longerdescription to be used in various places around the site. The title will likely be just your publication or site’s name,the tagline should be short (6-8 words) and a short paragraph is sufficient for the site description (you can always addadditional information about your organization on your site’s “About” page, the short description is just intended togive new visitors an introduction to what your site is about and normally appears as a sidebar widget).

Social Media Accounts - The Largo theme supports social media integration at both the site and author level. Youcan add links to your organization’s Facebook page and Twitter account under the Appearance > Theme Options menuand individual authors can add links to their social media accounts by editing their user profile.

Author Bios and Photos - In addition to adding links to their social media profiles, the authors on your site will wantto complete their user profile to at least include a short bio. In addition, they can add a photo by using Gravatar (notethat the e-mail used to create their WordPress account must match the e-mail they use with Gravatar).

3

Largo Project Documentation, Release 0.5

Google Analytics - If you use Google Analytics, you will want to have your ID handy so you can add it to your ThemeOptions. Your Google Analytics ID (also called a “property ID” will be in the following format: UA-XXXXXXXX-Xand is available from the Admin section of your Google Analytics account. Once you add your ID in the Largo ThemeOptions it will automatically add the appropriate code to all pages of your site so you should not use a plugin or modifythe theme to include your Google Analytics code anywhere else.

1.2 Getting Started

1.2.1 Download and Install WordPress

The Largo parent theme and plugins have been tested with the latest version of WordPress. Some hosting providersoffer one-click installation of WordPress and that should get you the latest version. If that does not work for you,download the latest version from the WordPress downloads page and follow their instructions to get it setup.

1.2.2 Download and Install Largo

The latest stable version of the Largo parent theme is available for download from the project repository on github ongithub. The master branch (download link) is always the latest stable release although you may sometimes want toalso keep an eye on the develop branch which contains our work on the next release of Largo. Note that we do notrecommend using the develop branch on a production site.

Once you have downloaded the Largo theme you’ll need to unzip it, and will typically want to rename the resultingfolder to just “largo” (github will include the name of the branch in the name of the folder, i.e. - largo-master, but toavoid potential problems with the following instructions using “largo” as the name of the folder will make your life alittle easier.

Now you’ll need to upload the “largo” theme folder to your hosting provider in the /wp-content/themes/ folder of yourWordPress installation.

If you don’t plan to modify the Largo theme beyond what is possible from the dashboard then you can just activate thetheme under Appearance > Themes and skip the following section about creating child themes.

1.2.3 Creating Child Themes

In order to make it easier to upgrade to future versions of the Largo parent theme, you will want to add any customiza-tions that are unique to your site by creating a child theme. WordPress has a tutorial you can follow that explains howto create and configure a child theme.

NEVER modify the Largo parent theme directly, even to make small changes. It will make your life much harderwhen we release a new version because your changes are highly likely to be overwritten.

To create a child theme, at a minimum you will need to create a new theme folder (call it something like “largo-child”in your wp-content/themes directory and add one file to it called style.css. That file would be used to add any customCSS unique to your child theme, but it also tells WordPress where to find the parent theme.

At the very top of the file you need to add at least the following:

/*Theme Name: Your Child Theme's NameTheme URI: Your Site URLDescription: Your Theme DescriptionAuthor: Your NameAuthor URI: Your Author URLTemplate: largo

4 Chapter 1. Installation And Setup

Largo Project Documentation, Release 0.5

Version: 0.1.0\*/

The line starting with “Template” must include the name of the folder that contains the parent theme files (this shouldbe “largo” unless you name the parent theme folder something different).

If you would prefer, we have created an example child theme that you can start from where we document our preferredstructure and how to modify the behavior, look and feel of Largo, create custom templates, etc.

To use this child theme, simply download and unzip it just as you did the Largo parent theme above, modify the headerblock in the style.css as described above and then upload the folder to your wp-content/themes directory along withthe Largo parent theme. The sample child theme contains a number of additional files and documentation that youmay not need so you might consider removing the elements you do not intend to use.

Now that you have a child theme created, login to your WordPress site and go to Appearance > Themes. Find yourchild theme, click “activate” and then you should see your new child theme in action on your site and can begincustomizing.

More: Using Child Themes.

1.2.4 Configure Theme Options

Now that you have activated your theme you will want to configure some of the built-in options that come with Largo.You can find these under Appearance > Theme Options.

There are tabs across the top of the page that allow you to access different sections of the Theme Options.

• Basic Settings allows you to enter some basic information about your site such as a short description and socialmedia links and to enable/disable and configure some of the built-in functionality in the Largo theme such asrelated content at the bottom of single articles and a number of menu areas that you will configure in the nextstep.

• Theme Images is where you will upload a number of images that the Largo theme requires. These include athumbnail-sized logo image and three banner images that are used as the site’s top banner on different screensizes.

• Layout Options allows you to choose between different homepage layouts and customize other elements of thesite’s layout.

• Advanced contains less frequently used functionality that can be toggled on/off and some other advanced set-tings.

More: Theme Options Detailed Documentation

1.2.5 Configure Menus And Sidebars

Once you setup your theme options, you will likely want to configure the menu areas on your site and possiblyconfigure the content of the default sidebars that are included as part of the Largo parent theme.

These are configured from the Appearance > Menus and Appearance > Widgets menus, respectively.

More:

• Menus Detailed Documentation

• Sidebars and Widgets Detailed Documentation

1.2. Getting Started 5

Largo Project Documentation, Release 0.5

1.2.6 Install Plugins

The Largo theme comes packaged with a number of plugins developed by NPR as part of their Project Argo plus someadditional recommended plugins that add various functionality to your Largo site. We have a complete list of theseplugins and what they are used for on our plugins page.

More: Plugins Detailed Documentation

6 Chapter 1. Installation And Setup

CHAPTER 2

General Documentation

2.1 The WordPress Settings Menu

Before you get started with the Largo-specific documentation, you may want to review the basic WordPress docu-mentation. Particularly if you are new to WordPress it will answer many of your questions about setting up your site,writing posts, uploading photos, and creating users. We try, wherever possible, to build things “the WordPress way”and not get in the way of the things WordPress core does really well. As a result, often, a quick search will help youout with basic questions or problems that are not specific to Largo.

That said, here are some of the items under the Settings menu in the WordPress dashboard that you will want to beaware of as you are setting up your site.

2.1.1 General

Clicking on Settings > General will take you to a page where you can setup many of the general options for your site.

This is where you set your site name, tagline, address, general admin user address, time format, and member permis-sions.

Your site description is set under Appearance > Theme Options > Basic Settings.

The site name, tagline and description are used in a number of places in Largo for SEO purposes (as the title tag onthe homepage, for meta descriptions, as a fallback for pages where a title or description is not specified, etc.) so you’llwant to make sure these are set.

The admin email address is also important because this is the email address that will be used for any notification emailsWordPress sends, such as when a new user registers or when a new comment is posted. It is also used as the defaultaddress for your site’s contact form.

This tab also allows you to set the timezone and language for your site. If you set the language to something otherthan English, both WordPress and Largo do incorporate multi-lingual support. You can find some details on how thatworks in the WordPress documentation.

2.1.2 Writing

The most important setting here is the Default Post Category. Typically you should consider setting the default categoryto something other than Uncategorized.

7

Largo Project Documentation, Release 0.5

2.1.3 Reading

Largo does not use most of the settings in this menu, instead setting things like the homepage layout in the Appearance> Theme Options menu.

The main setting to be aware of here controls whether or not search engines will be discouraged from crawl-ing your site and displaying it in search results. Enabling this checkbox inserts <meta name="robots"content="noindex,follow"> tag into your site’s header which will discourage search engines from index-ing your site. This is commonly used while sites are still under development to ensure that the site is not indexed and“visible” to search engines and users until you’re ready to make it live.

2.1.4 Discussion

The settings found in Settings > Discussion control commenting, comment moderation and notifications.

For an in-depth discussion of what these options do see the WP Codex entry on this screen.

Note that many sites use a third-party system or plugin such as Disqus or Facebook to replace the default WordPresscomment engine. If you use one of these third-party systems it may or may not respect the settings from this menuand you should consult that plugin’s documentation to be sure.

2.1.5 Media

Largo sets the media sizes required by the theme programmatically so you should not modify the settings in this menu.

2.1.6 Permalinks

The permalinks menu controls the format used for the URLs on your site.

To avoid confusing users and search engines you will typically want to set this once and then not change it. WordPressdoes try to rewrite URLs if the format is changed so that links will not be broken but it is not 100% reliable.

Note that for your content to be included in Google News the URLs for your articles must contain at least three digits.To meet this requirement many news sites will choose to use either the “month and name” or the “day and name”permalink option.

For more information about permalinks, see the WordPress Codex entry on permalinks.

2.1.7 Other

Additionally, many plugins will add sub-items to the Settings menu with settings that are specific to that plugin. Thosesettings will typically be covered in the documentation for that plugin.

2.2 Theme Options

When you first activate the Largo theme, there are a number options that need to be configured before you make thesite live. The majority of these can be found in the Appearance > Theme Options menu which you can access fromthe left sidebar of the WordPress administration interface.

The Theme Options page is organized into four sections which you can access by clicking on the relevant tab acrossthe top of the page: Basic Settings, Theme Images, Layout Options and Homepage Options.

8 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

2.2.1 Basic Settings

Site Description - This is a short description of your site that is used in a sidebar or footer widget. Ideally this shouldjust be a short paragraph (1-2 sentences in length) and you can include HTML in this box to link to the “About” pageof your site so that visitors can read more about your organization.

Feed URL - This is a link to the main RSS feed for your site. By default this will be http://yoursite.com/feed but ifyou use a feed management and/or analytics tool (such as Feedburner), you can replace the default link here and it willbe used in all relevant places on your Largo site.

Donate Button - The Largo theme includes an optional donate button in the top header. To enable the donate button,make sure the checkbox to show the donate button is checked and then add the link to your donation page, form orexternal payment processor here. Optionally, you can change the text of the button. The Largo theme also includes asidebar widget that you can use to link to a donation page in addition to or instead of the link in the top header.

Don’t Miss Menu - Under the main navbar on your Largo site is an optional secondary navigation menu that, bydefault, is called “Don’t Miss”. To enable this menu make sure the checkbox to show the Don’t Miss Menu ischecked. Optionally, you can customize the label that appears at the beginning of the menu or remove it entirely. Toadd or remove links from this menu visit Appearance > Menus from the left sidebar in the WordPress administrationinterface.

Footer Nav Menu - On the left side of the site footer is a configurable menu area. By default the label for this menuwill be your site name, but you can change it here. As with the Don’t Miss menu area, to add or remove links fromthis menu visit Appearance > Menus from the left sidebar in the WordPress administration interface.

Sticky Nav - The sticky navigation bar remains at the top of the reader’s window as they scroll. The default is to showthe sticky navbar, but you may want to hide it. You also have the option to show your site name in the sticky navbar,which is useful on smaller screens.

Copyright Message - By default this will display “Copyright [YEAR], Your Site Name” but you can enter your ownmessage here if you would like. You can include HTML in this area to link to external sites and use &copy; to displaya copyright symbol or %d to display the current year.

Google Analytics - The Largo theme has built in support for Google Analytics. Enter your Google Analytics ID hereand the relevant Google Analytics code will be automatically added to all of the pages on your site. Note that it isconfigured to not track logged in users to ensure accurate reporting.

Word to use for “Posts” - By default, WordPress calls single article pages “posts” but you might prefer to use anothername. You can specify the singular and plural forms separately.

Social Media Links - These are links to relevant social media profiles for your site or organization. These are used ina sidebar widget to provide links to like or follow your organization on Facebook and Twitter, in bylines to attributecontent to your organization and in special code in the header to make sure your content appears optimally whenshared by other users on these social networks.

Be careful to note the recommended format for each link type for maximum compatibility. These icons are by defaultused in the footer of your site’s pages, but you have the option to show them in the header.

Note that authors can add links to their own social media profiles by editing their user profile.

Single Post Social Icons - By default a box showing social media links will be shown at the top of single article pages.You can choose to hide this if you prefer. You can also choose which share icons should be displayed here, the verbused on Facebook buttons, whether or not your Twitter share count is displayed, and where the “Clean Read” linkshould be displayed on the page.

In previous versions of Largo, the option to have the author’s bio and social media links occupied this slot, and alsogoverned the visibility of share icons and the author bio at the end of the article. The article-bottom author bio andsocial links are now available as widgets.

2.2. Theme Options 9

Largo Project Documentation, Release 0.5

2.2.2 Theme Images

This section allows you to upload images that are used primarily in the top header of your Largo site. To add yourimages:

• Make sure you have created all six image sizes as outlined in our Pre-Launch Checklist and then click “Upload”by the image you want to add.

– 200x200px Square default thumbnail image

– 16x16px Favicon

– 768px-wide Small banner image

– 980px-wide Medium banner image

– 1170px-wide Large banner image

– 100px-tall site logo for use in the sticky header

• Drag and drop the image onto the uploader (or click “Select Files” and find the correct image on your computer).When the image has finished uploading, selected the full size image option, and then click the button at thebottom of the uploader that says “Use This Image”.

• If the image has uploaded correctly, you should see a thumbnail version of it and the link to the photo in thefield next to the “upload” button.

• Once you have uploaded all six images, be sure to click “Save Options” to save your changes.

There is one additional option in this section, a checkbox that allows you to use text in the place of the banner images.It is unlikely that you will use this option, but if you do, selecting this checkbox will use the Site Title and Descriptionfrom your Settings > General menu in the place of the the header images so make sure that you have set those optionsbefore you enable this feature.

2.2.3 Layout Options

Home Template - This choice determines what the top of your website’s main page looks like. The Largo themecurrently offers five homepage templates:

• Blog - This displays your most recent posts in reverse chronological order (newest at the top) with the ability tomake a post “sticky” so it stays at the top of the homepage.

• Big story, full-width image: Prominently features the top story by itself, with a full-width image, headline andexcerpt.

• One Big Story and list of featured stories: Prominently features the top story along with three other ‘Featuredon Homepage’ items, or by itself if none are specified. Best with Homepage Bottom set to ‘blank’

• One big story and list of stories from the same series: Prominently features the top story along with otherposts in its series along the right side. Requires the Series taxonomy to be enabled.

• Top Stories - If you select this layout you will want to ensure that you are adding featuring images and excerptsfor all of your posts and that you have at least six posts at all times set to “Homepage Featured” in the PostProminence taxonomy and at least one post (that MUST have a featured image set) marked as the “Top Story”,also in the Post Prominence taxonomy.

Sticky Posts - If enabled, the top sticky post will displayed in between the Homepage Template and the HomepageBottom, below the tag “Featured”. Posts can be marked sticky by opening the post editor, going to the “Publish”metabox, clicking “Edit” next to “Visibility”, then choosing “Public” and “Stick this post to the front page.”

Homepage bottom templates - Largo supports three options for the bottom of the homepage:

10 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

• A single-column list of recent posts with photos and excerpts

• A two-column widget area: This creates a new widget area in Appearance > Widgets that can be filled withwidgets. It appears empty until widgets have been added to this area.

• Nothing whatsoever

Category and Tag Display - Largo can display:

• a single category or tag above the headline for each story

• a list of tags below the story’s excerpt

• nothing at all

Number of posts - The number of posts displayed on the main area of the homepage, not counting posts in the toparea of the homepage or in the sticky box. The default is 10.

Categories to include or exclude - Enter a comma-separated list of category ID numbers here to excludethem from the front-page listing. in the main loop on the homepage (comma-separated list of values, seehttp://codex.wordpress.org/Class_Reference/WP_Query for correct format). The general approach is:

news,sports,12,13,press-releases,blog

Single Article Template - Starting with version 0.3, Largo introduced a new single-post template that more promi-nently highlights article content, which is the default. For backward compatibility, the pre-0.3 version is also available,which by default includes a sidebar. The new template optionally includes a sidebar of your choice.

Sidebar Options - These affect the presentation of the sidebar to the reader.

• Add a third sidebar used only on archive pages (category, tag, author and series pages), configurable in Appear-ance > Widgets

• An additional widget region just above the site footer region, configurable in Appearance > Widgets

• Fade the sidebar out on single story pages as the reader scrolls

You can also enter a list of additional sidebar regions that should be created, one on each line of the text box.

Footer Layout - The default footer is a 3 column footer with a wide center column. Alternatively you can choose tohave 3 or 4 equal columns. Each column is a widget area that can be configured under the Appearance > Widgetsmenu, where they will be labeled “Footer 1” through “Footer 3” or “Footer 4.”

2.2.4 Advanced Options

Custom LESS - Enabling this will let you change the theme’s colors and fonts in Appearance > CSS Variables.

Enable Series - Some sites may create a multi-part series or project that is only published for a set amount of timeand then should fall into the archive or appear on a “projects” archive page. To support this and also to allow for thecreation of custom landing pages, Largo adds an optional “series” taxonomy. When you create a new series, you canadd a term to this taxonomy and then make sure all of the posts in that series have this label applied. This will enablethe Largo theme to surface related posts in that series in at the bottom of a post (if you are using the “read next” widget)and, in some cases, also on the homepage (depending on the homepage layout you have selected). Largo also addsthe ability to create custom sidebars and landing pages for series archive pages, replacing the default series archivetemplate in WordPress. For more information, see Series.

Enable Custom Landing Pages - Requires Series to be enabled. Series landing pages allow you to summarize aseries of posts or tie a project together. For one example, see http://inewsnetwork.org/series/hit-and-run: the projectpage begins with a summary of the series, followed by posts within the series. For more information on creating aseries landing page, see Series Landing Pages.

Enable Optional Leaderboard Ad Zone - This creates a widget area above your site’s header that can be used todisplay ads. For more about this area, see Advertising.

2.2. Theme Options 11

Largo Project Documentation, Release 0.5

Enable Post Types - This taxonomy allows you to organize posts by content type, such as “Article,” Photo Gallery,”“Data,” etc. When you create a new post type you can assign it an icon, which will be used in certain places in thetheme. Each post type also has its own archive so that you can add links to your navigation to a page containing all ofyour “data” projects, for example. In the future, we plan to add custom templates specific to each content type to makethem easier to manage and more optimal when displayed to users on your public-facing site.‘ Sidebars for LandingPages - These set the default sidebars for custom landing pages, and can be overridden by the individual landing page.For more information, see Series Landing Pages.

Disclaimer - If checked, you can enter a default disclaimer that will be displayed on all posts.

Search Options - Google Custom Search generally returns better search results than WordPress’ included searchengine. If you would like to enable Google Custom Search, go to https://www.google.com/cse/create/new to set it up,then paste your search engine ID in the settings box and enable the checkbox.

Site Verification:

• Twitter Account ID: This is a 9-digit ID number used for verifying your site to Twitter Analytics

• Google site verification meta tag: This will be a long string of numbers and letters. For more information, seeGoogle’s documentation.

• Facebook admins meta tag: This is a comma-separated list of numerical FB user IDs you want to allow to accessFacebook insights for your site.

• Facebook app ID meta tag: This is a numerical app ID that will allow Facebook to capture insights for anysocial plugins active on your site and display them in your Facebook app/page insights. For more information,see Facebook’s documentation

• Bitly site verification: This is a string of numbers and letters used to verify your site with bitly analytics. Formore information, contact bitly.

SEO Options - You may choose to ask search engines to not index archive pages in addition to date archives.

INN Options - If INN_MEMBER is defined as true in your site’s wp-config.php or in your child theme, then you willhave the option to add the year that your organization joined INN. This will be displayed in the footer next to the INNlogo.

2.2.5 Deprecated Options

The following homepage layout templates are no longer included in Largo:

• Slider: An animated carousel of featured stories with large images. This should be automatically updated to the“Blog” template after upgrading Largo.

2.3 Menus

2.3.1 Available Menu Areas

The Largo theme has five customizable menu areas:

Global Navigation - The links in the dark gray bar at the very top of the page. When viewed on a small screen suchas a mobile device, this menu collapses and appears in a dropdown menu instead. The name of the menu area can bechanged under Appearance > Menus to set the top level target for the dropdown menu on small screens. Note that youdo not have to use this area at all if you do not wish to, but it can be a good place to put supplemental links such aslinks to your about or contact page or links to login or register (if relevant for your site)

Main Navigation - The main site navigation that appears in the menu bar/sticky nav in the header.

12 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

Don’t Miss - An optional menu area that you must enable and configure under Appearance > Theme Options beforeit will appear on your site (it is hidden by default). This is a good place to link to category, tag or series pages that youwant to highlight for your readers but not necessarily include in the main navbar.

Footer Navigation - This menu area appears in the left column of the site footer and could mirror some of thenavigation items in the header area or provide supplemental links to items such as your jobs page, ethics policy, orother items that might commonly appear in a website footer.

Footer Bottom - A menu area that appears at the very bottom of the footer and should be used to link to things likeyour site’s terms of service, privacy policy or other legal information that should appear with the copyright notice inthe site footer.

2.3.2 Deprecated Menu Areas

Navbar Categories List (removed in version 0.4) - This menu populates the main navigation bar with your site’sprimary content categories. When viewed on a small screen, this area will be collapsed into a dropdown menu. Notethat this is the only menu area that supports a multi-level menu (child categories will be displayed as dropdown menusup to two levels deep, but only the parent categories will be displayed on mobile devices).

Navbar Supplemental Links (removed in version 0.4) - This is another optional menu area that allows you to addadditional link to the main navbar. This menu will always appear to the right of the Navbar Categories List items andcollapses into a dropdown menu when viewed on small screen sizes.

NOTE: If you were previously using these menu areas the update script for version 0.4 will consolidate them into theMain Navigation menu area described above.

2.3.3 Setting Up And Using Menus

For a tutorial on how to add links to any of these menu areas, please see the WordPress Menu User Guide.

2.4 Sidebars and Widgets

2.4.1 Overview

Largo adds a number of widget areas and custom widgets to allow for easy, drag and drop management of contentblocks on your site.

Access and edit any of the following widget areas from the Appearance > Widgets menu in the WordPress Dashboard.

To add widgets to any of these areas, simply drag and drop a widget from the area on left to the widget area you wantit to appear in. Note that as soon as you add any widgets to a widget area, the default will no longer display so you willneed to completely populate the widget area with the widgets you want to display. Many widgets will have additionalsettings you can use to configure how they appear on your site.

For more about widgets and how WordPress handles them, see the WordPress Codex article on widgets.

2.4.2 Widget Areas

Sidebar Widget Areas

Note that the way some of these widget area appear on your site will depend on the layout options you set in theAppearance > Theme Options > Layout Options menu.

2.4. Sidebars and Widgets 13

Largo Project Documentation, Release 0.5

• Main Sidebar - By default this is the sidebar used for all non-single pages (homepage, category pages, datearchive pages, etc.)

• Single Sidebar - Used on single posts and pages. Note that if you do not populate this widget area, Largo willfallback to using the Main Sidebar instead. Additionally, as of Largo version 0.4, the recommended defaultlayout for single posts and pages is a single column layout that does not include a sidebar unless you explicitlyset one from the Layout Options > Custom Sidebar dropdown menu when editing an individual post. If youselect a sidebar from this dropdown menu, it typically appear as a skinny column floated to the left of yourcontent.

• Topic Sidebar - An optional widget area enabled from the Appearance > Theme Options > Layout Optionsmenu. When enabled, this widget area will be used in the place of the main sidebar on all category, tag andcustom taxonomy (e.g. - series) pages.

Footer Widget Areas

Depending on which layout you select in the Appearance > Theme Options > Layout Options menu for the FooterLayout option, you will see either three or four numbered footer widget areas (which are numbered left to right). Theseareas will typically be populated by some default widgets that you can modify or change by adding widgets of yourchoice in the Appearance > Widgets menu.

The Article Bottom Widget Area

Prior to version 0.4, Largo controlled the appearance of elements at the bottom of article pages using various settingsfrom the Appearance > Theme Options > Basic Settings menu. In version 0.4 we have made this a widget area insteadto allow for more flexibility in the type and order of elements that appear here.

By default, the only thing displayed at the bottom of an article is the comments section (when comments are enabled).Some of the elements you might consider adding to this area are the author bio, related posts and prev/next linkswidgets but many of the widgets in WordPress or those added by Largo are designed to be contextual and display wellin this area so you can experiment and see what best suits your needs.

Less Common Widget Areas

• Homepage Alert - For sites that cover breaking news, this is an optional widget area where you can add a textwidget to add a “breaking” banner to the top of the homepage. The styling for this widget area is very basicso if you plan to use it you’ll likely want to create either some custom CSS for a text widget and/or create andregister your own “breaking news” widget to be used in this widget area.

• Header Ad Zone - If you have enabled the optional header leaderboard ad zone from the Appearance > ThemeOptions > Advanced tab then this would be the widget are you’ll use to add an ad widget to appear in thatposition.

• Homepage Left Rail - If you are using a three column homepage layout this will be a widget area to managethe contents of the skinny column to the far left.

Custom Widget Areas

Largo also enables you to add any number of custom widget areas you might need for display on certain pages ofyour site. For example, you might want to create a sidebar for a category or series that is only displayed on the archivepage for that category/series and/or on the posts that appear in that category/series. Custom sidebars can be addedfrom the Appearance > Theme Options > Layout Options tab under the “Sidebar Options” header. Instructions forsettings these options can be found below.

2.4.3 Custom Widgets

Largo adds a number of custom widgets in addition to the standard widgets that come included with WordPress.

All of our widgets have:

14 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

• The choice of three backgrounds (default, reverse and none) to give you a variety of styling options and classesto use for custom CSS.

• The ability to be hidden on desktops, tablets and phones using the responsive utility classes from Twitter Boot-strap. We recommend hiding less necessary widgets for users on smaller viewports such as mobile devices inorder to create a cleaner, simpler experience that allows them to focus on your content without distraction.

• The ability to set a link for the widget title.

The widgets added by Largo include:

• INN Member Stories - Shows a list of curated stories from other member of INN.

• Largo Author Bio - Shows a bio of the author(s) for a given post including their photo and social media links(when filled out in their user profile).

• Largo Explore Related - A tabbed widget to show related stories by category/tag. We recommend using theLargo Related posts widget instead but this widget is retained in Largo version 0.4 for backwards compatibility.

• Largo Featured Posts - Show recent featured posts with thumbnails and excerpts.

• Largo Recent Comments - Show recent comments with links to the posts they appear on.

• Largo Related Posts - Show related posts that are either editorially determined (by adding related post IDs inthe Additional Options box of the post edit screen) or using a default related algorithm that tries to surface themost closely-related post(s) to a given post by series, category or tag.

• Largo Staff Roster - Display a list of the users on your site with options to limit by user role or excludeparticular users by setting an option in their user profile.

• Largo Taxonomy List - List all of the terms in a given taxonomy with links to their archive pages. This ismostly commonly used to generate a list of series/projects with links to the project pages.

• Largo About Site - Displays the site description provided in the Appearance > Theme Options > Basic Settingsmenu.

• Largo Donate Widget - Shows a donate message and button. The default message and link used in this widgetcan be configured in the Appearance > Theme Options > Basic Settings menu but can be overridden on a per-widget basis if you want to show different messages on different pages/sections of your site.

• Largo Facebook Widget - Shows a Facebook “like” box/feed.

• Largo Follow - Uses the social media links provided for your site in the Appearance > Theme Options > BasicSettings menu to show buttons to follow you on select social networks

• Largo Prev/Next Links - Most commonly used in the Article Bottom widget area, this will show links to thenext/prev post ordered by published date.

• Largo Recent Posts - A powerful widget to show recent posts in various formats with the option to limit bycategory, tag, custom taxonomy term and/or author.

• Largo Tag List - Typically used in the Article Bottom widget area, this will display a list of tags associated witha given post.

• Largo Twitter Widget - Allow for the display of a Twitter profile, list or search widget. Note that to use thiswidget you’ll need to create a widget (and grab the widget ID) from https://twitter.com/settings/widgets.

• Largo Disclaimer Site - When the “Enable Disclaimer Widget” option is enabled from the Appearance > ThemeOptions menu, this widget will show the article disclaimer you have provided. Optionally, you can override thedisclaimer on a per-article basis by modifying it from the post edit screen.

Deprecated in 0.4:

• Largo Footer Featured Posts - Works similarly to the Featured Widget above but limited to the “footer fea-tured” term in the prominence taxonomy.

2.4. Sidebars and Widgets 15

Largo Project Documentation, Release 0.5

• Largo Sidebar Featured Posts - Works similarly to the Featured Widget above but limited to the “footerfeatured” term in the prominence taxonomy.

2.4.4 Sidebar Options

Under the Appearance > Theme Options > Layout Options menu you will find a section labelled “Sidebar Options”.This area has a few options to configure the widget areas on your site:

• A checkbox to activate the “Topic Sidebar” as described above

• An option to include an optional widget area directly above the footer (used by a few sites to add sponsor logosor additional ad units).

• An option to fade the sidebar on single post pages with a user scrolls

And most importantly, a way to register custom widget areas. This is useful if you want to easily create additionalwidget areas for particular categories or projects on your site.

To add a new widget area, simply add the name of the widget area to the textbox with each widget area you’d like toregister on a new line and then click “Save Options”.

Once you have added custom widget areas you can add widgets to them from the Appearance > Widgets menu andthen you will be able to select them from the Layout Options > Custom Sidebar dropdown from the post edit page orfrom the Archive Sidebar dropdown when adding or managing a category, tag or series from the Posts menu.

2.5 Series Landing Pages

Custom landing pages allow you to summarize a series of posts or tie a project together. For one example, seehttp://inewsnetwork.org/series/hit-and-run: the project page begins with a summary of the series, followed by postswithin the series. Creating a custom landing page is a simple process.

1. Make sure “Custom Landing Pages for Series/Project Pages” is enabled in Appearance > Theme Options >Advanced.

2. Create a series

3. Add the series to posts

4. Create the landing page

2.5.1 Creating a series

Create a series in Posts > Series. Each series should have a name and a slug. If the new series is part of an already-existing series, you can add the parent series from the drop-down. The description is displayed in the standard landingpage layout. The sidebar can be chosen from a list of sidebars. If you want, you can create additional sidebars inAppearance > Theme Options > Layout Options > Sidebar Options.

Applying a series to a post can be done by selecting the appropriate series from the series list in the post editor. Thisoption can also be used to create a new series.

2.5.2 Creating the landing page

Landing pages are created through the Landing Pages > Add New entry in the Dashboard sidebar.

These settings must be set for the series landing page to function:

16 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

• Page Template: Must be set to “Series Landing Page default”

• Slug: A short, descriptive label for the page composed of the letters a-z and numbers 0-9. This must match theslug of the series that the landing page is for.

• Series: In the right-hand sidebar of the page editor, you must choose the series that the landing page is for.

Landing pages have the following options:

• Title: The name of the series.

• Display header: If header display is disabled, then the description will not appear.

• Show series byline: If the series is by more than one author, you may want to disable the series byline. Theseries byline is set at the bottom of the landing page settings page.

• Show social media sharing links: If disabled, social media icons will not appear.

• Layout style

– Standard: Uses title, description, and featured image. The featured image is set with the page’s“Featured Image” settings box.

– Alternate: Uses title, description, and custom HTML. Checking this option reveals a TinyMCE editorthat allows you to write additional content using the standard editor or paste in HTML through thetext editor.

• Layout

– One widget column on the right

– One widget column on the right and one narrower widget column on the left

– No widget columns.

These default to the options set in Theme Options > Advanced Options > Sidebars for Landing Pages, butthose values can be overridden.

• Number of posts per page: 10 is the default. Page load times may be negatively affected when choosing “All”.

• Post order and

• Post display options: Affects how the posts are displayed.

– Show featured image shows the post’s featured image

– Show excerpt shows the post excerpt

– Show byline shows the post byline

– Show categories and tags shows each post’s categories and tags

• Author: The author of the series. This defaults to the person who created the series, and can be hidden byunchecking the “Show Series Byline” option above. This can be a CoAuthors Plus guest author.

• Footer layout style

– None: The series page does not have a custom footer.

– Use widget: Creates a new “Series Name: Bottom” widget area, editable in Appearance > Widgets

– Custom HTML: Checking this option reveals a TinyMCE editor that allows you to write additionalcontent using the standard editor or paste in HTML through the text editor.

2.5. Series Landing Pages 17

Largo Project Documentation, Release 0.5

2.5.3 Common ways of customizing your landing page

Inserting a photo gallery:

1. Choose the “alternate” layout style.

2. Check “Custom HTML”.

3. In the editor that appears, choose to insert media, then choose your photos and insert them.

Inserting embeds, custom content, series descriptions, a featured video, etc:

1. Choose the “alternate” layout style.

2. Check “Custom HTML”.

3. In the editor that appears, insert your media into the text box.

Customizing the landing page’s sidebar:

1. In Appearance > Theme Options > Layout Options > Sidebar Options, enter the name of your series intothe text box on its own line, and then save the options.

2. In Appearance > Widgets, find the new sidebar you created, and add widgets to it. Save.

3. Return to your series landing page. Choose the custom sidebar from the dropdown.

4. Make sure your series landing page has the same slug as your series, and that that series is chosen in the “Series”post.

2.6 Taxonomies

2.6.1 Overview

Taxonomies are a way to label and organize the posts on your site.

Our general philosophy regarding taxonomies is that they should always be used to group like sorts of things togetherand never to mix different sorts of things within the same taxonomy. For this reason we create a number of customtaxonomies to supplement the default WordPress categories and tags taxonomies so that you won’t have to mix topicalorganization (e.g. - “Education,” “Politics,” etc.) with visual display (e.g. - “Homepage Block #3, “Featured,” etc.)

WordPress has two default taxonomies:

• Categories - The top level categories used to organize content on your site. We recommend using no more than8 to 10 categories. When selecting and naming your categories, think about the top level buckets you might useto group your content and particularly how visitors might browse your site. Since these are often used as themain navigation on the site, topic-based categories tend to be more useful than content types. Typically a labellike “Politics” is more meaningful to visitors than “Investigations” which, even though we may have clear ideaof what falls under that label, it’s unfamiliar and unclear jargon to the less-experienced reader.

• Tags - Keywords or topics used to group related posts together on a more micro level. These are typically people,places, things or subtopics that are used to surface related posts and to help search engines better understandwhat a post is about. For example, you might have a category called “Politics” and posts in that category mighthave tags like “Campaign Finance”, “Election 2012”, etc.

In addition to these two taxonomies, Largo adds three more custom taxonomies:

• Post Prominence - This is used to determine how and where posts are displayed on the site (for example, topstories on the homepage or featured content widgets in a sidebar or footer). You might also add additional termsto this taxonomy to create custom feeds for distribution to content partners (we will cover how to do that in a

18 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

later post) or for any other display-related purpose. Using this taxonomy is preferred to creating categories forthis purpose.

• Series (Optional) - Some sites may create a multi-part series or project that is only published for a set amountof time and then should fall into the archive or appear on a “projects” archive page. To support this and also toallow for the creation of custom landing pages, Largo adds an optional “series” taxonomy. When you create anew series, you can add a term to this taxonomy and then make sure all of the posts in that series have this labelapplied. This will enable the Largo theme to surface related posts in that series in at the bottom of a post (if youare using the “read next” widget) and, in some cases, also on the homepage (depending on the homepage layoutyou have selected). Largo also adds the ability to create custom sidebars and landing pages for series archivepages, replacing the default series archive template in WordPress.

• Post Types (Optional - new in version 0.4) - This taxonomy allows you to organize posts by content type, suchas “Article,” Photo Gallery,” “Data,” etc. When you create a new post type you can assign it an icon, which willbe used in certain places in the theme. Each post type also has its own archive so that you can add links to yournavigation to a page containing all of your “data” projects, for example. In the future, we plan to add customtemplates specific to each content type to make them easier to manage and more optimal when displayed tousers on your public-facing site.

Note: The “Series” and “Post Types” taxonomies are disabled by default, but you can enable them from the Appear-ance > Theme Options > Advanced menu.

You can add posts to any of these taxonomies from the post edit screen or using the WordPress quick edit functionalityfrom any list of posts. You simply check the term in the taxonomy you want to add to a post or you can click on “AddNew Category” to add a new term to a taxonomy (for example, if the post you are publishing is the first post in a newseries you can add that series directly from the page where you are working on that post).

Additionally you can add a description for each category, tag or series and also specify a custom sidebar to display on

Hint: For consistency, we recommend capitalizing every word in tags, categories and custom taxonomies (so: “MyFavorite Series” not “My favorite series” and “Campaign Finance” not “campaign finance”) and you should alsoalways use full names of public figures, places, etc. without titles (because titles can change over time, e.g. - “GroverCleveland” not “President Grover Cleveland”).

Note that in some cases you may need to click on the “Screen Options” tab at the very top right corner of the post editscreen to ensure that all of the taxonomies are visible.

2.6.2 Categories

The top level categories used to organize content on your site. We recommend using no more than 8 to 10 categories.When selecting and naming your categories, think about the top level buckets you might use to group your contentand particularly how visitors might browse your site. Since these are often used as the main navigation on the site,topic-based categories tend to be more useful than content types. Typically a label like “Politics” is more meaningful tovisitors than “Investigations” which, even though we may have clear idea of what falls under that label, it’s unfamiliarand unclear jargon to the less-experienced reader.

Add a new category by clicking on Posts > Categories and then provide the following information:

Options:

• Name: The name is how the category appears to visitors on your site or in your site navigation.

• Slug: The URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, andhyphens.

• Parent: A drop-down menu of other categories, this allows you to set a parent/child relationship for yourcategories. This does not make much of a difference for your visitors but it can be helpful to organize yourcategories if you have a lot of them.

2.6. Taxonomies 19

Largo Project Documentation, Release 0.5

• Description: In Largo the description is displayed at the top of the archive page for the category. It is also usedas the meta description and in the open graph tag for that page (this controls how the page appears in searchresults or when it is shared on various social networks).

• Archive Sidebar: The sidebar to show on this category’s archive page, chosen from a list of your currentlyregistered sidebars. Additional sidebars can be created in Appearance > Theme Options > Layout Options >Sidebar Options by entering names of new sidebars in the box. These sidebars will then become available underthe Appearance > Widgets menu where you can add and arrange the content you want to appear.

Optionally, categories can be created while editing a post by clicking on “add new category” under the list of currentcategories in the category box in the right column.

2.6.3 Tags

Keywords or topics used to group related posts together on a more micro level. These are typically people, places,things or subtopics that are used to surface related posts and to help search engines better understand what a postis about. For example, you might have a category called “Politics” and posts in that category might have tags like“Campaign Finance”, “Election 2012”, etc.

Add a new tag by clicking on Posts > Tags and then provide the following information

Options:

• Name: The name is how the tag appears to visitors on your site or in your site navigation.

• Slug: The URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, andhyphens.

• Description: In Largo the description is displayed at the top of the archive page for the category. It is also usedas the meta description and in the open graph tag for that page (this controls how the page appears in searchresults or when it is shared on various social networks).

• Archive Sidebar: The sidebar to show on this tag’s archive page, chosen from a list of your currently registeredsidebars. Additional sidebars can be created in Appearance > Theme Options > Layout Options > SidebarOptions by entering names of new sidebars in the box. These sidebars will then become available under theAppearance > Widgets menu where you can add and arrange the content you want to appear.

Optionally, tags can be created while editing a post by entering a comma-separated list of tags in the “tags” box in theright column.

2.6.4 Post Prominence

This is used to determine how and where posts are displayed on the site (for example, top stories on the homepage orfeatured content widgets in a sidebar or footer). You might also add additional terms to this taxonomy to create customfeeds for distribution to content partners (we will cover how to do that in a later post) or for any other display-relatedpurpose. Using this taxonomy is preferred to creating categories for this purpose.

Default Terms (added by Largo when the theme is activated):

• Top Story: If you are using the Newspaper or Carousel optional homepage layout, add this label to a post tomake it the top story on the homepage

• Featured in Category: This will allow you to designate a story to appear more prominently on category archivepages.

• Featured in Series: Select this option to allow this post to float to the top of any/all series landing pages sortingby Featured first.

20 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

• Footer Featured Widget: If you are using the Footer Featured Posts widget, add this label to posts to determinewhich to display in the widget.

• Homepage Featured: If you are using the Newspaper or Carousel optional homepage layout, add this label toposts to display them in the featured area on the homepage.

• Sidebar Featured Widget: If you are using the Sidebar Featured Posts widget, add this label to posts todetermine which to display in the widget.

It is rare that you will add additional terms to this taxonomy as they are typically added by your theme but should youneed to they can be added from the Posts > Post Prominence menu.

2.6.5 Series

This taxonomy is disabled by default, but you can enable it from the Appearance > Theme Options > AdvancedOptions menu.

Some sites may create a multi-part series or project that is only published for a set amount of time and then should fallinto the archive or appear on a “projects” archive page. To support this and also to allow for the creation of customlanding pages, Largo adds an optional “series” taxonomy. When you create a new series, you can add a term to thistaxonomy and then make sure all of the posts in that series have this label applied. This will enable the Largo themeto surface related posts in that series in at the bottom of a post (if you are using the “read next” widget) and, in somecases, also on the homepage (depending on the homepage layout you have selected). Largo also adds the ability tocreate custom sidebars and landing pages for series archive pages, replacing the default series archive template inWordPress.

Options:

• Name: The name of the series/project as you would like it to appear to visitors on your site or in your sitenavigation.

• Slug: The URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, andhyphens.

• Parent: A drop-down menu of other series, this allows you to set a parent/child relationship for your series.This does not make much of a difference for your visitors but it can be helpful to organize your series if youhave a lot of them.

• Description: In Largo the description is displayed at the top of the archive page for the series. It is also used asthe meta description and in the open graph tag for that page (this controls how the page appears in search resultsor when it is shared on various social networks).

• Archive Sidebar: The sidebar to show on this tag’s archive page, chosen from a list of your currently registeredsidebars. Additional sidebars can be created in Appearance > Theme Options > Layout Options > SidebarOptions by entering names of new sidebars in the box. These sidebars will then become available under theAppearance > Widgets menu where you can add and arrange the content you want to appear.

2.6.6 Post Types

An optional taxonomy added in version 0.4. This taxonomy is disabled by default, but you can enable it from theAppearance > Theme Options > Advanced menu.

This taxonomy allows you to organize posts by content type, such as “Article,” Photo Gallery,” “Data,” etc. When youcreate a new post type you can assign it an icon, which will be used in certain places in the theme. Each post type alsohas its own archive so that you can add links to your navigation to a page containing all of your “data” projects, forexample. In the future, we plan to add custom templates specific to each content type to make them easier to manageand more optimal when displayed to users on your public-facing site.

2.6. Taxonomies 21

Largo Project Documentation, Release 0.5

Options:

• Name: The name of the post type as you would like it to appear to visitors on your site or in your site navigation.

• Slug: The URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, andhyphens.

• Parent: A drop-down menu of other post types, this allows you to set a parent/child relationship for your posttype. This does not make much of a difference for your visitors but it can be helpful to organize your post typesif you have a lot of them.

• Description: In Largo the description is displayed at the top of the archive page for the post type. It is also usedas the meta description and in the open graph tag for that page (this controls how the page appears in searchresults or when it is shared on various social networks).

• Term icon: The icon the theme may display for posts of a given post type to help users to distinguish betweenthem quickly. By default, the icons available are: Search, Mail, Heart, Heart Empty, Star, Star Empty, Video-cam, Picture, Camera, Ok, Cancel, Plus, Minus, Help, Home, Link, Tag, Tags, Download, Print, Comment,Chat, Location, Doc Text, Doc Text Inv, Phone, Menu, Calendar, Headphones, Play, Table, Chart Bar, Spinner,Map, Share, Gplus, Pinterest, Cc, Flickr, Linkedin, Rss, Twitter, Youtube, Facebook, Github, Itunes, Tumblr,Instagram

2.7 Post Templates

2.7.1 Default Templates

Largo allows you to select between two default templates to use for posts and pages on your site. This default is setfrom the Appearance > Theme Options > Layout Options tab under the “Single Article Template” heading.

• One Column (Standard Layout) is a new default article template in Largo version 0.4 that focuses on read-ability, reduces distractions and allows for beautiful presentation of visual elements within a story with a large“hero” section at the top of the article for featured media (photo, video, slideshow or embedded media).

• Two Columns (Classic Layout) is the previous article template from Largo version 0.3 and before whichfeatures a content area on the left and a sidebar on the right.

2.7.2 Custom Templates

You can also select from either of the default templates or any custom page templates you may have registered onper-post/page basis. To change the template a given post or page is using, simply select the template you’d like to usefrom the Layout Options > Custom Sidebar dropdown on the post/page edit screen and then click “update”.

In this dropdown you will notice that Largo comes packaged with a “full width” template that is useful for creatingimmersive stories where you might want to include your regular header and footer but then have a blank template tocreate a lot of custom markup and formatting and/or to embed a large map or photos. This layout is too wide by defaultto use for a regular article and has very poor readability so we do not recommend using it for that purpose.

The full width template also provides an example of how to register your own custom post/page templates by addingeither “Template Name” (for pages, as is the default in WordPress) and/or “Single Post Template” (this extends thedefault WP functionality for pages to single posts as well) lines to the header block of a post/page template.

/*Template Name: Full Width PageSingle Post Template: Full-width (no sidebar)Description: Shows the post but does not load any sidebars, allowing content to span full container width.

*/

22 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

For more on custom post/page templates, see the related `WordPress codex entry <http://codex.wordpress.org/Page_Templates>`_.

2.8 Plugins

2.8.1 Overview

WordPress plugins are modules that extend the functionality of WordPress. Anyone can write them and WordPressmaintains a directory of available plugins. Since anyone can write them, this means that plugins vary widely in qualityso we’ve curated a list of plugins that add functionality commonly needed by news organizations and that we havetested to ensure they work well together and do not cause compatibility issues that sometimes crop up when usingless-trusted plugins.

2.8.2 Plugins From Project Argo

The Largo theme comes packaged with a number of plugins original created by NPR for Project Argo. In some caseswe have made modifications to these plugins to ensure compatibility with the Largo theme so we recommend usingthe included versions (which are also available from our team’s github account). When you activate the Largo themeyou should receive a message at the top of the WordPress admin dashboard that prompts you to install recommendedplugins.

Documentation for all of the Argo plugins, most of which remains applicable for our modified versions of the plugins,can be found here.

• As of version 0.4 the Argo Media Credit and Slideshow plugins have been folded directly into the Largo themeso they do not need to be installed separately. Documentation for the media credit plugin and slideshow plugincan be found on the Project Argo site here and here, respectively.

• Additionally, version 0.4 now includes the Clean Contact plugin to allow you to easily add simple contactforms to pages on your site. You can find documentation for this plugin in the WordPress plugin directory.

• We have also modified the Navis DocumentCloud plugin to make it work a bit better within a responsive layout.We recommend using the version of the plugin that comes packaged with the Largo theme, but the instructionsfor how to add a DocumentCloud document to a post from the Project Argo site are still valid.

• The Argo Links plugin is useful for collecting links from around the web and for creating link roundup posts.We have made some modifications to this plugin, most notably to add a sidebar widget to display your recentlysaved links, but for the most part it will work exactly as documented on the Project Argo site.

The are two other plugins developed by NPR as part of Project Argo that we have not updated and we are not, atthis point, 100% certain that they will work with the latest versions of WordPress and Largo so we do not necessarilyrecommend using them. That said, here’s what they do in case you’d like to give them a try:

• Argo Audio Player enables you to add embedded audio to your posts. Depending on your specific needsyou might prefer using a plugin called PowerPress to support podcasting, or you might want to instead hostyour audio on SoundCloud and use their embedded player. If you want to give the Argo Audio Player a try,documentation can be found here.

• Argo Jiffy Posts enables support for embed.ly’s oEmbed API. This allows you to easily embed content inWordPress posts using nothing more than a URL. Note that embed.ly is not a free service (pricing informationhere) but might be worth considering if your organization plans to embed a lot of third party content and richmedia on your site.

2.8. Plugins 23

Largo Project Documentation, Release 0.5

2.8.3 Other Recommended Plugins

In addition to the Argo plugins, we have included a curated list of other plugins that will enable various functionalitythat many news organizations might find useful. Note that while we have tested these plugins with the latest versionof Largo and WordPress, they are developed and maintained by their respective third-party developers.

• Akismet is a widely used WordPress plugin to protect your site from comment and trackback spam. Activationof this plugin requires an Akismet API key which you can obtain for free from Askimet .

• Better WordPress Google XML Sitemaps will create a sitemap index of your site that you can then submit toGoogle (and Google News) and other search engines to maximize the visibility of your content. Documentationfor this plugin can be found on the plug in website

• Disqus Comment System replaces the default WordPress comment system with a more robust alternative thatincludes more community features and enhanced moderation capability. This plugin requires a Disqus accountto activate but the setup process will walk you through creating one and adding your site. Documentation canbe found on the Disqus website.

• Edit Flow adds advanced workflow features to WordPress including the ability to manage additional user roles,editorial comments and an editorial calendar. Documentation can be found on the Edit Flow website.

• W3 Total Cache is a caching plugin for WordPress that will improve the load time of your site and help yourserver to better deal with large traffic spikes. Caching is heavily dependent on your server setup, and while W3Total Cache is one of the most powerful (and flexible) WordPress caching solutions out there, if it does not workfor you WP Super Cache is another popular alternative. Note that this is not relevant for sites that we host forINN members as our hosting company, WP Engine, has their own caching system.

• DoubleClick for WordPress is used to insert standard ad units into Largo. Read its documentation for moredetails.

2.8.4 Complete List of Plugins Available

For hosted INN member sites using Largo, this is a complete list of the plugins that are currently installed and availablein our production environment.

Note that since we use WordPress multisite, individual site admins are not able to install and activate plugins; Thisneeds to be done at the network level.

If you would like to have a plugin added to this list or installed and activated for your site we prefer that you contactus through the Largo help desk and describe the functionality you are trying to add rather than asking if we’ll installPlugin X for you. In some cases what you are after might already be possible in Largo and/or we might know of abetter plugin to accomplish the desired result.

We strive to maintain a secure environment for all of our hosted Largo sites and to avoid potential compatibility issues,so in some cases we may refuse to install a particular plugin if we believe it might cause problems for you or for us.We will, however, always try to work with you and recommend an alternative.

Here is a complete list of the plugins currently installed and available.

Recommended/curated plugins:

• Akismet - Spam prevention

• Better WordPress Google XML Sitemaps - Create and manage sitemaps for submission to Google and GoogleNews

• Breadcrumb NavXT - Used by some sites to add breadcrumb navigation

• Caspio Deploy2 - Enables ShortCode placeholders for use with the Caspio cloud computing database applicationservice.

24 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

• Chartbeat - Adds Chartbeat pinging to Wordpress.

• Co-Authors Plus - Allows multiple authors to be assigned to a post.

• Constant Contact Plugin - Adds integration for the Constant Contact email marketing service

• Disqus Comment System - The Disqus comment system replaces your WordPress comment system with yourcomments hosted and powered by Disqus.

• DoubleClick for WordPress - DoubleClick ad integration, maintained by INN.

• Edit Flow - Adds better editorial workflow options to the WordPress admin

• Facebook Comments - Replaces the default WordPress comment system with Facebook comments

• Liveblog - A simple way to add live blogs to your site.

• Navis DocumentCloud - Embed DocumentCloud documents that won’t be eaten by the visual editor

• News Quizzes - A WordPress wrapper for Mother Jones’ news quiz tool

• Redirection - Manage all your 301 redirects and monitor 404 errors

• Simple Tags - Extended Tagging for WordPress 4.0.x : Suggested Tags, Mass edit tags, Auto-tags, Autocomple-tion, Related Posts etc.

• Slack - Adds Slack notifications when you publish posts, receive new comments, etc.

• TablePress - TablePress enables you to create and manage tables in your posts and pages, without having to writeHTML code. Also installed are the DataTables Counter Column, DataTables Sorting plugins and PaginationLength Change “All” entry extensions.

• Tweetable Text - Make your posts more shareable. Add a Tweet and Buffer button to key sentences right insideeach blog post with a simple [tweetable] tag.

• TinyMCE Advanced - Enables advanced features and plugins in TinyMCE, the visual editor in WordPress.

• WP DS NPR API - A collection of tools for reusing content from NPR.org supplied by NPR Digital Services.

Premium plugins we’ve bought a site license for INN member sites:

• Business Directory Plugin - Provides the ability to maintain a free or paid business directory on your WordPresspowered site. We also have a license for the Paypal Gateway Module.

• Gravity Forms - Easily create web forms and manage form entries within the WordPress admin. We also have alicense for the Gravity Forms PayPal Add-On.

• The Events Calendar Pro - The Events Calendar PRO, a premium add-on to the open source The Events Calendarplugin (required), enables recurring events, custom attributes, venue pages, new widgets and a host of otherpremium features.

• WPJobBoard - Adds a job board to your site.

Plugins from Project Argo:

• Argo Audio Player - No longer updated/maintained, we recommend using an alternative service such as Sound-Cloud for embedding audio in posts

• Argo Links - Curate links and display them in a sidebar widget or create link roundup posts

• Navis Jiffy Posts - Makes it easy to quickly create a post from a URL

• Navis Slideshows - Slideshows that take advantage of the Slides jQuery plugin

Utilities:

• Categories to Tags Converter - Convert existing categories to tags or tags to categories, selectively.

2.8. Plugins 25

Largo Project Documentation, Release 0.5

• CodeStyling Localization - a utility for generating translation files from within the WordPress dashboard.

• Core Control - Core Control is a set of plugin modules which can be used to control certain aspects of theWordPress control.

• Empty Tags Remover - Removes the empty tags, tags with no posts attached.

• Regenerate Thumbnails - Allows you to regenerate all thumbnails after changing the thumbnail sizes.

• Taxonomy Converter - Copy or convert terms between taxonomies.

• Term Management Tools - Allows you to merge terms and set term parents in bulk

• Vice Versa - Convert Pages to Posts and Vice Versa

• Theme Check - A simple and easy way to test your theme for all the latest WordPress standards and practices.

• WordPress Importer - Import posts, pages, comments, custom fields, categories, tags and more from a WordPressexport file.

• WP Maintenance Mode - Adds a splash page to your site that lets visitors know your site is down for mainte-nance.

Plugins that we have reluctantly installed for and are in-use by typically one site that we do not necessarily endorseor recommend using:

• Advanced Custom Fields including the Options Page and Repeater Field add-ons.

• Charity Thermometer

• iframe

• Membership Premium

• Pippity

• WooDojo

• WP-Member

2.9 Contact Forms

To allow for the addition of simple contact forms to your site, Largo incorporates a slightly customized version of theClean Contact plugin.

The settings for this plugin can be found under Settings > Clean Contact. By default it will send email submittedthrough the form to the admin email address you set under the Settings > General menu.

Creating a contact page is as simple as creating a new page and putting the following shortcode in the editor, on itsown line where you want the contact form to appear:

[clean-contact]

Feel free to put additional information on the page either before or after the contact form.

You can also use the [clean-contact] shortcode in posts to provide a contact form there.

Finally, it is possible to override the default settings for the contact form directly from the shortcode using the followingparameters:

[clean-contact: prefix="help" email="test@example.com" thanks="Cheers!" bcc="admin@example.com" thanks_url="/thankyou.html"]

26 Chapter 2. General Documentation

Largo Project Documentation, Release 0.5

2.10 Advertising

2.10.1 Supported Plugin: DoubleClick for WordPress

Largo supports DoubleClick for WordPress. Simply install the plugin and follow the steps outlined in the DoubleClickfor WordPress documentation.

You will neeed a DoubleClick for Publishers or Google AdSense account set up before you begin this process.

Note: If you use INN’s hosted version of Largo you do not have the ability to install and activate plugins and willneed to ask us to do this for you. Please submit a service request and we’ll be happy to help.

2.10.2 Enable the Leaderboard Ad Zone (optional)

If you want to run ads at the top of the page, above your masthead:

1. Go to Appearance > Theme Options > Advanced

2. Check “Enable Optional Leaderboard Ad Zone”

If your ads are not showing up, check that your ad widgets are set to be visible in Dashboard > Widgets. Try resizingyour browser window to be wider or narrower.

2.10. Advertising 27

Largo Project Documentation, Release 0.5

28 Chapter 2. General Documentation

CHAPTER 3

For Developers

3.1 For Developers

3.1.1 Overview

Project Largo is released as open source software and anyone is welcome to download or fork the project from ourgithub repository and use it as they like.

If you use Largo for a project we’d love to hear from you so can we add you to our list of sites using Largo and helpget the word out.

The preferred way of building a site with Largo is by creating a WordPress child theme. We have created a sample,heavily documented, child theme to help you understand the way we structure our child themes in the hopes that itwill give you a solid framework to get started. There is more information on setting up Largo and using child themesin the download and installation section of our documentation.

3.1.2 Setting up a development environment

We use a set of tools to make setting up a Largo development environment as easy and consistent as possible.

We encourage all INN member organizations looking to add features to or otherwise modify their theme to use thissame setup, since doing so will make support and collaboration between members and INN easier.

Read:

Setting up a complete Largo dev environment

This recipe will walk you through setting up a fresh WordPress install on a Vagrant Virtualbox machine with INN’sdeploy tools and Largo installed.

We’ll walk you through the overall setup of the WordPress directory, and then we’ll walk you through setting up Largoand its development requirements.

Software to install first

From INN’s computer setup guide, install the following software:

• git

• wget

29

Largo Project Documentation, Release 0.5

• curl

• phpunit

• virtualenv and virtualenvwrapper

• an SSH key

• VirtualBox

• Vagrant

• npm and grunt-cli

If you’re on OSX, you will also want to install Homebrew, to assist in the installation of the above.

Once you have all that set up, you’re ready to install Largo and WordPress inside a virtual machine!

Setting up Largo and WordPress

1. First, create a new directory. This will be version-controlled with git, to make it easier to update Largo and thedeploy tools. If you’re hosting WordPress someplace that allows SFTP access, our deploy tools will help youversion-control your deploy, for fun and profit.

mkdir umbrellacd umbrellagit init

2. Add the deploy-tools and Largo repositories.

git submodule add https://github.com/INN/deploy-tools.git toolsgit submodule add https://github.com/INN/Largo.git wp-content/themes/largo-dev

3. Update all the submodules

git submodule update --init --recursive

4. While you’re at it, copy some configuration files from the deploy-toools folders to the project root:

cp -r tools/examples/ .

5. Now, on to Largo.

cd wp-content/themes/largo-dev

6. You’re going to have to install some things first.

7. First, install the Python dependencies.

We use a few Python libraries for this project, including Fabric which powers the INN deploy-tools toelegantly run many common but complex tasks. In the OS X setup guide, you should have installedPython virtualenv and virtualenvwrapper.

Make sure you tell virtualenvwrapper where the umbrella is.

export WORKON_HOME=~/largo-umbrellamkdir -p $WORKON_HOMEsource /usr/local/bin/virtualenvwrapper.sh

You should add that last line to your .bashrc or your .bash_profile.

Now we can create a virtual environment and install the required Python libraries:

30 Chapter 3. For Developers

Largo Project Documentation, Release 0.5

mkvirtualenv largo-umbrella --no-site-packagesworkon largo-umbrellapip install -r requirements.txt

8. Our API docs/function reference uses doxphp to generate documentation based on the comments embedded inLargo’s source code. You’ll need to install doxphp to generate API docs.

• Installation process with PEAR:

pear channel-discover pear.avalanche123.compear install avalanche123/doxphp-beta

• Installation process with git. This requires you to know where your bin directory is

git clone https://github.com/avalanche123/doxphp.gitcd doxphp/binmv doxph* /path/to/bin/

The last step may require you to use sudo.

9. Make sure that you have the necessary prerequisites for these next steps.

From the top level of the project, run the setup routine as described in the deploy-tools documentation

fab wp.verify_prerequisites

If the script returns any errors, it will also include (hopefully) helpful information on how to rectifythe problems. You may need to reinstall curl.

If the above command fails to run, make sure you have run the workon and pip install com-mands listed above in step 7.

10. Time to install WordPress.

INN’s deploy tools have a handy utility that will install any tagged release of WordPress for you.

(a) cd to the top level of your project, on the same level as the tools/ directory where INN/deploy-tools was installed.

(b) Find the version number of the latest release of WordPress and use its number in the folloiwingcommand

fab wp.install:4.2.2

(c) In the computer setup section above, you installed Vagrant. Now, create the virtual machine:

vagrant up

(a) While you’re waiting, why not stand up, stretch, and make a cup of tea? Downloading the virtualmachine disk image and provisioning it will take a while.In that time, it downloads the image ofa Ubuntu Linux system, installs the MySQL and PHP servers, along with all of the most recentupdates, and configures it just so that all the Fabric commands work.

(b) When it’s done, edit your /etc/hosts file:

sudo nano /etc/hosts

Enter your password, use the arrow keys to position the cursor at the end of the file and add thefollowing line:

3.1. For Developers 31

Largo Project Documentation, Release 0.5

192.168.33.10 vagrant.dev

Then use Ctrl-O to save your changes and Ctrl-X to exit the editor.

This tells your system that whenever you use the address http://vagrant.dev, you really meanthe IP address of the virtual machine. If you’re working on a multisite instance of WordPress, you canadd the subdomains such as another.blog.at.vagrant.dev at the end of the line, separatedby a space from vagrant.dev.

5. Now that the vagrant box is up and running, you can create a database for it to use:

fab vagrant.create_db

Without any arguments, this command will read the defaults from the Fabfile.py in the root of your projectdirectory.

12. Now, let’s take a snapshot of the virtual machine in its new, provisioned, freshly-deployed state.

vagrant plugin install vagrant-vbox-snapshotvagrant snapshot take default snapshot_name_goes_here

You can name the snapshot anything you want, and I would recommend describing it in a short way that describeswhat that state would give you if you were to revert.

13. Now you’re going to set up WordPress on Vagrant. Open a browser and point it at http://vagrant.dev/. You shouldautomatically be redirected to http://vagrant.dev/wp-admin/setup-config.php. Choose your language, then enterthe details below as they are entered in your Fabfile.py:

* Database Name: `largoproject`

* User Name: `root`

* Password: `root`

* Database Host: `localhost`

* Table Prefix: `wp_`

14. If you are working on a multisite install, you will want to add these settings to wp-config.php at the bottom,before “Do not edit below this line.”

/* Make this a multisite install. */define('MULTISITE', true);define('SUBDOMAIN_INSTALL', true);define('DOMAIN_CURRENT_SITE', 'vagrant.dev');define('PATH_CURRENT_SITE', '/');define('SITE_ID_CURRENT_SITE', 1);define('BLOG_ID_CURRENT_SITE', 1);

All done? Log into WordPress and start poking around. Remember to take Vagrant snapshots when you get thingsworking how you like the. You’ll probably want to take one after you add some posts and configure your menus fortesting purposes. If you want to log into the vagrant box, it’s as easy as vagrant ssh.

You have installed:

• INN’s deploy tools

• the Largo theme

• Grunt and the nodejs packages we use to handle a bunch of things

• pip, virtualenv, a largo-docs virtualenv, sphinx, and everything needed to rebuild the documentation

• doxphp and dpxphp2sphinx

• WordPress on a Vagrant virtual machine

32 Chapter 3. For Developers

Largo Project Documentation, Release 0.5

Some notes about Vagrant

You can work on files without booting Vagrant, but if you want to view the effects of changing the files, you’ll want torun vagrant up from the root folder of your project, the one that contains the Vagrantfile.

If you want to turn vagrant off for a while, run vagrant suspend. Suspended vagrant boxes can be brough backto life with vagrant up.

When you want to shut down Vagrant, run vagrant halt.

If you want to poke around in the Vagrant box, run vagrant ssh. You don’t have to enter any passwords or unlockany ssh keys - Vagrant controls those itself.

If you’re unable to log in, try powering the Vagrant machine off through the Virtualbox graphical user interface,or by finding the VM name in VBoxManage list runningvms and using it in VBoxManage controlvm<name|uuid> acpipowerbutton

Some notes about deploy-tools and Fabric

The full list of supported commands can be found in the deploy-tools documentation.

Most fabric commands take the form of

fab <environment> <branch> <action>fab <action that defines its own environment>:arguments

Every command in the list of commands is prefixed with fab.

If you recieve an error when running your command, make sure that you have run workon largo-umbrella, orthe name of the Python virtualenv you are using. When run, workon will prefix your prompt:

blk@oyster:~$ workon largo(largo)blk@oyster:~$

To exit the virtualenv, you can use the command deactivate.

Setting up Largo to contribute documentation

If you just want to help us write documentation, you don’t have to go through the complete setup process.

Once you’ve completed this recipe, you’ll be able to:

• rebuild the documentation

• preview your edits in a browser

• rebuild the translation files.

• push your edits to GitHub and request that we incorporate them in Largo

This presumes that you’re familiar with the command line, and are using OSX or another UNIX-like system.

Setting up

This presumes that you’re familiar with the command line, and are using OSX or another UNIX-like system.

1. Fork INN/Largo into your own GitHub account.

2. Clone your branch:

3.1. For Developers 33

Largo Project Documentation, Release 0.5

git clone git@github.com:you/Largo.git

3. Check out the write-the-docs branch

git checkout write-the-docs

4. Install the required dependencies

We use some Python libraries to generate our documentation. To install the requirements:

cd docs

Not required, but it’s recommended to install and use virtualenv:

mkvirtualenv largo-docsworkon largo-docs

Then:

pip install -r requirements.txt

5. Our API docs/function reference uses doxphp to generate documentation based on the comments embedded inLargo’s source code. You’ll need to install doxphp to generate API docs.

• Install with PEAR:

pear channel-discover pear.avalanche123.compear install avalanche123/doxphp-beta

• Install with git. This requires you to know where your bin directory is, and may require sudo.

git clone https://github.com/avalanche123/doxphp.gitcd doxphp/binmv doxph* /path/to/bin/

6. With all dependencies installed, running the generator is as simple as:

cd docsmake php && make html

But if you don’t want to have to manually recreate the documentation every time you save a file, you can run gruntwatch from the Largo directory. This command only rebuilds documentation, though, and doesn’t recompile the APIdocs.

7. You can view the generated docs in the docs/_build/html directory

There are two main ways of doing this. First, you can view the files with a browser as files. It won’tbe the best experience.

The other, better option is to run a sinple web server in the directory that the HTML documentationwas output to, and then view them normally as a website in your browser:

cd docs/_build/htmlpython -m SimpleHTTPServer 8081

The (ideal) procedure for contributing documentation

1. Choose an issue

2. Comment on the issue that you’re taking it.

34 Chapter 3. For Developers

Largo Project Documentation, Release 0.5

3. Create a new branch with your contributions, named after the issue:

git checkout -b 613-partials-sticky-posts

4. Make your changes

5. Commit and push:

git commit git push -u origin 613-partials-sticky-posts

6. Create a pull request from your branch to INN/Largo

• How to make a PR on GitHub

• If it’s a big PR, please make sure it’s well-documented. Thanks!

Resources for writing documentation

• Sphinx’ PHP domain-specific markup

• Sphinx reStructuredText primer and quickstart guide

3.1.3 Child Themes

What is a child theme?

From the WordPress Codex:

A child theme is a theme that inherits the functionality and styling of another theme, called the parenttheme. Child themes are the recommended way of modifying an existing theme.

Why should you use a child theme?

In order to make it easier to upgrade to future versions of the Largo parent theme, you will want to add any customiza-tions that are unique to your site by creating a child theme. WordPress has a tutorial you can follow that explains howto create and configure a child theme.

More: Creating Child Themes

Using Child Themes

Child themes are a feature of WordPress that allow you to extend and override the parent theme that the child theme isbased upon. We encourage you to create a child theme for your project.

Changing Basic Styling Largo has a built-in way to change some basic styling options.

To enable this option, from the Appearance > Theme Options screen click on the “Advanced” tab and check the boxlabelled “Enable Custom LESS to CSS For Theme Customization” and then save the settings.

You will now see an additional menu item under the Appearance menu labelled “CSS Variables”. From this menu youwill be able to change some basic styling attributes of your Largo site, including the color scheme, fonts and font-sizes.

This option is only intended for making some basic changes to your site’s styles. For anything more complex you willneed to create a child theme.

3.1. For Developers 35

Largo Project Documentation, Release 0.5

Advanced Theme Development and Modification We’ve created a Largo-Sample-Child-Theme repository to il-lustrate how we organize child themes that extend Largo.

Visit the repository page to learn more about the following as they pertain to Largo-based child themes:

• Unit Tests and Continuous Integration

• Stylesheets (LESS and CSS)

• Theme Directory Layout

• Custom Theme Javascript or CSS

• Removing or replacing Largo Javascript or CSS

3.1.4 Technical Notes

A few brief technical notes that might be helpful as you get started:

About the inc/ directory

When you download the theme you’ll notice that the /inc folder contains most of the add-on functionality for the parenttheme and all of these files are then loaded up via functions.php

Pluggable (overridable) Largo functions

Many of Largo’s core functions are pluggable so you can write your own version of them by using the same functionname in a child theme’s functions.php.

You can read up on how that works in the WordPress codex section about child themes.

See: Function Refernce.

Theme Options and the Options Framework

Largo uses the Options Framework for the Appearance > Theme Options menu pages.

If you need to access a Theme Options value, use of_get_option() instead of the usual get_option(). Thetheme options pages themselves can be customized from options.php in the main theme folder.

Homepage Templates

See Homepage layouts from our Largo-Sample-Child-Theme repository.

LESS and CSS

The Largo parent theme uses LESS CSS to generate the stylesheets including a number of elements borrowed andtweaked from Twitter Bootstrap.

You will notice that the theme’s main style.css is empty except for the header block because we enqueue our stylesfrom css/style.css (the output of /less/style.less when it’s compiled), overriding the WordPress default behaviorof including the style.css file in the root of the theme directory.

36 Chapter 3. For Developers

Largo Project Documentation, Release 0.5

TGM Plugin Activation

We use TGM Plugin Activation to package a couple of plugins with the Largo theme that are not currently availablein the WordPress plugin directory and to recommend plugins for a number of tasks that are commonly requested fornews websites.

• The rest of the theme files and the folder structure should be familiar to most WordPress developers, but if youhave any questions, feel free to get in touch.

Compiling translation files

To rebuild the translation files, run the following commands:

grunt potmsgmerge -o lang/es_ES.po.merged lang/es_ES.po lang/largo.potmv lang/es_ES.po.merged lang/es_ES.pogrunt po2mo

Images

See the Pre-Launch Checklist to see the list of image types and sizes you’ll need to get your site up and running.

More on image sizes:

Largo Image Sizes and Constants

Largo defines several image sizes for use in various parts of the theme. All sizes are based on a set of constants definedin functions.php. Child themes can override these presets to change the size of images throughout the theme.

Image Sizes The following image sizes are registered in Largo, using the constants defined below.

• 60x60

– 60x60px image crop.

• rect_thumb

– 800x600px image crop

– Used for cat/tax archive pages.

• medium

– Image size defined by constants: MEDIUM_WIDTHxMEDIUM_HEIGHT

– Default is 336px wide by a flexible height.

• large

– Image size defined by constants: LARGE_WIDTHxLARGE_HEIGHT

– Default is 771px wide by a flexible height.

• full

– Image size defined by constants: FULL_WIDTHxFULL_HEIGHT

– Default is 1170px wide by a flexible height.

• third-full

3.1. For Developers 37

Largo Project Documentation, Release 0.5

– Image size defined by: (FULL_WIDTH/3)xFULL_HEIGHT

– Default is 390px wide by a flexible height.

• two-third-full

– Image size defined by: (FULL_WIDTH*2/3)xFULL_HEIGHT

– Default is 780px wide by a flexible height.

Constants Width:

• FULL_WIDTH (default: 1170): the largest width for the largest image size

• LARGE_WIDTH (default: 771): medium image crop width

• MEDIUM_WIDTH (default: 336): small image crop width

Height:

Largo does not impose any height limits on crop sizes. Thus the defaults are set to 9999.

• FULL_HEIGHT (default: 9999): full image crop height

• LARGE_HEIGHT (default: 9999): medium image crop height

• MEDIUM_HEIGHT (default: 9999): small image crop height

See also Largo’s list of constants.

3.1.5 Function Reference

NOTE: the function reference is a work-in-progress and may not be very useful at the moment.

You can always read Largo’s source on Github.

Function reference by file

• feed-mailchimp.php

• functions.php

• options.php

• homepages/homepage.php

• homepages/layouts/HomepageSingleWithSeriesStories.php

• homepages/zones/zones.php

• inc/custom-feeds.php

• inc/custom-less-variables.php

• inc/deprecated.php

• inc/editor.php

• inc/enqueue.php

• inc/featured-content.php

• inc/featured-media.php

• inc/helpers.php

38 Chapter 3. For Developers

Largo Project Documentation, Release 0.5

• inc/images.php

• inc/metabox-api.php

• inc/nav-menus.php

• inc/plugin-init.php

• inc/post-metaboxes.php

• inc/post-tags.php

• inc/post-templates.php

• inc/related-content.php

• inc/sidebars.php

• inc/taxonomies.php

• inc/term-icons.php

• inc/term-meta.php

• inc/term-sidebars.php

• inc/update.php

• inc/users.php

• inc/verify.php

• inc/widgets.php

• inc/customizer/customizer.php

• inc/widgets/largo-facebook.php

• inc/widgets/largo-follow.php

• inc/widgets/largo-image-widget.php

• inc/widgets/largo-post-series-links.php

• inc/widgets/largo-recent-comments.php

• inc/widgets/largo-recent-posts.php

• inc/widgets/largo-twitter.php

• inc/wp-taxonomy-landing/taxonomy-landing.php

• inc/wp-taxonomy-landing/functions/cftl-admin.php

• inc/wp-taxonomy-landing/functions/cftl-series-order.php

• partials/content-argolinks.php

• partials/content.php

• partials/footer-widget-area.php

• partials/sidebar-archive.php

• partials/sidebar-single.php

• partials/sidebar.php

3.1. For Developers 39

Largo Project Documentation, Release 0.5

Largo Constants

The image constants

Largo’s image constants are used to define the crop and scaling sizes that WordPress automatically chops your imageinto.

Width:

• FULL_WIDTH (default: 1170): the largest width for the largest image size

• LARGE_WIDTH (default: 771): medium image crop width

• MEDIUM_WIDTH (default: 336): small image crop width

Height:

Largo does not impose any height limits on crop sizes. Thus the defaults are set to 9999.

• FULL_HEIGHT (default: 9999): full image crop height

• LARGE_HEIGHT (default: 9999): medium image crop height

• MEDIUM_HEIGHT (default: 9999): small image crop height

For more information about how Largo handles image sizes, see Image Sizes.

The other constants

constant INN_HOSTEDINN_HOSTED indicates whether or not a WordPress instance is hosted by INN. This setting should be set inwp-config.php, but there is no reason for you to set this.

If INN_HOSTED is true, then INN_MEMBER below is also true.

constant INN_MEMBERINN_MEMBER indicates whether or not a WordPress site belongs to a member of the Institute for NonprofitNews.

INN_MEMBER is defined as true in functions.php if it is not otherwise defined and if INN_HOSTED istrue. If INN_HOSTED is false, then INN_MEMBER will also be false unless INN_MEMBER is explicitly definedin wp_config.php or in the functions.php of a child theme.

constant LARGO_DEBUGLARGO_DEBUG should be set to true in development environments. It controls many behaviors:

•in inc/enqueue.php, LARGO_DEBUG controls whether or not minified versions of the following files are used:

– css/style.css

– js/largoCore.js

– css/widgets-php.css

– js/widgets-php.js

•in inc/custom-less-variables.php, LARGO_DEBUG controls whether or not minified versionsof the recompiled files are used.

•in inc/featured-media.php, LARGO_DEBUG controls whether or not minified versions of the following files are used:

– js/featured-media.js

40 Chapter 3. For Developers

Largo Project Documentation, Release 0.5

•in inc/post-metaboxes.php, LARGO_DEBUG controls whether or not minified versions of the following files are used:

– js/custom-sidebar.js

– js/top-terms.js

•in inc/term-icons.php, LARGO_DEBUG controls whether or not minified versions of the following files are used:

– js/custom-term-icons.js

•in inc/update.php,

– js/update-page.js

Define LARGO_DEBUG to true in your wp-config.php with the following line:

define( 'LARGO_DEBUG', TRUE);

Please be careful with LARGO_DEBUG-related functionality, as it is difficult to write tests for functions includingconstants.

constant OPTIONS_FRAMEWORK_DIRECTORYThis constant represents the URI of the options framework, defined as get_template_directory_uri(). ’/lib/options-framework/’ in functions.php. This path is used to enqueue the optionsframework CSS, color picker CSS, jquery-dependent color picker, iris.min.js, the options framework scripts,and the options framework media library uploader.

constant SHOW_GLOBAL_NAVThe Global Nav is a thin blck bar displayed in the header of Largo, goverened by SHOW_GLOBAL_NAV.SHOW_GLOBAL_NAV defaults to true, but child themes can set it to false with define(’SHOW_GLOBAL_NAV’, FALSE ); in their theme functions.php.

constant SHOW_STICKY_NAVThe sticky nav appears on the homepage and all internal pages, and on mobile devices, governed bySHOW_STICKY_NAV. SHOW_STICKY_NAV my be defined to be true or false, but the easiest way to set itis to check “Show the Sticky Nav” in the Theme Options section of Largo.

constant SHOW_MAIN_NAVThe main navigation appears on the homepage and all internal pages, but not on mobile devices, governed bySHOW_MAIN_NAV. SHOW_MAIN_NAV defaults to true, but child themes can set it to false with define(’SHOW_GLOBAL_NAV’, FALSE ); in their theme ‘‘functions.

constant SHOW_SECONDARY_NAV

constant SHOW_CATEGORY_RELATED_TOPICS

constant LARGO_AVATAR_META_NAME

constant LARGO_AVATAR_ACTION_NAME

constant LARGO_AVATAR_INPUT_NAME

constant JCLV_UNCOMPRESSED

constant DOING_AUTOSAVE

constant PICTUREFILL_WP_PATH

constant PICTUREFILL_WP_URL

constant PICTUREFILL_WP_VERSION

constant CFTL_SELF_DIR

3.1. For Developers 41

Largo Project Documentation, Release 0.5

constant LARGO_TEMPLATE_LANDING_VERSION

constant MEDIA_CREDIT_POSTMETA_KEY

3.1.6 Bug Reports and Feature Requests

Our preferred way for you to submit bug reports, requests for new features or even questions about how things workin Largo is by opening a new issue on the Largo github repository.

3.1.7 Contributing to Largo

We welcome (and encourage) anyone who wants to contribute back to the project.

To begin, please review our contribution guidelines.

We have many ways you can contribute and not all are technical. Wherever possible we will flag issues that we believeare good for beginners or for less/non-technical contributors (writing/improving documentation, etc.).

Our roadmap, open issues, suggested features and discussion can always be found in the issues section of the Largogithub repository.

We also have documentation on the Anatomy of a Pull Request and Submission Protocol and Contributing to theINN Nerds docs repo using Github.com which explain, at a high level, the process of contributing to Github projects,generally.

If you would like to help with the documentation, here are some resources:

• Sphinx’ PHP domain-specific markup

• Sphinx reStructuredText primer and quickstart guide

If you have feedback on this collection of documentation, please get in touch.

3.2 Largo Constants

3.2.1 The image constants

Largo’s image constants are used to define the crop and scaling sizes that WordPress automatically chops your imageinto.

Width:

• FULL_WIDTH (default: 1170): the largest width for the largest image size

• LARGE_WIDTH (default: 771): medium image crop width

• MEDIUM_WIDTH (default: 336): small image crop width

Height:

Largo does not impose any height limits on crop sizes. Thus the defaults are set to 9999.

• FULL_HEIGHT (default: 9999): full image crop height

• LARGE_HEIGHT (default: 9999): medium image crop height

• MEDIUM_HEIGHT (default: 9999): small image crop height

For more information about how Largo handles image sizes, see Image Sizes.

42 Chapter 3. For Developers

Largo Project Documentation, Release 0.5

3.2.2 The other constants

constant INN_HOSTEDINN_HOSTED indicates whether or not a WordPress instance is hosted by INN. This setting should be set inwp-config.php, but there is no reason for you to set this.

If INN_HOSTED is true, then INN_MEMBER below is also true.

constant INN_MEMBERINN_MEMBER indicates whether or not a WordPress site belongs to a member of the Institute for NonprofitNews.

INN_MEMBER is defined as true in functions.php if it is not otherwise defined and if INN_HOSTED istrue. If INN_HOSTED is false, then INN_MEMBER will also be false unless INN_MEMBER is explicitly definedin wp_config.php or in the functions.php of a child theme.

constant LARGO_DEBUGLARGO_DEBUG should be set to true in development environments. It controls many behaviors:

•in inc/enqueue.php, LARGO_DEBUG controls whether or not minified versions of the following files are used:

– css/style.css

– js/largoCore.js

– css/widgets-php.css

– js/widgets-php.js

•in inc/custom-less-variables.php, LARGO_DEBUG controls whether or not minified versionsof the recompiled files are used.

•in inc/featured-media.php, LARGO_DEBUG controls whether or not minified versions of the following files are used:

– js/featured-media.js

•in inc/post-metaboxes.php, LARGO_DEBUG controls whether or not minified versions of the following files are used:

– js/custom-sidebar.js

– js/top-terms.js

•in inc/term-icons.php, LARGO_DEBUG controls whether or not minified versions of the following files are used:

– js/custom-term-icons.js

•in inc/update.php,

– js/update-page.js

Define LARGO_DEBUG to true in your wp-config.php with the following line:

define( 'LARGO_DEBUG', TRUE);

Please be careful with LARGO_DEBUG-related functionality, as it is difficult to write tests for functions includingconstants.

constant OPTIONS_FRAMEWORK_DIRECTORYThis constant represents the URI of the options framework, defined as get_template_directory_uri(). ’/lib/options-framework/’ in functions.php. This path is used to enqueue the options

3.2. Largo Constants 43

Largo Project Documentation, Release 0.5

framework CSS, color picker CSS, jquery-dependent color picker, iris.min.js, the options framework scripts,and the options framework media library uploader.

constant SHOW_GLOBAL_NAVThe Global Nav is a thin blck bar displayed in the header of Largo, goverened by SHOW_GLOBAL_NAV.SHOW_GLOBAL_NAV defaults to true, but child themes can set it to false with define(’SHOW_GLOBAL_NAV’, FALSE ); in their theme functions.php.

constant SHOW_STICKY_NAVThe sticky nav appears on the homepage and all internal pages, and on mobile devices, governed bySHOW_STICKY_NAV. SHOW_STICKY_NAV my be defined to be true or false, but the easiest way to set itis to check “Show the Sticky Nav” in the Theme Options section of Largo.

constant SHOW_MAIN_NAVThe main navigation appears on the homepage and all internal pages, but not on mobile devices, governed bySHOW_MAIN_NAV. SHOW_MAIN_NAV defaults to true, but child themes can set it to false with define(’SHOW_GLOBAL_NAV’, FALSE ); in their theme ‘‘functions.

constant SHOW_SECONDARY_NAV

constant SHOW_CATEGORY_RELATED_TOPICS

constant LARGO_AVATAR_META_NAME

constant LARGO_AVATAR_ACTION_NAME

constant LARGO_AVATAR_INPUT_NAME

constant JCLV_UNCOMPRESSED

constant DOING_AUTOSAVE

constant PICTUREFILL_WP_PATH

constant PICTUREFILL_WP_URL

constant PICTUREFILL_WP_VERSION

constant CFTL_SELF_DIR

constant LARGO_TEMPLATE_LANDING_VERSION

constant MEDIA_CREDIT_POSTMETA_KEY

3.3 Feedback on these docs

If you have comments or suggestions on this documentation, you can reach us through the following ways:

• File an issue on Largo’s Github repository

• Send an email to nerds@inn.org

• Tweet to us @innnerds

44 Chapter 3. For Developers

Index

CCFTL_SELF_DIR (global constant), 41, 44

DDOING_AUTOSAVE (global constant), 41, 44

IINN_HOSTED (global constant), 40, 43INN_MEMBER (global constant), 40, 43

JJCLV_UNCOMPRESSED (global constant), 41, 44

LLARGO_AVATAR_ACTION_NAME (global constant),

41, 44LARGO_AVATAR_INPUT_NAME (global constant),

41, 44LARGO_AVATAR_META_NAME (global constant), 41,

44LARGO_DEBUG (global constant), 40, 43LARGO_TEMPLATE_LANDING_VERSION (global

constant), 41, 44

MMEDIA_CREDIT_POSTMETA_KEY (global constant),

42, 44

OOPTIONS_FRAMEWORK_DIRECTORY (global con-

stant), 41, 43

PPICTUREFILL_WP_PATH (global constant), 41, 44PICTUREFILL_WP_URL (global constant), 41, 44PICTUREFILL_WP_VERSION (global constant), 41, 44

SSHOW_CATEGORY_RELATED_TOPICS (global con-

stant), 41, 44

SHOW_GLOBAL_NAV (global constant), 41, 44SHOW_MAIN_NAV (global constant), 41, 44SHOW_SECONDARY_NAV (global constant), 41, 44SHOW_STICKY_NAV (global constant), 41, 44

45