LSE Cities Web Handbook

(1)

LSE Cities Web Handbook

Release 1.0

Andrea Rota

(2)

(3)

Contents

1 Documentation for team members 3

1.1 Urban Age conferences . . . 3

2 Operations documentation 13

2.1 Managing the WordPress network . . . 13

3 Documentation for developers 15

3.1 Web content management overview . . . 15

(4)

(5)

LSE Cities Web Handbook, Release 1.0

This handbook is meant to document processes, workflows and requirements for all the centre’s activities that involve managing content on the web (e.g. preparing content for an Urban Age conference).

The handbook contains:

• information forteam members involved in the production of content for the web; • documentation for the management of the centre’sweb operations

• documentation forweb developersworking on frontend and backend code for the LSE Cities website. It doesn’t contain detailed guidance for website editors: for this, see theWeb editors’ handbook.

(6)

(7)

CHAPTER

1 Documentation for team members

1.1 Urban Age conferences

Getting the LSE Cities website ready for the annual Urban Age conference is a process that normally spans several months, from the publishing of a simple landing page up to the launch of the full conference website’s content just before the event.

The following sections list the key stages of the run-up to a new conference; links to more detailed documentation for content editors/developers are provided where applicable.

1.1.1 Conference landing page

We normally publish a simple page with key information about the upcoming conference as soon as we are ready to announce the event’s themes, host city and dates. For an example of such a landing page, see the screenshot below:

(8)

(9)

The initial page is normally placed on the main LSE Cities website, under Urban Age -> Conferences. Later on, as more content is made available, the conference’s materials may be moved to a dedicated microsite (seeConference micrositesbelow for more details).

When

In the past few years, we have usually published the conference landing page in late spring/early summer. As soon as the conference’s dates and themes are confirmed we can start setting up the landing page, to be published whenver agreed.

Who

The landing page is prepared and published by the communications team, with input from the conference manager.

Content needed

• conference location (city only - we don’t normally publicise the event’s location as access is by invitation only) • conference title (e.g. Electric City, Governing Urban Futures, etc.), if applicable

• conference dates

• brief conference blurb (100 to 300 words); at this early stage, this may include names of a few confirmed speakers, if appropriate, as we would normally publish a full list of speakers just before the conference

• heading photo

1.1.2 ‘Register your interest’ form

Besides introducing the upcoming conference’s themes, the landing page is also used to collect applications from visitors interested in the event: we use a web form for this, asking for some key information (name, email address and why they are interested in the conference) and, optionally, for more details (city, country, organisation, role, areas/topics of interest).

Users who submit their application online agree to receive email updates about the conference from LSE Cities, and they are given the option to sign up for all LSE Cities newsletters.

Data gathered through this form is used alongside other research done to screen potential speakers and invitees, al-though we want to make sure that the form is perceived just as a signup form for updates rather than a full application form to be invited to the conference.

To this effect, applicants receive a short email confirming that their submission has been received and that they will be kept updated about the conference.

When

Ideally as soon as the landing page is published or as soon as possible thereafter.

Who

The communications team sets up the form in WordPress and, where applicable, grants access to the list of submissions received to the conference manager and other colleagues who may need to screen submissions.

(10)

Content needed

A brief text (around 100 words max) for the automated confirmation email sent to visitors once they submit their contact details.

1.1.3 Conference microsites

Until 2009 (Urban Age Istanbul conference) the full conference content was hosted on the main centre’s website (at the time, urban-age.net).

In 2010 we developed a microsite for the Global Metro Summit conference in Chicago (http://globalmetrosummit.net/

- the microsite has since been taken offline and its contents have been moved to the main LSE Cities website); in 2012 we designed and developed a microsite for the Electric City conference in London, using the distinctive branding developed for this event; in 2013 we designed and developed a microsite for the City Transformations conference in Rio de Janeiro, with the intention to make this microsite’s layout a ‘standard’ template to be reused for future conferences when no major custom branding is needed.

Conference microsites require a quick initial setup and no additional editorial overhead, compared to a con-ference section on the main LSE Cities website, while allowing us to use a short, easy-to-share web address (e.g.http://ec2012.lsecities.net/rather thanhttp://lsecities.net/ua/conferences/2012-london/) and most importantly are small, self-contained websites hosting all the conference-related content in an easy to browse format.

Recent past conference microsites included a few key areas:

• Front page (also used for live video and Twitter streams during the conference) • Programme

• Speakers

• Newspaper (the conference’s publication, in web format)

• Data (where applicable, a selection of data charts/maps from the conference’s newspaper) • Press (press releases/logos/press materials)

• Conference photos

• Videos (hosting short interviews to conference speakers and attendees; videos of session conferences are added shortly after the conference to the Programme page)

• Media (media coverage, storify summaries of the conference days, etc.)

When

If a microsite is used, this can be set up as early as initial conference information is published and could be used instead of a landing page hosted on the main LSE Cities website; in practice, in the past few years we have only launched a conference’s microsite from a few weeks to a few days before the conference itself.

Who

The initial setup of a conference microsite requires a little custom development and web server administration; content can be managed throughout the lifetime of the microsite by the communications team within the main WordPress dashboard used for all the rest of our online content.

(11)

Content needed

Before the initial setup of a microsite, theweb addressneeds to be chosen; ideally this would be similar to those used in 2012 (ec2012.lsecities.net, for Electric City 2012) or 2013 (rio2013.lsecities.net). It is possible to use just the year (e.g. 2014.lsecities.net), if appropriate.

We should avoid registering new domain names unless necessary for specific reasons (as it was done in 2010 for the globalmetrosummit.net domain), as this would then bind us to renewing the domain name registration for a number of years to avoid breaking links used on external websites, whereas we can easily manage anything in the format

xxyyzz.lsecities.netwithout any additional cost and effort.

If a conference microsite is launched early, the same content needed for the landing page is enough to populate a first version of the microsite.

Ifbackground photosare used (these can be used with the page template developed for the Rio 2013 conference), ideally we should have at least ten good quality photos, which are then displayed randomly every time a page is loaded. Each photo should be at least 1920 pixels wide and for each photo we need:

• author details

• any required attribution information (e.g. for photos from Flickr’s Creative Commons pool)

• ideally also the location where the photo was shot (this is so that we can store data for future uses such as overlay photo captions, interactive map of the places depicted in the photos, etc.)

1.1.4 Conference video: live streaming and recording

As we would like to allow a wide public to follow the conference live, we have been livestreaming on the web all the recent conferences; additionally, all the conference video feeds are recorded so that we can publish them to the LSE Cities YouTube channel after the conference, where applicable: a few individual sessions from past conferences have not been published for various reasons, and we decided not to publish the Rio 2013 conference videos due to quality issues. A copy of the original recordings is also kept in the office, archived for future uses.

Video recording and livestreaming arrangements at past conferences varied according to the local video service providers contracted for the events.

In London (2012) a dedicated crew filmed the whole event with multiple cameras, and the same video feed streamed to the Internet was also displayed on three big screens at the conference venues so that every audience member could see speakers, slides, highlights even from seats with limited visibility to the main stage. Additionally, a video director was in charge of coordinating the camera crew and selecting in real time which camera feed was being shown in the live video stream (e.g. alternating focus between slides, speaker, audience members at debate time, etc.).

Besides the camera/direction/recording arrangements at the conference venue, to stream the conference live we need the video production company to set up the streaming infrastructure for us, including checking speed/bandwidth and reliability of the Internet connection at the venue, and to provide us with the HTML code to be inserted on the conference’s microsite.

Video layout for published videos

(12)

(source:http://youtu.be/3D1WeSCSkPQ)

Full-screen slides, speaker on the side (large frame):

(source:http://youtu.be/BxJ-27Nnakc)

Full-screen slides, speaker on the side (small frame):

(13)

(source:http://youtu.be/0xx_dkv9DEY)

When

Arrangements for video recording and livestreaming should be in place well in advance of the conference; we would normally aim to run a full livestreaming test two weeks before the conference.

Who

Most of the video setup and work at the venue is normally done by local companies: we need to provide our require-ments (see below) and to make sure that the service they provide matches our specifications.

Content/information needed

Video recording: we should aim for: • full HD video recording

• at the very least two cameras (one for speakers/panelists and another for screen/slides/audience) • recorded video should be stored using Apple ProRes or Avid DNxHD codecs

• if different angles/sources are selected live and the resulting video stream is recorded, we would still need to keep the ‘raw’ unedited footage from each of the cameras used

• likewise, if session titles and speaker names are added to the live stream, we need raw footage without added titles so that we can further edit the original video when needed.

Livestreaming:

• it is important to confirm well in advance the speed/bandwidth of the internet connection available at the venue for livestreaming of video;

(14)

• this should be a dedicated connection (i.e. not shared with any other Internet usage such as staff or conference attendees Internet access);

• the maximum quality of the stream available to watchers depends largely on the upload bandwidth of the dedi-cated Internet connection - for reference seeYouTube’s help page on live video resolution;

• whilst YouTube provides a free livestreaming service, it is advisablenotto rely on it for the Urban Age con-ferences, as YouTube’s service is monitored by an automated copyright infringement system, which is known for occasionally mis-identifying content as infringing, terminating the affected livestreaming with little hope of having it reinstated within any useful timeframe.

In order to make the live video player available on the conference’s microsite, we will then just need the HTML embed code for the livestream from the company managing the actual streaming.

The size of the embedded video player depends on each visitor’s screen size, however this will not stretch beyond 960 pixels, using the current conference microsite layout.

1.1.5 Speaker profiles

Speaker profiles and conference programme pages are generated from a single set of data, which links conference sessions to speakers/chairs/respondents; we can, however, publish even a partial list of speakers as soon as they are confirmed, even before work on the programme has started.

When

As soon as a speaker’s profile is finalised we can add it to the website’s backend database: whether speakers are added one by one or as a single batch, ideally all the speaker profiles should be in the database no later than one month before the conference.

Who

Once speaker data is confirmed, it can be uploaded by the communications team.

Content needed

For each speaker, we need: • name

• affiliation(s) and role(s) • blurb (50 words max)

• photo (at least 500x500px for the web, close crop)

1.1.6 Conference programme

When

In 2012 and 2013 we started entering programme information on the website backend as early as a couple of weeks before the conference, although the final programme was then only made public just before the conference.

In order to be able to link speakers (and, later on, individual presentation videos and slides) to each session, we need to enter a large amount of metadata, which takes time to be uploaded: we should therefore aim to dedicate a full day to the preparation of the programme for the website.

(15)

Who

Once programme sessions are confirmed, they can be added to the website backend by the communications team.

Content needed

For each session, we need: • session title

• start and end times

• names of chair(s), speaker(s), respondent(s)

It’s probably best if all the sessions are added to the website at the same time: this can be done by copying all the required data from the version of the programme prepared for print, so in practice a PDF of the final programme is all we need to prepare the web version.

1.1.7 Press information

We make press releases, media packs/logos/photos available on the Press page of the conference microsites. Any materials that need to be published on this page should be sent to the communications team.

1.1.8 Twitter coverage

Starting with the 2012 Electric City conference, we have invited people to use a Twitter hashtag for any tweets related to the conference (#UAElectric for the 2012 conference, #UARio for the 2013 conference). While the conference is happening, we add a live twitter box to the microsite’s frontpage, showing all the live coverage of the conference as it happens on Twitter.

We also feature the hashtag prominently on the microsite (so far, we placed it on the site heading, to the right of the top navigation bar) and disseminate it widely before the conference via our pre-conference email campaigns.

Content needed

We just need to confirm which hashtag we wish to use; setting up the live coverage box and adding the hashtag to the site’s header takes a few moments only.

(16)

(17)

CHAPTER

2 Operations documentation

2.1 Managing the WordPress network

2.1.1 WordPress updates

If applying WordPress updates manually (rather than letting WordPress perform the update automatically), once the new WordPress core has been installed, update of individual network sites may fail because of PHP not accepting self-signed X.509 certificates in use on some of the network sites.

To manually trigger an update in this case, just visithttps://<address-of-site>/wp-admin/upgrade.php?action=upgrade

(e.g.https://lsecities.net/wp-admin/upgrade.php?action=upgrade).

2.1.2 Enabling uploads of larger files

We normally keep file size limit for WordPress Media Library items down to around 20MB to avoid accidental uploads of unnecessarily large files.

In order to temporarily raise the limit, a new limit can be configured from the WordPress Network admin section under Settings -> Network Settings, section Upload settings (at the bottom of the page).

2.1.3 Enabling uploads of specific file types

Any file type that is allowed into WordPress Media Library needs to be explicitly whitelisted - WordPress will other-wise refuse the upload for security reasons.

The list of allowed file types can be configured from the WordPress Network admin section under Settings -> Network Settings, section Upload settings (at the bottom of the page).

(18)

(19)

CHAPTER

3 Documentation for developers

3.1 Web content management overview

Web content for LSE Cities is managed through WordPress; the Pods plugin is used to manage all the different content types specific to LSE Cities (research projects, publications, events, audio/video items, people, etc.) besides the basic Page and Post types provided by WordPress.

Content managed through WordPress + Pods is processed by theLSE Cities WordPress Themeto generate the web pages of the LSE Cities website athttp://lsecities.net/. This WordPress theme was initially developed as a standard theme, whereby each page type is generated through a specific WordPress template or variants of a shared template depending on context; the theme’s source code is gradually being updated in order to enforce a clean separation between thedataused to generate web pages and the actualtemplatesfor each page, and to allow for distinct parts of the WordPress theme to be developed independently by different developers and designers.

The following sections illustrate the core development tooling workflows and outline the skills needed to manage each workflow. Core skills needed to develop any part of the LSE Cities WordPress theme are:

• Version control with Git

• Gulp for asset-management pipelines

(20)

3.1.1 LSE Cities WordPress Theme

The overall structure of the LSE Cities WordPress theme is outlined in the chart above: Content, as managed by editors through the WordPress dashboard, is processed to generate the web pages of the lsecities.net website and of any conference microsites, as well as to make LSE Cities and Urban Age content available for API consumption by apps (such as the new content archive search interface and the upcoming Urban Age digital platform). Stylesheets and Javascript code are preprocessed for optimizations and to enable faster content loading and page rendering.

(21)

3.1.2 Generating web pages

The section of chart highlighted above illustrates the steps involved in the generation of each web page available to visitors.

• Pods codefetchescontentfrom the WordPress + Pods backend as needed and assembles a PHP data structure (content data) ready to be used by a templating engine.

For example, when generating content data for an event’s detail page, the Pods code retrieves the event’s data from the Events pod, speaker profiles from the People pod, and a list of past and upcoming event (to be displayed in the event page’s sidebar) from the Events pod. It then returns a data structure which includes all the event’s information, speaker profiles and event calendar.

• Twig templates using HAML syntaxthen turncontent datainto theHTML pagesthat are sent to visitors’ browsers (after being cached and optionally distributed through load balancers).

Twig provides a much cleaner templating system than stock PHP, and theMtHAML libraryallows to use Twig with terse HAML syntax for rapid prototyping and development.

Skills required to manage this part of the WordPress theme

For the first step (content to content data via Pods code):

• Knowledge of WordPress internals and WordPress theme development • Pods API

For the second step (content data to HTML5 pages via Twig/HAML templating): • HAML markup

(22)

3.1.3 LSE Cities API

The section of chart highlighted above illustrates the steps involved in the generation ofWP-API JSON dataserved through the LSE Cities API.

• As forcontent dataused to generate web pages,Pods codefetchescontentfrom the WordPress + Pods backend as needed and assembles a PHP data structure (content data).

• Rather than further processingcontent datathrough a templating engine, this is serialized to JSON documents and sent to API consumers according to any applicable ACLs.

LSE Cities API data is currently used (packaged as an exported full dump of the whole LSE Cities content) to power the new content archive search interface. It could as well be used by any other API consumer (for example, the upcoming Urban Age digital platform or by packaged native web apps), either as an exported dump, via live queries to the LSE Cities API or, for optimal performance, it could be exported to a fast, distributed JSON data store such as PostgreSQL and then used without the performance penalty imposed by PHP and WordPress.

Moreover, using the LSE Cities API the lsecities.net website itself could in theory be generated via any CMS pipeline other than WordPress itself, if needed in the future for performance, integration or other reasons, whilst still managing the site’s content itself within WordPress.

• Knowledge of WordPress internals and WordPress theme development • Pods API

• WP-API

• Experience with API development

(23)

3.1.4 Content styling

The section of chart highlighted above illustrates the steps involved in the generation of the main app.css stylesheet that is used on the lsecities.net website as well as on conference microsites (such as the Urban Age Governing Urban Futures - Delhi 2014 microsite).

• SourceSCSS stylesheetsare developed using SASS (SCSS syntax); all of the theme’s stylesheets and any SASS library arecompiled to plain CSS via LibSass, minified and concatenatedinto a singleapp.cssstylesheet which includes all the theme’s styles (except those enqueued by WordPress plugins).

The LSE Cities WordPress theme was initially developed using the (now deprecated)1140px CSS Gridand is currently being refactored as a mobile-first, progressively-enhanced, responsive theme using theSusylibrary.

• Knowledge of WordPress internals and WordPress theme development • SASS

• CSS3

• Responsive web design • Mobile-first design

(24)

3.1.5 Javascript workflow

The section of chart highlighted above illustrates the steps involved in the generation of the main app.js Javascript bundle that is used for the frontend code on the lsecities.net website as well as on conference microsites.

• The LSE CitiesJavascript sourcesand all the CommonJS dependencies arebundled via Browserifyinto a singleapp.jsJavascript file which includes all the frontend code for lsecities.net (except any scripts enqueued by WordPress plugins).

Javascript dependencies that are not available in CommonJS format are bundled via browserify-shim; modules not available via npm are installed via Bower.

• Knowledge of WordPress internals and WordPress theme development • Javascript

• Browserify & browserify-shim

• Progressive enhancement best practices

(25)

CHAPTER

4 Indices and tables

• genindex

• modindex