ARCHITECTURE.md

Architecture

More insight information about the way material-tools works.

Quick Links

• Creating a custom Material Build
• Creating a static theme stylesheet
• How to run AngularJS in NodeJS
• Why are some files manually compiled
• Under-the-Hood: Understanding the Virtual Context

Creating a custom Material Build

Material Tools for AngularJS Material allows developers to build a subset of the AngularJS Material framework with specific components.

As a developer you could just specify the given components and material-tools will run AngularJS Material in the NodeJS environment.

Read more about running an AngularJS module in NodeJS

The tools will then resolve all dependencies of the specified modules and fetch all required files.

Some type of files are going to be manually compiled by tools to have more control about the output.
Read more why some files need to be compiled manually.

At the end all generated output files will be written to a given folder or can be also accessed from NodeJS

Each output file will be also available with compressed / minified content.
Read more about the files, which will be generated

Creating a static theme stylesheet

Another great feature of Material Tools for AngularJS Material is the generation of a static theme stylesheet.

You may have noticed that in AngularJS Material the generation of the themes inside of the browser could damage the performance. Especially storing the generated styles in <style> elements in the documents head is not really efficient.

The browser is not able to make any optimizations, and it also takes a while to be able to see the styles in action.

This issue can be solved by having a static theme stylesheet.

To be able to build a static theme stylesheet the tools need to be able to access the $mdTheming service.

As part of the Virtual Context, we also hook into the AngularJS prototype to build our own injector, which includes all services, directives, providers and more.

This allows us to access the $mdThemingProvider, which is responsible for configuring the theme. Once you configure the theme, we instantiate our service by calling the $get method of the provider.

After instantiating the $mdTheming service we could run the theme generation and hook into the mocked document.head

The head will contain the generated theme styles as <style> elements, which will be extracted then.

How to run AngularJS in NodeJS

To be able to run an AngularJS module in NodeJS, the tools need to mock a browser environment.

Material Tools for AngularJS Material only mocks the most necessary parts of the browser. This keeps the mock as small as possible.

Material Tools for AngularJS Material assigns this created mock to the global window variable.

NodeJS binds the global window variable to globals, which is shared between all files.

This can lead to situations, where the tools are interfering with the user's build process.

• The mock is polluting the globals of NodeJS.
• The NodeJS module cache will be polluted with wrong exports.

Read more about the way we solved that issue with the Virtual Context.

Why are some type of files compiled manually

Some developers are expecting Material Tools for AngularJS Material to export the AngularJS Material stylesheet without the layouts included by default.

Since the core module of AngularJS Material always includes the layouts by default, we are not able to retrieve the core module without the layouts included.

To work around this issue, we have to manually compile the core module with explicitly excluding the layout stylesheets.

Under-the-Hood: Understanding the Virtual Context

Material Tools for AngularJS Material places a high value on the isolation of the modified NodeJS environment.

The Virtual Context allows the tools to run specific code completely isolated in another V8 context.
This not only isolates the given code, it also provides a minimalistic NodeJS environment.

You can require other files from the Virtual Context without leaving the isolated context.

A minimal require method has been created inside of the plain V8 context, which supports:

• Nesting of the isolated context
• Creating / Overwriting context global variables (e.g window)
• Enabling strict mode

The Virtual Context plays an important role in Material Tools for AngularJS Material, because it allows us to completely isolate our changes from the original NodeJS context. It also allows us to overwrite the globals, as mentioned.

Overwriting the globals is important when running an AngularJS application in NodeJS.

That's why the Virtual Context is also responsible for mocking the most necessary parts of a browser to run an AngularJS application.