Reconfiguring references
Image references
Image references occur where images are embedded in a Fonto document.
-
Add the web reference package (fontoxml-cms-browser) to your platform (via sdk portal) and add this to your config/fonto-manifest.json.
-
Find the <image>-insert and <image>-edit operations and replace the steps with the following:
-
[Only for edit operation] Add a
transform/retrieve
stepReference From Permanent Id -
This is used to preselect the current image if it is in a folder opened by the user.
-
Set the data
continue
toOn Error true
-
Set the data to the reference we are editing. Recommended is to use an inline XPath expression like: “x__$data('contextNode')/@href”
-
This step exports a
reference
object tooperation
Data
-
-
Refactor the modal step
-
Change the modal operation name to
open-image-browser-modal
-
The properties on
step
can be removedData Note that allowBrowse, assetDataProvider, rootNodeTemplateUrl and any other previously available configuration options for the modals are removed. The basic modal has the following features: without search / with upload / with preview and with a folder dropdown. If the standard browser does not meet your needs you can fork our open source add-on and make changes as you see fit.
-
[Only for edit operation] Set the
selected
to "{{reference.target}}"(from the previous step).Image Id
-
-
Add a
transform/create
stepPermanent Id For Reference -
Set the data
target
to “{{selectedImageId}}” -
Set the data
r
eference
to “image”Type
-
-
End with the insertion or edit operation of your choosing, but change the “{{attributes.<url|href|etc>}}” string with “{{permanentId}}”
-
Hyperlinks, web references
A hyperlink or web reference is a reference to an URL schema, eg. a website, email address or FTP site. The target is commonly found elsewhere on the inter- or intranet, and is usually not managed through Fonto.
Examples in this step assume an <xref> element with attribute “href” that contains a permanentId which can be resolved to an external URL with a reference object of type “web”. The examples are illustratory, and details are likely to differ depending on your schema and previous configuration.
-
Add the web reference package (fontoxml-web-references) to your platform (via sdk portal) and add this to your config/fonto-manifest.json.
-
Find the <web>-insert and <web>-edit operation and replace the steps with the following:
-
[Only for edit operation][only if using permanent id's] Add a transform/retrieve
Reference From Permanent Id step -
Set the data
continue
toOn Error true
-
Set the data
permanent
to the reference we are editing. Recommended is to use an inline XPath expression like: “x__$data('contextNode')/@href”Id -
This step exports a
reference
object tooperation
Data
-
-
Refactor the modal step
-
Change the modal operation name to
-
[Only for edit operation] Set the
url
to “{{reference.target}}” (from the previous step), or retrieve a value using an inline XPath like: “x__$data('contextNode')/@href” if you don't use permanent id's) -
The modal will export the
url operation
with the value the user put in.Data
-
-
[Only if using permanent id's] Add a transform/create
Permanent Id For Reference step -
Set the data
target
to “{{url}}” -
Set the data
reference
to “web”Type
-
-
End with the insertion or edit operation of your choosing, but change the “{{attributes.<url|href|etc>}}” string with “{{permanentId}}” or "{{url}}"
-
-
Find the <web> family configuration
-
Add the name of the popover to your family configuration (Web
Reference Popover, or make your own, Create a popover). Because the 7.0 SDK offers more granular control, the popover should be manually configured instead of it being automatically provided by the platform: Other
configureAsInlineLink(sxModule, 'self::xref', 'link', 'href', { /** existing config **/ visualization: { popoverComponentName: 'WebReferencePopover', popoverData: { editOperationName: 'my-<web>-edit', targetIsPermanentId: true, targetQuery: '@href' } } });
If you use configure
As Inline Link and don’t want to use permanent id’s the fourth argument should be undefined.
-
Add popoverData to your family configuration:
-
edit
: If you want anOperation Name Edit
button in your popover; add an edit operation name -
target
: Set this to true if your web links have permanent id’s. (The default is false)Is Permanent Id -
delete
: Use this if you need a different delete operation thanOperation Name reference-delete
for you web link. -
target
: The query for getting the target value. For example "".Query
-
-
If you use the open-web-reference-modal-for-insert operation for inserting new hyperlinks and the user selected an already-valid URL in the content, then the modal will be skipped and a hyperlink is applied right away. If you use the open-web-reference-modal-for-edit operation, the modal will always be shown regardless of the selection.
Crosslinks, cross references
A cross reference is a reference from one XML position to another. A cross reference can reference an entire XML document or an element in the same or another XML document.
-
Add the cross reference package (fontoxml-crosslink-references) to your platform (via sdk portal) and add this to your
config/fonto-manifest.json
-
Find the <crosslink>-insert <crosslink>-edit operation and replace the steps with the following:
-
[Only for edit operation][only if using permanent id's] Add a transform/retrieve
Reference From Permanent Id step -
Set the data
continue
toOn Error true
-
Set the data
permanent
to the reference we are editing. Recommended is to use an inline XPath expression like: “x__$data('contextNode')/@href”Id -
This step exports a
reference
object tooperation
Data
-
-
[Only for edit operation] Make a transform to transform the url into a documentId (and a nodeId)
-
If you used a DITA reference type, you can use
transform/resolve
Dita Url -
If you used a custom reference type, use that Javascript class for inspiration
-
-
Refactor the modal step, the old cross link browser must be replaced with a new one. Please refer to the section “Upgrading a browse modal” to find which interface is the most suitable and how you can customize it.
-
Your original interface is likely to correlate with one of the following:
If one of these standard browsers do not meet your needs you can fork one of the open source add-ons and make changes as you see fit.
-
Add optional stepData that is needed for your new open modal operation. (In most cases a
linkable
)Elements Query -
[Only for edit operation] Add the documentId (and nodeId) to the stepdata which you resolved in the previous step(s)
-
-
Use a transform step to transform the
document
(andId node
selected in the modal into anId) url
-
If you used a DITA reference type, you can use
transform/create
Dita Url From Loaded Target -
If you used a custom reference type, that Javascript class will contain the code that should be ported to a new transform.
-
-
[only if using permanent id's] Add a transform/create
Permanent Id For Reference step -
Set the data
target
to “{{url}}” -
Set the data
reference
to “crosslink/document/internal/etc...”Type
-
-
End with the insertion or edit operation of your choosing, but change the “{{attributes.<url|href|etc>}}” string with "{{url}}" or with “{{permanentId}}” if you use permanent id's
-
-
Find a suitable React component for the popover
-
If you have a DITA reference type you can use
Dita
.Cross Reference Popover -
If you have a custom reference type you can use
Cross
, from the open source add-on fontoxml-crosslink-references, as basis for a new component, which takes care of the visualisation of the popoverReference Popover -
Add the property
resolve
, To resolve theReference target
into adocument
(and aId node
).Id
-
-
If you have a custom reference type and want more control over visualization you can use
Fx
(fontoxml-fx) as basis for a new component. This allows you to determine the content of the popover, without having to handle the state or errors.Reference Popover -
If you’ve created a new component, register it in the
install.js
JavaScript
uiManager.registerReactComponent('MyCrossReferencePopover', MyCrossReferencePopover);
-
-
Find the <crosslink> family configuration
-
Add the name of the popover to your family configuration. Because the 7.0 SDK offers more granular control, the popover should be manually configured instead of it being automatically provided by the platform:
JavaScript
configureAsInlineLink(sxModule, 'self::xref', 'link', 'href', { /** existing config **/ visualization: { popoverComponentName: 'MyCrossReferencePopover', popoverData: { editOperationName: 'my-<crosslink>-edit', targetIsPermanentId: true, targetQuery: '@href' } } });
If you use configure
As Inline Link and don’t want to use permanent id's the fourth argument should be undefined.
-
-
Add popoverData to your family configuration:
-
edit
: If you want an “Edit” button in your popover; add an edit operation nameOperation Name -
target
: Set this toIs Permanent Id true
if your crosslinks have permanent id’s. (The default isfalse
) -
delete
: Use this if you need a different delete operation thanOperation Name reference-delete
for you cross link. -
target
: The query for getting the target value. For example "Query @href
".
-