Customizing the DITA behavior in Collective Spaces
Configure your own custom DITA specialization for use with Collective Spaces, or change the out-of-the-box configuration.
Before you begin
If you want to configure your own custom DITA specialization, you also need your DTD and corresponding XML Schema file. As Collective Spaces uses a compiled schema format, the XML Schema is required.
Procedure
- If you want to change the behavior only, without adding or updating custom DITA specialization, skip ahead to step 7.
- Go to the Web\Author\ASP\DocTypes\ folder, where Content Manager keeps all DTD, XML Schema and catalog-related files. You will need to install the new DTD and XML Schema files there. More information here: Install DTDs/Schema's.
- Add entries for the new DTD and XML Schema files in the catalog.xml. More information here: Configuring the OASIS catalog.
You can now successfully upload XML documents that refer to the new DTD in Content Manager.
- Add entries for the new DTD and XML Schema files in the catalog-mapping.xml file. Add a line like the following to this file:
<match rootelement="apiref" dtdpublicid="-//SDL//DTD DITA API Reference//EN" dtdsystemid="dita-sdl/1.3/dtd/apiref/dtd/apiref.dtd" xsdsystemid="urn:sdl:names:tc:dita:spec:apiref:xsd:apiref.xsd" xsdname="" xsduri="apiref.xsd" /> - Replace all attribute values in this line with values that are correct for your DTD and Schema.
- In order to validate your schemas and configuration files and compile the schemas to a format Collective Spaces understands, start PowerShell as administrator and run the following ISHDeploy command:
Set-ISHFontoSchemaExperience -IshDeployment InfoShare(You only need to use the-IshDeploymentswitch if you have multiple deployments.InfoShareis the name of the default deployment.) If all is correct, the command saves the resulting files in the Web\InfoShareCS\custom\ folder (overwriting the existing SchemaLocationConfig.xml file and saving the generated compiled schema files in the schemas\ subfolder) and restarts the web application pool of Collective Spaces automatically. In your browser, in Collective Spaces, you can now open a publication that contains XML documents that refers to the new DTD. You will see the out-of-the-box behavior, which is always applied to any DTD, but which might not look nice or behave well for your new DTD yet.Note: To perform the schema compilation, theSet-ISHFontoSchemaExperiencecommand compresses the schemas, starts the App\Utilities\FontoSchemaCompiler\FontoXml.Sdk.SchemaCompiler.App.exe application, passes the compressed schemas to it to compile them, and stops the application again. - To configure custom specialized XML elements or overwrite (parts of) the out-of-the-box configuration for the standard DITA elements, you can make additions to the BehaviorConfig.xml file, which is empty by default. More information here: BehaviorConfig.xml and here: BehaviorConfig.xml - Examples and How To
- After making changes to the BehaviorConfig.xml file, start PowerShell as administrator and run the following ISHDeploy command (again, if you ran it in step 6):
Set-ISHFontoSchemaExperience -IshDeployment InfoShareAuthorThis will validate whether your XML is correct, and if all is correct, save the SchemaLocationConfig.xml and compiled schemas, and restart the web application pool, so that you can see the result of your changes immediately (after reloading the publication in the browser).
- Collective Spaces - BehaviorConfig.xml
The Collective Spaces user interfaces ship with default rendering and menu behavior for the DITA XML elements, defined in the DITA OASIS and SDL DTDs and schemas. You can customize Collective Spaces by editing the configuration file BehaviorConfig.xml, which is applied on top of the default behavior. In BehaviorConfig.xml, you define how DITA XML elements should be rendered for an XML document, which contextual menu items to show and which menu items to show in the Custom top menu tab. - Collective Spaces - SchemaLocationConfig.xml
The SchemaLocationConfig.xml file is used by Collective Spaces and contains the file locations of the custom schemas together with their matching compiled schema location and their DTD Public ID or schema URN.