[title sub="Written by Chris Graham (ocProducts)"]Composr Supplementary: Inline editing in Composr[/title] Inline editing is achieved in Composr via an internal framework called fractional editing. By default inline editing is implemented for some content titles (when shown as screen titles), and for some member profile fields. [contents]decimal,lower-alpha[/contents] [title="2"]Enabling and support status[/title] Inline editing has to first be enabled from the configuration: Admin Zone > Setup > Configuration > Feature options > Advanced It is not enabled by default for 2 reasons: 1) The default inline editing experience is very basic 2) We do not like to impose overly-complex layout assumptions/requirements on themers To this end inline editing is supported only as a feature for programmers to deploy, not as an out-of-the-box solution. [title="2"]Limitations[/title] Inline editing only supports fields that may be edited in a text-based way. For title fields this will also be true. For CPFs, this is hard-coded to the following field types (expressed as the raw hook codenames, hard-coded in [tt]sources/cns_members.php[/tt]): - [tt]long_text[/tt] - [tt]long_trans[/tt] - [tt]short_trans[/tt] - [tt]list[/tt] - [tt]short_text[/tt] - [tt]codename[/tt] - [tt]url[/tt] - [tt]integer[/tt] - [tt]float[/tt] - [tt]email[/tt] [title="2"]Using inline editing[/title] Inline editing is either activated by an edit button, or by a special click. By default it is by a special click. We will cover how to change that under 'Templating' below. You can know if a special click may be used by a dashed border appearing when hovering the mouse. You need to hold down at least two keyboard modifier keys (e.g. Alt and Shift) and then click the field. We aren't completely specific on the fields because browsers sometimes reserve some of the keys, or keyboards might be missing them. On a Mac the Command key will also work as one of the fields, and on Windows the Windows key. You conclude inline editing by pressing enter. You cancel by pressing escape. Inline editing will run via an AJAX request, and then it will update the displayed field value with the new rendered value. [title="2"]How it works[/title] Fractional editing is literally the fractional handling of a standard Composr POSTed edit form. It only works on edit forms that have been coded to support this. [title="2"]Tempcode[/title] Fractional editing is activated via the [tt]FRACTIONAL_EDITABLE[/tt] directive. The directive takes the following parameters: - The first parameter [required] is the raw (unrendered) source text that is edited (e.g. raw Comcode) - The second parameter [required] is the field name used in the normal edit form - The third parameter [required] is a page-link to the edit actualiser (i.e. where the edit form goes to) - The fourth parameter should be set to '1' if the field supports Comcode - The fifth parameter should be set to '1' if visible editing links should be used (as opposed to needing a special click). - The sixth parameter is '1' is if an access check passed otherwise '0' (if omitted, does an Admin Zone access check instead). The inner content of the directive is the displayed (rendered) text (e.g. parsed Comcode, or at least HTML-escaped text) -- it is what would be there anyway if there was no directive. E.g.: [code="Tempcode"] {+START,FRACTIONAL_EDITABLE,Some Title,title,cms:cms_example:_edit:12,0,1,1}Some & Title{+END} [/code] This example is using a page-link of a fake example module called [tt]cms_example[/tt], in the CMS zone. It has an actualiser screen at [tt]_edit[/tt], and ID #12 is being edited. The sixth parameter may be given the value of this [tt]SUPPORTS_FRACTIONAL_EDITABLE[/tt] symbol. The symbol takes the following parameters: - The first parameter [required] is the same page-link as the third parameter to the directive. This is used to check zone and page access to the edit page. - The second parameter [required] is for further checks. In the below example I'm seeing if the current user is the content's original submitter. E.g. [tt]{$SUPPORTS_FRACTIONAL_EDITABLE,cms:cms_example:_edit:12,{$EQ,{SUBMITTER},{$MEMBER}}}[/tt] [title="3"]Edit widgets[/title] Before calling the [tt]FRACTIONAL_EDITABLE[/tt] directive, you can set a Tempcode variable to identify what field widget to edit with. You may use: - [tt]line[/tt] - [tt]textarea[/tt] - Or, a [tt]|[/tt]-separated list of list options Example for line editing: [code="Tempcode"] {$SET,edit_type,line} {+START,FRACTIONAL_EDITABLE,Some Title,title,cms:cms_example:_edit:12,0,1,1}Some & Title{+END} [/code] Example for text editing: [code="Tempcode"] {$SET,edit_type,textarea} {+START,FRACTIONAL_EDITABLE,Some Description,description,cms:cms_example:_edit:12,0,1,1}Some & Description{+END} [/code] Example for list editing: [code="Tempcode"] {$SET,edit_type,a|b|c} {+START,FRACTIONAL_EDITABLE,Some Option,option,cms:cms_example:_edit:12,0,1,1}Some & Option{+END} [/code] Or you can fetch the list values automatically: [code="Tempcode"] {$SET,edit_type,{$CPF_LIST,Option Name,|,0}} {+START,FRACTIONAL_EDITABLE,Some Option,option,cms:cms_example:_edit:12,0,1,1}Some & Option{+END} [/code] [title="2"]Example for member profile editing[/title] Imagine you want to deploy a CPF on a custom comcode page, and want to let a member edit their own CPF from that page. This Tempcode would make it possible: [code="Tempcode"] {+START,FRACTIONAL_EDITABLE,{$CPF_VALUE,About me,{$MEMBER}},field_1,_SEARCH:members:view:{$MEMBER},1,1,1}{$COMCODE,{$CPF_VALUE,About me,{$MEMBER}}}{+END} [/code] (where [tt]field_1[/tt] represents CPF with ID #1) The [tt]CPF_VALUE[/tt] symbol is being used to get a raw CPF value. Therefore to get the rendered field value we have to map it through the [tt]COMCODE[/tt] symbol. The editing page-link is under the view screen, as there's no separate actualiser screen for member profile editing, it's built into the tab display code. [title="2"]PHP[/title] From a PHP perspective, the edit code needs to assign special field values as the default for any field that is not passed. These field values are: - [tt]INTEGER_MAGIC_NULL[/tt] - [tt]STRING_MAGIC_NULL[/tt] The Composr [tt]query_update[/tt] method will detect these values as fields to omit from the SQL [tt]UPDATE[/tt] query. This is enough in most cases. However, you can also call the [tt]fractional_edit()[/tt] function to detect if a fractional update is happening. Using this is necessary for reading in checkbox fields, as unchecked fields cannot be distinguished from omitted fields due to an unfortunate design flaw in HTML. For example: [code="PHP"] $example_checkbox_value = post_param_integer('example_checkbox_value', fractional_edit() ? INTEGER_MAGIC_NULL : 0); [/code] [title="2"]Templating[/title] These 3 templates are relevant to fractional editing: 1) [tt]FRACTIONAL_EDIT.tpl[/tt] -- implements the HTML for the fractional editable interface 2) [tt]fractional_edit.js[/tt] -- implements the JavaScript for the fractional editable interface 3) [tt]CNS_MEMBER_PROFILE_ABOUT.tpl[/tt] -- shows how CPFs are mapped to the [tt]FRACTIONAL_EDITABLE[/tt] directive. It makes heavy use of extra field metadata passed from [tt]sources/hooks/systems/profiles_tabs/about.php[/tt] [concepts 1_key="Inline editing" 1_value="The process of editing individual data fields directly from the website front-end" 2_key="Fractional editing" 2_value="The framework Composr provides for inline editing" ]Concepts[/concepts] [title="2"]See also[/title] - [page="_SEARCH:tut_tempcode"]Tempcode programming[/page] {$SET,tutorial_tags,core_themeing,Design & Themeing,expert}{$SET,tutorial_add_date,Jan 2018}{$SET,tutorial_summary,An explanation of how the inline editing functionality deep within Composr works.}[block]main_tutorial_rating[/block]