Original subtitles

1 1

Let's now analyze what we get in this 2

2

project folder we created. 3

3

I opened it here in Visual Studio Code, 4

4

and before we dive into the folders and files we got here, 5

5

two things. 6

6

First of all, the look of my IDE here. 7

7

If you don't have the same one, and you want the same one, 8

8

under File, Preferences, 9

9

Color Theme, you can pick the color theme, 10

10

and I'm using the Dark+ theme here. 11

11

Now, in addition, you very likely have different folder 12

12

and file icons. 13

13

You get the same ones as I do if you go to View, Extensions, 14

14

and you there search for Material Icon. 15

15

Visual Studio Code has support for community extensions, 16

16

and that is a visual extension, 17

17

so not related to Power BI Visuals, 18

18

but simply affecting how my IDE looks like, 19

19

and I got this Material Icon theme installed. 20

20

And the effect of this theme 21

21

is simply that the folders and files have different icons. 22

22

So, that's pure cosmetics, 23

23

you don't need that, but if you want it, 24

24

that's how you get this look. 25

25

With that, let's analyze what we got here, 26

26

and let's start at the top. 27

27

The .vscode folder is a pure editor configuration folder. 28

28

The two files it holds just configure my IDE here, 29

29

and therefore if you are using a different IDE, 30

30

for example, you don't even need them, 31

31

you might not even have them, and you can fully ignore that. 32

32

The assets folder holds a icon.png file, 33

33

which is a image. 34

34

And in general, if your visual would use more images, 35

35

you would put them there, 36

36

because from there you could use them in your code layer. 37

37

Since your visual is, in the end, 38

38

just a combination of HTML, CSS, and JavaScript, 39

39

which are all web technologies, 40

40

you can also embed and use images. 41

41

Because in the end, your visual is just a mini-website 42

42

hosted by Power BI's service, you would say, 43

43

and therefore anything you can use on a website 44

44

can be generally be also be used in your visual, 45

45

and images are a part of that. 46

46

In addition here, you would set up the icon 47

47

your visual uses in the toolset 48

48

when users want to use your visual, 49

49

and that becomes important when we later package our visual, 50

50

and I'll come back to that, well, later. 51

51

The dist folder will later then hold our packaged up visual, 52

52

which is ready to share with other users. 53

53

Currently it's empty, 54

54

because we're still in development mode, 55

55

we're still working on the visual. 56

56

The node_modules folder holds extra project dependencies 57

57

which we have here. 58

58

Our project here uses TypeScript, 59

59

and when we write the code, 60

60

we don't want to reinvent the wheel 61

61

for everything we do, 62

62

and we will use third-party libraries 63

63

to make certain things easier for us as a developer. 64

64

Those libraries are automatically managed 65

65

and stored here in the node_modules folder, 66

66

and therefore you shouldn't edit this folder, 67

67

it will be managed for you. 68

68

In here, for example, you find a bunch of folders 69

69

that are related to d3, 70

70

which is a package we'll later use to 71

71

draw something onto the screen. 72

72

Now, the src folder holds two .ts files, 73

73

and .ts, of course, stands for TypeScript. 74

74

These are the files that hold the actual code 75

75

you're going to write, and you're going to work in, 76

76

and these are the files we're going to edit 77

77

throughout this module. 78

78

I'll come back to those in more detail later therefore. 79

79

The style folder holds the visual.less file. 80

80

Now, styling is done with a language that's called Less, 81

81

and Less is a bit like TypeScript for JavaScript, 82

82

Less is an extension to CSS. 83

83

And CSS is the official web styling language, you could say. 84

84

You can also write regular CSS code in here if you want, 85

85

but Less adds some extra features. 86

86

And for example here, if I change yellow to red, 87

87

and this pbiviz start process is still running, 88

88

if we go back to our preview and we reload, 89

89

you see now the background here is red. 90

90

So, that's how these things are related. 91

91

And then below that we got a bunch of configuration files. 92

92

capabalities.json, for example, 93

93

controls how Power BI's service 94

94

is able to communicate with our visual. 95

95

For example, what can be configured 96

96

from in that Power BI service, 97

97

which configuration options are exposed to the end-user. 98

98

So, that's basically a technical document 99

99

describing how our visual in code, 100

100

and our visual in Power BI's service are able to interact. 101

101

Now, in here we can actually delete something, 102

102

and that's this objects node. 103

103

You can fold it by hovering here on the left 104

104

and clicking on that arrow, 105

105

and that makes it easy to remove the entire objects node. 106

106

We don't need it here, and I'll come back to it later, 107

107

so delete it and save the file thereafter. 108

108

package-lock.json and package.json 109

109

are project management files. 110

110

They manage the dependencies of our project, 111

111

and a couple of other things, 112

112

but the dependencies are the most important part. 113

113

So basically, here we specify third-party packages 114

114

our project uses, like for example d3, 115

115

this visualization package, 116

116

which we will use later to draw something onto the screen. 117

117

Now, dependencies stored here 118

118

are in the end the project's, and their dependencies, 119

119

which are stored in node_modules. 120

120

That's how this file gets managed in the end. 121

121

If you would share 122

122

your entire project with another developer, 123

123

you could also delete the node_modules folder 124

124

because it's quite a big folder, 125

125

so to make it smaller you could delete it, 126

126

and as long as the package.json file is there, 127

127

it's easy to recreate this node_modules folder. 128

128

All that would need to be done is that 129

129

in your project folder, 130

130

and that's why I'll temporarily quit pbiviz start, 131

131

in your project folder you can run npm install, 132

132

and that will look at the package.json file 133

133

and install all those dependencies, 134

134

and their dependencies, into your node_modules folder, 135

135

and it would recreate that folder if it's missing, 136

136

but that's just a side note. 137

137

With that, I'm going to bring this pbiviz start process 138

138

back up, so that we can continue developing. 139

139

Now, the pbiviz.json file is in every configuration file 140

140

for our visual. 141

141

And at least for me here, it's quite unreadable, 142

142

but we can right-click into it and choose Format Document, 143

143

or use the shortcut, 144

144

to auto format this code to be more readable. 145

145

Now, here we can configure our visual, 146

146

but whereas capabilities.json 147

147

is basically a file that tells Power BI's service 148

148

how to use our visual, 149

149

pbiviz.json is a file that is meant for humans. 150

150

Of course, not like this, 151

151

but the information we store in there, 152

152

like the description, or the displayName of our visual, 153

153

that's all information that shows up in different places. 154

154

For example, in Power BI's service, 155

155

or if we package and share our visual 156

156

in things like the AppSource market. 157

157

So, the configuration here is basically meant for humans. 158

158

Generally, the configuration here 159

159

is meant for Power BI's service. 160

160

Now, there are some items in pbiviz.json 161

161

which are also meant our project setup 162

162

and for the computer in the end, 163

163

and that's, for example, assets, 164

164

where we define which assets we're using. 165

165

That's the style configuration here, 166

166

where we basically make clear where our styles are defined, 167

167

that it's in the visual.less file in the style folder. 168

168

And if you would for example change the filename 169

169

of visual.less, you would therefore need to update it here. 170

170

But we can keep all the defaults. 171

171

We don't need to add in anything here. 172

172

I'll just save the file because I reformatted it. 173

173

Now, the other three files here 174

174

are there to configure TypeScript, 175

175

that programming language we're using, 176

176

and unless you really know what you're doing, 177

177

you can therefore definitely stick 178

178

to the defaults there as well. 179

179

Now with that, let's go back 180

180

to these TypeScript files up there. 181

181

And we can actually delete the settings.ts file, 182

182

we don't need it here. 183

183

And then visual.ts, we can delete all 184

184

that green text here at the beginning, 185

185

that's a comment, which we don't need. 186

186

And now let's see what we have in this file. 187

187

In there, we got a bunch of imports. 188

188

Imports are a language feature 189

189

that ties different files together. 190

190

They basically help the project know 191

191

where certain features are coming from, 192

192

and if you're using a certain feature in a file, 193

193

you need to specify a import to tell, 194

194

let's say the programming language, 195

195

where to find that feature. 196

196

And for example here, 197

197

we had a import where we imported something 198

198

from that file we just deleted. 199

199

Since I deleted the file, 200

200

I can also delete this import here. 201

201

Below that, we have a so called class. 202

202

A class is a language construct 203

203

which basically is best described 204

204

as a blueprint for an object. 205

205

But that of course leads us to the next question, 206

206

what's an object? 207

207

And object is a data structure in programming, 208

208

and in the end, our visual, in code to the computer, 209

209

is such an object. 210

210

Full of information, of commands, and of data. 211

211

And Power BI's service, again, consumes our object. 212

212

So, we're building, or we're defining an object here, 213

213

and Power BI's service is then able to use it. 214

214

Now, this class has some properties. 215

215

These four things here are so-called properties, 216

216

that's basically data that's stored in this object, 217

217

data that we can use in our code, 218

218

or data that Power BI's service might be using. 219

219

Now, that's actually data we only use in our code here. 220

220

And then we got two so-called methods, 221

221

the constructor method and the update method. 222

222

We actually got more, but let's focus on those two. 223

223

Methods are basically commands that can be executed. 224

224

So, that's code on demand, as I like to call it. 225

225

And these two methods are required by Power BI's service 226

226

to bring something onto the screen, 227

227

and to update it whenever out data changes. 228

228

To be precise, the constructor here 229

229

has all the code that runs when the visual is loaded 230

230

and constructed for the first time. 231

231

The update method here, on the other hand, 232

232

has the code that should execute 233

233

whenever the data attached to our visual changes. 234

234

So here for example, if I add and remove data, 235

235

this triggers the update method. 236

236

And the other methods down there 237

237

are utility methods that were part of that default visual, 238

238

which we don't need per se though, 239

239

and which we therefore can just delete. 240

240

Now, how does Power BI's service know 241

241

that it should run the update method 242

242

whenever our data changes though? 243

243

We could have any method name after all here, 244

244

it's our code, so I could have named this whatever. 245

245

Well, actually now we're getting an error up here 246

246

that our class Visual incorrectly implements the interface 247

247

IVisual. 248

248

That's this part here. 249

249

This class implements something, 250

250

it implements a so-called interface, 251

251

and an interface basically is a contract 252

252

that forces us to add certain features to this class. 253

253

To be precise, this IVisual contract, 254

254

which we signed by implementing this interface, 255

255

forces us to have an update method. 256

256

And that happens to ensure 257

257

that Power BI's service is able to call an update method, 258

258

because Power BI's service wants an update method. 259

259

It only knows how to call a method named update 260

260

when our data changed. 261

261

So, in order to ensure that we have such a method 262

262

and we don't, by accident for example, 263

263

name this method differently, 264

264

our visuals should implement this contract 265

265

because this contract tells us that we need that method, 266

266

and if we then should accidentally forget it 267

267

or name it differently, we get an error which we can fix. 268

268

So, that's simply a extra, you could say, security mechanism 269

269

for us as a developer 270

270

to make sure that we're writing proper code. 271

271

That's the big picture. 272

272

It will certainly all become a bit clearer 273

273

as we write code, and as we develop our visual. 274

274

For the moment, we can do more cleanup work. 275

275

We can delete these four properties, 276

276

and we can actually also delete 277

277

all the code in the constructor, 278

278

not the constructor itself though, just the code in there, 279

279

and all the code in update. 280

280

And now we can also delete all the imports 281

281

which are now slightly grayed out, 282

282

in my case the imports from line 10 to line 13. 283

283

With that, this is a pretty clean and lean file, 284

284

and we can now use that file 285

285

to build our visual from the ground up. 286

286

Of course, if you know reload here and Power BI's service, 287

287

you won't see anything because now we deleted all the code, 288

288

so what should be displayed here? 289

289

But that's where we're going to pick up on, 290

290

and that's where we will continue with.