officedev/script-lab

Create, run and share your code directly from Office

Script Lab, a Microsoft Garage project

Experiment with the Office JavaScript API without leaving Excel, Outlook, Word, or PowerPoint!

Get Script Lab in Excel, Word, and PowerPoint, or Script Lab for Outlook, free from Microsoft AppSource.

Read the blog post on the future of Script Lab.

Topics

• What is Script Lab?
• Get Started
• Import someone else's snippet, or export your own
• Report a bug, or suggest a feature
• Stay up-to-date
• Contribute to Script Lab
• Rate and review
• Articles & FAQs
• External media coverage
• Code of Conduct

What is Script Lab?

Wouldn't it be crazy if you could launch Excel, click to open a small code window, and then instantly start writing and executing JavaScript that interacts with your spreadsheet?

Script lab is a tool for anyone who wants to learn about writing Office Add-ins for Excel, Outlook, Word, or PowerPoint. The focus is the Office JavaScript API, which is the technology you need for building Office Add-ins that run across platforms. Maybe you're an experienced Office developer and you want to quickly prototype a feature for your add-in. Or maybe you've never tried writing code for Office and you just want to play with a sample and tweak it to learn more. Either way, Script Lab is for you.

Script Lab has three main features:

• Code in a pane beside your spreadsheet.
  • IntelliSense is there while you type so you can easily discover and use the Office JavaScript objects and methods. Script Lab uses the Monaco editor, the same tech that powers VS Code, so it's beautiful and lightweight.
  • Samples are pre-installed with Script Lab, so you don't have to start from scratch
  • Your can use any TypeScript features like arrow functions, template strings, and async/await (i.e., a good chunk of ES6 and ES7 features). But it's not only script: your snippets can also use HTML, CSS, and references to external libraries and data on the web.
• Run the code in another pane beside the editor.
  • Execution can include logic, API calls to Office, UI in the pane, and even output to a console.
  • Every time you make a code change you can refresh the editor and run the new version in seconds.
• Share your snippets.
  • If you create a snippet you'd like to share, you can copy it to your clipboard, save it as a GitHub gist. Then send the gist link to someone else to use on their computer.
  • The Import feature lets you load other people's snippets.

Script Lab works in Office 2013 or later on Windows, Office on the web, or Office on Mac.

You can get Script Lab right now for free from Microsoft AppSource! It works for Excel, Word, and PowerPoint.

If you're interested in developing for Outlook, you can get Script Lab for Outlook, also free from AppSource.

Script Lab is a Microsoft Garage project that began at a hackathon. You can read the story of the original Script Lab creation on the Garage website.

Here's a 1-minute teaser video:

Get Started

Explore Office JavaScript API using Script Lab

This 10-minute demo explains how to use the main features:

Import someone else's snippet, or export your own

Script Lab is built around sharing. If someone gives you a URL to a GitHub Gist, simply open Script Lab, use the hamburger menu at the top left to see the menu, and choose "Import" category (either on the left or top, depending on the available screen space). Then, enter the URL of the Gist, and click the "Import" button at the bottom of the screen. In just these few clicks, you will be able to view and run someone else's snippet!

Conversely, to share your snippet with someone, choose the "Copy to clipboard" button with the open snippet. You can share as a public GitHub Gist, or you can paste the snippet from the clipboard, and share it from there.

Report a bug, or suggest a feature

To report a bug, create a new issue. Please provide as much detail as you can, tell us: the operating system, the Office build number, and your browser (if you're using Office on the web).

If you have a suggestion for a feature, please feel free to file it under "issues" as well, and we will tag it appropriately. The more detail, the better! (see more at CONTRIBUTING.md).

If you have a question, please ask it on Stack Overflow and tag your questions with office-js and scriptlab.

Stay up-to-date

• Follow @OfficeDev on Twitter
• Follow Script Lab articles on medium.com
• Join our Office Developer program at developer.microsoft.com

Contribute to Script Lab

There are a bunch of ways you can contribute to Script Lab:

• File bugs & suggestions (see Report a bug, or suggest a feature).
• Contribute new samples, or improve existing one. Please submit a pull request to the office-js-snippets repo; more info in the README of that repo.
• Spread the word! Whether through writing a blog post (examples), recording a video, tweeting about us, or sharing snippets with colleagues or the StackOverflow community -- we want more of the world to use Script Lab!
• Help improve the documentation. If you feel like this README or the CONTRIBUTING.md doc could use more details, please send a pull request!

Rate and review

Leave a star-rating and (optionally) a review blurb for Script Lab on the Office Store review page.

We'd prefer you report issues on GitHub.

Articles & FAQs

• Announcing Script Lab React (January 1, 2019): Official blog post
• Script Lab overview: "You can write JavaScript in Excel!"
• Project history & the technology behind it: Episode 127 on the Office 365 Developer Podcast

External media coverage

• August 29, 2017: "Start Developing in OfficeJS Today with Script Lab" by David Craig at theofficecontext.com
• July 30, 2017: [German] "Eigene Script Lab Scripte in Office Online testen". (Auto-translation: "Test your own Script Lab scripts in Office Online") by Mourad Louha
• June 14, 2017: [Portuguese] "Script Lab: Novo add-in da Microsoft". (Auto-translation: "Script Lab: New Microsoft add-in"), by Leonardo Xavier.
• May 1, 2017: [German] "Prototyping von Microsoft Office JavaScript Add-Ins mit Script Lab". (Auto-translation: "Prototyping Microsoft Office JavaScript add-ins with Script Lab"), by Mourad Louha
• May 1, 2017: [Portuguese] "Microsoft lança o Script Lab". (Auto-translation: "Microsoft Launches Script Lab"), by Felipe Costa Gualberto.
• April 18, 2017: "Microsoft Garage Releases Script Lab" by Ryan Maskell at winbuzzer.com

Code of conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

script-lab's Issues

Clarify quality bars

In terms of localization, a11y, styling, and overall functionality

Port Script Lab custom functions experience to new codebase

Ability to give feedback (send a smile/frown)

Authentication with GitHub

Create an express server to handle the clientSecret
Connect to client UI

Test in all browsers for styling + smoke-testing

Test across IE/Edge/Firefox/Chrome and across hosts.
For functional smoke-testing, see the comprehensive list at https://github.com/OfficeDev/script-lab/blob/master/TESTING.md

Settings View

Add types / share types between React components

Incorporate animations

Implement unit tests for all React components

Export to Clipboard

Copy the YAML gist directly to clipboard under share

Make Ctrl+S not try to save the webpage

Make the focus color for the PivotBar have more contrast

I tried applying the same technique used for the Nav menu in the backstage, but it didn't seem to work for the PivotBar (File switcher).

Deployment: N-1 versioning

UPDATED Nov 6 2018, feel free to ignore some of the other comments that were from earlier days

Need to:

• Spin up a CDN (similar to "scriptlab.azureedge.net") to be able to experiment outside of production.
• For any copied assets (monaco editor), ensure that get copied into a versioned folder number (e.g.,
  https://script-lab.azureedge.net/libs/monaco-editor-0-10-0/.... That way we can update dependencies in the future.
• Ensure that older assets continue to be copied for X amount of time. That way, an older HTML page (served off of the CDN) doesn't end up referencing removed JS files. Maintain a JSON file with assets and their dates, and remove as needed. Script Lab today already does most of this.
• Experiment with whether need any cache settings in the CDN or in meta tags of the HTML pages or in server configuration, etc.
  • HTML should probably just "never cache" (or should it?...)
  • JS files should all get hashes via webpack and then should be always-cache.
  • Use "web.config" so specify this (?)

Integrate aXe

https://axe-core.org/

This will help check for things like sufficient contrast, proper labels, etc.

Allow arbitrary import URL as long as it points to plain text file with yaml in it

E.g.: https://gist.githubusercontent.com/Zlatkovsky/05a5ede7af7dafadc963229da0edf78b/raw/51f1f48725ad0fea16a39a076d3078876ab73d6b/Custom%2520Functions%2520demo.yaml

React Cleanup

Go through each React component, and delete any unused props, apply same convention to all components, share typings.

Remove libraries from Intellisense when switched off of a solution

Right now, it will add whatever new libraries are needed, but it won't remove libraries that are no longer needed, potentially allowing for people to have intellisense for libraries that aren't actually there

Localization Support

Update gist

This feature relies on #18. Once a snippet has been exported as a gist, it should be able to be updated. (Have changes be pushed to it.)

Investigate 20 sec stall time when on localhost

Note: this issue does not occur when using 127.0.0.1

Libraries IntelliSense: don't over-fire auto-completion

Only have it give suggestions if you are at the beginning of a line:

Repro: https://appsforoffice.microsoft.com/lib/1/hosted/off
hit ctrl + space and see what happens

Implement Error handling for all sagas and services

For dev.office.com

• Embedding view
• Browsable samples gallery
• Port over the "Open in Script Lab" logic

[Note, perhaps we can get someone from Keith's team to chip in on this one, too]

Fix the styling for the profile pic icon when there is no user logged in

Currently, I have it just as a white circle, but it should probably be a generic user icon.

Delete functionality on backstage

It would be great to have a delete button on the backstage so we can delete snippets faster and possibly even delete multiple snippets at once.

Make the Delete button delete the current solution and files

Make sure to test in the case where there is only 1 solution, and it is deleted.

Make Backstage Fully Accessible

Swap out the lists used for samples, and my snippets to be the Fabric DetailsList component.

Cache the libraries (contents) so that theres never an instance of no intellisense

Either in sessionStorage or localStorage

Other bits of Script Lab functionality: auth helpers

Import a snippet

Be able to import a snippet via a url, or directly pasting in the YAML

Export snippet as gist

This feature is the ability to publish a snippet as a gist, both publicly and secretly.

Put "Apply", "Cancel", and "Restore" options in the settings view

Un-hardcode Office.d.ts for Monaco's Intellisense

Refactor Libraries UI from Snippet Settings to Monaco

Incorp. Prettier into editor

if possible

Basic Deployment of Client

Get the client code deployed so others can see.

Continuous Integration Deployment & environments

Currently, the site must be manually deployed. This feature will allow for continuous integration deployment for both the client, and server code.

View all shared gists

This requires #15 to be completed so that metadata can be fetched for a user's shared gists. (Both public and secret.)

Add aria labels everywhere to get proper screen reader functionality

Telemetry

Hook up basic initial telemetry

Upgrade to TypeScript 3.0

Create JSON Schema for Settings

Export/publish story (at minimum, on par with what Script Lab 2017 had)

While we're at it, we should also consider allowing an option to publish as CONTENT add-in instead of assuming taskpane (see OfficeDev/script-lab-2017#889)

Theming / Host Detection

Un-hard-code the theming to be based on which Office host the client is in.
Also, allow the user to toggle some settings such as light vs. dark, and editor color schemes.

TODO: Add appropriate license + README

Fix the colors for the MessageBar

Currently, the pale green looks yellow against the dark green file switcher.

Refactor to use <Only /> component

Got frustrated with having to put:

{ someConditionThatDeterminesIfShouldRender && <ComponentToRenderConditionally /> }

Instead thought this looked a lot cleaner and clear on intentions:

const Only = ({ when, children }) => (when ? children : null)

yielding code that looks like:

<Only when={someConditionThatDeterminesRendering}>
  <ComponentToRenderConditionally />
</Only>

Apply this refactoring to other areas that have aforementioned pattern.

Add TSLint to Monaco

Remove Github.js

We don't need this dependency, and we can just manually make the calls..

Setting up staging environments

Creating alpha, beta, prod staging environments and integrating a way to be able to switch between them from the client.