MetroPress v2 Documentation
 

1  Overview

MetroPress is an app template that powers the transformation of any WordPress website into a Windows Store App.
 
Building on the foundation of version 1 and the feedback from the community, version 2 has undergone major additions to its architecture that include:
  • Modularization – creates separatio of functions and enhances extendibility
  • WordPress.com Support – sites hosted on WordPress.com are now supported as well
  • Theme/Template System
    • Offers easy and flexible customization
    • Has a number of default color themes and templates to choose from
  • Live Tile Support – display new posts by pulling the WordPress website with a background task

MetroPress is primarily constructed using HTML5, WinJS, and Cascading Style Sheet (CSS).

 


 

2 Features

MetroPress v2 offers the following set of features:
Functionality Self-Hosted WordPress Wordpress.com
Recent Posts Yes Yes
Posts by Category Yes Yes
Pages Yes Yes
Bookmarking Yes Yes
Sharing Yes Yes
Auto Fetch when scroll to the end Yes Yes
Show Related Posts Yes Yes
Show Comments Yes Yes
Post Commenting Yes Yes
Requires Client ID/Secret from Wordpress.com
Live Tile Yes Yes
Search Yes Yes

3 Building Your First MetroPress App Using Your WordPress Website

This section guides you through building your first MetroPress App from your WordPress website. For details on further configuration and customization please refer to the subsequent sections.

3.1 Download MetroPress  

Download MetroPress from CodePlex: https://metropress.codeplex.com

3.2 Compile The VS Solution

Unzip the downloaded file, compile, and run the MetroPress solution in Visual Studio 2012 on your Windows 8 system. As you compile, it will bring up the MetroPress App, but it connects to http://ideanotion.net by default.

3.3 Change It to Your Own Website

Open up option.js in the js folder, find http://ideanotion.net and replace it with your website’s URL.
 
If your WordPress site is self-hosted, make sure that you have the plugin JSON API installed - http://wordpress.org/extend/plugins/json-api/

3.4 Self-Hosted WordPress or WordPress.com

If WordPress is self-hosted, include only wp.module.js on line 6 and remove lines 19 to 22.
If you WordPress is at WordPress.com, use wpcom.module.js instead, and remove lines 16 to 18.

3.5 Update Page Title

Change the App Title to your own on line 11. Or if you wish to use an image instead, specify the image URL on line 10.

 
 

3.6 Add Categories, Pages, Most Recent Posts, and Bookmarks

Each item in the modules array (line 15) represents a module for the App to load.  
{name: wordpressModule, options: {apiUrl: ‘http://ideanotion.net’, title: “Pages”, categoryId: wordpersssModule.PAGES, pagesIds: [2, 546, 565]}}
The following sets up the categories and pages to display from your wordpress site.

3.6.1 Add Categories

Assign an array of category IDs to categoryId. For example: categoryIds: [3, 5, 19]

3.6.2 Add Pages

Assign wordpressModule.PAGES to categoryId and assign an array of page IDs to pageIds. For example: categoryId: wordpressModule.PAGES, pageIds: [2, 243, 33]

To find your pageIDs goto WordPress admin, when you edit your page the post ID is shown on the URL.

  

3.6.3 Add Recent Posts

Assign wordpressModule.MOSTRECENT to categoryId.

3.6.4 Add Bookmarks

Assign wordpressModule.BOOKMARKS to categoryId.
NOTE: For WordPress.com hosted sites, use slug instead of ID.

3.6.5 Compile

Compile your solution and run again to have your own Windows Store App!

 

 

4 Solution Breakdowns

This section will provide a brief breakdown of the Visual Studio solution for MetroPress v2. Whether you download the release version or directly sync from source on CodePlex, you will find a trunk folder that contains a MetroPress.sln file and a MetroPress folder. If desired, you may rename the solution file from MetroPress.sln to your own project name.

  


You need Visual Studio 2012 to open the solution. Upon opening it, you will see the following files and folder:

              

4.1 css folder

The css folder contains a default.css and a theme folder. default.css consists of the styles applied throughout the App that makes it look and behave consistently.
 
Each CSS file in the themes folder defines a theme. A theme CSS file can either be imported in the default.css or be included in default.html at the root of the solution. More detail is provided in section 5.

4.2 images folder

The images folder stores the required images of the App, as well as any other custom images you might have.

4.3 js folder

The js folder contains the core JavaScript files for the App. The main file that needs to be edited is options.js which is used for configuring the App.

  • default.js – starting point of the App 
  • hub.js – loads up hub.html and sets things up by calling functions defined in metropress.js (Section 4.2)  
  • liveTileTask.js – handles the support of live tiles 
  • metroPress.js – contains core logics of the application 
  • navigator.js – controls the navigational behaviors of the App 
  • options.js – configures the application and the modules (Section 4.3) 
  • share-source.js – handles the Sharing functionality  

4.4 modules folder

Modularization, introduced in v2, greatly enhances the extendibility of MetroPress. By convention, each folder in the modules folder represents a different module, each with its own CSS, JavaScript files, and HTML files. The modules to be used are specified in options.js.

4.5 pages folder

The pages folder contains hub.html and about-flyout.html.

4.5.1 Hub.html

The Hub page (hub.html and hub.js) handles all the modules included in the Hub (The main page).

  • Each included module is initialized when the application is first loaded.
  • Render() function is called whenever there is a change in layout or viewing mode (back and forward on page)
  • Update() function is called when there is navigational changes (back and forward of pages)
  • Refresh() function is called when the Refresh button is clicked
If you wish to extend or implement a new module, please refer to Section 4.1 Modules for details on implementation of a module that conforms to the Hub page’s requirement.

4.5.2 about-flyout.html

The file about-flyout.html is defined for the About page specified in the Settings Charm (Section 4.8).


 
 

4.6 default.html

This is the default container page for the MetroPress App.


 

5 Components

This section will provide details on the main feature components that constitute MetroPress.

5.1 Modules

Modularization emphasizes separating the functionality of a program into independent, interchangeable modules, such that each contains everything necessary to execute only one aspect of the desired functionality. MetroPress modules are designed and developed following this paradigm. It represents a separation of concerns, and improves maintainability by enforcing logical boundaries between components.
 
Each module consists of its own HTML, CSS, and JavaScript files. A module serves two main purposes:

  1. Specifying the data source 
  2. Determining how initialization happens, what and when content will be rendered, updated, refreshed, or called. Specifically, a module maintains its own data access, caching, and rendering of content.
Modules are selected in options.js. The main application (Hub page, Section 4.2) interacts with each module by a set of basic functions such as Render(), Update(), Refresh(), Cancel(), and other functions that handle Search and Live Tiles. To perform functions, each module needs to be instantiated with a specific task. The application can include multiple instances of modules, each managing or manipulating module data in a different ways. For example, showing recent posts vs. showing pages of the website or producing YouTube playlist vs. pulling the latest videos.  
To implement a module that the Hub page consumes, one constructor and six methods must be implemented.

Method Name constructor(metroPress, options)
Input Params metroPress – metroPress object
options – JSON object options
Output None
Description Setup the module with the passed in options

 
Method Name render(elem)
Input Params elem – the HTML element from Hub Page to render module content
Output Promise Object
Description Create a promise object and render the HTML fragment or dynamically create HTML elements and append to “elem”.  This is call every time user navigates to the hub page

 
Method Name update(viewState)
Input Params viewState – Application View State
Output N/A
Description Update the content (Grid/ListView) by fetching from data source or cached.  This is call onload or when viewState changes

 
Method Name refresh(viewState)
Input Params viewState – Application View State
Output N/A
Description This is called when User click on the refresh command.  Clear the cached data, and update the content (Grid/ListView) by fetching from data source

 
Method Name cancel()
Input Params None
Output None
Description To cancel any WinJS.xhr fetching operation.  This is called from application when navigate away from current page, or refreshed.   

 
Method Name searchInit()
Input Params None
Output None
Description This is when to hook up the search charm.  For example:
Windows.ApplicationModel.Search.SearchPane.getForCurrentView().onquerysubmitted = function(args) { … } 
 
This is called when application is ready.

 
Method Name getLiveTileList()
Input Params None
Output None
Description This is called from a background task in (Worker scope).  Fetch and return a list of data in this format:
{
imgUrl: “”
title : “”
}

 
MetroPress v2 currently includes two types of modules that can be instantiated: one that supports WordPress.com hosted websites and the other for self-hosted WordPress websites.

5.1.1 Modules – WordPressComModule

The WordpressComModule works with any WordPress.com website.  An instance of this module can display the following: Most Recent Posts, Pages, Posts by a category, or bookmarked posts. The module can be initialized to handle Search and Live Tile as well.
 
In options.js, instance of module can be configured by these parameters:

Options Parameter Description
title Title to display in the Hub Page on top of its GridView
If categoryId is set to wordpresscomModule.PAGES, title will not be displayed.
siteDomain User’s WordPress.com site domain URL.  Do not include “http://” prefix.  
i.e. (metropress.wordpress.com)
categoryId Defines the category this module will fetch from user’s WordPress.Com website.  Use category slur in string (i.e. “Tech”)
 
Or, use of the predefined values:
wordpresscomModule.PAGES:  pages
wordpresscomModule.BOOKMARK: bookmarked pages or posts
wordpresscomModule.MOSTRECENT: most recent posts
pageIds Array of page ID to fetch from user’s WordPress.com website.  This is only applicable if categoryId = wordpresscomModule.PAGES.
 
i.e. ([1,2,8])
clientId In order to allow user to post comment to user’s WordPress.com website, a WordPress Application Client ID/Secret must be generated and provided here.
 
See this link on how to create Client ID/Secret: https://developer.wordpress.com/apps/new/
clientSecret See above.

 

5.1.2 Module – WordPressModule (Self-hosted)

The WordpressModule works with any self-hosted WordPress website. The WordPress website must have already install the JSON API plugin in order for MetroPress to interact with. An instance of this module can display the following:  Most Recent Posts, Pages, Posts by a category, or bookmarked posts. The module can be initialized to handle Search and Live Tile as well.

In options.js, instance of module can be configured by these parameters:

Options Parameter Description
title Title to display in the Hub Page on top of its GridView
If categoryId is set to wordpressModule.PAGES, title will not be displayed.
apiURL User’s self-hosted WordPress website URL.  Please use full url in this format “http://www.ideanotion.com/”
categoryId Defines the category ID this module will fetch from user’s website.  Use category id in integer type format (i.e. 6)

Or, use of the predefined values:
wordpressModule.PAGES:  pages
wordpressModule.BOOKMARK: bookmarked pages or posts
wordpressModule.MOSTRECENT: most recent posts
pageIds Array of page ID to fetch from user’s WordPress.com website.  This is only applicable if categoryId = wordpresscomModule.PAGES.

i.e. ([1,2,8])


5.2 Hub Page

The Hub Page (~/pages/hub.html) is the landing page when the application launches. hub.js will initialize each module, and trigger the module to render and update its content on the Hub Content Area.

5.3 Options.js

The application and modules are setup in options.js. It imports the module JavaScripts and sets all the options. It is essential to understand options.js in order to correctly setup MetroPress.

Options Parameter Description
appTitleImage Title Image Url ;  If specified, it will ignore the appTitle parameter
appTitle Title text
cacheTime # of Minutes to keep the cached data
mainUrl Main Url to share when user click the Share Charm in the hub page
privacyUrl Url for the privacy page, launch from Settings Charm
modules See module options section below
searchModule See module options section below
liveTileModule See module options section below


5.4 Images

The following are the default set of images for the App.

File name Dimension Purpose
background.png Varies Background image of the app.  A good resolution will be 1920 by 1080.  If you want to enable the scrolling background effect, use a double wide background such as 3840 x 1080 or higher
badgelogo.png 24x24px Badge icon on Win8 start screen
blank.png Varies Default background when no featured image
logo.png 150x150px The default app logo
smalllogo.png 30x30px Smaller dimension of the default app logo
splashscreen.png 620x300px Image for the splash screen
storelogo.png 50x50px Logo displayed in Windows Store
widelogo.png 310x150px Large icon on Win8 start screen


5.5 Search Charm

Both modules can be configured in options.js to handle Search Charm.  When user enters a query into the search charm, the application navigates to the module’s search page displaying the results.

5.6 Share Charm

Share Charm is handled by MetroPress. The default behavior is to share the mainUrl defined in options.js. This is useful in hub page or other pages that doesn’t have content to share. However, a module can override that behavior if the page has a special Div element:

<div class=”mp-sharetitle=”this is the title” permalink=”http://blah.com”>
   This is the description…
</div>

The Share Charm will use the title, permalink and div inner Html as description. The class mp-share will by default keep the element hidden.


5.7 Live Tiles

Live Tiles is improved in version 2 by using background task to update the tile. Both modules can be configured in options.js to handle Live Tiles. Live tiles will show the latest 5 posts. This is the general flow:


5.8 Settings Charm

Two menu items were added to the Settings Charm.  

  • About Us flyout defined in /html/About-flyout.html
  • Privacy Policy will launch Internet Explorer to display the privacy URL defined in options.j


5.8 Bookmarking

User can bookmark any post or page to view it at a later time.  Bookmarked items will only be shown at the Hub page if one instance of the module is configured as Bookmark type.

Figure 2- Bookmark Icon and Bookmarked Posts
   

5.9 LocalStorage Caching

MetroPress and modules utilize LocalStorage to cache data to improve performance, and allow off line access. The modules stored fetched posts, and pages into localStorage along with a timestamp.  When loading from localStorage, the timestamp is used to check if it exceeded the CacheTime set by the options.js.

During development, one may need to flush the cache, and the quickest way is to increment the localStorageSchemaVersion.  This will clear the EVERYTHING from the localStorage when the application launches.

var metroPress = {
   // Change Storage Version to empty the local storage
   localStorageSchemaVersion: '20130101-1',
   modules: [],
   initialized: false,
   accessToken: null,



 6 Theme Customization

The CCS styling rules govern the look and feel of MetroPress. It is important that the theme system is easy-to-customize and flexible. The CSS files are organized into four separate groups.  

Type Path Description Extendable
Application /css/default.css Default elements such as typography, Size, common controls, and other non-theme-able elements. No
Theme /css/themes/custom.*.css Theme elements such as font, colors, background colors, background images Yes
Module /modules/css/*.css Module specific styling No
Template /modules/css/templates/*.css Defines the main Grid View layout template   Yes


6.1 Application-Specific CSS: Default.css

Default.css defines the positioning, layout of the application, common controls, and HTML elements.  Default.css have rules specific to different application View State (i.e. snapped). Default.css is less likely to be modified, it is recommended that styles are changed in Theme CSS.

6.2 Theme CSS: Custom.*.css

The theme CSS defines the colors, font, and background of a MetroPress App. It also defines CSS classes and common HTML elements such as <h1> to <h6>, <a>, <body>, etc.  

Few default themes were provided: custom.light.css, custom.dark.css, and custom.orange.css. They are a good starting place to extend and customize your own MetroPress application.

To choose one of the default themes, open default.css and find the import statement at the beginning of the file.  Then change the file name to apply a different theme:

@import  url('themes/custom.light.css');

This is a breakdown of CSS classes that custom.*.css must define:

CSS Class Name Description
.mp-color-header Default font color for header and <h1> to <h6>
.mp-color-text Default font color for text and body text
.mp-color-title Default font color for title used by modules
.mp-color-subtitle Default font color for sub-title used by modules
.mp-color-link Default font color for links <a>
.mp-bg-main Default background color for the main application
.mp-bg-overlay Default background color for the Grid text overlay
.win-backbutton Back button color


Theme Custom.*.css Colors Diagram









6.3 Module Specific CSS

These CSS defines the overall module styling and such as positioning of various controls and elements.  They are located at folder ~/modules/{module name}/css

6.4 Module Template CSS

MetroPress uses ListView (GridView) to group and display WordPress posts and pages into tiles. GridView is highly customizable through CSS, and can easily achieve different looks by changing CSS rules. The CSS rules that control the layout of the GridView were extracted into Template CSS. They are located in folder ~/modules/{module name}/css/templates

Three default templates were provided: normal.css, large.css, and wide.css. To choose a template, open modules/<module name>/css/<module name>.module.css. Then locate the import statement at the beginning of the file.  Change the file path name to apply a different template:

@import url('templates/normal.css');

                                                           Large.css                                                                                  wide.css

normal.css


6.5 Grid View HTML and CSS Class Diagram

A WordPress post or page tile is composed using 3 piece of information: image, title and subtitle. Below we will show a walk-through on how a “normal” template tile is being styled and layout.  
The Html template is defined below:

<div class="wp-item wp-item-0" > 

<div class="wp-image-container">   

              <div class="wp-image"></div> 
      </div> 
       <div class="wp-text-section mp-bg-overlay">             
                <h3 class="mp-color-title win-type-ellipsis">…</h3> 
                <h5 class="mp-color-subtitle win-type-ellipsis">…</h5> 
       </div> 
</div>

The normal.css control the layout of the tile using -ms-grid and related CSS rules.  

  1. Formats the tile into a square 220x220px, and 2 rows – one for image, one for the text section.
.wp-list .wp-item {
   overflow: hidden;  
   display: -ms-grid;
   -ms-grid-columns: 1fr;
   -ms-grid-rows: 160px 60px;
   width: 220px;
   height: 220px;
}
  1. Fit the image container into the first row, and assign 160px height to the image
.wp-list .wp-item .wp-image-container {
   overflow: hidden;
   position: relative;
   -ms-grid-row: 1;
   -ms-grid-row-span: 1;
}

.wp-list .wp-item .wp-image-container .wp-image{
   height:160px;
   width:220px;
   background-position: center;
   background-size:cover;
}
  1. Fit the text section into row 2
.wp-list .wp-item .wp-text-section {
   padding: 4px 12px 8px;
   -ms-grid-row: 2;
   z-index: 1;
   width: calc(100% - 24px);
   height: 100%;    
Here is a schematic look of the HTML and CSS classes:

 

Quick Start Guide v1.0

 

F.A.Q.

 

 

 

 

 

 

 

 

Last edited Mar 4, 2013 at 5:52 PM by michaelsiu, version 90

Comments

No comments yet.