ORKNavigableOrderedTask Class Reference

Inherits from	ORKOrderedTask : NSObject
Declared in	ORKNavigableOrderedTask.h ORKNavigableOrderedTask.m

Overview

The ORKNavigableOrderedTask class adds conditional step navigation to the behavior inherited from the ORKOrderedTask class.

For implementing conditional task navigation, you must instantiate concrete subclasses of ORKStepNavigationRule and ORKSkipStepNavigationRule and attach them to trigger steps by using the setNavigationRule:forTriggerStepIdentifier: and setSkipNavigationRule:forStepIdentifier: methods.

For example, if you want to display a survey question only when the user answered Yes to a previous question you can use ORKPredicateStepNavigationRule; or if you want to define an arbitrary jump between two steps you can use ORKDirectStepNavigationRule. You can also optionally omit steps by using ORKPredicateSkipStepNavigationRule objects.

Note that each step in the task can have at most one attached navigation rule and one attached skip navigation rule.

Navigable ordered tasks support looping over previously visited steps. Note, however, that results for steps that are visited more than once will be ovewritten when you revisit the step on the loop. Thus, going over a loop will produce duplicate results within the task results for the steps that are seen more than once, but all the duplicate step results will point to the same result instance: the one corresponding to the last time you visited the step.

The same applies when navigating backwards over looped steps: only your last valid answer is shown every time you encounter a revisited step.

Other Methods

`– setNavigationRule:forTriggerStepIdentifier:`

Adds a navigation rule for a trigger step identifier.

- (void)setNavigationRule:(ORKStepNavigationRule *)stepNavigationRule forTriggerStepIdentifier:(NSString *)triggerStepIdentifier

Parameters

`stepNavigationRule`	The step navigation rule to be used when navigating forward from the trigger step. A strong reference to the rule is kept by the task.
`triggerStepIdentifier`	The identifier of the step that triggers the rule.

Discussion

The rule will be used to obtain a new destination step when the participant goes forward from the trigger step. You cannot add two different navigation rules to the same trigger step identifier; only the most recently added rule is kept.

Declared In

ORKNavigableOrderedTask.h

`– navigationRuleForTriggerStepIdentifier:`

Returns the step navigation rule associated with a trigger step identifier, or nil if there is no rule associated with that step identifier.

- (nullable ORKStepNavigationRule *)navigationRuleForTriggerStepIdentifier:(NSString *)triggerStepIdentifier

Parameters

`triggerStepIdentifier`	The identifier of the step whose rule you want to retrieve.

Return Value

A step navigation rule, or nil if the trigger step identifier has none.

Declared In

ORKNavigableOrderedTask.h

`– removeNavigationRuleForTriggerStepIdentifier:`

Removes the navigation rule, if any, associated with the specified trigger step identifier.

- (void)removeNavigationRuleForTriggerStepIdentifier:(NSString *)triggerStepIdentifier

Parameters

`triggerStepIdentifier`	The identifier of the step whose rule is to be removed.

Declared In

ORKNavigableOrderedTask.h

`stepNavigationRules`

A dictionary of step navigation rules in the task, keyed by trigger step identifier.

@property (nonatomic, copy, readonly) NSDictionary<NSString*ORKStepNavigationRule*> *stepNavigationRules

Discussion

Each object in the dictionary should be a ORKStepNavigationRule subclass.

Declared In

ORKNavigableOrderedTask.h

`– setSkipNavigationRule:forStepIdentifier:`

Adds a skip step navigation rule for a step identifier.

- (void)setSkipNavigationRule:(ORKSkipStepNavigationRule *)skipStepNavigationRule forStepIdentifier:(NSString *)stepIdentifier

Parameters

`skipStepNavigationRule`	The skip step navigation rule to be used to determine if the step should be skipped. A strong reference to the rule is kept by the task.
`stepIdentifier`	The identifier of the step that is checked against the skip rule.

Discussion

The rule will be used to decide if the identified step needs to be skipped. You cannot add two different skip navigation rules to the same step identifier; only the most recently added rule is kept.

Declared In

ORKNavigableOrderedTask.h

`– skipNavigationRuleForStepIdentifier:`

Returns the skip step navigation rule associated with a step identifier, or nil if there is no skip rule associated with that step identifier.

- (nullable ORKSkipStepNavigationRule *)skipNavigationRuleForStepIdentifier:(NSString *)stepIdentifier

Parameters

`stepIdentifier`	The identifier of the step whose skip rule you want to retrieve.

Return Value

A skip step navigation rule, or nil if the step identifier has none.

Declared In

ORKNavigableOrderedTask.h

`– removeSkipNavigationRuleForStepIdentifier:`

Removes the skip step navigation rule, if any, associated with the specified step identifier.

- (void)removeSkipNavigationRuleForStepIdentifier:(NSString *)stepIdentifier

Parameters

`stepIdentifier`	The identifier of the step whose rule is to be removed.

Declared In

ORKNavigableOrderedTask.h

`skipStepNavigationRules`

A dictionary of step navigation rules in the task, keyed by trigger step identifier.

@property (nonatomic, copy, readonly) NSDictionary<NSString*ORKSkipStepNavigationRule*> *skipStepNavigationRules

Discussion

Each object in the dictionary should be a ORKStepNavigationRule subclass.

Declared In

ORKNavigableOrderedTask.h

`– setStepModifier:forStepIdentifier:`

Adds a step modifier for a step identifier.

- (void)setStepModifier:(ORKStepModifier *)stepModifier forStepIdentifier:(NSString *)stepIdentifier

Parameters

`stepModifier`	The step modifier associated with this step
`stepIdentifier`	The identifier of the step that is checked against the skip rule.

Declared In

ORKNavigableOrderedTask.h

`– stepModifierForStepIdentifier:`

Returns the step modifier associated with a step identifier, or nil if there is no step modifier associated with that step identifier.

- (nullable ORKStepModifier *)stepModifierForStepIdentifier:(NSString *)stepIdentifier

Parameters

`stepIdentifier`	The identifier of the step to be modified

Return Value

A step modifier, or nil if the step identifier has none.

Declared In

ORKNavigableOrderedTask.h

`– removeStepModifierForStepIdentifier:`

Removes the step modifier, if any, associated with the specified step identifier.

- (void)removeStepModifierForStepIdentifier:(NSString *)stepIdentifier

Parameters

`stepIdentifier`	The identifier of the step whose rule is to be removed.

Declared In

ORKNavigableOrderedTask.h

`stepModifiers`

A dictionary of step modifiers in the task, keyed by trigger step identifier.

@property (nonatomic, copy, readonly) NSDictionary<NSString*ORKStepModifier*> *stepModifiers

Discussion

Each object in the dictionary should be a ORKStepModifier subclass.

Declared In

ORKNavigableOrderedTask.h

`shouldReportProgress`

Determines whether the task should report its progress as a linear ordered task or not. The default value of this property is NO.

@property (nonatomic) BOOL shouldReportProgress

Declared In

ORKNavigableOrderedTask.h

Other Methods

`– initWithIdentifier:steps:`

Returns an initialized ordered task using the specified identifier and array of steps.

- (instancetype)initWithIdentifier:(NSString *)identifier steps:(NSArray<ORKStep*> *)steps

Parameters

`identifier`	The unique identifier for the task.
`steps`	An array of `ORKStep` objects in the order in which they should be presented.

Return Value

An initialized ordered task.

Declared In

ORKOrderedTask.h

`– stepAfterStep:withResult:`

- (ORKStep *)stepAfterStep:(ORKStep *)step withResult:(ORKTaskResult *)result

Declared In

ORKTask.h

`– stepBeforeStep:withResult:`

- (ORKStep *)stepBeforeStep:(ORKStep *)step withResult:(ORKTaskResult *)result

Declared In

ORKTask.h

`– progressOfCurrentStep:withResult:`

- (ORKTaskProgress)progressOfCurrentStep:(ORKStep *)step withResult:(ORKTaskResult *)result

Declared In

ORKTask.h

`– initWithCoder:`

Returns an ordered task initialized from data in the given unarchiver.

- (instancetype)initWithCoder:(NSCoder *)aDecoder

Parameters

`aDecoder`	The coder from which to initialize the ordered task.

Return Value

An initialized ordered task.

Discussion

An ordered task can be serialized and deserialized with NSKeyedArchiver. Note that this serialization includes strings that might need to be localized.

Declared In

ORKOrderedTask.h