Reconfiguring 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/retrieveReferenceFromPermanentId step

    • This is used to preselect the current image if it is in a folder opened by the user.

    • Set the data continueOnError to 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 to operationData

  • Refactor the modal step

    • Change the modal operation name to open-image-browser-modal

    • The properties on stepData can be removed

      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 selectedImageId to "{{reference.target}}"(from the previous step).

  • Add a transform/createPermanentIdForReference step

    • Set the data target to “{{selectedImageId}}”

    • Set the data referenceType to “image”

  • End with the insertion or edit operation of your choosing, but change the “{{attributes.<url|href|etc>}}” string with “{{permanentId}}”

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.

• 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/retrieveReferenceFromPermanentId step

    • Set the data continueOnError to true

    • Set the data permanentId 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 to operationData

  • 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 operationData with the value the user put in.

  • [Only if using permanent id's] Add a transform/createPermanentIdForReference step

    • Set the data target to “{{url}}”

    • Set the data referenceType to “web”

  • 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 (WebReferencePopover, 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 configureAsInlineLink and don’t want to use permanent id’s the fourth argument should be undefined.

  • Add popoverData to your family configuration:

    • editOperationName: If you want an Edit button in your popover; add an edit operation name

    • targetIsPermanentId: Set this to true if your web links have permanent id’s. (The default is false)

    • deleteOperationName: Use this if you need a different delete operation than reference-delete for you web link.

    • targetQuery: The query for getting the target value. For example "".

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/retrieveReferenceFromPermanentId step

    • Set the data continueOnError to true

    • Set the data permanentId 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 to operationData

  • [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/resolveDitaUrl

    • 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:

      • open-nodes-browser-modal

      • open-project-browser-modal

      • open-document-with-link-selector-browser-modal

      • open-document-browser-modal

      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 linkableElementsQuery)

    • [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 documentId (and nodeId) selected in the modal into an url

    • If you used a DITA reference type, you can use transform/createDitaUrlFromLoadedTarget

    • 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/createPermanentIdForReference step

    • Set the data target to “{{url}}”

    • Set the data referenceType to “crosslink/document/internal/etc...”

  • 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 DitaCrossReferencePopover.

  • If you have a custom reference type you can use CrossReferencePopover, from the open source add-on fontoxml-crosslink-references, as basis for a new component, which takes care of the visualisation of the popover

    • Add the property resolveReference, To resolve the target into a documentId (and a nodeId).

  • If you have a custom reference type and want more control over visualization you can use FxReferencePopover (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.

  • 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 configureAsInlineLink and don’t want to use permanent id's the fourth argument should be undefined.

• Add popoverData to your family configuration:

  • editOperationName: If you want an “Edit” button in your popover; add an edit operation name

  • targetIsPermanentId: Set this to true if your crosslinks have permanent id’s. (The default is false)

  • deleteOperationName: Use this if you need a different delete operation than reference-delete for you cross link.

  • targetQuery: The query for getting the target value. For example "@href".