Skip to content

HalDocument

Mihael Safaric edited this page Jul 27, 2020 · 14 revisions

When fetching a list of resources, some other data may be retrieved in the response (ie. pagination information).

Note: HalDocument is opinionated. If behaviours of HalDocument are not fully suitable for your case, you can create an additional class which extends HalDocument and then use that class instead of pure HalDocument class. A custom HalDocument class can be set on a model level (see ModelConfig) or on a datastore level (see DatastoreConfig).

When an instance of HalDocument is created, it gets a few parameters in the constructor:

  • rawResource: RawHalResource

    • HAL formatted object fetched from the server
  • rawResponse: HttpResponse<any>

    • raw HTTP response fetched from the server
  • modelClass: ModelConstructor<T>

    • model class which will be used for creating models
  • datastore: DatastoreService

Once instantiated, HalDocument parses rawResponse and generates models and pagination properties.

Properties

  • models: Array<Model>

    • instances of modelClass class which is passed through the constructor
  • pagination: Pagination

    • instance of Pagination class
    • TODO make a way to override Pagination class on DatastoreService level, and on ModelService level
  • hasEmbeddedItems: boolean

    • returns true if list items were included in the first HTTP request
  • itemLinks: Array<RawHalLink>

    • returns links to the specific list items
  • selfLink: string

    • GET: returns URL to the resource

Methods

getPage

getPage<T extends HalModel>(pageNumber: number, includeRelationships?: Array<string>, requestOptions?: RequestOptions, subsequentRequestsOptions: RequestOptions): Observable<HalDocument<T>>;
  • it fetches the specific page by making a GET call to /ResourceName with page query parameter (it calls find method on Datastore service)

  • it doesn't change the value of halDocument.models (which returns the first page)

  • requestOptions: RequestOptions

    • optional
    • additional request options
    • those options will be used only for the main request, custom options for relationship calls can be set via subsequentRequestsOptions
  • subsequentRequestsOptions: RequestOptions

    • optional
    • when specified, the specified request options will be used for the relationship calls which do not have request options specified through includeRelationships parameter
    • if the specific relationship has request options specified in includeRelationships, subsequentRequestsOptions will be ignored for that API call