This documentation refers to the latest trunk version of the Inline Edit code. For documentation specific to a particular release, please see Previous Versions of API Documents.
Inline Edit Overview
The Inline Edit allows users to edit content within the context of their work rather than going to an "edit mode". It can be applied to any text, assuming a very simple contract is maintained:
- The elements that are part of the Inline Edit component have some kind of container element.
- The text you wish to make editable is within the component container.
You can optionally provide your own markup that will be used for the edit mode, but if not, default markup is provided.
Creation
Creating a single Inline Edit
fluid.inlineEdit(componentContainer, options);
Return: The Inline Edit component object.
- Inline Edit Component Description
- Simple Text Inline Edit Component Description
- Inline Edit API
- Dropdown Inline Edit API
- Rich Text Inline Edit API
- Simple Text Inline Edit Tutorial
Join the infusion-users mailing list and ask your questions there.
Creating Multiple Inline Edits
fluid.inlineEdits(componentContainer, options);
Return: An array of the Inline Edit component objects.
This function will find any elements within the given container that are identified as 'editables' and apply the Inline Edit component to them.
Parameters
componentContainer
The componentContainer
parameter is a selector, a single-element jQuery, or a DOM element specifying the root DOM node of the Inline Edit markup.
options
The options
parameter is an optional data structure that configures the Inline Edit component(s), as described below in the Options section.
Supported Events
The Inline Edit component fires the following events (for more information about events in the Fluid Framework, see Events for Component Users):
Event |
Type |
Description |
Parameters |
Parameter Description |
---|---|---|---|---|
|
default |
This event is fired once the inline edit component is initialized. |
|
|
|
default |
This event is fired any time the model for the component has changed, that is, any time the value of the text associated with the component has changed. |
|
|
|
"preventable" |
This event fires just before the component switches from 'view' mode into 'edit' mode. Because the event is preventable, listeners may prevent the component from actually entering edit mode. |
none |
|
|
default |
This event fires just after the component has finished entering 'edit' mode. |
none |
|
|
"preventable" |
This event fires just before the component switches out of 'edit' mode, i.e. before the newly edited value is stored in the model. Because the event is preventable, listeners may prevent the new value from being stored in the model, i.e. they may cancel the edit. |
|
|
|
default |
This event fires just after the newly edited value is stored in the model. Note that it only fires if the |
|
|
Functions
These functions are defined on the central that
object returned from the inlineEdit construction function - for example with
var that = fluid.inlineEdit(componentContainer, options);
that.edit();
Switches the component into edit mode. The events onBeginEdit
and afterBeginEdit
will fire.
that.finish();
Switches the component out of edit mode into display mode, updating the displayed text with the current content of the edit field. The events onFinishEdit
and afterFinishEdit
will fire. If the model value has changed, there will be a call to modelUpdated
in between these calls.
that.cancel();
Cancels the in-progress edit and switches back to view mode.
that.isEditing();
Determines if the component is currently in edit mode: Returns true if edit mode is shown, false if view mode is shown.
that.refreshView(source);
Updates the state of the inline editor in the DOM, based on changes that may have happened to the model.
that.tooltipEnabled();
Returns a boolean indicating whether or not the tooltip is enabled.
/** * Pushes external changes to the model into the inline editor, refreshing its * rendering in the DOM. The modelChanged event will fire. * * @param {String} newValue The bare value of the model, that is, the string being edited * @param {Object} source An optional "source" (perhaps a DOM element) which triggered this event */ that.updateModelValue(newValue, source);
Updates the component's internal representation of the text to a new value. If the value differs from the existing value, the modelChanged
event will fire and the component will be re-rendered.
/** * Pushes external changes to the model into the inline editor, refreshing its * rendering in the DOM. The modelChanged event will fire. * * @param {Object} newValue The full value of the new model, that is, a model object which * contains the editable value as the element named "value" * @param {Object} source An optional "source" (perhaps a DOM element) which triggered this event */ that.updateModel(newValue, source);
Similar to updateModelValue
, only accepts specification of the overall model object (housing the editable value under the key value
).
that.model
Not a function, but a data structure. This directly represents the "model" or state of the editable component. External users should consider this structure as read-only, and only make modifications through the updateModel
call above.
Options
The following options to the creator functions can be used to customize the behaviour of the Inline Edit component:
Name |
Description |
Values |
Default |
---|---|---|---|
|
Javascript object containing selectors for various fragments of the Inline Edit component. |
The object can contain any subset of the following keys: |
selectors: { text: ".flc-inlineEdit-text", editContainer: ".flc-inlineEdit-editContainer", edit: ".flc-inlineEdit-edit", textEditButton: ".flc-inlineEdit-textEditButton" // New in v1.3 }
|
New in v1.3: |
Configuration of short messages and strings which the component uses in its UI |
key-value structure with |
strings: { textEditButton: "Edit text %text", editModeInstruction: "Press Escape to cancel, Enter or Tab when finished." } |
|
JavaScript object containing listeners to be attached to the supported events. |
Keys in the object are event names, values are functions or arrays of functions. |
|
|
Javascript object containing CSS style names that will be applied to the Inline Edit component. |
The object can contain any subset of the following keys: |
styles: { text: "fl-inlineEdit-text", edit: "fl-inlineEdit-edit", invitation: "fl-inlineEdit-invitation", defaultViewStyle: "fl-inlineEdit-emptyText-invitation", emptyDefaultViewText: "fl-inlineEdit-emptyDefaultViewText", focus: "fl-inlineEdit-focus", tooltip: "fl-inlineEdit-tooltip", editModeInstruction: "fl-inlineEdit-editModeInstruction", // New in v1.3 displayView: "fl-inlineEdit-simple-editableText fl-inlineEdit-textContainer", // New in v1.3 textEditButton: "fl-offScreen-hidden" // New in v1.3 }
|
|
Javascript object containing pixel values that will configure the size of the edit field. |
The object can contain any subset of the following keys: |
paddings: { edit: 10, minimumEdit: 80, minimumView: 60 } |
|
Indicates whether the values stored for |
boolean |
|
|
Determines whether receiving an "Enter" keypress will cause the component to finish editing and commit the changed value. If this is given a direct value |
boolean |
|
New in v1.3: |
A function that calls upon the markup corresponding to the display mode of the component. |
function - |
|
|
A function that creates or recognises the markup corresponding to the editable view of the component. The function is intended to inspect the state of the existing markup, and if it is "incomplete" in some way, to fill in the required fields. In all cases, the function returns a structure return { container: [jQuery], field: [jQuery] };
|
function - |
<span><input type='text' class='flc-inlineEdit-edit fl-inlineEdit-edit'/></span> |
|
A ViewAccessor, or name of one, which is used to store and retrieve the editable value from the read-only view of the control, peering with the tag referenced by the selector |
|
"fluid.inlineEdit.standardAccessor" |
|
A InlineEditView, or name of one, which is used to operate the implementation of the |
|
"fluid.inlineEdit.standardDisplayView" |
|
As for |
|
"fluid.inlineEdit.standardAccessor" |
|
As for |
|
"fluid.inlineEdit.standardEditView" |
|
For |
boolean |
false |
|
A function which acts on the overall component to bind a handler for the |
|
null |
|
Indicates whether or not to automatically select the editable text when the component switches into edit mode. |
boolean |
|
|
The default text to use when filling in an empty component. Set to empty to suppress this behaviour |
string |
"Click here to edit" |
|
Indicates whether or not the component should display a custom ("invitation") tooltip on mouse hover |
boolean |
|
|
The text to use for the tooltip to be displayed when hovering the mouse over the component |
string |
"Click item to edit" |
|
The id to be used for the DOM node holding the tooltip |
string |
"tooltip" |
|
The delay, in ms, between starting to hover over the component and showing the tooltip |
number |
1000 |
Additional options for Multiple Inline Edits
The options for the creation of multiple Inline Edits are the same as those for the creation of a single Inline Edit, with the addition of a selector for identifying the editable elements. The default selector is defined as follows:
selectors: { editables: ".flc-inlineEditable" }
InlineEdit Types
Several of the InlineEdit configuration elements make use of various "Implicit" or "Duck Typed" objects which have particular structures or signatures.
<script type="text/javascript" src="lib/jquery/core/js/jquery.js"></script> <script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.core.js"></script> <script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.widget.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="lib/jquery/ui/js/jquery.ui.position.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="lib/jquery/plugins/tooltip/js/jquery.tooltip.js"></script> <script type="text/javascript" src="framework/core/js/FluidDocument.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="framework/core/js/jquery.keyboard-a11y.js"></script> <script type="text/javascript" src="framework/core/js/Fluid.js"></script> <script type="text/javascript" src="framework/core/js/DataBinding.js"></script> <!-- New in v1.4 --> <script type="text/javascript" src="components/tooltip/js/Tooltip.js"></script> <!-- New in v1.3 --> <script type="text/javascript" src="components/inlineEdit/js/InlineEdit.js"></script>