Category Archives: Office 365

Building a Cloud Business App: Kudos

Office 365 is an ideal business app platform providing a core set of services expected in today’s business apps and a central location for installing, discovering, and managing apps. Office 365 makes these business apps available where users already spend their time – in SharePoint and Office.

Visual Studio 2013 streamlines modern business app development for Office 365 and SharePoint 2013 with the Cloud Business App project. This walkthrough will show how you can build social, touch-centric, cross-platform Office 365 business applications that run well on modern devices.

What we’re going to build

In our scenario, let’s say my organization is on Office 365. The company encourages cross-team collaboration and would like to build an app that allows employees to send kudos to fellow employees.

An employee can find the app on SharePoint. He or she can launch the app on desktop browsers or different mobile devices. The app allows a user to send kudos to a coworker and shows a list of kudos users sent and received.

Figure 1. The kudos app we will be building in this walkthrough
Figure 1. The kudos app we will be building in this walkthrough

Let’s build this app with Cloud Business App!

Create a Cloud Business App project

Let’s create a Cloud Business App project. We are creating an app for Office 365, so you can find the Cloud Business App template under Office/SharePoint for both VB and C#. This categorization is based on the language used in the middle tier; the client is HTML and JavaScript.

Let’s name the project KudosApp and choose OK.

Figure 2. Create a new Cloud Business App project in Visual Studio     Figure 2. Create a new Cloud Business App project in Visual Studio

You first need an Office 365 developer site to start building apps for Office/SharePoint. If you don’t have an account for development, you can sign up for free 30-day trial at dev.office.com. If you are a MSDN subscriber, you will receive the subscription as a benefit.

Enter your SharePoint development site here and choose OK.

Figure 3. Enter your Office 365 developer site     Figure 3. Enter your Office 365 developer site

Once created, you will find a Cloud Business App is comprised of four projects in the solution:

  1. Server project, which is a basic ASP.NET project used to add tables and connect to data sources
  2. Standard SharePoint project, which provides a connection to Office 365
  3. HTML client project, a JavaScript project in which you define the UI for your app
  4. A Cloud Business App project, which ties all the other projects together
Figure 4. Solution Explorer     Figure 4. Solution Explorer

Define data

Let’s start by defining the data model for our app. In Cloud Business App, you can create new tables or attach to external data sources such as SQL, Odata, and SharePoint assets. In our scenario, we send and receive kudos, so let’s create a table for kudos. Choose Create new table.

Figure 5. Add a new table in the Table Design     Figure 5. Add a new table in the Table Designer

Name the table Kudos and add two fields:

  • KudosTo (Person)
  • Message (String)

The Table Designer provides a set of business types, such as PhoneNumber, Email, and Person. They include specific validation logic and visualizations both in the tooling and runtime.

Figure 6. Add some fields in the Table Designer     Figure 6. Add some fields in the Table Designer

There is a growing trend in integrating social features into modern business applications. Cloud Business App makes it easy by integrating with the SharePoint Newsfeed feature.

With the title of the Kudos table selected, you can enable social under the Social category in Properties window. Select Post when Created. When a kudos is created, the app will post the activity to Newsfeed.

Figure 7. Enable Social feature in your a     Figure 7. Enable Social feature in your app

Create queries

In our app, we want to show kudos sent by me, as well as the kudos I received. We can create two queries for these. Choose Add Query button in the tool bar of the Table Designer.

Figure 8. Choose "Query" button to add a custom query for this table     Figure 8. Choose “Query” button to add a custom query for this table

In Query Designer, name the query KudosSent. We want the query to return all kudos created by me, so let’s filter it by setting CreatedBy equals to Current User. Let’s also sort it by the Created field.

Figure 9. Customize the query with the Query Designer     Figure 9. Customize the query with the Query Designer

We will create another query via the context menu of the Kudos table in Solution Explorer.

Figure 10. Add another query via the context menu     Figure 10. Add another query via the context menu

This time, we will name the query KudosReceived and filter by setting KudosTo equals Current User.

Figure 11. Customize another query     Figure 11. Customize another query

Create a browse screen

Now that we’ve defined the data model, let’s design the UI for the app. Create a screen via the context menu on Screens node in Solution Explorer.

Figure 12. Add a screen via the context menu     Figure 12. Add a screen via the context menu

The Add New Screen dialog box will appear. Cloud Business App provides three screen templates that represent common UI patterns for browsing, viewing, adding, and editing data. Let’s start with a browse screen that shows all kudos sent by me.

Select Browse Data Screen, name the screen WelcomeToKudos and select KudosSent query as the screen data. Choose OK.

Figure 13. Create a screen by choosing a screen template     Figure 13. Create a screen by choosing a screen template

A screen is created for you. In the Screen Designer, you see a Screen Content Tree in the middle that represents the visual elements in the UI. Visual elements are bound to a data on the Data Members List on the left.

For example, in this screen, we have list visual showing values from the KudosSent data set.

Figure 14. Your UI elements are laid out in the Screen Designer     Figure 14. Your UI elements are laid out in the Screen Designer

We can also choose to render the data set as a Table or a Tile List visual. Let’s use Tile List.

Figure 15. Change the visual control     Figure 15. Change the visual control

The node under the Tile List indicates what fields will show up in a tile.

Figure 16. We will display kudos as a tile list     Figure 16. We will display kudos as a tile list

Since this is a list of kudos sent by me, let’s delete the Created By field. We will also delete the ModifiedBy and Modified fields.

Figure 17. Customize the tile list     Figure 17. Customize the tile list

You may have noticed that Cloud Business App automatically created audit fields for you (Created, CreatedBy, Modified, and ModifiedBy). It is a common requirement in business apps, so the tool handles it for you (you can turn it off in the Table Designer).

In the tile, the Kudos To field is rendered with a Person Viewer control. We can customize what will show up in the Person Viewer via the Properties window. Change the Display Mode to Name with picture and title.

Figure 18. Customize the look-and-feel of a visual control     Figure 18. Customize the look-and-feel of a visual control

Let’s also change the font and alignment of the Created field. Select Created. In Properties window, change Font Style to Small and Text Alignment to Right.

Figure 19. Customize the font and alignment of a visual control     Figure 19. Customize the font and alignment of a visual control

Create an add screen

We have a list of kudos sent by me. Let’s create some UI to add kudos. In WelcomeToKudos screen, add a button in the Command Bar.

Figure 20. Add a button to the screen     Figure 20. Add a button to the screen

The Add Button dialog box will appear.

Figure 21. Add Button dialog box     Figure 21. Add Button dialog box

You can write your own method for this button using JavaScript code or, in our case, we can select from a set of commonly used features. In the Choose an existing method dropdown menu, select KudosSent.addAndEditNew.

We are saying that, when the button is chosen, we will add a new record to the KudosSent data set via a new screen we are about to create. Choose OK.

Figure 22. Choose an existing method     Figure 22. Choose an existing method

The tool will guide us to create a new screen for adding a kudos. Name the screen SendKudos and choose OK.

Figure 23. Create a screen to add a kudo     Figure 23. Create a screen to add a kudo

A new screen (SendKudos) is now created.

Figure 24. New screen created in the Screen Designer     Figure 24. New screen created in the Screen Designer

Let’s check what we’ve got so far! Press F5 to run the app.

Figure 25. Run the application     Figure 25. Run the application

We have an empty list and an add button on the screen. Let’s add a kudos. Choose Add Kudos. The Send Kudos screen (rendered as a dialog box) will appear.

Figure 26. UI to add a kudo     Figure 26. UI to add a kudo

Note that all layouts adapt well to different form factors. Resizing the browser window gives you an idea of how the app looks on a phone or tablet. Everything is optimized for touch, but works equally well on a desktop browser using keyboard and mouse.

Figure 27. App in a small form factor     Figure 27. App in a small form factor

Customize the UI while running in the browser

In the Send Kudos dialog box, Message is rendered as a text box. We want to change it to a text area. Also, since we only have two fields in the screen, we don’t need to show two columns in bigger form factors. For these types of UI tweaks on the screen, I can quickly make these changes without closing the browser and press F5 again.

Go back to the designer (without closing the browser) and change the Message fields to use Text Area control.

Figure 28. Customize the UI in Visual Studio while the app is running     Figure 28. Customize the UI in Visual Studio while the app is running

Let’s also change the KudosTo display mode to show picture and title.

Figure 29. Customize the visual control     Figure 29. Customize the visual control

Now, let’s remove the columns. Drag Kudos To and Message out of the columns layout, then delete columns layout.

Figure 30. Customize the UI layout     Figure 30. Customize the UI layout

Choose Save All in the designer and refresh the browser. Choose Add Kudos again. All the UI changes are now reflected in the app. This provides an efficient iterative design experience.

Let’s add a Kudos. The Kudos To value can be selected using an auto-complete text box based on Active Directory.

Figure 31. Choose a person from the auto complete text box     Figure 31. Choose a person from the auto complete text box

Choose Save and the newly added kudos will appear in the list.

Figure 32. A kudo is created in the app     Figure 32. A kudo is created in the app

Notice, you can see additional Office 365 integration here. When you hover your mouse over the person, it shows presence information. You can send an IM, e-mail, or schedule a meeting right here.

Figure 33. Presence information inside of the tile     Figure 33. Presence information inside of the tile

Create a screen tab

Now we have a list of kudos sent by me. Let’s also add a list of kudos I received. We can show the two lists on the same screen using two different screen tabs.

Close the browser and return to Visual Studio. Open the WelcomeToKudos screen. Notice our tile list is currently under a screen tab called Kudos List. By default, every screen has one screen tab. The tab UI will not show in the app unless you have more than one screen tab.

Figure 34. By default, there is one screen tab in the screen     Figure 34. By default, there is one screen tab in the screen

Let’s add another screen tab. Choose the Tabs node and select Add Tab.

Figure 35. Add a new screen tab     Figure 35. Add a new screen tab

A new screen tab is now added.

Figure 36. New screen tab is created     Figure 36. New screen tab is created

In Properties window, change the Display Name of first screen tab to Kudos Sent and the second screen tab to Kudos Received.

Figure 37. Change the display name of the screen tabs     Figure 37. Change the display name of the screen tabs

Add new data to the screen

Now, we need to add the list of kudos I received under the newly created screen tab. Recall we created a KudosReceived query earlier. Let’s include that query on the screen. Choose Add Data Item button in the toolbar.

Figure 38. Add a data member to the screen     Figure 38. Add a data member to the screen

In the Add Data Item dialog box, select KudosReceived and choose OK.

Figure 39. Select a data member to add to the screen     Figure 39. Select a data member to add to the screen

The query now appears in the Data Members List.

Figure 40. A new data member is added to the sc     Figure 40. A new data member is added to the screen

Drag the query under the second screen tab on the Screen Content Tree.

Figure 41. Create UI for the newly added data member     Figure 41. Create UI for the newly added data member

Like we did with the first list, let’s change the Kudos Received list to a Tile List. Customize the tile to show only Created By, Message, and Created.

Figure 42. Customize the tile list     Figure 42. Customize the tile list

Press F5 again to see the changes. Now, there are two screen tabs on the screen.

Figure 43. App displays 2 screen tabs     Figure 43. App displays 2 screen tabs

If you send a kudos to yourself, you will see it in the second screen tab.

Figure 44. Kudos Received tab shows all kudos created by the current user     Figure 44. Kudos Received tab shows all kudos created by the current user

Remember when we created the Kudos table, we enabled the social feature. Now, if we open the Newsfeed page, we will see some posts by the app.

Write business logic

So far, we have a completely functional app now without writing a single line of code!

Cloud Business App lets you focus your energy on the unique value of the app: the business logic. Let’s say we don’t want you to be able to send kudos to yourself and we want to write some validation logic for that.

Open the Kudos table. Business logic is written on the middle tier, which is represented by the server project in your solution. The Table Designer provides you with entry points into the data pipeline of your app.

Open the Write Code dropdown menu in the tool bar, you will find a list of code entry points for business logic. Choose KudosSet_Validate.

Figure 45. Entry points for writing business logic     Figure 45. Entry points for writing business logic

It will take you to the code entry point in the Code Editor.

Figure 46. Write validation logic     Figure 46. Write validation logic

Write the following code.

if (entity.KudosTo == Application.Current.User.Email)
{
  results.AddPropertyError("You cannot send kudos to yourself", 
  entity.Details.Properties.KudosTo);
}

Now, run the app and try to send a kudos to yourself. You will get the validation error.

Figure 47. Validation logic is invoked in the running app   Figure 47. Validation logic is invoked in the running app

Publish the app

Finally, when I’m ready to publish this app to my organization, I can choose the Cloud Business App project and select Publish. I can follow the Publish Wizard to step through different deployment options.

Figure 48. Publish your app   Figure 48. Publish your app

The app is in the app catalog and can be installed on one or more sites for people to use.

Figure 49. The app is published to the app catalog   Figure 49. The app is published to the app catalog

Conclusion

To summarize, you saw a highly productive experience for defining data and screens that enable you to quickly get an app up and running. The app has a professional looking UI that blends with SharePoint and is integrated with a set of Office 365 services. This allows you to focus on your business logic and get more done.

To learn more about Cloud Business Apps, visit Apps for Office and SharePoint Dev Center and Cloud Business Apps on MSDN.

Advertisements

Script insertion via a Page Viewer Web Part

What is a Page Viewer Web Part?

A PVWP allows you to embed in your page another Web Page. Technically, a PVWP doesn’t do much, it is just a wrapper for a html iframe element.

iframes have a bad reputation. One of the main reason is that people often confuse them with frames. An excerpt from the MDN page:

Using the <frame> element is not encouraged because of certain disadvantages such as performance problems and lack of accessibility for users with screen readers. Instead of the <frame> element, <iframe> may be preferred.

As a matter of fact, iframes are enjoying a surge in popularity in modern Web design. They serve as building blocks in modular pages (several SharePoint Web Parts rely on iframes), and are a key component of application pages (for example on Twitter, Facebook or with Disqus). I would expect them to become even more popular once the new iframe html5 attributes become widely available.

Note: besides linking to Web pages, the PVWP also has options to display folders or file content.

How is this similar to the CEWP?

As explained in my old post, a CEWP allows you to embed, via its content link property, Web content (html, stylesheets or scripts) in your page. A PVWP acts in a similar way, except that the linked file is a whole Web page, instead of a fragment stored in a text file.

But this means two different pages?

Right. With a CEWP, the code fragment becomes part of the host page. With a PVWP, the code remains in its own page. That said, it doesn’t mean that the two pages cannot communicate, within the boundaries allowed by the same origin policy. In particular, an iframe can access and modify its host page. In the basic example shown below, the code in the iframe accesses the parent body to change its background color.

ParentDocument

Any real life example to share?

Sure! In the past few months, I published in this blog several demos from my SPELL library. SPELL is built to work in dual mode: either “inline” for direct insertion within a page (CEWP, Master Page, etc.), or “app” for inclusion in an iframe. For example, the process navigation showcased in this blog post is inserted via a PVWP. Same for its sibling featuring a button navigation. Other solutions like the SPELL Tabs or mini-BI work exactly the same way.

Why use a PVWP rather than a CEWP?

That’s a good question. While other environments have a good case for iframed scripts, we SharePoint users can already rely on the CEWP to link to html, css and JavaScript. Still, I see a couple benefits when using a PVWP.

1/ Sandbox

Because the iframe loads another page, this provides a clear separation between the host page and the iframe content. The sandboxed environment avoids code conflicts. This can be for example useful:

  • for charting apps, to make sure that the styles of the main page don’t interfere with the styles of the chart itself.
  • for scripting: if your app requires a specific jQuery version, you can run it within the iframe, without having to worry about the main page running a different version.

2/ Standalone

One constraint with Web Parts is that they have to live in a page. Picture a SharePoint dashboard: you view it as a whole, with no easy option to isolate a specific chart. With a PVWP, the chart can be viewed either embedded in the dashboard or directly in its underlying page. This scenario is showcased in this post: with read only permissions on my site, you cannot build a SharePoint dashboard page, but you can still interact with the individual chart page.

Even better, standalone pages work great with SharePoint dialogs. Iframing is actually the technique SharePoint relies on with forms: when you open a new, display or edit form in a dialog, you are simply opening newform.aspx, dispform.aspx or editform.aspx in an iframe! Do I have a dialog example with SPELL? Thanks for asking :-) You’ll find it here. Working with standalone pages allows to pile up dialogs and create the drill-down effect.

3/ Asynchronous load

Because the host page and the iframe are two different pages, the browser can load them in parallel, so this “should” result in better performance. With a CEWP, the content becomes part of the host page and execution will follow the page flow.

4/ Links across site collections

The CEWP allows you to link to an external file, but only within a same site collection. An iframe doesn’t have such restrictions, so a single application page stored in SharePoint can be reused across site collections.

5/ Storage of parameters

This is a technique I use with the SPELL library – not really standard but let me explain it anyway.

Because the script running in the iframe can access its own url, this url becomes a place where you can store parameters. For example the URL for the SPELL Tabs will look like this:

Tabs.aspx#css.activeBackground=orange;css.inactiveBackground=blue;css.hoverBackground=lightblue

For cascading dropdowns, the url would be for example:

CascadingSelect.aspx#form.parentLabel=State;form.childLabel=City;source.listName=Locations;source.parentField.DisplayName=State

You might find the above urls intimidating, but if you look at SharePoint urls they actually work in a similar fashion. The point is: if you used a CEWP, you’d need to store one snippet of code for each cascading dropdown you implement. With the above method, one single page called CascadingSelect.aspx can be reused across all site collections!

Note:  In practice the SPELL library includes editors, the above paths are not built manually.

Of course, iframes also have some drawbacks. The asynchronous load complicates the relationship between the iframed content and the parent’s content. The sandbox means that if the same code is needed in both the host page and the iframe, locally you have to load it twice (or find a trick…). Both the CEWP and the PVWP have their place in SharePoint design!