Tag Archives: Webpart

People-Search Wire Frame Page3

SharePoint/SPFx: Returning to Webpart Development Part #2

Recently I was asked to develop a webpart for a modern SharePoint site. My first thoughts were; where do I start, I haven’t done any webpart development for years? I would like to share my journey with you over the next few posts and hope my experience will help new and returning developers along the way.

In my previous post I covered:

In this post I will cover:

Avoiding Pitfalls Part #1

Let’s start by addressing the pitfalls I listed in my last post:

1. Distracted by someone else’s code

This one is easy; we are going create a new / blank project. If we need to refer to someone elses code for inspiration, then we will do this outside of our project.

2. Getting bogged down in detail

The React website has a great article on this called Thinking in React which I recommend reading. So, let’s practice what we preach….

3. Avoid the muddying of data and presentation code/layers

Well the plan we made to avoid the previous pitfall will also help with this too. If we are still confused it is because we need to do some more planning… 😊

4. Check the SPFx Project Generator Version

The tooling used to scaffold SPFx project is out of date. This should not be a problem if you have just configured a new brand environment/machine. If, however like me you are coming back to an existing environment/machine then I would recommend uninstalling everything SPFx related:

npm uninstall @microsoft/generator-sharepoint --global
npm uninstall yo --global
npm uninstall gulp --global

And finally, Node.js using the “Add or remove programmes…” to check the version and uninstall if required.

Once done, you can re-install the tools with confidence…

Solution Design (Avoiding Pitfalls Part #2)

Let’s start by creating a wire-frame, which essentially is a design without branding or colours. There are many great tools on the market for creating wire-frames, such as Balsamiq, Lucidchart or Microsoft Visio. However for this example, I am going to use Microsoft PowerPoint to demonstrate how easy it is to create an effective wire-frame. Click here to open my People-Search-Wire-Frame.pdf file.

Wire-Frames

Start by adding the components to the diagram, while thinking about how the end-user would interact with your webpart.

People Search Wire Frame Page 1

On the next diagram I have labelled each control, giving a brief description of each control and / or its behaviour. If you are a solo developer you may decide to skip this detail, however, I find the validation process useful.

People Search Wire Frame Page 2

The last page/diagram breaks the webpart down into components. I have done this by functionality, repeatability and in some cases, where the data will come from.

People Search Wire Frame Page 3

Data Sources

Now that I have a design I can start thinking about where the data is going to come from. In the past I may have used SharePoint Search with the User Profile Service, however today I am going to use the Microsoft Graph API, as “The Graph” combines multiple Microsoft 365 services into a single endpoint.

Tip: The Graph Explorer is a great place to start working Microsoft Graph, it has a number of sample queries to run against dummy data or better still sign in to your Microsoft 365 Tenant and test queries against your own data (see my next tip).

Tip: Sign-up to the Microsoft Developer Programme and get a Microsoft 365 developer subscription to develop your solutions independent of your production environment.

The table below lists the components I expect to build, obviously this may change if I find other complexities once the build is under way, plus:

  • The Data Source gives a rough idea as to where to find the data.
  • The Expected Results gives a rough idea of shape of the data.
  • The Component Action describes what the component will do with the data.
Component NameData SourceExpected ResultsComponent Actions
Search Wrapper
Search BoxGraph UsersZero to more itemsFilter
Search ClearClear data & filters
Filter WrapperGraph UsersZero to more items
Filter Combo-boxGraph UsersZero to more itemsFilter
Filter Auto-suggestGraph UsersZero to more itemsFilter
Result WrapperGraph UsersZero to more items
Result CardGraph UserOne itemDisplay
Result User PhotoGraph User PhotoOne itemDisplay
Result User PresenceGraph User PresenceOne itemDisplay
Result User ContactGraph UserOne itemDisplay
Footer WrapperGraph UsersZero to more itemsDisplay
Components List

Choosing a Framework

Just because you are developing a SPFx webpart does not mean you have to build it in React, there are other options, such as “No JavaScript framework” (i.e. hand-rolled or do it yourself) or Angular.

Sorry to disappoint, however I am going to stick with React – React Hooks possibly with useReducer.

Creating a SPFx Project

To help you reproduce my solution I have listed the steps below.

Creating a VS Code Workspace

I am a fan of Workspaces they enable you to save and share preferences including UK/NZ spellings…

  1. Create your project directory, for example:
    C:\…\Company.SPFx.Webparts.People
  2. Open Visual Studio and navigate to: File -> Open folder…
  3. Next locate and open your new directory
  4. Once opened navigate to: File -> Save Workspace As…
  5. Navigate up a folder, enter “Company.SPFx.Webparts.People.code-workspace” and click save

Scaffold the SPFx Project

Now we are ready to open the Terminal window with VS Code and run the Yeoman SharePoint generator.

  1. Open Terminal: [Ctrl]+[`]
  2. Enter the following commands:
yo @microsoft/sharepoint
  1. Next enter: MS-Graph People Search – Press enter
  2. Select: SharePoint Online only (latest) – press enter
  3. Use the current folder – press enter
  4. Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment or adding apps in sites? – Y
  5. Will the components in the solution require permissions to access web APIs that are unique and not shared with other components in the tenant? N
  6. Select: WebPart – press enter
  7. What is your Web part name? People Search – press enter
  8. What is your Web part description? Search for people within your organisation using Microsoft Graph – press enter
  9. Select: React – press enter

Once the Yeoman command has completed, we can check the solution by running the following commands:

gulp clean
gulp build
npm shrinkwrap
gulp serve

Source Control

I am going to designate source control out of scope for this post, however what I would recommend committing your code (or backing it up) at this point, so that you have a place you can rollback to if it all goes wrong.

Next time

For my next post I will focus on building the structure of my webpart.

Troubleshooting SPFx Webparts: Useful Links

Based upon the App Catolog (Catalogue) being configured with the following URL:
https://<tenant>.sharepoint.com/sites/Apps/

Apps for SharePoint
A catalog to store apps for SharePoint
https://<tenant>.sharepoint.com/sites/Apps/AppCatalog/Forms/AllItems.aspx

Client Side Assets
A library to store client side assets
https://<tenent>.sharepoint.com/sites/Apps/ClientSideAssets/AllItems.aspx

Client Side Component Manifests
A list to store client component manifests
https://<tenent>.harepoint.com/sites/Apps/Lists/ComponentManifests/AllItems.aspx

Cheat Sheet: Fixing SharePoint Page Layouts containing Webpart with the same ID

I had problems upgrading a WSP containing one or more Page Layouts?
Unable to edit or update a Page Layout?

Related article: Editing SharePoint Webparts embedded within Page Layouts https://www.sjlewis.com/2015/10/15/editing-sharepoint-webparts-embedded-within-page-layouts/

  • Navigate to the site settings of the root website (within a site collection)
  • Click Master pages and page layouts and locate the Page Layouts
  • Make a note of the file name, for example: PageLayout.aspx
    Note: you will not be able to view or edit the page layout directly by clicking on the title or a menu item
  • Using one of the URL below, change the tenant and file name to create the required URL: https://tenant.sharepoint.com/_catalogs/masterpage/PageLayout.aspx?Contents=1
  • Once the Web Part Page Maintenance page has loaded, starting from the top select the duplicate webparts and then click Delete

You should now be able to complete the update or upgrade action you previously set out to do.

Cheat Sheet: Editing SharePoint Webparts embedded within Page Layouts

  • Navigate to the site settings of the root website (within a site collection)
  • Click Master pages and page layouts and locate the Page Layouts
  • Make a note of the file name, for example: PageLayout.aspx
    Note: you will not be able to view or edit the page layout directly by clicking on the title or a menu item
  • Using the example below, change the tenant and file name to create the required URL: https://tenant.sharepoint.com/_catalogs/masterpage/PageLayout.aspx?ControlMode=Edit&DisplayMode=Design
  • Enter your new URL into a browser to start editing the embedded webparts and content.

If however you see this error: “A Web Part with this ID has already been added to this page” then take a look at this post first: https://www.sjlewis.com/2015/11/18/fixing-sharepoint-page-layouts-containing-webpart-with-the-same-id/

Client-side Development Techniques with CQWP(s) and JavaScript…

The other day I was talking to one of my colleague John Holah about retrieving large amounts of data from a SharePoint 2010 Lists using “client-side” v “OOB” techniques for a particular client, who has set use a number of challenges/limitations:

  • Our access is limited to Site Collections
  • We cannot deploy server-side code
  • Internet Explorer 8 is used by all of client’s employees (120,000 Users globally)

Depending on what the end goal, previously we used these techniques to retrieve data:

  1. CQWP* and write custom XSL to render the content as HTML
  2. Call a SharePoint web service using a JavaScript library call SPServices and
  3. populate an array or an object before rending it as HTML

Option 1: is relatively quick to implement, however it has a number of limitations:

  1. The source of the content is limited to either a Content Type or a List
  2. In my opinion, it is not as easy to apply logic to XSL as it is to JavaScript
  3. IE8 times-out if a large number of rows are rendered to the UI (this can vary depending on the number of columns as well as rows and the complexity of the HTML)

Option 2: is has flexibility, however:

  1. A call to a web service is not as efficient as the CQWP in retrieving data.
  2. A significant number of lines of code needs to be written to call web service (particularly if it’s asynchronous)
  3. Supporting custom code is time consuming as developer coding styles and techniques vary

So what if we combined the two techniques? Would we get the rapid development of the CQWP and flexibility SPServices? Well I’ll let you decide after I show you some code:

Step 1

As preparation create a new list called “Product Relationships” and add the following columns:

Column                      Type
-----------------------------------------
Product1                    Number
Product2                    Number

And add some items, for example:

Product1          Product2
------------------------------------------
 2                   13
 6                    2
13                   14
15                   16
18                   19
20                   18
20                   19

Step 2

Add a CQWP to a page, configure it to point to your new list and export (save to your local machine for editing).

Step 3

Add the following directory structure to the “Style Library” directory of you site collections root sites:

\Branding\XSL\MyWebpart

And upload the MyWebpart.wepart file having add the reference (path) to the XSL file (you will create shortly):

  • ItemXslLink
  • MainXslLink
  • HeaderXslLink

And then edit the element called “Xsl”.
Once completed the file should look something like the following:

Step 4

Create a copy of the ContentQueryMain.xsl file located in  “\Style Library\XSL Style Sheets\” and edit it so that it looks something like this:

The lines of code to look at in detail starting from the top are:

<script />

The tag referencing the “_temp.js” file, this would normally be placed in the master page, however for the demo it is here.

<div id="relationshipEditor">…</div>

Used by the JavaScript to inject the demo content.

<script>…</script>

Wraps around the XSL template which will populate a JavaScript Array.

var pr = SJLewis.ProductRelationships;

Creates is a shortcut to a JavaScript Namespace.

<xsl:call-template name="populateArray" />

Does what is says, called the populateArray template.

<xsl:for-each select="$Rows">…</xsl:template>

Loops through the list items.

pr.productRelationships.push(new pr.productRelationship(…));

The “new pr.productRelationship(…)” code creates a new object containing data from the list item. And “pr.productRelationships.push()” add the object to the array.

pr.doSomeStuff();

Is a function that loops though the array and added the content to the page.

Step 5

Create a new JavaScript file for called “_temp.js” and add the following code:

And upload to this directory:

/MySiteCollction/Style Library/Branding/HTML/MyWebPart/_temp.js

Step 6

Reload the page and as baring no errors you page may look something like this:

Test 20 - 20
Test 20 - 20
Test 18 - 18
Test 15 - 15
Test 13 - 13
Test 6 - 6
Test 2 – 2

This model could easily be extended to retrieve data from multiple Content Types or Lists by adding more CQWPs and then exposing more objects and arrays from the “SJLewis.ProductRelationships” namespace. And instead of each CQWP calling the “doSomeStuff()” function to populate a DIV tag, they could call a “trigger()” function that informed a custom event handler when the data is loaded and ready for processing (e.g. combined, filtered and displayed by a div exposed by a CEWP).

XSL / JSRender Trap (Updated 14/07/2014)

When adding properties to a HTML tag located within your CQWP’s XSL file, which the value will be populated by JSRender, be sure to escape the curly braces like this:

Otherwise the XSL parser will strip the {{attr:ID}}} from the tags properties and the HTML will be rendered like this {attr:ID}.

CQWP Cashing(Updated 16/07/2014)​

Can’t see your new data and you need to see it immediately? Sounds like you need to turn off Caching. To do this, export the webpart and edit the property called “UseCache” by changing its value to “False”. The result should look like this:

Next save the webpart file and upload to your “Web parts” gallery and the final step is to replace the original webpart with using your new definition.

Glossary of terms:
  • CQWP:  Content Query Webpart
  • CEWP:  Content Editor Webpart
  • OOB:     Out of the box​

SharePoint Online Public Site: how to access the Webpart Gallery

When working with SharePoint Online’s Public Site you may have noticed that you do not have access to the Webparts Gallery from the Settings page. It would appear that, at least for my version of O365 SharePoint, Microsoft has hidden the “Web parts” link from the Settings page.

If you need to manage your custom webparts, here is a simple trick. Go to your Team Site setting’s page and click on the “Webparts” link and copy the URL into a text editor (e.g. Notepad++), for example:

https://[SITE-NAME].sharepoint.com/_layouts/15/start.aspx#/_catalogs/wp/Forms/AllItems.aspx

Next copy your Public Site’s base URL:

https://[SITE-NAME]-public.sharepoint.com/

Then take the path from the Team Site:

/_layouts/15/start.aspx#/_catalogs/wp/Forms/AllItems.aspx

Note the most important part of the path is:

/_catalogs/wp/Forms/AllItems.aspx

And append to you Public Site’s URL making a complete URL like this:

https://[SITE-NAME]public.sharepoint.com/_layouts/15/start.aspx#/_catalogs/wp/Forms/AllItems.aspx

Finally, past the newly created URL into your browser and wait for it to load Public Site’s Webpart Gallery…

Quick Referrence

If you can’t be bothered to go through these steps, I’ve listed the paths to the missing Galleries links below, with the exception of the “Site content types”:

  • List templates                   /_catalogs/lt/Forms/AllItems.aspx
  • Site columns                     /_layouts/15/mngfield.aspx
  • Recycle Bin                       /_layouts/15/AdminRecycleBin.aspx
  • Solutions                           /_catalogs/solutions/Forms/AllItems.aspx
  • Top Link Bar                    /_layouts/15/topnav.aspx
  • Tree view                         /_layouts/15/navoptions.aspx
  • Web parts                        /_catalogs/wp/Forms/AllItems.aspx

05/08/2013 (UK Date) Update:

Content Types can be managed using SharePoint Designer 2013.​

10/10/2013 (UK Date) Update:

Subsites can be managed using SharePoint Designer 2013.​

Update January 2015:

Starting January 2015, Microsoft is making changes to the SharePoint Online Public Website feature. Customers who currently use this feature will continue to have access to the feature for a minimum of two years after the changeover date of March 9, 2015. New customers who subscribe to Office 365 after the changeover date won’t have access to this feature. Moving forward, Office 365 customers will have access to industry-leading third-party offerings that will enable them to have a public website that provides a complete online solution and presence.

https://support.microsoft.com/en-us/kb/3027254