Skip to content

Commit 8e18665

Browse files
alison-mkalison-mk
authored
[Excel] (Data types) Add basic types with metadata snippet (#994)
* [Excel] (Data types) Add basic types with metadata snippet * Fix a couple bugs * Code review feedback * Run yarn start
1 parent 58684e4 commit 8e18665

File tree

5 files changed

+382
-0
lines changed

5 files changed

+382
-0
lines changed

‎playlists-prod/excel.yaml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -403,6 +403,15 @@
403403
group: Data Types
404404
api_set:
405405
ExcelApi: '1.16'
406+
- id: excel-data-types-basic-types
407+
name: Basic types with metadata
408+
fileName: data-types-basic-types.yaml
409+
description: This sample shows how to work with metadata on basic types.
410+
rawUrl: >-
411+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/excel/20-data-types/data-types-basic-types.yaml
412+
group: Data Types
413+
api_set:
414+
ExcelApi: '1.19'
406415
- id: excel-data-validation
407416
name: Data validation
408417
fileName: data-validation.yaml

‎playlists/excel.yaml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -403,6 +403,15 @@
403403
group: Data Types
404404
api_set:
405405
ExcelApi: '1.16'
406+
- id: excel-data-types-basic-types
407+
name: Basic types with metadata
408+
fileName: data-types-basic-types.yaml
409+
description: This sample shows how to work with metadata on basic types.
410+
rawUrl: >-
411+
https://raw.githubusercontent.com/OfficeDev/office-js-snippets/main/samples/excel/20-data-types/data-types-basic-types.yaml
412+
group: Data Types
413+
api_set:
414+
ExcelApi: '1.19'
406415
- id: excel-data-validation
407416
name: Data validation
408417
fileName: data-validation.yaml

‎samples/excel/20-data-types/data-types-basic-types.yaml

Lines changed: 362 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,362 @@
1+
order: 8
2+
id: excel-data-types-basic-types
3+
name: Basic types with metadata
4+
description: This sample shows how to work with metadata on basic types.
5+
host: EXCEL
6+
api_set:
7+
ExcelApi: '1.19'
8+
script:
9+
content: |-
10+
document.getElementById("setup").addEventListener("click", () => tryCatch(setup));
11+
document.getElementById("set-basic-types-with-metadata").addEventListener("click", () => tryCatch(setBasicTypesWithMetadata));
12+
document.getElementById("set-referenced-values").addEventListener("click", () => tryCatch(setReferencedValues));
13+
document.getElementById("set-circular-reference-values").addEventListener("click", () => tryCatch(setCircularReferenceValues));
14+
document.getElementById("print-to-console").addEventListener("click", () => tryCatch(printToConsole));
15+
16+
const sheetName = "Sample";
17+
18+
/** Add basic types with metadata to the worksheet. */
19+
async function setBasicTypesWithMetadata() {
20+
await Excel.run(async (context) => {
21+
// Get the worksheet and target range.
22+
const sheet = context.workbook.worksheets.getItem(sheetName);
23+
const dataRange = sheet.getRange("A1:A4");
24+
25+
// Write a variety of basic types with metadata to the range.
26+
dataRange.valuesAsJson = [
27+
[doubleWithFormatAndMetadata],
28+
[doubleWithMetadata],
29+
[stringWithMetadata],
30+
[booleanWithMetadata]
31+
];
32+
33+
dataRange.format.autofitColumns();
34+
await context.sync();
35+
});
36+
}
37+
38+
/** Set basic types with metadata that reference other basic types in the worksheet. */
39+
async function setReferencedValues() {
40+
await Excel.run(async (context) => {
41+
// Get the worksheet and target range.
42+
const sheet = context.workbook.worksheets.getItem(sheetName);
43+
const targetRange = sheet.getRange("A5");
44+
45+
// Write a string with metadata that references other values.
46+
targetRange.valuesAsJson = [
47+
[stringWithReferencedValues]
48+
];
49+
targetRange.format.autofitColumns();
50+
51+
await context.sync();
52+
});
53+
}
54+
55+
/** Set basic types with metadata that contain circular references. */
56+
async function setCircularReferenceValues() {
57+
await Excel.run(async (context) => {
58+
// Get the worksheet and target range.
59+
const sheet = context.workbook.worksheets.getItem(sheetName);
60+
const targetRange = sheet.getRange("A6");
61+
62+
// Write a string with metadata that contains circular references.
63+
targetRange.valuesAsJson = [
64+
[stringWithCircularReferences]
65+
];
66+
targetRange.format.autofitColumns();
67+
68+
await context.sync();
69+
});
70+
}
71+
72+
/** Get and log information about the basic types in the worksheet. */
73+
async function printToConsole() {
74+
await Excel.run(async (context) => {
75+
// Get the worksheet and target range.
76+
const sheet = context.workbook.worksheets.getItem(sheetName);
77+
const dataRange = sheet.getRange("A1:A6");
78+
79+
// Load the data type property of the range.
80+
dataRange.load("valuesAsJson");
81+
await context.sync();
82+
83+
const dataValues = dataRange.valuesAsJson;
84+
85+
// Print information about the data types to the console.
86+
console.log("Basic types as an array:", dataValues);
87+
});
88+
}
89+
90+
/** Set up Sample worksheet. */
91+
async function setup() {
92+
await Excel.run(async (context) => {
93+
// Create a new worksheet and activate it.
94+
context.workbook.worksheets.getItemOrNullObject(sheetName).delete();
95+
const sheet = context.workbook.worksheets.add(sheetName);
96+
sheet.activate();
97+
98+
await context.sync();
99+
});
100+
}
101+
102+
/** Default helper for invoking an action and handling errors. */
103+
async function tryCatch(callback) {
104+
try {
105+
await callback();
106+
} catch (error) {
107+
// Note: In a production add-in, you'd want to notify the user through your add-in's UI.
108+
console.error(error);
109+
}
110+
}
111+
112+
/** Basic string value with metadata. */
113+
const basicStringValue: Excel.StringCellValue = {
114+
type: Excel.CellValueType.string,
115+
basicType: Excel.CellValueType.string,
116+
basicValue: "This is a basic string value"
117+
};
118+
119+
/** Basic double value with metadata. */
120+
const basicDoubleValue: Excel.DoubleCellValue = {
121+
type: Excel.CellValueType.double,
122+
basicType: Excel.CellValueType.double,
123+
basicValue: 10
124+
};
125+
126+
/** Basic boolean value with metadata. */
127+
const basicBooleanValue: Excel.BooleanCellValue = {
128+
type: Excel.CellValueType.boolean,
129+
basicType: Excel.CellValueType.boolean,
130+
basicValue: true
131+
};
132+
133+
/** Web image cell value. */
134+
const imageCellValue: Excel.WebImageCellValue = {
135+
type: "WebImage",
136+
basicType: "Error",
137+
basicValue: "#VALUE!",
138+
address: "https://github.com/OfficeDev/office-js-snippets/blob/main/.github/images/microsoft-logo.png?raw=true",
139+
};
140+
141+
/** Basic view layout with icon for card and compact views. */
142+
const basicViewLayoutWithIcon: Excel.BasicViewLayouts = {
143+
card: {
144+
title: "This is the title",
145+
sections: [
146+
{
147+
layout: "List",
148+
properties: ["stringProperty", "booleanProperty", "doubleProperty"],
149+
collapsed: false,
150+
collapsible: true
151+
}
152+
],
153+
subTitle: {
154+
property: "stringProperty"
155+
},
156+
mainImage: {
157+
property: "imageProperty"
158+
}
159+
},
160+
compact: {
161+
icon: Excel.EntityCompactLayoutIcons.animalDog
162+
}
163+
};
164+
165+
/** Simple view layout without icon. */
166+
const basicViewLayoutSimple: Excel.BasicViewLayouts = {
167+
card: {
168+
title: "This is the title",
169+
subTitle: {
170+
property: "stringProperty"
171+
}
172+
}
173+
};
174+
175+
/** Cell value provider attributes for data source attribution. */
176+
const cellValueProvider: Excel.CellValueProviderAttributes = {
177+
description: "Microsoft Bing",
178+
logoSourceAddress: "https://github.com/OfficeDev/office-js-snippets/blob/main/.github/images/microsoft-logo.png?raw=true",
179+
logoTargetAddress: "http://microsoft.com"
180+
};
181+
182+
/** Double value with formatting and metadata. */
183+
const doubleWithFormatAndMetadata: Excel.DoubleCellValue = {
184+
type: Excel.CellValueType.double,
185+
basicType: Excel.CellValueType.double,
186+
basicValue: 300,
187+
numberFormat: "$0.00",
188+
properties: {
189+
stringProperty: basicStringValue,
190+
booleanProperty: basicBooleanValue,
191+
doubleProperty: basicDoubleValue,
192+
imageProperty: imageCellValue
193+
},
194+
layouts: basicViewLayoutWithIcon,
195+
provider: cellValueProvider
196+
};
197+
198+
/** Double value with metadata but no special formatting. */
199+
const doubleWithMetadata: Excel.DoubleCellValue = {
200+
type: Excel.CellValueType.double,
201+
basicType: Excel.CellValueType.double,
202+
basicValue: 123.45,
203+
properties: {
204+
stringProperty: basicStringValue,
205+
booleanProperty: basicBooleanValue,
206+
doubleProperty: basicDoubleValue,
207+
imageProperty: imageCellValue
208+
},
209+
layouts: basicViewLayoutSimple,
210+
provider: cellValueProvider
211+
};
212+
213+
/** String value with metadata. */
214+
const stringWithMetadata: Excel.StringCellValue = {
215+
type: Excel.CellValueType.string,
216+
basicType: Excel.CellValueType.string,
217+
basicValue: "String with metadata",
218+
properties: {
219+
stringProperty: basicStringValue,
220+
booleanProperty: basicBooleanValue,
221+
doubleProperty: basicDoubleValue,
222+
imageProperty: imageCellValue
223+
},
224+
layouts: basicViewLayoutWithIcon,
225+
provider: cellValueProvider
226+
};
227+
228+
/** Boolean value with metadata. */
229+
const booleanWithMetadata: Excel.BooleanCellValue = {
230+
type: Excel.CellValueType.boolean,
231+
basicType: Excel.CellValueType.boolean,
232+
basicValue: true,
233+
properties: {
234+
stringProperty: basicStringValue,
235+
booleanProperty: basicBooleanValue,
236+
doubleProperty: basicDoubleValue,
237+
imageProperty: imageCellValue
238+
},
239+
layouts: basicViewLayoutSimple,
240+
provider: cellValueProvider
241+
};
242+
243+
/** String with metadata that references other values. */
244+
const stringWithReferencedValues = {
245+
type: Excel.CellValueType.string,
246+
basicType: Excel.CellValueType.string,
247+
basicValue: "String with referenced values",
248+
properties: {
249+
stringProperty: {
250+
type: Excel.CellValueType.reference,
251+
reference: 0
252+
},
253+
booleanProperty: {
254+
type: Excel.CellValueType.reference,
255+
reference: 1
256+
},
257+
doubleWithFormatProperty: {
258+
type: Excel.CellValueType.reference,
259+
reference: 2
260+
},
261+
doubleProperty: {
262+
type: Excel.CellValueType.reference,
263+
reference: 3
264+
}
265+
},
266+
referencedValues: [stringWithMetadata, booleanWithMetadata, doubleWithFormatAndMetadata, doubleWithMetadata],
267+
layouts: {
268+
compact: {
269+
icon: Excel.EntityCompactLayoutIcons.apple
270+
}
271+
}
272+
};
273+
274+
/** String with metadata that contains circular references. */
275+
const stringWithCircularReferences = {
276+
type: Excel.CellValueType.string,
277+
basicType: Excel.CellValueType.string,
278+
basicValue: "String with circular references",
279+
properties: {
280+
doubleProperty: {
281+
type: Excel.CellValueType.double,
282+
basicType: Excel.CellValueType.double,
283+
basicValue: 10,
284+
properties: {
285+
stringProperty: basicStringValue,
286+
doubleProperty: basicDoubleValue,
287+
booleanProperty: basicBooleanValue,
288+
rootProperty: {
289+
type: Excel.CellValueType.reference,
290+
reference: 0
291+
}
292+
},
293+
referencedValues: [
294+
{
295+
type: Excel.ReferenceValueType.root
296+
}
297+
]
298+
}
299+
},
300+
layouts: {
301+
compact: {
302+
icon: Excel.EntityCompactLayoutIcons.animalTurtle
303+
}
304+
}
305+
};
306+
language: typescript
307+
template:
308+
content: |-
309+
<section class="ms-Fabric ms-font-m">
310+
<p>This sample shows how to create basic types with metadata and then work with those basic types.</p>
311+
</section>
312+
<section class="ms-Fabric setup ms-font-m">
313+
<h3>Set up</h3>
314+
<button id="setup" class="ms-Button">
315+
<span class="ms-Button-label">Add worksheet</span>
316+
</button>
317+
</section>
318+
<section class="ms-Fabric samples ms-font-m">
319+
<h3>Try it out</h3>
320+
<p>Add basic types to the worksheet. Select the icon in each cell to see a data type card with metadata.</p>
321+
<button id="set-basic-types-with-metadata" class="ms-Button">
322+
<span class="ms-Button-label">Create basic types with metadata</span>
323+
</button>
324+
</section>
325+
<section class="ms-Fabric samples ms-font-m">
326+
<p>Add a basic type with referenced values. Open the data type card to see other values in the worksheet that this basic type references&mdash;it references cells <strong>A1</strong>, <strong>A2</strong>, <strong>A3</strong>, and <strong>A4</strong>.</p>
327+
<button id="set-referenced-values" class="ms-Button">
328+
<span class="ms-Button-label">Create basic type with referenced values</span>
329+
</button>
330+
</section>
331+
<section class="ms-Fabric samples ms-font-m">
332+
<p>Add a basic type with circular references. Open the data type card and select the <strong>doubleProperty</strong> to see the circular references.</p>
333+
<button id="set-circular-reference-values" class="ms-Button">
334+
<span class="ms-Button-label">Create basic type with circular references</span>
335+
</button>
336+
</section>
337+
<section class="ms-Fabric samples ms-font-m">
338+
<p>Print information about each of your basic types to the console.</p>
339+
<button id="print-to-console" class="ms-Button">
340+
<span class="ms-Button-label">Print basic types to console</span>
341+
</button>
342+
</section>
343+
language: html
344+
style:
345+
content: |-
346+
section.samples {
347+
margin-top: 20px;
348+
}
349+
350+
section.samples .ms-Button, section.setup .ms-Button {
351+
display: block;
352+
margin-bottom: 5px;
353+
margin-left: 20px;
354+
min-width: 80px;
355+
}
356+
language: css
357+
libraries: |-
358+
https://appsforoffice.microsoft.com/lib/1/hosted/office.js
359+
https://appsforoffice.microsoft.com/lib/1/hosted/office.d.ts
360+
361+
https://unpkg.com/[email protected]/dist/css/fabric.min.css
362+
https://unpkg.com/[email protected]/dist/css/fabric.components.min.css

0 commit comments

Comments
 (0)