Within components you may sometimes need access to a specific child element. To accomplish this, the framework allows for declaratively querying for elements, inspired by Angular's @ViewChild
/@ViewChildren
approach.
When only a single element is expected, use the @BlueriqChild
decorator on a field:
The property bindings will be kept in sync as elements come and go. Please note that the properties will not be available inside of the constructor, as the queries have not been evaluated at that time. In any of Angular's lifecycle hooks you will however be able to access the query results.
Optionally, a Blueriq selector is accepted as second argument, in between the element type and optional options object. The options are as follows:
false
true
in which case the property may also receive an undefined
value. Therefore, we recommend to include undefined
in the type specification as shown in the example above to make it obvious that all code paths have to deal with the element being possibly undefined
. By enabling TypeScript's strictNullChecks
option, the TypeScript compiler will guard against unchecked usage of the property.false
false
Observable
that you may subscribe to to receive updates. Upon subscription you will immediately receive the most recent query result. It is not guaranteed that the resulting element has actually changed when the observable emits.false
bqIncluded
pipe will skip over it when rendering children. This is useful in the situation where you need to extract a certain element out of the page but still need to render all other children as usual, in which case the excluded element will be skipped over.When multiple elements are expected, use the @BlueriqChildren
decorator on a field:
The property bindings will be kept in sync as elements come and go. Please note that the properties will not be available inside of the constructor, as the queries have not been evaluated at that time. In any of Angular's lifecycle hooks you will however be able to access the query results.
Optionally, a Blueriq selector is accepted as second argument, in between the element type and optional options object. The options are as follows:
false
true
in which case a descriptive exception will be thrown when no matching elements can be found.false
false
Observable
that you may subscribe to to receive updates. Upon subscription you will immediately receive the most recent query results as an array. It is not guaranteed that the resulting elements have actually changed when the observable emits.false
bqIncluded
pipe will skip over when rendering children. This is useful in the situation where you need to extract certain elements out of the page but still need to render all other children as usual, in which case the excluded elements will be skipped over.As briefly discussed above in the available options, the querying mechanism allows for excluding an element. Together with the bqIncluded
pipe, an element that has been excluded will be skipped from rendering. This is useful in the situation where you need to extract a certain element from the page to render differently from other elements, while still needing to show all other children normally.
The bqElement
directive will render an element even in the case it has been excluded. This is by design, as it allows to query for an element in order to show it in a custom location, but still use its dedicated component.
For an excluded element to be actually skipped from rendering, the
bqIncluded
pipe must be used everywhere when rendering an element's children.
The framework is only able to automatically identify @BlueriqChild
/@BlueriqChildren
decorators in Blueriq components. Angular services that want to use @BlueriqChild
/@BlueriqChildren
need to attach themselves to the querying engine manually:
In contrast to components, ngOnInit
is not called for Angular services. As shown in the example above, the queried properties will be available immediately after you have attached the querying engine.
You must take care of detaching the service from the query engine when the service is destroyed, otherwise memory leaks will occur.
Note that BlueriqQuerying
service is only present within the component tree and not in services provided by an Angular module. Hence, such services must be provided by components themselves:
By default, the injected BlueriqQuerying
service is bound to the current Blueriq element to start querying from, corresponding with the Container
in above example. If you need to query from a different element, pass it as secondary argument when attaching.
With the ability to let Angular services query the Blueriq element tree, we recommend complex Blueriq tree structures to be represented by "structure services" that are reusable across components. These services may then contain logic to transform the Blueriq element tree into a representation that better fits the view.
The Blueriq framework ships with structure services for tables and pagination structures.