scope.md

What does scope even mean?

In the context of Heartwood "scope" specifically refers to an organization or a location that all operations, permissions, and data filter by for a particular session.

While a person is viewing one of your Skill Views, they may chose to only show information relevant for a specific location and later decide to change to another location.

It is up to you, the mightly skills developer, to honor any scope set (if it makes sense for your skill).

Global is a term used to let you know that an object is not tied to an organization or location.

You will need special permissions for your skill to emit global events.

Scoping your skill view's behaviors

You can let Heartwood take care of requiring a location or an organization to be selected by implementing getScope() in your skill view.

export default class RootSkillViewController extends AbstractSkillViewController<Args> {
  public getScope() {
    return ['organization', 'employed'];
  }
}

Valid scopes are: [organization,location,employed]. If you add employed the person viewing must actually work at the organization or location in scope. All these permissions are managed for you.

Loading scope

A Scope instance is passed to your Skill View Controller's load hook when invoked after first render.

export default class RootSkillViewController extends AbstractSkillViewController<Args> {
  public async load(options: SkillViewControllerLoadOptions<Args>) {
    const { scope } = options;

    //getting scope
    const organization = await scope.getCurrentOrganization();
    const location = await scope.getCurrentLocation();

    //setting scope
    scope.setCurrentOrganizationId(organization.id);
    scope.setCurrentLocationId(organization.id);
  }
}

Test scope

Test scope is accessible through the View Fixture. Make sure you have seeded some organizations and locations before starting!

@login()
export default class RenderingRootViewControllerTest extends AbstractLocationsViewsTest {
  @test()
  protected static isScopedByOrganization() {
    vcAssert.assertSkillViewScopedBy(this.vc, "organization");
    vcAssert.assertSkillViewNotScoped(this.vc); //will fail if
  }

  @test()
  @seed("organizations", 1)
  @seed("locations", 1)
  protected static async loadingSetsStartingLocation() {
    const scope = this.views.getScope();

    //getting scope
    const organization = await scope.getCurrentOrganization();
    const location = await scope.getCurrentLocation();

    //setting scope
    scope.setCurrentOrganization(organization.id);
    scope.setCurrentLocation(organization.id);
  }
}