3 Building Your First IdeaPress App Using Your WordPress Website

3.1 Download 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.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:

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:

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.

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.2 Add Pages

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

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.

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:

Specifying the data source

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 objectoptions – 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 GridViewIf 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: categorywordpresscomModule.PAGES: pageswordpresscomModule.BOOKMARK: bookmarked pages or postswordpresscomModule.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.

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 GridViewIf typeId is set to wordpressModule.PAGES, title will not be displayed.

Defines the type of this module. It can be one of the following values: wordpressModule.CATEGORY: categorywordpressModule.PAGES: pageswordpressModule.BOOKMARK: bookmarked pages or postswordpressModule.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:

<divclass="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.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.

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:

@importurl('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:

@importurl('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: