jwidget/hash

Consumption

import hash, {IHash} from "jwidget/hash";

Default export#

hash: IHash

Instance of IHash singleton. Provides a transparent Property-compatible interface over location.hash manipulations. Value of this property is always equal to location.hash without leading "#" symbol. Has a built-in protection against infinite redirections.

IHash#

Hierarchy#

Description#

Interface of hash object. Extension of IProperty<string> interface with updating status indicator and replaceState optional parameter of set method.

The built-in implementation of this interface also listens to "hashchange" DOM event to properly update own state. It makes this properly transparently mirror current browser location.hash value.

Fields#

updating#

readonly updating: boolean

Indicates if hash assignment is in progress at the moment. While updating is true, location.hash gets modified and changeEvent gets triggered. Checking this flag in corresponding event handlers may prevent infinite loops and unexpected callback conflicts.

iid (inherited from Identifiable)#

readonly iid: number

Instance ID.

Auto-incrementing object unique ID. Extend Class to have such an identifier auto-assigned, or simply call newIid method to obtain one.

changeEvent (inherited from Bindable)#

readonly changeEvent: Listenable<Bindable.ChangeEventParams<V>>

Property value has just been changed. Triggered in result of set method call if the value has been changed.

silent (inherited from Bindable)#

readonly silent: boolean

Checks if this property never triggers events. This knowledge may help you do certain code optimizations.

Methods#

set#

(value: string = "", replaceState?: boolean)

value
New hash value to assign.
replaceState
Replace the current browser historical state rather than pushing a new state to the stack. Pass this flag on any automated redirection to let browser properly handle "Back" button click.

Assigns location.hash to a new value (equal to "#" + value) and triggers changeEvent. Rises updating flag to prevent infinite loops and callback conflicts during this time.

Default implementation of this method provides an extra layer of infinite redirection protection. If more than 25 redirections occur during 1 second, the property blocks further assignments and writes an error into browser console listing all redirections that were supposed to happen.

ownValue (inherited from IProperty)#

(): this

returns
this

Makes this property an owner of its value. It means that the value is destroyed automatically on reassignment or destruction of the property.

destroy (inherited from IClass)#

(): void

Class destructor invocation method. Destroys all aggregated objects and releases all bindings. You must call this method explicitly from outside, because JavaScript doesn't support automatic class destructor calling.

const object = new MyClass();

// ...

// Once object is not needed anymore, destroy it
object.destroy();

Alternatively (and optimally), you should use own method to aggregate this object inside another one.

own (inherited from IClass)#

<T extends Destroyable>(obj: T): T

obj
Object to aggregate.
returns
obj

Aggregates the object. It means that the specified object is automatically destroyed on this object destruction. The aggregated objects are destroyed in reverse order. Returns obj object, which makes it easy to use in field definition:

private selected = this.own(new Property(false));
owning (inherited from IClass)#

(obj: Destroyable): this

obj
Object to aggregate.
returns
this

Aggregates the object. It means that the specified object is automatically destroyed on this object destruction. The aggregated objects are destroyed in reverse order. Returns this object, which makes it easy to use in object instantiation:

const items = new List();
return new Panel(items).owning(items);
get (inherited from Bindable)#

(): V

returns
Current property value.

Think twice before calling this method - probably it makes sense to use some kind of binding instead?

map (inherited from Bindable)#

<U>(create: (value: V) => U, config?: Mapper.Config<U>): DestroyableBindable<U>

create
Mapping function.
config
Configuration options.
returns
Mapped property.

Builds a new property containing the result of the create function called on this property value. To stop synchronization, destroy the resulting property. To map multiple properties at once, use Mapper.

Example 1. Double number
const num = new Property<number>(3);
const double = num.map(value => 2 * value);
expect(double.get()).toBe(6);
num.set(5);
expect(double.get()).toBe(10);

Pass destroy option to destroy the previously mapped values.

Example 2. Typical bindable model mapping to UI component
@template('<div><div jwid="report"></div></div>')
class App extends Component {
    constructor(private report: Bindable<Report>) {}

    protected renderReport() {
        return this.own(report.map(report => new ReportView(report), {destroy}));
    }
}

Pass viaNull option to reverse mapper updating flow. Default flow is:

  1. Create a new value.
  2. Reassign target property.
  3. Destroy the old value.

Setting this option to true changes the flow the next way:

  1. Set target value to null.
  2. Destroy the old value.
  3. Create a new value.
  4. Assign target property.