Skip to content
This repository

IdeaPress transforms any WordPress website to a Windows Store App.

README.md

Documentation


1 Overview

IdeaPress 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

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


2 Features

IdeaPress 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 IdeaPress App Using Your WordPress Website

3.1 Download IdeaPress

Download IdeaPress from GitHub: https://github.com/ideanotion/ideapress

3.2 Compile The VS Solution

Unzip the downloaded file, compile, and run the IdeaPress solution in Visual Studio 2013 on your Windows 8.1 system. As you compile, it will bring up the IdeaPress 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

The default options included both Self-hosted WordPress and WordPress.com modules. If WordPress is self-hosted, please include only wp.module.js and remove anything associated to ** wordpresscomModule**. Otherwise if you WordPress is at WordPress.com, use wpcom.module.js and remove anything associated to wordpressModule.
Self-hosted website is the website where you manage your hosting.
In this case, your options.js will look like this:

modules: [
{ name: wordpressModule, options: { apiUrl: 'http://{youdomain.com}/', title: "Pages", typeId: wordpressModule.PAGES, pageIds: [{PageIDs}] } },
{ name: wordpressModule, options: { apiUrl: 'http://{youdomain.com}/', title: "Recent News", typeId: wordpressModule.MOSTRECENT } },
{ name: wordpressModule, options: { apiUrl: 'http://{youdomain.com}/', title: "Bookmark", typeId: wordpressModule.BOOKMARKS } },

{ name: wordpressModule, options: { apiUrl: 'http://{youdomain.com}/', title: {CategoryName}, typeId: wordpressModule.CATEGORY,categoryId: {CategoryID} } },
],
searchModule: { name: wordpressModule, options: { apiUrl: 'http://{youdomain.com}/', title: "Search" } },
liveTileModule: { name: wordpressModule, options: { apiUrl: 'http://{youdomain.com}/', title: "Live Tile", squareTileType: Windows.UI.Notifications.TileTemplateType.tileSquarePeekImageAndText04, wideTileType: Windows.UI.Notifications.TileTemplateType.tileWideImageAndText01 } },

Wordpress.com site is the blog that is hosted on Wordpress.com which usually looks liek this: http://{mydomain}.wordpress.com. Or if it is a VIP wordpress site, you wil have your own domain, but you are still required to enter the original wordpress.com address for IdeaPress setup.
In this case, your options.js will look like this:

modules: [
{ name: wordpresscomModule, options: { apiUrl: 'http://{youdomain}.wordpress.com/', title: "Pages", typeId: wordpresscomModule.PAGES, pageIds: [{PageIDs}], clientId: {clientId}, clientSecret: {clientSecret} } },
{ name: wordpresscomModule, options: { apiUrl: 'http://{youdomain}.wordpress.com/', title: "Recent News", typeId: wordpresscomModule.MOSTRECENT, clientId: {clientId}, clientSecret: {clientSecret} } },
{ name: wordpresscomModule, options: { apiUrl: 'http://{youdomain}.wordpress.com/', title: "Bookmark", typeId: wordpresscomModule.BOOKMARK, clientId: {clientId}, clientSecret: {clientSecret}S } },

{ name: wordpresscomModule, options: { apiUrl: 'http://{youdomain}.wordpress.com/', title: {CategoryName}, typeId: wordpresscomModule.CATEGORY,categoryId: {Slug}, clientId: {clientId}, clientSecret: {clientSecret} } },
],
searchModule: { name: wordpresscomModule, options: { apiUrl: 'http://{youdomain}.wordpress.com/', title: "Search" } },
liveTileModule: { name: wordpresscomModule, options: { apiUrl: 'http://{youdomain}.wordpress.com/', title: "Live Tile", squareTileType: Windows.UI.Notifications.TileTemplateType.tileSquarePeekImageAndText04, wideTileType: Windows.UI.Notifications.TileTemplateType.tileWideImageAndText01 } },

3.5 Update Page Title

Use your own App Title by specifying the value in appTitle. Or if you wish to use an image instead, specify the image URL using appTitleImage.

image alt

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”, typeId: wordpersssModule.PAGES, pagesIds: [2, 546, 565]}} The following sets up the categories and pages to display from your wordpress site.

3.6.1 Add a Category

Assign wordpressModule.CATEGORY to typeId, choose a title, and assign the category Id to categoryId. For example: typeId: wordpressModule.CATEGORY, categoryId: 45, title: "Tech"

NOTE For Self-Hosted WordPress, you can find your categoryId by going to the WordPress admin. When you edit your category, the tag ID is shown on the URL. 95image alt

NOTE: For WordPress.com hosted sites, use slug instead of Category ID.

3.6.2 Add Pages

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

To find your pageIDs, please goto WordPress admin. When you edit your page, the post ID is shown on the URL. 95image alt

3.6.3 Add Recent Posts

Assign wordpressModule.MOSTRECENT to typeId.

3.6.4 Add Bookmarks

Assign wordpressModule.BOOKMARKS to typeId.

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 IdeaPress v2. Whether you download the release version or clone from github, you will find a IdeaPress.sln file and a IdeaPress folder. If desired, you may rename the solution file from IdeaPress.sln to your own project name.

You need Visual Studio 2013 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 core.js (Section 4.5.1)
  • liveTileTask.js – handles the support of live tiles
  • core.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 IdeaPress. 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 IdeaPress App.


5 Components

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

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. IdeaPress 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.5.1) 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(ideaPress, options)
Input Params ideaPress – ideaPress object
options – JSON object options
Output None
Desctiption 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
Desctiption 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
Desctiption 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
Desctiption 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
Desctiption 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
Desctiption This is called from a background task in (Worker scope). Fetch and return a list of data in this format:
{
imgUrl: “”
title : “”
}

IdeaPress 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 typeId 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. (ideapress.wordpress.com)
typeId Defines the type of this module. It can be one of the following values:
wordpresscomModule.CATEGORY: category
wordpresscomModule.PAGES: pages
wordpresscomModule.BOOKMARK: bookmarked pages or posts
wordpresscomModule.MOSTRECENT: most recent posts
categoryId Defines the category this module will fetch from user’s WordPress.Com website. Use category slur in string (i.e. “Tech”). This is only applicable if typeId = wordpresscomModule.CATEGORY.

i.e. "Tech"
pageIds Array of page ID to fetch from user’s WordPress.com website. This is only applicable if typeId = 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 IdeaPress 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 typeId 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/”
typeId Defines the type of this module. It can be one of the following values:
wordpressModule.CATEGORY: category
wordpressModule.PAGES: pages
wordpressModule.BOOKMARK: bookmarked pages or posts
wordpressModule.MOSTRECENT: most recent posts
categoryId Defines the category this module will fetch from user’s WordPress website. This is only applicable if typeId = wordpressModule.CATEGORY.

i.e. 6
pageIds Array of page ID to fetch from user’s WordPress website. This is only applicable if typeId = wordpressModule.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 IdeaPress.

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 IdeaPress. 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-share" title="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.9 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.

5.10 LocalStorage Caching

IdeaPress 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 ideaPress = {
   // 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 IdeaPress. 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 IdeaPress App. It also defines CSS classes and common HTML elements such as <1> to <6>, <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 IdeaPress 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 <1> to <6>
.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
.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

IdeaPress 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//css/.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');

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.

  • 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;
}
  • 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;
}
  • 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:

License

GPL v3 with an ADDITIONAL TERM per GPL Section 7

Copyright (c) 2013 Idea Notion Development Inc.

Something went wrong with that request. Please try again.