Tag

Interactive

Browsing

Introduction

According to Microsoft documentation, you can use a base64-encoded image for your web part icons. However, base64-encoded SVG images -- as is shown in the documentation -- don't work as expected. And by the looks of it, this hasn't worked for a while.

Since the SPFx team has been working tirelessly to deliver more than 15 releases of SPFx since its general availability, I'm sure we can forgive them for letting something so minor fall through the cracks.

However, I really don't like how icons that were converted from PNG look slightly blurry. (I tend to obsess about little things like that sometimes).

As I was writing another post for my SharePoint Framework Design series, I decided to get to the bottom of the issue.

As it turns out, it was pretty easy to solve.

TL;DR

This is an interactive post: we'll convert your SVG so that you can use it as an SPFx web part icon.

If you don't care about the explanation, you can go straight to the solution

The Challenge

My challenge was that I wanted to use SVG images in my web part's manifest, but I didn't want to have a separate SVG asset. I wanted to define a base64-encoded SVG file, as is demonstrated in the SharePoint documentation.

I knew it didn't work (believe me, I've tried), so I wanted a solution that would not rely on any unsupported hacks.

Since I don't have access to change the SharePoint code, I needed a solution that would work without requiring any changes from SharePoint.

How SPFx web part icons work

According to the Microsoft documentation, for your SPFx web part icon you can use either an Office UI Fabric icon, an external icon image, or a base64-encoded image.

To change your icon to an Office UI Fabric icon, you simply open your web part's [YourWebPartName].manifest.json and change the "officeFabricIconFontName" node to the name of the icon you want from the UI Fabric site.

The default icon is Page. If you wanted to change your icon to the Sunny icon, you would simply change the following line:

"officeFabricIconFontName": "Page",

To this:

"officeFabricIconFontName": "Sunny",

Note that you have to re-build the web part (run gulp build) and reload your workbench (press [F5] on your keyboard) before you'll see the new icon. Trust me, I wasted a lot of time trying to figure out why my new icons weren't showing up.

If you want to set the icon to an external image, you'll want to find the URL of a publicly-accessible image and change your web part's manifest "officeFabricIconFontName" attribute from the following:

"officeFabricIconFontName": "Page",

For a "iconImageUrl" image URL, as follows:

 "iconImageUrl": "https://assets.contoso.com/weather.png",

You can also use a CDN, or use your SharePoint CDN to store your images.

If you don't want to use an external image, you'll want to use a base64-encoded image.

To do so, you'll have to first convert your image using a tool like this web site. Once you have your base64-encoded image, you'll change your web part's manifest from this:

"officeFabricIconFontName": "Page",

To this:

 "iconImageUrl": "data:...",

And you would put the entire base64-encoded string as the web part's URL. Because you see, the base64-encoded string is actually a valid URL.

It is just a special kind of URL, called a data URI.

About data URI

Base64-encoded images, whether they are SVG or PNG, JPG, or GIF, rely on data URI. Data URI allow you to embed a resource in a URI which would normally result in a separate HTTP request.

Most data URI consists of the data type of the item (e.g.: image/png), followed by a semicolon, and the data of that file.

The cool thing about data URI is that -- on most modern browsers -- you can pretty much use them anywhere you would normally use a link to a resource.

Parker

For example, to show the above image of Parker in HTML, you would embed an img element and point the src attribute to the URL of the image, as follows:

<img src="https://avatars0.githubusercontent.com/u/31443929?s=200&v=4" />

Using a data URI, you could also do this:

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAABpUUlEQVR4nOxdBVgU2xc/S3d3d0iDtKgI2N3d+tBnd+uzu7D924mJGIgoIAooKiGIIp1KLsvS+f/mbrAxu+xiofL75JvZmTt3Ztd75vQ5Qi0tLdCJTnQCHwK/+gE60YmOjE4C6...

Which produces this image:

The first version of this image had a URL pointing to the original source of the image, while the second one contained the actual image!

To generate the super-long gibberish, I used this online base64-encoder and uploaded a copy of Parker's avatar, then copied that super-long string it generated into the src attribute of my img tag.

You have to base64-encode the image because you're trying to embed a binary file inside of HTML.

Except that SVG files are not binaries...

Using data URI without base64-encoding

SVG files are simply text markup files, like HTML.

During my research, I found an article entitled Probably don't base64 SVG which explains that when you base64-encode an image...

"It takes 4 characters per 3 bytes of data, plus potentially a bit of padding at the end."

Essentially, base64-encoding SVG takes more room than the original file! Files are essentially 133% bigger!

Fortunately, you can actually use your UTF-8 encoded SVG file inside a data URI as follows:

<img src="data:image/svg+xml; ... ">

Now, you need to make sure that you don't embed unsupported characters inside your src attribute. For example, if your SVG has a single quote (') and your src attribute uses single-quotes to define it, you'll want to escape the '.

Fortunately, Taylor Hunt wrote a great article explaining how to encode SVGs in data URI while optimizing them to help you with that.

Taylor's awesome article inspired someone to write a codepen to encode SVGs.

I forked Jakob-e's codepen to make my own which makes it easy to encode SVGs to work as a data URI icon for a web part's manifest.

Using a data URI SVG as your icon

To use your custom SVG as an icon, take the following steps:

  1. Design an icon so that it fits within a square, ideally 64x64, or at least 32x32.

  2. Make sure that your icon <svg> element sets the width and height attributes -- otherwise, your icon will be cropped and/or will not appear centered. To do so, simply change your SVG opening tag from:

    <svg>

    To this:

    <svg height="64" width="64">
  3. Consider optimizing your SVG by using SVGOMG or a similar tool.

  4. Paste your SVG in the box below to encode your SVG

VariableValue
Original SVG

  1. In your web part's [YourWebPartName].manifest.json, change the following line:

    "officeFabricIconFontName": "Page",

    To this:


    Don't forget the extra , at the end of the line.

  2. Rebuild your web part by running gulp build
  3. Refresh your workbench

Your new SVG icon should appear!

Conclusion

You still can't use base64-encoded icons as your web part icon -- at that's probably a good thing, because base64-encoded SVG files are bigger! -- but you can use a data URI image instead.

This article shows you how to convert your SVG so that it will produce beautiful web part icons.

Regardless of whether Microsoft ever fixes the issue with SVG icons for web parts, you should still consider optimizing your SVG before using it in your solutions.

I hope this helps?

Updates

  • September 1, 2019: This approach will also work for application extension.

Sources

Introduction

Sometimes, you just want to create a link to someone's Delve profile in SharePoint Online.

Thanks to an article from The Baretta, we know how to formulate the link.

However, since I started doing interactive blog posts, I thought I'd create one which automatically generates the URL for you.

To create a link to a Delve profile

To create a link to someone's Delve profile:

  1. Take your tenant name, and add -my.sharepoint.com/PersonImmersive.aspx?accountname=i%3A0%23%2Ef%7Cmembership%7C to the end of it.
  2. Append the person's email address at the end of what you got in step 1.

Generate a link now

Enter the your tenant name (the part before .sharepoint.com and without https://) and the email address of the person for whom you want to create a profile below, and the URL will automatically be created for you. Click Copy to clipboard to send it to your clipboard.

Don't worry, we don't store any information you enter.

VariableValue
SharePoint Online tenant name
User's email address

Your URL:

https://mytenant-my.sharepoint.com/PersonImmersive.aspx?accountname=i%3A0%23%2Ef%7Cmembership%7Csomeuser@mytenant.com


Conclusion

That's all there is to it. I really just wanted to create another interactive blog post, because they are fun to create!

Thanks to The Baretta for posting this information in the first place.

Photo credit

Delve screenshot from Microsoft

Introduction

I have to admit, I still consider myself a GitHub newbie.

Most of my clients use TFS or Azure DevOps and my previous experiences with GitHub were unpleasant.

But since I started contributing to the Office 365 Developer Community, I had no choice but to become familiar with GitHub.

The majority of the repositories under https://github.com/SharePoint and https://github.com/officedev -- for example -- have contributing guidelines, but they assume that you have a basic understanding of GitHub -- or at least, a better understanding of GitHub than I had when I started contributing.

Because I still hesitate with GitHub commands once in a while, I use a cheat sheet when I start a new PnP contribution. I copy and paste the GitHub commands from the cheat sheet and substitute placeholders with the values I want. It is really an amalgamation of GitHub commands from the various contributing guideline documents I have found useful into (I hope) a coherent set of instructions. I try to use the GitHub browser interface wherever I can, and GitHub commands where it is easier.

I have written this post to answer all the questions I had when I started. It is really a note for myself, but I hope it can be useful for someone else who wants to get started. While this article is written specifically for PnP contributions, they also apply to most open source contributions on GitHub.

I am not a GitHub expert. There may be better ways to do what is described in this post, but these are the instructions that have worked well for me in the past. If you have any suggestions on how to improve the instructions, please submit a comment below. I'll even buy you a coffee when you're in town!

This article focuses on the GitHub commands. If you need help with your first contribution, David Warner II has kindly volunteered to help anyone with their first PnP contribution. He's a true master on the topic.

Note

I'm trying something new today: interactive, personalized instructions for you. Yes, you!

Instead of putting placeholders in the instructions (like [your_repo_name]) that you have to change as you follow the instructions, the placeholders are connected to a form at the top of each section.

When you change the values of the placeholders, the instructions in this post change automatically!

To get customized instructions, just replace the placeholder values with your own values.

Don't worry, we don't save any values you entered.

Let me know if you like this in the comments below. If you do, I may do more interactive posts in the future. It's kinda fun!

Overview

If you know me, you know that I love processes.

The diagram below represents the contribution process that we'll discuss today.

graph LR
AA[Fork repository]-->A
A[Clone repository]-->B[Create branch]
B-->C[Contribute]
C-->D[Push changes]
D-->E[Submit pull request]
E-->|Repeat|B

It consists of the following steps:

  1. Fork repository
  2. Clone repository
  3. Create a branch
  4. Contribute
  5. Push changes
  6. Submit pull request
  7. Repeat (go back to Create branch)

Step 1: Fork repository

Before you can contribute to a repository, you need to Fork it. Forking a repository creates a copy of it from the original owner's account to your own.

Once you have created your own fork, you can freely change the code in your own copy of the repository without worrying about affecting the original repository, or upstream repository. However, GitHub remembers what the upstream repository is, which will make it easy for you to submit your contributions when you're done but also to synchronize changes that have been made to the upstream repository since you forked it.

Forking only happens within GitHub; it doesn't affect the code on your machine (that is, until you clone it, but that'll happen later).

How to fork a repository

  1. In your browser go to http://github.com and find the repository you want to contribute to. For example, the sp-dev-fx-webparts is where you would submit SharePoint web part samples.
  2. In the upper right corner, select the Fork button
    The Fork button in GitHub
  3. If you haven't already logged in to GitHub, you'll be prompted to do so. If you haven't already created a GitHub account, you'll be able to create one. If you have already logged in, it will automatically begin the forking process. You get a cute little animation showing that it is "copying" the repository, and you end up in your own copy of the repository.
    The Forking has begun
  4. You'll know that you're in a fork because the owner will have changed to you, and it should say "forked from ..."
    hugoabernier/sp-dev-fx-webparts forked from SharePoint/sp-dev-fx-webparts

The repository name should now be [your_github_username]/[repo_name], for example, if you forked SharePoint/sp-dev-fx-webparts and your username is hugoabernier, your forked repository will be called hugoabernier/sp-dev-fx-webparts.


Enter your own variables

Take a second to enter the original repository URL and your GitHub username below, and the rest of this post will automatically change to match what you should see:

VariableValue
Original Repository (Upstream)
Your GitHub username

You have created your own fork! This is what is called an origin repository. I know, I know, the terms are confusing, but here is a table that may help break down the differences:

CharacteristicsUpstreamOrigin
What is itThe original repositoryYour forked instance of a repository
Where is ithttps://github.com/SharePoint/sp-dev-fx-webpartshttps://github.com/[your_github_username]/sp-dev-fx-webparts
Who owns itSharePoint (Not you!)[your_github_username] (You)
What changes should you makeCreate issues, submit a pull requestWhatever you want
What is the impact of your changesAffects the original repositoryAffects only your fork
Who can see your changesEveryoneEveryone who looks at your repository, unless you made it private

Once you have forked a repository, clicking on Fork again will do nothing; It simply redirects you to your own fork.

Step 2: Clone repository

Once you created your origin repository, it is time to clone it. Cloning a repository creates a copy of your fork to your local machine, so you can work on it.

The cloned repository, which will reside on your local hard-drive, will become your local repository; The repository that is on GitHub will be what's called your remote repository.

You can make any changes to the local files on your hard-drive, it will only affect your local repository. It won't affect your remote repository (until later, when we push the changes).

To clone your repository

  1. From your computer, launch whatever tool you like to run Git commands. Some people like Git Bash, but I prefer Cmder or the Node.js command prompt.
  2. Make sure that your command prompt is in the directory where you'll want to create your local repositories. I like to use c:\github. You can do so by typing:
    cd \github

    or, if using Git Bash:

    cd /c/github
  3. The repository you will clone will be created a directory within your current directory. To clone the repository, just type git clone followed by the URL of the repository you forked in the previous section. Note that the URL should end with .git:
    git clone https://github.com/[your_github_username]/sp-dev-fx-webparts.git
    

    It should create a directory with the same name as your repo, then should download all the files locally to that directory. It doesn't take very long, but it really depends on your internet connection. This is what it should look like:
    Git Clone in action

  4. Once your local repo is created, change to the directory that was just created by typing cd followed by the repo name and [Enter]:
    cd sp-dev-fx-webparts
    
  5. To link your local repo with the original upstream repo, you'll type git remote add upstream followed by the original upstream repo URL, as follows:
    git remote add upstream https://github.com/SharePoint/sp-dev-fx-webparts.git
    

    Linking to the upstream repo will make your life easier later when you want to make more contributions.

  6. Before you start making changes, you should make sure that you have the latest version from the original upstream repository. Of course, since you just forked the repo, you should already up to date, but if make more contributions later, you'll want to make sure you're always making your new contributions against the latest code. To do so, simply type the following:
    git fetch upstream

Now you'll have a local repository with a remote that is connected to the upstream repo that we can create a branch from.

Step 3: Create a branch

In GitHub, repositories usually have multiple branches. In GitHub, a branch is a way to keep track of change by grouping them into a feature set. The master branch is usually the default branch, where all approved code usually ends up. You normally shouldn't make changes to the master branch directly, that's what pull requests are for.

When you want to make changes in a repo, you should create your own branch to help keep track of the changes you're making. For example, if you want to add a cool feature to a repo, you would create a branch called cool-feature. Meanwhile, someone else may create their own branch called coolest-feature, which may later become the basis for someone else's most-coolest-feature branch.

Eventually, when those branches are submitted via a pull request (assuming they get approved), they'll end up being merged back to the master branch.

Branches in GitHub

Most PnP repositories usually have a dev branch, which is meant to be your starting point for your changes.

Take a moment to look in your repo for any contribution guidelines to make make sure that the starting branch is the dev branch.

To help you, David Warner II and I have compiled a list of popular PnP repositories that will tell you which branch you should use.

Once you have confirmed what branch you should start from, you should create own branch from the starting branch, and give it a name that will describe what you'll be doing in that branch. For example coolerest-feature, or hugo-patch-1. Try to avoid spaces and funny characters.


Enter your own variables

Enter the name of the branch you want to create, and we'll update the instructions for you:

VariableValue
Start branch name (default is dev)
Branch name

To create your branch

To create your branch, follow these steps:

  1. To create a branch, we'll start by calling git pull upstream, which will update your local repository with the latest changes from the upstream repository. We'll also specify which branch to start from, and what to call the new branch by typing the following:
    git pull upstream dev:coolerest-feature
    
  2. Now we'll let your forked origin repo know about the new branch you've created by typing git push origin followed by your new branch name, as follows:
    git push origin coolerest-feature
    
  3. Finally, we'll switch to the new branch you've created by calling git checkout, followed by your new branch name. Type the following:
    git checkout coolerest-feature
    

If you're using Cmder, you should see that your prompt has changed to indicate that you're now in your new branch:
New branch

Note: If you need instructions to configure Cmder to display your repo and branch, read my earlier post

Now you're reading to contribute!

Step 4: Contribute

Now that you have your own branch, you can make the changes you need. Please make sure you follow the Microsoft Open Source code of conduct.

If you aren't sure about the code of conduct, you can also check out the [Code of Conduct FAQ] (https://opensource.microsoft.com/codeofconduct/faq/).

Once you're done making your changes, you'll want to push your contributions.

Step 5: Push your changes

As you make changes to files in your local branch, your changes will be tracked locally. Changing the files in your local folder does not affect the local repository until you commit your changes.

Once you have committed your changes to the local repository, you can push your changes to your remote repository (the one on GitHub.com).

You can do so by following these steps:

  1. From the local branch folder, type:
    git add .
  2. Commit your changes by typing git commit -v -a -m followed by a comment indicating what your changes were. For example, if you wanted to say "Initial commit", you would type the following:
    git commit -v -a -m "Initial commit"

Now your changes are committed with a comment. Time to submit a pull request!

Step 6: Submit a pull request

In GitHub, a pull request is really simply a request for someone else to review the work that you've done and merge your changes in. When you create a pull request, you need to select two branches on GitHub, the branch that you've made your changes on, and the branch where you would want to merge your changes into.

To do so, follow these steps:

  1. Push your changes to your origin repository (the forked repository you created), you'll want to type git push origin followed by your branch name, as follows:
    git push origin coolerest-feature
    
  2. Once done, use your browser to your forked repository (https://github.com/[your_github_username]/sp-dev-fx-webparts), you should see that your changes have already been reflected to GitHub.
  3. From your forked repository, click on Pull requests in the navigation, then click on New pull request. Optionally, you can visit https://github.com/hugoabernier/sp-dev-fx-webparts/pull/new/coolerest-feature.
    New pull request
  4. You'll be prompted to confirm the branches you want to merge, with an arrow going from one branch to another. Make sure that the arrow is pointing from your branch on your forked repo to the branch on the remote repo. If you follow all the steps above, you should also see Able to merge.
    New pull request
  5. Provide a descriptive title for your pull request. For example, New coolerest feature
  6. Most PnP repositories have a pull request template. Please be courteous and follow the instructions in the template. Follow the prompts and answer as much as possible. If there are sections that say > _(DELETE THIS PARAGRAPH AFTER READING)_, delete them.
  7. When you have filled the template, click Create pull request.

After you've completed your pull request, you'll see that its status is marked as Open

New open pull request

All you have to do now is to wait for your pull request to be merged with the master branch.

It can take a few days, sometimes weeks before your pull request is approved. Please be patient; Most reviewers are volunteers and have a day-to-day job.

While you're waiting, you can start a new contribution!

Step 7: Repeat

If you want to continue making contributions, you simply create a new branch from the original base branch. For example, if you were created the second update to your coolerest-feature, you could call your next branch coolerest-feature-2.


Enter your own variable

Enter the name of the next branch you want to create, and we'll update the instructions for you:

VariableValue
Next branch name

To create your next branch, follow these steps:

  1. Calling git pull upstream with your next branch name by typing the following:
    git pull upstream dev:coolerest-feature-2
    
  2. Push your new branch by typing git push origin followed by your next branch name, as follows:
    git push origin coolerest-feature-2
    
  3. Finally, switch to your new branch by calling git checkout, followed by your next branch name. Type the following:
    git checkout coolerest-feature-2
    

Once your next branch is created, continue contributing as you did before (contribute, push your changes, submit a pull request).

Deleting your branch

Once your pull request has been approved and merged to the master, you can delete your branch. Do not delete your branch before it has been approved -- just in case you need to make a change to your pull request before it has been approved.

Trust me on this one.

Conclusion

I know, this was a long post. However, I hope that it will be useful for someone who wants to get started with making contributions to the PnP community.

For more information

There are many other resources available out there. Here are some that you should definitely check out:

Updates

  • August 23, 2019: Added For more information section, because there are many great references out there that people should know about. Also, added link to the latest list of popular PnP repositories

Photo credits

Branch image by GitHub.
Note image by Pexels from Pixabay