Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FLUID-5249: New documentation covering framework reorganisation under FLUID-5249 #63

Merged
merged 13 commits into from Aug 26, 2015

Conversation

Projects
None yet
3 participants
@amb26
Copy link
Member

commented Apr 22, 2015

and other JIRAs. Documentation for new features for ContextAwareness (FLUID-5264) and Priority (FLUID-5506) features

amb26 added some commits Apr 22, 2015

FLUID-5249: New documentation covering framework reorganisation under…
… FLUID-5249 and other JIRAs. Documentation for new features for ContextAwareness (FLUID-5264) and Priority (FLUID-5506) features
FLUID-5249: Concluded updating documentation for i) removal of autoIn…
…it, ii) removal of surplus framework grades, iii) new ContextAwareness API
Merge branch 'master' into FLUID-5249
Conflicts:
	src/documents/ComponentConfigurationOptions.md
	src/documents/ComponentGrades.md
	src/documents/InfusionEventSystem.md
	src/documents/IoCReferences.md
	src/documents/IoCSS.md
@@ -18,10 +18,9 @@ Rename "fluid.prefs.enactors" to "fluid.prefs.enactor"

<div class="infusion-docs-note"><strong>Note:</strong> According to the [comment](https://github.com/fluid-project/infusion/blob/master/src/framework/core/js/FluidView.js#L38-L39) on the implementation for relay components, in Infusion 2.0, relay components will be renamed back to its original names. If the rename has been made, this section can be ignored.</div>

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Can we update this comment to clearly describe the reality that the base component grades have been renamed?

Also, can we document other 1.5-2.0 changes such as the removal of demands blocks, non-dynamic invokers, etc.?

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 13, 2015

Member

I also notice that the list of options supported by all components has changed, we should probably mention that. Also, the 'applier' option of modelComponents seems to be gone...

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 13, 2015

Member

I also see that grade linkages have been removed, we should mention that

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 13, 2015

Member

onAttach and onClear have been removed

This comment has been minimized.

Copy link
@amb26

amb26 Aug 14, 2015

Author Member

gradeLinkage to me counts as a "less widely-used feature" so I added an entry to it in the DeprecationsIn1_5 page referred to at the head of the list

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 14, 2015

Member

thanks for the pointer, @amb26, I forgot to check the deprecations page. Should we be adding a DeprecationsIn2_0 page?

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 14, 2015

Member

Mention the change from fluid.event.makeEventFirer to fluid.makeEventFirer?

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 14, 2015

Member

priority and namespace added to distributeOptions possibilities

In every case the `options` argument is optional. Where the parameter `model` appears it directly represents the model to be managed by the applier. Where parameter `holder` appears, it represents instead an object which is expected _to be a container for the model_ where the model itself is held in this object at the member named `model`. In framework use this argument will actually hold the owning component itself, although the applier makes no use of any properties of this object other than the one held at `model`.
Instantiating a ChangeApplier manually is no longer recommended in current versions of the framework. Its implementation is tightly bound into its location in
an IoC component tree and should be constructed by the IoC system itself.
Under the old ChangeApplier semantics, the `model` handle was closed over and remained constant for the lifetime of the applier. The framework contained utilities such a `fluid.model.copyModel` which assisted the user in working with a model with changing contents whilst keeping its base reference constant. Under the new ChangeApplier semantics, the `model` base reference is not stable and in fact starts by holding the value `undefined` as every model component initialises.

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Do we still need to retain this reference to the "old ChangeApplier semantics," since this is in fact now the "old old ChangeApplier semantic." In the spirit of 2.0 as a shedding of legacy concepts, can we also ditch this documentation or is it still crucial?

Under the old ChangeApplier semantics, the `model` handle was closed over and remained constant for the lifetime of the applier. The framework contained utilities such a `fluid.model.copyModel` which assisted the user in working with a model with changing contents whilst keeping its base reference constant. Under the new ChangeApplier semantics, the `model` base reference is not stable and in fact starts by holding the value `undefined` as every model component initialises.
### Operating transactions manually ###
Similarly to manual construction of a ChangeApplier, this is not recommended for normal users of the framework. It may be appropriate for advanced users of the framework who are building higher-level frameworks layered over it.
A user may be interested in economising on notifications to model updates - by batching these up into a single transaction, there will

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Has this changed in Infusion master yet? If so, can we update the documentation? If not, can we say something to the effect of "after Infusion 2.0 beta1?" or "prior to the final release of Infusion 2.0?"

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 13, 2015

Member

The dash between "updates" and "by batching" should probably be a semicolon i.e. "... to model updates; by batching these..."

</tr>
<tr>
<th>Notes</th>
<td>The Framework will create event firers for the listed events. It is the responsibility of the component to fire the events at the appropriate times.</td>

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Is it worth clarifying here that the primary component lifecycle events, such as onCreate and onDestroy are fired automatically by the framework?

<td><code>members</code> differ from <code>invokers</code> in that the arguments of members are not resolved at invocation time.
The right-hand-side may contain an <a href="ExpansionOfComponentOptions.md">expander</a> definition, which may perhaps itself resolve onto an <a href="Invokers.md">invoker</a>.</td>
<td>Both component developers and integrators can define listeners for events.
<a href="Invokers.md">Invokers</a> and <a href="ExpansionOfComponentOptions.md">Expanders</a> can be used as listeners here. Note that as well as being a simple string holding the name of an event on this component, a listener key may also be a full <a href="IoCReferences.md">IoC Reference</a> to any other event held in the component tree (for example <code>"{parentComponent}.events.parentEvent"</code>. As well as being a simple function name, a the value associated with the key may be a <a href="InfusionEventSystem.md">Listener Record</a> or else follow the syntax of an invoker indicating that the registered listener receives a different signature from the one that the event has fired (see <a href="EventInjectionAndBoiling.md">Event injection and boiling</a>).</td>

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Is it true that an expander "can be used as a listener here," or is it slightly more subtle (i.e. the result of an expander can be used as a listener)?

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

typo "a the value"

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

My impression is that this note might will benefit from seeing specific example code (or links to pages where specific examples are available).

@@ -48,14 +47,15 @@ fluid.default("fluid.parent", {

##### In 2.0 #####

In Infusion 2.0 where relay components are introduced, sharing models no longer requires the change applier to be shared:
In Infusion 2.0 where relay components are introduced, the change applier must not be configured separately - model sharing

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 12, 2015

Member

It would be good if "change applier" here was a link to the ChangeApplier documentation. Also, perhaps instead of "must not" maybe "doesn't need to be"?

This comment has been minimized.

Copy link
@amb26

amb26 Aug 13, 2015

Author Member

I think "must not be" - the user is pretty likely to corrupt this or future versions of the framework by attempting to directly configure any part of the model relay machinery. We do still support "changeApplierOptions" as a means of routing options to the applier - although currently we don't support any particularly useful options there.


The declarative style for registering interest in change events uses an entry in the `modelListeners` options area of a `modelRelayComponent`. These listeners are attached to the applier during the construction process of the entire component (and its surrounding tree) and so will therefore become notified as part of the [initial transaction](ModelRelay.md#the-initial-transaction) - they will therefore get to observe the model changing state from its primordial value of undefined to holding their initial resolved value. This is the **recommended** way of listening to model changes using the ChangeApplier system.
The declarative style for registering interest in change events uses an entry in the `modelListeners` options area of a `modelComponent`. These listeners are attached to the applier during the construction process of the entire component (and its surrounding tree) and so will therefore become notified as part of the [initial transaction](ModelRelay.md#the-initial-transaction) - they will therefore get to observe the model changing state from its primordial value of undefined to holding their initial resolved value. This is the **recommended** way of listening to model changes using the ChangeApplier system.

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 12, 2015

Member

This might be a good opportunity to find a different word than "primordial" (which also occurs in the ModelRelay documentation page). Perhaps "initial"?

This comment has been minimized.

Copy link
@amb26

amb26 Aug 13, 2015

Author Member

"initial" already signifies the same as it did in previous versions of the framework - that is, the "initial synchronised value of the model" taking into account all sources of initial values. I'm open to improved suggestions for "primordial" - perhaps "grandeval" or "sephiric"?

<table>
<tr>
<th>Description</th>
<td>An object containing the data model to be used by the component.</td>
<td>An object providing instructions for how particular options should be merged when integrator options are merged with default values.</td>

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

In other parts of the documentation, we refer to "a record" rather than "an object." Is there a reason we don't do so here?

This comment has been minimized.

Copy link
@amb26

amb26 Aug 13, 2015

Author Member

Perhaps because the pieces of documentation were written by different people at different times? : P - I've normalised this to "record" here

</tr>
<tr>
<th>Notes</th>
<td>If a <a href="ChangeApplier.md">ChangeApplier</a> is not provided using the <code><a href="#applier">applier</a></code> option, the Framework will create one for the provided model. </td>
<td>It is uncommon to need this option. The most common use case is to protect "exotic values" derived from some external library or framework from being corrupted by the options merging/expansion process by use of the "nomerge" policy.</td>

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Is there an example of a kind of "exotic value" that one should typically protect? Or conversely, is there an example of a value that might seem like it needs be guarded, but doesn't? What about, say, a reference to a DOM object or other browser-implemented object (e.g. a Blob or an AudioContext or an Element)?

@@ -8,9 +8,9 @@ This section explains and documents the various Javascript API calls for instant

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 12, 2015

Member

In the opening paragraph, it would be good if the first use of "ChangeApplier" was a link to the ChangeApplier page.

<td>It is not necessary to provide an applier: By default, an applier will be created with <code>fluid.makeChangeApplier()</code>, using any options specified with <code><a href="#changeapplieroptions">changeApplierOptions</a></code>.

This option is most commonly used to share a common ChangeApplier between components in a component tree: the <code>applier</code> option can be used to reference the ChangeApplier of another component in the tree.</td>
<td>Some special context names may be available within the subcomponent's definition block, for example <code>{source}</code> and <code>{sourcePath}</code> or <code>{arguments}</code>. <em>This framework facility will be replaced by a more declarative equivalent in time and should be used with caution.</em></td>

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

In what way should it be used with caution? Should we explicitly state that this is an unstable (or unsupported) API? Or should I apply some other form of caution (i.e. only using it for specific types of problems)?

This comment has been minimized.

Copy link
@amb26

amb26 Aug 13, 2015

Author Member

I'm not really too sure what to say here. The API is not exactly "unstable" since we plan to support it for a while, and it has been supported for some time in the past. It is just one of these suspicious areas, like the old "init functions" etc. where we clearly haven't completely succeeded in understanding a problem area yet. Perhaps by "caution" I mean, "you should consult with someone before using this to confirm that it is appropriate".

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 13, 2015

Member

I think I'd go ahead and say exactly this. "If you think you might need to use this feature, ask on < link to community forums > for advice" or something to that effect.

</pre></td>
</tr>
<tr>
<tr>

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Extra whitespace.

<th>Notes</th>
<td>Both component developers and integrators can define listeners for events.
<a href="Invokers.md">Invokers</a> and <a href="ExpansionOfComponentOptions.md">Expanders</a> can be used as listeners here. Note that as well as being a simple string holding the name of an event on this component, a listener key may also be a full <a href="IoCReferences.md">IoC Reference</a> to any other event held in the component tree (for example <code>"{parentComponent}.events.parentEvent"</code>. As well as being a simple function name, a the value associated with the key may be a <a href="InfusionEventSystem.md">Listener Record</a> or else follow the syntax of an invoker indicating that the registered listener receives a different signature from the one that the event has fired (see <a href="EventInjectionAndBoiling.md">Event injection and boiling</a>).</td>
<td>A set of rules or constraints linking values held in this model to those elsewhere in the component tree (or to other values within this model)</td>

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Is it worth noting here that these constraints are specific, and are operated by the Infusion model transformation, or is this too much detail for this page? At very least, we should probably provide a link to where the user can learn more about these "rules or constraints."

This comment has been minimized.

Copy link
@amb26

amb26 Aug 13, 2015

Author Member

The link is below in the "See also" section

* [`viewComponent` options](#view-components) described above,
* and those defined below.

Component developers are free to define their own additional options.

### selectorsToIgnore ###
**NOTE**: The Infusion Renderer system will be rewritten completely for the Infusion 2.0 release - the use of the current renderer and component hierarchy is not recommended.

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Again, can we be more specific, at least by saying "rewritten completely before the final release of Infusion 2.0?" It's this kind of issue that makes me increasingly wonder if we should indeed be more frequently updating our major revision numbers. The question of "when" is very fuzzy with our current plan to issue a long series of not-fully-roadmapped betas.

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 13, 2015

Member

We have a "note" style that would set this off better visually, making it more noticable. This would be a good place to use it.

This comment has been minimized.

Copy link
@amb26

amb26 Aug 14, 2015

Author Member

Can you refer me to an example of using this "note" style?

<em>
<strong>NOTE:</strong> for the Infusion 2.0 release this grade will become redundant as it will be the default for every grade
</em>
A "little" component is the most basic component: it supports options merging with defaults (<a href="tutorial-gettingStartedWithInfusion/BasicComponentCreation-LittleComponents.md">Little Components</a>), as well as

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

It's debatable, but I think I'd prefer italicization to quoting here, as in "A little component is the most basic component..."

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

And should we even still be calling these "little" components now that they've been renamed? I'd recommend we ditch the prefix and rename the appropriate documentation pages.

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 13, 2015

Member

This link to BasicComponentCreation-LittleComponents.md is broken, and the link text is in appropriate.

<strong>NOTE:</strong> for the Infusion 2.0 release this grade will become redundant as it will be the default for every grade
</em>
A "little" component is the most basic component: it supports options merging with defaults (<a href="tutorial-gettingStartedWithInfusion/BasicComponentCreation-LittleComponents.md">Little Components</a>), as well as
that instantiating event firers based on default framework events (onCreate, onDestroy, onDetach)

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Typo: unnecesary "that".

<td>
A "little" component is the most basic component: it supports options merging with defaults (<a href="tutorial-gettingStartedWithInfusion/BasicComponentCreation-LittleComponents.md">Little Components</a>). All Fluid components are derived from this grade, and in general all things not derived from this grade are non-components (e.g. plain functions, or model transformation transforms, etc.)
A "model" component is a little component that additionally provides supports for a component's model, defined in the components options, and operations on it (<a href="tutorial-gettingStartedWithInfusion/ModelComponents.md">Tutorial - Model Components</a>).

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Apostrophe missing: "components" -> "component's"

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Is it worth referencing what these "operations" are? i.e. that the component a) has a ChangeApplier automatically assigned to it, and b) supports relays between models? Or is it better to keep it simple and general on this page?

<td>
A "model" component is already a little component that additionally provides supports for a component's model, defined in the components options, and operations on it (<a href="tutorial-gettingStartedWithInfusion/ModelComponents.md">Tutorial - Model Components</a>).
A "view" component is a fluid.modelComponent is bound to a DOM container node, holds a <a href="DOMBinder.md">DOM Binder</a> and supports a view (<a href="tutorial-gettingStartedWithInfusion/ViewComponents.md">Tutorial - View Components).

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

typo: missing "that." "A "view" component is a fluid.modelComponent is bound to a DOM..." -> "A "view" component is a fluid.modelComponent that is bound to a DOM..."

<td>fluid.rendererRelayComponent</td>
<td>
A "renderer" component is already a vew component that bears a renderer. There are additional features provided by this component grade specified on the <a href="tutorial-gettingStartedWithInfusion/RendererComponents.md#useful-functions-and-events">Useful functions and events</a> section of the <a href="tutorial-gettingStartedWithInfusion/RendererComponents.md">Tutorial - Renderer Components</a> page
A "renderer" component is a view component that also bears a renderer. There are additional features provided by this component grade specified on the <a href="RendererComponents.md#useful-functions-and-events">Useful functions and events</a> section of the <a href="tutorial-gettingStartedWithInfusion/RendererComponents.md">Tutorial - Renderer Components</a> page

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Does it "bear" a Renderer, or does it implement some kind of lifecycle for rendering? A renderer, currently, is somewhat different from, say, a ChangeApplier, isn't it?

A component's grades should be specified using the `gradeNames` option in the components defaults block, as shown in the examples below. The `gradeNames` option holds a string or Array of Strings.

<div class="infusion-docs-note"><strong>Note:</strong> In the examples below, the <code>autoInit</code> flag is not actually a grade, but is added to the <code>gradeNames</code> array to control how the component is created. See <a href="#initializing-graded-components">Initializing Graded Components</a> below for more information about the <code>autoInit</code> flag. The <code>autoInit</code> flag will soon become the default. Always use the <code>autoInit</code> flag, unless you have a very good reason not to.</div>
A component's grades should be specified using the `gradeNames` option in the components defaults block, as shown in the examples below. The `gradeNames` option holds a `String` or `Array of String`.

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

What happens if gradeNames is omitted from a component's definition?

## Combining Grades ##

Since the `fluid.defaults` directive introduces a grade into the system, various components can be composed to create new ones. Options, fields and methods introduced by the ancestor grades will be merged. The merging happens, firstly in hierarchical order (grades comprising the ancestor grade are resolved before the actual component grades resolution) and secondly in the left-to-right order (defaults from the grade on the right taking precedence over the defaults from the grade on the left, more details can be found at the JIRA [FLUID-5085](http://issues.fluidproject.org/browse/FLUID-5085)). For example:
Since the `fluid.defaults` directive introduces a grade into the system, various components can be composed to create new ones. Options, fields and methods introduced by the ancestor grades will be merged.
The merging happens, firstly in hierarchical order (grades comprising the ancestor grade are resolved before the actual component grades resolution) and secondly in the right-to-left order (defaults from the grade on the left taking precedence over the defaults from the grade on the right, more details can be found at the JIRA [FLUID-5085](http://issues.fluidproject.org/browse/FLUID-5085)). For example:

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Rather than pointing the reader to a rather context-specific JIRA ticket, can we just describe those "more details" here or elsewhere in the documentation?

This comment has been minimized.

Copy link
@amb26

amb26 Aug 13, 2015

Author Member

The details are pretty esoteric and not really of interest to even moderately regular users of the framework - given in practice we find that "the expected thing mostly happens" when people write grade lists. The useful pointer in the JIRA is that, in particular, we do not operate the standard "C3 linearization algorithm" (or anything like it) that is common in OO-like systems - https://en.wikipedia.org/wiki/C3_linearization - I don't know if it's worth trying to make this point or highlight it anywhere else/otherwise.

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 13, 2015

Member

I'd suggest ditching the reference to the JIRA, and adding a reference that is essentially the same as what you say here: (roughly) "This is in contrast to the C3 linearization algorithm (link) that is common in other object oriented inheritance schemes."

category: API
---

The ContextAwareness API of Infusion provides a powerful suite of grades and utilities that allow a component to be responsive to aspects of its contexts in a flexible and open-ended way.

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

I think we can use "context" singular rather than "contexts" here, though I'm open to debate.

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 12, 2015

Member

The word context should be a link to the Contexts documentation.

A `contextAware` component can be responsive to contexts, whose influence is organised as a set of mutually orthogonal "adaptations", where the set of adaptations itself is open to extension by
integrators and adopters. The primary grade enabling a component to opt into this scheme is named `fluid.contextAware`. Any component derived from this grade will advertise an
area of its options named `contextAwareness` which organises the rules for its adaptation in a hierarchical way - at the top level by "adaptation" and then at the nested level by
"checks".

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

I think it would be hugely helpful, by this point in the documentation, to provide a concrete example of a kind of "context awareness" that a component may want to provide. Perhaps a common kind of feature or browser detection, for example? Readers will benefit from being able to map the terminology to a specific example while they're reading. It might even be nice to provide some simple sample code right at the beginning, again so that the following section about adaptationRecords is clearer.

<table>
<thead>
<tr>
<th colspan="3">Members of a <code>adaptationRecord</code> entry within the <code>contextAwareness</code> block of a <code>fluid.contextAware</code> component</th>

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Typo: "Members of a adaptationRecord" -> "Members of an adaptationRecord"

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 13, 2015

Member

It would be very helpful to the reader if there was a code example before this table. It would help to clarify the relationship between adaptation records, contextAwareness blocks, etc. much more easily than linear text.


### Example `contextAwareness` record

The most adaptible component in the framework is currently the [Uploader](togo/Uploader.md) which currently can respond to three "dimensions" of adaptation. Two of these,

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

I think it might be better to use an example that isn't our own component, but nonetheless is a simple example of something related to browser feature detection.

});
```

`technology` refers to the implementation technology of the uploader. For previous releases, this supported a Flash-based engine as well as an HTML engine targetted at a back-levelled HTML

This comment has been minimized.

Copy link
@colinbdclark

colinbdclark Aug 12, 2015

Member

Too much historical detail clouds the clarity of this example.

@amb26

This comment has been minimized.

Copy link
Member Author

commented Aug 17, 2015

@colinbdclark , @acheetham - ready for another look. I've also made some fixes to styling, global structure and the docpad scripts.

@@ -39,14 +39,25 @@
[
{ "pageName": "Events", "href": "/Events.html" },
{ "pageName": "Infusion Event System", "href": "/InfusionEventSystem.html" },
{ "pageName": "Priorities", "href": "/Priorities.html" },

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 18, 2015

Member

Given that priorities apply to so much more than just events, I wonder if we should put this in a different section of the ToC - maybe the "Defining Components" section, since that's where most of the broadly-relevant stuff is.

@@ -36,11 +38,10 @@
<div class="fl-panelBar">
<span class="fl-prefsEditor-buttons">
<button id="reset" class="flc-prefsEditor-reset fl-prefsEditor-reset"><span class="fl-icon-undo"></span> Reset</button>
<button id="show-hide" class="flc-slidingPanel-toggleButton fl-prefsEditor-showHide"> Show/Hide</button>
<button id="show-hide" class="flc-slidingPanel-toggleButton fl-prefsEditor-showHide">+ Show Display Preferences</button>

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 18, 2015

Member

This change is not necessary: UIO will replace the button text. In fact, leaving it as "show/hide" is a helpful debugging aid, since it allows you to tell at a glance if UIO didn't initialize.

This comment has been minimized.

Copy link
@amb26

amb26 Aug 18, 2015

Author Member

This change is necessary to avoid the appalling jank as the UIO initialiser replaces the button text very late into initialisation of the page. Hopefully we can continue to fix the other sources of jank bugs such as https://issues.fluidproject.org/browse/FLUID-5481 since they give our docs site an amateurish appearance. I don't believe that any of our typical docs users will find it valuable to tell "at a glance" whether UIO initialized or not : P

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 18, 2015

The file Events.md doesn't really seem to serve much purpose. Could we get rid of it?

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 18, 2015

There are some problems with the UIO integration. It works and all, but a) the button is about one pixel high; b) when the panel opens and the page slides down, the ToC doesn’t also slide down.

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 18, 2015

I like the separate scrolling for the ToC and the content, but on pages that are very short, the footer is floating up in the middle of the page. We should try to have the minimum height of the page be the window height.

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 18, 2015

There's supposed to be a gap between the main header of the page and the upper black nav bar, but that seems to be gone now, and it looks rather crowded.

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 18, 2015

The ToC link to APIChangesFrom1_5to2_0.html doesn't actually contain any text; can't tell why. The link is there in the generated html, but without any text in it.


Rename "fluid.prefs.enactors" to "fluid.prefs.enactor"
This section describes major APIs that were in common use. For information about less widely-used features removed in 2.0, consult [Deprecations in 1.5)(DeprecationsIn1_5.md).

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 18, 2015

Member

Typo in this link: ) should be ]

@amb26

This comment has been minimized.

Copy link
Member Author

commented Aug 19, 2015

Addressed most of the recent comments - UIO is working again, but I didn't have much luck with the footer - I don't think this can be tackled without changing the containment structure of the markup significantly (I already moved up the footer several levels in the document to prevent it bashing into the "position:fixed" TOC at the left). Perhaps @jhung has some ideas - Cheers

* **model** and **evented components** add support for models and events (respectively) to **little components**
* **view components** support models and events, and also add support for views.
* **model** components add support for models to **plain components**
* **view components** support models, and also add support for views.
* **renderer components** are **view components** with the [Renderer](../Renderer.md) added.

![A venn diagram showing the composition of grades](../images/component-grades-venn-diagram.svg)

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 19, 2015

Member

This venn diagram needs updating; the paragraph below it still refers to "little component"; the "next" link at the end needs updating


## Grade and Default Options ##

A component's grade and any default options are registered with the framework using a call to [`fluid.defaults`](https://github.com/fluid-project/infusion/blob/infusion-1.5/src/framework/core/js/Fluid.js#L1519-L1539), which has two parameters: the component name and an object containing the defaults. The parent grades for the component are specified in an array in the defaults called `gradeNames`. For a **little component**, specify the grade as `fluid.component`:

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 19, 2015

Member

This paragraph refers to "little component" – we're not using that phrase anymore, are we?

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 19, 2015

Member

The link to the code for "fluid.defaults" is still pointing to the 1.5 tag. I just searched through all of the markdown files, and there are several links to that tag (26). We should update them.

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 19, 2015

The link at the bottom of the "getting started" tutorial's Model Components page still points to the now non-existent Evented Components page

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 19, 2015

The paragraph at the top of the "getting started" tutorial's View Components page still refers to little and evented components.

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 19, 2015

The "Defining components" link at the top of the "Using String Templates" tutorial still links to the little components page

console.log("Event listener received number " + number + " and condition " + condition);
};

fluid.defaults("examples.eventedComponent", {

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 19, 2015

Member

Does it make sense to use "evented" in the name of the component, now that everything is evented by default?

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 19, 2015

The "getting started" tutorial's Renderer Components page still has a link to the Evented Components page

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 19, 2015

The Event Injection and Boiling page has a link with link text "eventedComponent" – should probably just be "comonent"?

Events in Infusion are model-oriented, and aren't specific to the DOM. [Events](InfusionEventSystem.md) have a very plain implementation in Infusion &#8212; an event here is really just another kind of function call.
Any function signature can be an event signature, any function can be an event listener, and an event's `fire` method is a plain function handle that can be handed around just like any other function.
There is no special kind of "Event Object" that gets handed around to event listeners, and anyone can easily define a new event by simply calling `fluid.makeEventFirer()`.
In practice, users should use the events which are created automatically by the framework as part of the initialisation of every [Component](tutorial-gettingStartedWithInfusion/EventedComponents.md).

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 19, 2015

Member

This link is still referencing the EventedComponents page

@@ -46,11 +46,13 @@ A top-level options block named **`events`** is supported on every component der
</tr>
</table>

**NOTE**: _`preventable` events are very rarely used and will soon be deprecated in the framework_.

For every such entry in the `events` section of a component's options, the framework will construct a corresponding ***event firer*** with the same name in the `events` section of the constructed component. The most common use of an event firer is to call its member named `fire` with some set of arguments. Here is a simple, self-contained example:

```javascript
fluid.defaults("examples.eventedComponent", {

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 19, 2015

Member

Does it make sense to keep using "evented" in the example component names?

the updates will propagate only in one direction. This can still be highly useful. In addition to its invertibility, the propagation of updates through a relay rule can be fine-tuned by the options
`forward` and `backward`, as described in the following section.

####Controlling propagation through a relay rule####

This comment has been minimized.

Copy link
@acheetham

acheetham Aug 19, 2015

Member

These headers don't seem to be rendering as headers.

@acheetham

This comment has been minimized.

Copy link
Member

commented Aug 19, 2015

The link to the "API Changes from 1.5 to 2.0" page is still broken in the ToC

@amb26

This comment has been minimized.

Copy link
Member Author

commented Aug 20, 2015

"API Changes from 1.5 to 2.0" works for me - what do you observe when operating the link? Does the URL look correct? Does a file like the one it is pointing to exist in the "out" directory?

@amb26

This comment has been minimized.

Copy link
Member Author

commented Aug 20, 2015

Ready for further further review

@acheetham acheetham merged commit 2135d12 into fluid-project:master Aug 26, 2015

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.