import Property from 'f.lux/src/Property.js'

public class | source

Property

Direct Subclass:

ArrayProperty, CollectionProperty, IndexedProperty, IsolatedProperty, MapProperty, ObjectProperty, PrimitiveProperty

Indirect Subclass:

LifecycleProperty, ModelProperty, PojoEndpointProperty, RestEndpointProperty, TransientProperty, TransientsProperty

Base class for custom f.lux properties. A Property has a lifespan from when the state property is mapped until it is replaced/deleted. This differs from Shadow as its lifespan that lasts from the time of mapping until the state property is replaced/deleted OR the shadow property is invalidated due to a local change or a descendant property change.

Most shadow state properties can be implemented without writing a Property subclass, relying on autoshadowing, or defining the state structure using StateType along with one of the built-in property class createClass() static methods. The primary reason for writing a Property subclass is to tie into the f.lux property life-cycle.

This class provides an experimental check pointing api. Check pointing allows the state to be recorded at a point in time and then later reset to that point. This is handy when a form may accept changes and then allow the user to cancel the edit session.

Life cycle methods:

propertyWillShadow() - invoked just before a state property is going to be shadowed using this instance. Shadow state is not valid during this method.
propertyDidShadow() - property was shadowed and fully functional.
propertyChildInvalidated(childProperty, sourceProperty) - a child property mutation action has occurred and it's value will change in store's next update.
propertyDidUpdate() - state managed by this property has changed.
propertyWillUnshadow() - invoked just before the shadow property is removed from the shadow state because the state property being shadowed has been removed from the application state.

See:

Constructor Summary

Public Constructor
public	constructor(stateType: StateType) If a StateType is not passed to this constructor then one is located using StateType.from thus ensuring the f.lux shadowing process is defined for this property.

Member Summary

Public Members
public	[_ImplementationClass]: *
public	[_ShadowClass]: *
public	[_autoShadow]: *
public	[_checkpoint]: {"data": *}
public	[_impl]: *
public	[_initialState]: *
public	[_mixins]: *[]
public	[_parent]: *
public	[_pid]: *
public	[_readonly]: *
public	[_shader]: *
public	[_stateType]: *
public	[_store]: *

Method Summary

Public Methods
public	$$(): Property Use this.$$() in shadow methods to get access to the property.
public	autoShadow(): boolean Gets if autoshadowing is enabled for this property.
public	checkpoint() Copies the current actual state for later reset using Property#resetToCheckpoint.
public	clearCheckpoint() Clears an existing checkpoint created using Property#checkpoint.
public	create$(impl: *): Access Creates the object to be assigned to the shadow.$ property.
public	dotPath(): string Gets the path from root property using a dot (`.`) separator.
public	getCheckpoint(): * Gets the checkpoint state previously recorded using Property#checkpoint.
public	getInitialState(state: ): Gets the initial state for a property at the beginning of the property mounting process.
public	hasCheckpoint(): boolean Gets if an existing checkpoint has be created using Property#checkpoint.
public	initialState(): * Gets the result from StateType#computeInitialState.
public	isActive(): boolean Gets if the property is currently shadowing an actual state property.
public	isIsolated(): boolean Gets if property is an actual isolated property managed by the store.
public	isReadonly(): boolean Gets if the property allows for assignment through the shadow state, ie `todo.desc = "go skiing"`.
public	isRoot(): boolean Gets if this is the shadow state root property.
public	name(): string \| number The property name by which this property is referenced by the Property.parent.
public	nextState(): * Gets what the actual state for this property will be after the Store updates all pending actions.
public	owner(): Property Gets the object containing or managing this property.
public	parent(): Property Gets the parent property.
public	parentShadow(): Shadow Gets the parent's shadow property.
public	path(): [] Gets the Property#name components from the root property to this property.
public	pid(): number Gets the unique f.lux ID for this property.
public	propertyChildInvalidated(childProperty: Property, sourceProperty: Property) A child property or one of its descendents wil be changing state.
public	propertyDidShadow() Invoked by the f.lux shadowing process after a property initially shadows a state property.
public	propertyDidUpdate() Invoked by the f.lux shadowing process after a property is reshadowed.
public	propertyWillShadow() Invoked by the f.lux shadowing process just before a property initially shadows a state property.
public	propertyWillUnshadow() Invoked by the f.lux shadowing process just before a property will be removed from the shadow state.
public	resetToCheckpoint() Replaces the current property state with a checkpoint state previously recorded using Property#checkpoint.
public	root(): Property Gets the shadow state root property for the Store managing this property.
public	rootShadow(): Shadow Gets the root shadow state for the Store managing this property.
public	setAutoshadow(auto: boolean): * Sets the auto shadow property flag.
public	setImplementationClass(ImplClass: *)
public	setInitialState(state: *): Property Explicitly sets an initial state that will be used if the state tree does not have a value for this property.
public	setReadonly(readonly: *) Sets the readonly flag which will prevent an assignment from changing the value.
public	setShadowClass(ShadowClass: Shadow) Sets the class to be used for the shadow api
public	shader(state: ): Gets the Shader instance for this property.
public	shadowClass(): * Returns the Shadow subclass used to virtualize the state property.
public	slashPath(): string Gets the path from root property using a slash (`/`) separator.
public	state(): * Gets the actual state being shadowed.
public	stateType(): * Gets the StateType used for creating this property.
public	store(): * Gets the {@Link Store} containing the application state.
public	touch() Triggers a reshadow of the properties shadow state.
public	typeName(): * Gets this property's StateType.typeName value.
public	update(callback: function) Makes changes to the next proeprty state.

Public Constructors

public constructor(stateType: StateType) source

If a StateType is not passed to this constructor then one is located using StateType.from thus ensuring the f.lux shadowing process is defined for this property.

Params:

Name	Type	Attribute	Description
stateType	StateType	optional	a specialized StateType instance describing how f.lux should shadow this property.

Public Members

public [_ImplementationClass]: * source

public [_ShadowClass]: * source

public [_autoShadow]: * source

public [_checkpoint]: {"data": *} source

public [_impl]: * source

public [_initialState]: * source

public [_mixins]: *[] source

public [_parent]: * source

public [_pid]: * source

public [_readonly]: * source

public [_shader]: * source

public [_stateType]: * source

public [_store]: * source

Public Methods

public $$(): Property source

Use this.$$() in shadow methods to get access to the property. Useful in Property subclass @shadow methods since the method will be bound to the shadow. Exposing on the Property allows for the same code to work when called as a member function using this or called through a shadow function.

Return:

Property

the property instance (this)

public autoShadow(): boolean source

Gets if autoshadowing is enabled for this property. Unlike the Property#readonly shadowing attribute, autoshadowing is not hierarchically determined.

Return:

boolean

true if autoshadowing is enabled

public checkpoint() source

Copies the current actual state for later reset using Property#resetToCheckpoint. An existing checkpoint will take precedence over subsequent calls.

public clearCheckpoint() source

Clears an existing checkpoint created using Property#checkpoint.

public create$(impl: *): Access source

Creates the object to be assigned to the shadow.$ property. Subclasses can override this method to setup a chain of specialized accessors ($()). See Access for details on setting up specialized accessors. This is an advanced feature and rarely required.

Params:

Name	Type	Attribute	Description
impl	*

Return:

Access

a property accessor instance.

public dotPath(): string source

Gets the path from root property using a dot (.) separator. Suitable for using with the lodash result() function.

Return:

string

path with each component joined by a .

See:

https://lodash.com/docs/4.17.4#result

public getCheckpoint(): * source

Gets the checkpoint state previously recorded using Property#checkpoint.

Return:

*	the checkpoint data if checkpoint is set.

public getInitialState(state: ): source

Gets the initial state for a property at the beginning of the property mounting process. This implementation merges the StateType#initialStateWithDefaults, the initial state set using #setInitialState, and the state passed in from the existing store state. The store's state property values take precedence. The explicitly set initial state is used only when the state parameter is undefined.

Params:

Name	Type	Attribute	Description
state	*		the store's property state at the time of mounting.

Return:

*	merged state with the state parameter taking precedence if the initial state is set otherwise returns the state parameter. This base implementation simply returns the state parameter

public hasCheckpoint(): boolean source

Gets if an existing checkpoint has be created using Property#checkpoint.

Return:

boolean

true if a checkpoint has been recorded.

public initialState(): * source

Gets the result from StateType#computeInitialState.

Return:

public isActive(): boolean source

Gets if the property is currently shadowing an actual state property.

Return:

boolean

public isIsolated(): boolean source

Gets if property is an actual isolated property managed by the store. This implementation always returns false. Override to change behavior.

Return:

boolean

public isReadonly(): boolean source

Gets if the property allows for assignment through the shadow state, ie todo.desc = "go skiing". The readonly attribute is hierarchically determined through the parent property if not explicitly set.

Return:

boolean

true if assignment is not allowed

public isRoot(): boolean source

Gets if this is the shadow state root property.

Return:

boolean

true if this is the root property of the Store managing the application state.

public name(): string | number source

The property name by which this property is referenced by the Property.parent.

Return:

string | number

the name or undefined if not active. A string for an object child property and a nuber for an array element.

public nextState(): * source

Gets what the actual state for this property will be after the Store updates all pending actions.

Return:

*	the next state or `undefined` if not active.

public owner(): Property source

Gets the object containing or managing this property. All properties have an owner except the root property. Isolated properties are a case where a property is independently managed by the store so it can have an owner but not a parent.

Return:

Property

alias for Property#parent

public parent(): Property source

Gets the parent property.

Return:

Property

the parent property or undefined if this is the shadow state root.

public parentShadow(): Shadow source

Gets the parent's shadow property.

Return:

Shadow

public path(): [] source

Gets the Property#name components from the root property to this property.

Return:

[]	array where each name component is either a `string` or `number` depending on the each parent component's type.

public pid(): number source

Gets the unique f.lux ID for this property.

Return:

number

the id

public propertyChildInvalidated(childProperty: Property, sourceProperty: Property) source

A child property or one of its descendents wil be changing state. Useful hook when a property needs to perform some bookkeepng for child properties. Utilizing this hook provides a chance to make tracking changes in shadow properties before the store updates its state.