Office Development – Installing and Running Yeoman

Office Development - Yeoman

In the previous two posts around creating your first Word add-in we installed Node JS in the first post Office Development – Installing Node.js and installed Git in the second post Office Development – Installing Git. If you haven’t done this already move along and do that first.

In this post, third in the series of building your first Word Add-in (based on the JavaScript API for Office) we will install and use another tool called Yeoman.

Yeoman

Yeoman used to be a member of the social class in late medieval to early modern England (source wiki: https://en.wikipedia.org/wiki/Yeoman) but these days it is the name for an open source scaffolding tool, released at Google I/O 2012. Yeoman runs as a command-line tool and will provide you with a boiler plate project for several different solutions. Because the software is open sourced you can find it on GitHub: https://github.com/yeoman

Over time there have been created many generators for Yeoman to do all sorts of things such as creating website starters and more. The reason why we discuss it here is because they (the Office Dev Team) also created a generator that allows you to quickly build a Microsoft Office Add-in project using the Yeoman scaffolding tool.

You can use this if you simply want to start creating an add-in with a basic text editor other than Visual Studio. Of course, you can also use more advanced text editors including Visual Studio of Visual Studio Code but just to show you that you don’t need much to create your first add-in you can use this option.

Installation is easy (provided you installed the tools from the other two blogposts):

Open a Command window (Windows Flag, Command) and run:

npm install -g yo generator-office

This will globally (-g) install the Yeoman (yo) package and the Office Generator (generator-office) on your machine. The routine ends in an automatically engaged final check by yodoctor:

clip_image002

You can also check it yourself by running the command:

npm list -g -depth=0

clip_image004

If all went well you should see, as you can see in the picture above, at least yo@<version> and generator-office@<version>.

Now will be the time to generate our first Word Add-in … hooray!

Enter the command line command:

yo office

This will kick off a series of questions needed to create your add-in based on your input:

clip_image006

Except for the name I opted to keep the defaults. You can select other than the defaults but for now keeping the defaults is ok.

Yeoman starts generating the add-in for you and in the meantime a website is opened with instructions. The instructions take you by the hand and will guide you through the process when the add-in finished generating.

clip_image008

At this time generating your add-in is probably finished, so follow the instructions from the webpage by clicking Next

According to this page the next command should be:

npm start

This will start the local server hosting the add-in at:

https://localhost:3000

As you can see it will be hosted at a ‘secure’ site (https) on port 3000. This ‘secure’ site could give you some headache however. Initially the site needs the firewall to be opened:

clip_image010

I’d recommend unchecking the Public Networks checkbox and only to allow it on your Private Networks for now.

Continuing the process will result in another security issue:

clip_image012

Another no-go? Well, maybe … but let’s click “Details” first and find out what this is all about. So far not a real smooth experience for the novice office add-in developer don’t you think? Go ahead, click “Details”:

clip_image014

Ah! What it says is that your PC doesn’t trust the website’s security certificate … and to be more specific it found that the name of the hostname on the security certificate is different than the one you are trying to visit.

This is quite logical because you are visiting your localhost and the website’s security certificate, as you will find out a bit later, is signed to by “Internet Widgits Pty Ltd” so against all recommendations continue and click the “Go on to the webpage” link.

clip_image016

And there you have it! Your first Word Add-in!

“Well, hel-lo … there is no Word here, what do you mean” you might say … and you are right (again).

Although I explained in my earlier blogposts that Add-ins built by using the JavaScript for Office APIs basically are websites hosted in the Office client such as Word you’ve seen here that your really are building a website.

The security issues will however throw a big issue loading this website in the Word client. It will simply be rejected as it appeared to be unsafe to run.

Solving the certificate issue is a story on itself so I will put this in a separate blogpost.

What you’ve seen so far is that you built your new add-in by simply using some web development tools. No Visual Studio installations, nothing of this all. Obviously, you can use Visual Studio to create Office Add-ins, and I will show you that in another series of blogposts. For now we still need to finalize our first journey of creating this Word Add-in but we need to overcome our security issues first.

And therefor, to be continued …

Office Development – Installing Git

Office Development - Git

In our previous step to build our first Word Add-in with JavaScript for Office we installed Nodejs. Today we continue with installing Git. Over time there will not be a need to install these tools again, by then you will be a professional web developer living in the world of these tools and probably have these installed already before jumping into another project.

For now I assume you didn’t have the tools installed, but you can check on the command line with the command:

git –version

If you already installed Git you probably see something like this:

clip_image002

You can find the Git installer just by GoogleBinging for “Git” and this will lead you to:

https://git-scm.com

Now, on the right you see a nice downloader button that selects your installer based on the machine that you are on. Click this, and hit Run (usually you wouldn’t be so dumb and save the downloader first on your machine in order to have the anti-virus checker check your download but for now we just let it run #yolo … )

clip_image004

As usual the first dialog you’ll see are the GNU License terms, your only option is to agree by clicking next or abandon the installer and start reading a good book and continue living your life without the software. Today we’ll decide to go on however …

clip_image006

Now select a few components. You can add some icons to the desktop and I opt for the settings to add Windows Explorer Integration and the other defaults.

clip_image008

I also have it install the icons on the desktop for quick access, you can always throw ‘em in the bin if you think they are in your way.

clip_image010

The next dialog above is for adjusting the PATH environment. My option is to “Use Git from the Windows Command Prompt”. Note that with this option you’ll be able to use both Git Bash

Bash what? …

Ok, ok, I know, if you are native from Windows you probably won’t even know what Bash is. For now, you don’t need to know other than that this is some sort of a Linux command line option.

Don’t worry, you get the hang of it once you are moved over to the ‘other side’.

clip_image012

Choosing the HTTPS transport backend I opted to “Use the native Windows Secure Channel library” (just because we are still in the mood of Windows, you can change this later if you like).

clip_image014

Configuring the line ends I leave the default as it was the recommended setting on Windows “Checkout Windows-style, commit Unix-style line endings”

You already noticed it, there is a lot of Unix influencing here … Bash, LineFeeds … it takes me back to the time I studied Computer Science. #throwbackwednesday

The next dialog is no different. Configure the terminal emulator to use with Git Bash

clip_image016

The option selected allows you to use both MinTTY as terminal emulator as the common Windows Console (“cmd.exe”).

clip_image018

Again, select the defaults to enable file system caching and enabling the Git Credential manager. Hitting Install will kick off the Git Installer to install all the selected options you entered on the dialogs above:

clip_image020

clip_image022

Done, if you want to have a quick view at what Bash is tick the option to Launch Git Bash. Otherwise it will just lead you to the Release Notes (if you didn’t remove the check before “View Release Notes” that is). You now have Git on your machine, check the version again by running git –version again.

You should see this (or a newer version if you read this later than the day of the blogpost):

clip_image002[1]

Ready to go into the next step to install Yeoman.

Yeoman whaaaaaaaaaaaaaat?

Yes, Yeoman … more in my next blog post.

Hang in there and see you tomorrow! You get used to it … let it all get into your system, GoogleBing it a bit for some extra context, perform all the steps from above doing it yourself and be ready for the next step.

Office Development – Installing Node.js

Office Development - NodeJs

It’s time to try to build our first Word Add-in using the JavaScript for Office APIs. We won’t look at the specifics but we will just start building and see where we’ll end.

I will go into detail a lot because this is what you often won’t see in the tutorials. By going into the small detailed steps, I hope you (and I for myself) won’t get lost. Also, I think it is just good to document it in detail so if you want to look back later all steps are easy to recover. The risk is of course that by then everything changed .

For this first Word Add-in, we will be using Yeoman and not to make things too complicated we start with Windows, the platform most existing Office developers come from. Yeoman is a Web Scaffolding Tool for Modern Webapps. That’s right webapps … welcome to the world of Web Developers. A world of weird named tools such as Grunt or Gulp and nothing like the .NET world.

With Yeoman, you can generate a project from scratch that inserts all you need to start quickly. To install Yeoman, you need to install Node.js and Git. For Node.js we go to nodejs.org and on the start page of this site you see the downloads:

clip_image002

What you see is two options: LTS (Long Term Support) and Current. The LTS version is the most stable version and this is the version that they committed to support for the long term. With the Current version, you are on your own. For now, it is ok to install the LTS release.

To check if you already have installed Node open a command window (cmd) and type:

node -v <enter>

If it isn’t installed you obviously won’t get a version returned, otherwise you’ll see something like:

V6.11.0

We’ll install v6.11.2 in this case so here we go:

clip_image004

Click Next to continue …

clip_image006

Check the checkbox to accept the License Agreement and click Next

clip_image008

Select the Destination Folder (just leave as it is, or if you want it somewhere else change the path) and click Next to continue.

clip_image010

As you can see here is also the option to install the npm package manager. You’ll see later on that this tool will be used a lot to keep your installed packages up to date or just to install new packages. I just install all options here and click Next to continue.

clip_image012

Ready to install Node.js … Click Install!

Accept the security dialog to install in elevated mode and wait for the installer to finish up.

clip_image014

Done!

clip_image016

Click Finish to close the Node.js Setup Wizard and check the current installed version by opening a Command window (Windows Flag, Run, Cmd) and type

node -v <enter>

Result:

V6.11.2

NodeJS IX

In my next post, we’ll continue by installing Git and continue our endeavor to build our first JavaScript for Office Word Add-in.

In the meantime try to read some more about Node.js on their website: https://nodejs.org

To be continued …