Sharing templates with a customed framework

[TopSolid]

Hi!
I have templates that I wish to share with my team using an updatable chanel as an addon with a customized framework.
I use Oxygen 26 Editor.
I have setup a public github repo with all the structure + autogenerated zip when update.
https://github.com/TopSolid/oxygen-dita-framework
I use this URL as addon entry
https://topsolid.github.io/oxygen-dita- ... nsions.xml
I have tried also with
https://topsolid.github.io/oxygen-dita- ... teSite.xml
But nothing works
Gravité: error
Description: Unable to load add-on "topsolid.dita.framework". Missing required "href" attribute.
I have added href attribute everywhere I could, I am stuck.
Is there any resources/templates/docs that could help me to debug this?
Merci
David

[Radu]

Hello David,

From your original post, only the first link works for me, the second and third ones do not.

If I try to use Oxygen's Help->"Install new add-ons" to install the framework from this URL:
https://raw.githubusercontent.com/TopSo ... ension.xml
things seem to work for me.
So this XML file looks good to me:
https://github.com/TopSolid/oxygen-dita ... ension.xml

This other XML config file I do not know what it represents, Oxygen does not have any knowledge about this type of XML vocabulary:
https://github.com/TopSolid/oxygen-dita ... /addon.xml

Regards,
Radu

[TopSolid]

Hi Radu,
Thanks for your feedback and help.

Yes by the meantime I have found and modified the correct content of extension.xml and now installation works.
But I have now a problem, after installation, the framework is not recognized and loaded in Oxygen. It has something to do with the structure of the zip. Error message :
Les erreurs suivantes ont été rencontrées pendant l'installation des add-ons :
Wrong package structure. Please pack the framework root
directory not just it's contents. Detected roots: [C:\Users\david-a\AppData\Roaming\com.oxygenxml\extensions\v26.1\frameworks\topsolid.dita.framework\addon.xml, C:\Users\david-a\AppData\Roaming\com.oxygenxml\extensions\v26.1\frameworks\topsolid.dita.framework\frameworks]
I have tried to zip with or without topsolid.dita.framework folder and it does not work either.
Can you check what is wrong?

image.png

https://topsolid.github.io/oxygen-dita- ... mework.zip
You can test and install it from here
https://topsolid.github.io/oxygen-dita- ... ension.xml
I am sure it is something basic in the organization of folders in the zip.
When there's no error, the structure of files is:
C:\Users\david-a\AppData\Roaming\com.oxygenxml\extensions\v26.1\frameworks\topsolid.dita.framework\topsolid.dita.framework\frameworks\topsolid.oxygen.dita\framework.xml
Can you specify the correct structure to make it work?
Thanks in advance, Radu!
Best
David

[Radu]

Hello David,
Just remove the "addon.xml" from inside the zip file and you should be OK.
The addon.xml sits outside of the zip file and refers to it.
Regards,
Radu

[TopSolid]

Hello Radu,
Thanks for your feedback.
After having removed addon.xml from the zip file, I have this new error:

Code: Select all

ID Système: https://topsolid.github.io/oxygen-dita-framework/addon.xml
Gravité: error
Description: 404 Not Found for: https://topsolid.github.io/oxygen-dita-framework/addon.xml?_=1744888816436

So I have moved addon.xml to this URL

Code: Select all

https://topsolid.github.io/oxygen-dita-framework/addon.xml

The error disappeared, the extension seems to be correctly installed this time but no sign of installed framework or templates. It does not appear in the list of associated documents.
Can you check what is wrong?
You can test with this URL

Code: Select all

https://topsolid.github.io/oxygen-dita-framework/extension.xml

Thank you
David

[Radu]

Hi David,
What you have at this location is not an Oxygen add-on XML descriptor file:
https://topsolid.github.io/oxygen-dita- ... /addon.xml
From where did you read the documentation that lead you to create this "addon.xml" file format?

An Oxygen add-on XML file which refers to a frameworks folder looks like this:
https://github.com/wendellpiez/JATSKit/ ... mework.xml

What you have at this location is indeed an Oxygen add-on XML descriptor file:
https://topsolid.github.io/oxygen-dita- ... ension.xml

which works when I attempt to install the framework from it. But the contents of the framework itself, the "framework.xml" file:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<framework id="topsolid.oxygen.dita" name="TopSolid Oxygen DITA Framework" version="1.0">
  <extensionBundle>
    <oxygenOptions>
      <fileTypes>
        <fileType name="DITA" description="TopSolid Oxygen DITA Framework" extensions="dita"/>
      </fileTypes>
    </oxygenOptions>
  </extensionBundle>
  
  <documentType>
    <description>TopSolid Oxygen DITA Framework</description>
    <priority>200</priority>
    <extensions>dita</extensions>
    <templateFolder>templates</templateFolder>
    <mainElement name="task"/>
  </documentType>
  
  <templateAccess relativePath="templates"/>
   
  <association>
    <publicId>-//OASIS//DTD DITA Task//EN</publicId>
  </association>

  <recognition>
    <mainElement name="task"/>
    <fileExtension>dita</fileExtension>
  </recognition>
</framework>

this again is not an XML format recognized by Oxygen in any way. So from where did you get the information to create such a file?
Our official documentation for creating framework configurations is here:
https://www.oxygenxml.com/doc/versions/ ... intro.html

Regards,
Radu

[TopSolid]

Hello radu,
I have used ChatGPT 4o which is supposed to be the latest version and it is all wrong about the format. I think its data is obsolete regarding the way how to develop a framework with Oxygen 27.
Do you know what it is the minimal structure of a .framework file to expose templates? What must be the name of .framework file?
I have modified the file and updated the zip with that it is still not working

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<serialized version="12.2" xml:space="preserve">
	<map>
		<entry>
			<String>document.types</String>
			<documentTypeDescriptor-array>
				<documentTypeDescriptor>
					<field name="name">
						<String>topsolid.oxygen.dita</String>
					</field>
					<field name="templatesLocations">
						<String-array>
							<String>${frameworkDir}/templates</String>
						</String-array>
					</field>
					<field name="description">
						<String>TopSolid Oxygen DITA Framework</String>
					</field>
				</documentTypeDescriptor>
			</documentTypeDescriptor-array>
		</entry>
	</map>
</serialized>

Thanks for your help!
David

[Radu]

Hi David,

We cannot control how an AI engine hallucinates when asked about stuff related to Oxygen. No version of Oxygen has ever had those XML formats for writing addon or framework XML files.

As per our official documentation for creating a .framework file, framework files in general are not manually created, you use Oxygen's UI from the Oxygen Preferences->"Document Type Association" page.
https://www.oxygenxml.com/doc/versions/ ... intro.html

Or the alternative is to create an ".exf" file if you want to manually maintain the XML framework file and again this is covered in our docs:
https://www.oxygenxml.com/doc/versions/ ... cript.html

Regards,
Radu

[Radu]

Hi,

Out of curiosity I tried ChatGPT today with the prompt "create an oxygen xml framework configuration file which adds a new template folder" and indeed it gives a wrong answer even if the "Search web" button is toggled.
Our user's guide has it's own AI assistant, so maybe you can use that instead:
https://www.oxygenxml.com/doc/versions/27.1/ug-editor/

It gives this answer to the same prompt:

Code: Select all

AI Assistant

To create an Oxygen XML framework configuration file that adds a new template folder, you can follow these steps:

    Create a Custom Template:
        First, create a new file that will serve as your template. Customize it as needed to be a starting point for new documents.
        Save this template in a directory within your custom framework directory. For example, you might create a directory named templates.

    Configure the Framework:
        Open the Document Type Configuration dialog box for your specific framework.
        Navigate to the Templates tab. This tab allows you to specify directories where new document templates are located for the framework.
        Click the Add button to add your new directory to the list. It's recommended to use a relative path to the framework directory, such as ${frameworkDir}/templates.

    Save and Test:
        Click OK to save your changes in the dialog boxes.
        To test the template, open the New Document wizard and you should see your custom template in the folder for your custom framework.

For more detailed instructions, you can refer to the Customizing New Document Templates for a Framework and Templates Tab sections in the Oxygen XML documentation.