ºÝºÝߣ

ºÝºÝߣShare a Scribd company logo

Deploying Schemas and XMetaL Customization Files

?
?
XMetaL
XMetaL

Derek Read discusses how XMetaL locates schemas, customization files, and other resources needed for document editing. It first looks in the same folder as the schema, then in default installation folders, and will auto-generate files if they are not found. Complex customizations may involve multiple files packaged together, such as in a XAC file. The XMetaL Developer tool assists with debugging the lookup process. Questions about specific CMS integrations should be directed to the CMS provider.

1 of 23
in 37 minutes Episode 14 Deploying Schemas and XMetaL Customization Files Derek Read, XMetaL Technical Support Brought to you by XMetaL Technical Services ? 2010 JustSystems Inc.
Agenda ? Application-Level vs Document-Level Customizations ? How does XMetaL Author¡­ ¨C ¡­locate a DTD? ¨C ¡­locate an XSD (W3C Schema)? ¨C ¡­locate customization files? ? Complex Customizations, XAC files, XMetaL Developer ? Debugging the lookup process ? Questions ? 2010 JustSystems Inc.
Application-Level Customizations ? One or more macros contained in an MCR file loaded at application initialization. ? May include supporting files (XFT, config and any other file types) called from or used by the macros. ? Macros loaded at startup: <xmetal install>Macrosxmetal.mcr <xmetal install>Macrosmacros.mcr <xmetal install>Startup*.mcr ? Other files may be located anywhere. ? Include macros in your own custom *.mcr file in Startup folder unless required by specific APIs (as documented). ? Toolbars and menus are best customized using script and not delivered as *.TBR files. ? 2010 JustSystems Inc.
Startup Sequence ? The basic startup sequence for XMetaL Author includes: ¨C Load catalog files into memory. ¨C Load Application-Level macros and fire any relevant events. ? This means that for any changes to catalog and Application-Level macros to take effect XMetaL Author must be restarted. ? 2010 JustSystems Inc.
Document-Level Customizations ? A schema (DTD* or XSD*) and all files used to enhance the editing experience for an author working with documents based on that schema. ? Minimum customization includes: ¨C schemaName.dtd / schemaName.xsd / schemaName.rlx / schemaName.rld / schemaName.rls (SGML DTD) ¨C schemaName.css** ¨C schemaName.ctm** * DTD or XSD may reference other files, such as *.mod, *.ent, etc. ** If these files are not present they will be auto-generated. So, all customizations should include properly designed files of these types to provide the best authoring experience. ? 2010 JustSystems Inc.
Document-Level Customizations (continued¡­) ? Optional file types (loaded if found): ¨C schemaName_structure.css* ¨C schemaName.mcr ¨C schemaName.tbr** ¨C schemaName.att ¨C <path><filename>.xft*** * Will be auto-generated if not found when the main CSS file is auto-generated. If the main CSS file is found but this file is missing schemaName_structure.css will not be auto-generated. ** Recommend modifying toolbars and menus via script as delivery of updates to these settings through TBR files can be troublesome. *** Loaded according to <XFTReplacements> settings in the CTM file. ? 2010 JustSystems Inc.
Document-Level Customizations (continued¡­) ? You may choose to distribute only the compiled form of a DTD or XSD (RLX/RLS or RLD file). ? Compiled form may be useful when the DTD or XSD references many other files (file management). ? You may wish to reduce chances of end users modifying the schema. ? 2010 JustSystems Inc.
Locating a DTD ? 2010 JustSystems Inc.
Locating an XSD (W3C Schema) ? 2010 JustSystems Inc.
Locating Customization Files ? Look in same folder as schema (DTD / XSD / RLX / RLD / RLS) and load any of the following if found: schemaName.xac* schemaName.css schemaName_structure.css schemaName.ctm schemaName.mcr * XAC should take precedence. The XAC should be unpacked and the files it contains used. However, we do not support mixing XAC with a ¡°traditional¡± set of customization files so it is best to distribute one or the other. Note as well that the XAC file itself should normally contain the rules file (usually the compiled version in RLX or RLD form) so an external rules file is not necessary when a XAC file is used. ? 2010 JustSystems Inc.
Locating Customization Files (continued¡­) ? If not found in same folder as schema then load*: <xmetal install>DisplayschemaName.css <xmetal install>DisplayschemaName_structure.css <xmetal install>RulesschemaName.ctm <xmetal install>MacrosschemaName.mcr * There are INI settings to alter these paths. Refer to the XMetaL Developer Customization Guide. ? 2010 JustSystems Inc.
Locating Customization Files (continued¡­) ? If still not found: schemaName.css : auto-generate. schemaName.ctm : auto-generate. schemaName_structure.css : If schemaName.css was auto-generated then auto-generated, else if schemaName.css was found then this will not auto-generate. schemaName.mcr : fail to load. ? Auto-generated files should end up here: %appdata%SoftQuadXMetaL6.0gen<drive><recreate schema path> Example: C:Documents and SettingsdreadApplication DataSoftQuadXMetaL6.0genCmyDTDs*.* ? 2010 JustSystems Inc.
Complex Customizations ? Customizations may consist of many files. ? Keep files close together whenever possible. ? Place files in well-known locations. ActiveDocument.ResourceSet provides information about all files loaded automatically (via XAC or otherwise). ? 2010 JustSystems Inc.
Complex Customizations (continued¡­) ? For file types that are not automatically located there are APIs to help: ¨C ActiveDocument.RulesFile tells you the location of the active schema. Useful for finding files delivered in XAC file or otherwise located relative to the schema (DTD, XSD, RLX, RLD, RLS). ¨C Application.Path gives location to xmetal60.exe. Lets you do things like (JScript): Application.Path+"Rules" ? Use Windows Environment Variables to create ¡°limited- user savvy¡± customizations when constructing file paths. Examples: %temp%, %appdata%, %userprofile%, etc¡­ ? 2010 JustSystems Inc.
On_Application_Resolve_Entity Example: <MACRO name="On_Application_Resolve_Entity" hide="false" lang="JScript"><![CDATA[ //Put this macro in StartupmyApplicationMacros.mcr var msg = ""; var entInfo = Application.ResolveEntityInfo; msg += "From doctype declaration (DTD or XSD?): "; msg += entInfo.IsDocType(); //Following properties are read/write. //This is where you would do any overrides. //Any ¡°read¡± comes from the XML file //a ¡°write¡± affects memory only. msg += "nSYSTEM id: " + entInfo.systemID; msg += "nPUBLIC id: " + entInfo.publicID; Application.Alert(msg); ]]></MACRO> ? 2010 JustSystems Inc.
What About XFT Forms? ? Path to XFT is relative to the CTM file. If the CTM file is found then the XFT will be found. ? When using Application.CreateFormDlg() the XFT path should be a full path. ? To find the full path for any file delivered by XAC (including XFT) use script similar to this: //JScript Example: var rfPath = ActiveDocument.RulesFile; var xacFolder = rfPath.substr(0,rfPath.lastIndexOf("")); var myForm = xacFolder + "myform.xft"; Application.CreateFormDlg(myForm); ? 2010 JustSystems Inc.
XAC Files ? XMetaL Developer builds both a XAC file and a ¡°traditional¡± customization (RLX + CSS + CTM + MCR + other). ? XAC file consists of a ZIP archive (renamed *.xac) containing all customization files and a manifest. ? Unpacked to a temp folder before being opened. ? 2010 JustSystems Inc.
XAC Files (continued¡­) ? XMetaL Developer puts all files in the same folder when building. Distribute either XAC or ¡°traditional¡± files only. Do not distribute both. ? When designing complex customizations my personal preference is to avoid XAC files as the unpacking process can add a little bit of complexity. ? 2010 JustSystems Inc.
XMetaL Developer ? Using F5 to debug XMetaL Author from within XMetaL Developer triggers some additional functionality that links the current project (schema and other files) directly to XMetaL Author (or XMAX). ? CSS and CTM files can be modified in XMetaL Developer and these changes are automatically reflected in the authoring tool. ? XMetaL Author adds two items to the Edit menu to allow you to jump back to a particular element in either the CSS or CTM editor. ? 2010 JustSystems Inc.
XMetaL Developer (continued¡­) ? Usually macros can be modified with an ¡°edit and continue¡± feature. ¨C Exceptions are adding new macros and certain events. ? Always test customizations on a machine that does not have XMetaL Developer installed as a final step before distributing to end users. ? 2010 JustSystems Inc.
CMS Systems ? Some CMS integrations require document-level customization files to be installed on the client machine. ? Some CMS integrations store document-level customization files in the CMS and push these files to the client machine when documents are checked out. ? In both cases the CMS integration provider should provide documentation on where XMetaL customization files should be placed and how to configure them to work with that particular CMS. ? 2010 JustSystems Inc.
Settings for Troubleshooting ? Use the following xmetal60.ini settings to troubleshoot DTD and XSD look-up problems. make_log_file = yes * log_file = <path> ** * Default is ?no?. ** Default is the install folder for xmetal60.exe so on some systems (non- admins / UAC enabled) you will need to alter this. Specify the full path and filename of the file. Example: C:tempxm_lookup.log ? 2010 JustSystems Inc.
Q&A Thank you for attending! Next ¡°37 Minute¡± Webinar: Watch for an announcement at http://forums.xmetal.com ? 2010 JustSystems Inc.

More Related Content

Deploying Schemas and XMetaL Customization Files

  • 1. in 37 minutes Episode 14 Deploying Schemas and XMetaL Customization Files Derek Read, XMetaL Technical Support Brought to you by XMetaL Technical Services ? 2010 JustSystems Inc.
  • 2. Agenda ? Application-Level vs Document-Level Customizations ? How does XMetaL Author¡­ ¨C ¡­locate a DTD? ¨C ¡­locate an XSD (W3C Schema)? ¨C ¡­locate customization files? ? Complex Customizations, XAC files, XMetaL Developer ? Debugging the lookup process ? Questions ? 2010 JustSystems Inc.
  • 3. Application-Level Customizations ? One or more macros contained in an MCR file loaded at application initialization. ? May include supporting files (XFT, config and any other file types) called from or used by the macros. ? Macros loaded at startup: <xmetal install>Macrosxmetal.mcr <xmetal install>Macrosmacros.mcr <xmetal install>Startup*.mcr ? Other files may be located anywhere. ? Include macros in your own custom *.mcr file in Startup folder unless required by specific APIs (as documented). ? Toolbars and menus are best customized using script and not delivered as *.TBR files. ? 2010 JustSystems Inc.
  • 4. Startup Sequence ? The basic startup sequence for XMetaL Author includes: ¨C Load catalog files into memory. ¨C Load Application-Level macros and fire any relevant events. ? This means that for any changes to catalog and Application-Level macros to take effect XMetaL Author must be restarted. ? 2010 JustSystems Inc.
  • 5. Document-Level Customizations ? A schema (DTD* or XSD*) and all files used to enhance the editing experience for an author working with documents based on that schema. ? Minimum customization includes: ¨C schemaName.dtd / schemaName.xsd / schemaName.rlx / schemaName.rld / schemaName.rls (SGML DTD) ¨C schemaName.css** ¨C schemaName.ctm** * DTD or XSD may reference other files, such as *.mod, *.ent, etc. ** If these files are not present they will be auto-generated. So, all customizations should include properly designed files of these types to provide the best authoring experience. ? 2010 JustSystems Inc.
  • 6. Document-Level Customizations (continued¡­) ? Optional file types (loaded if found): ¨C schemaName_structure.css* ¨C schemaName.mcr ¨C schemaName.tbr** ¨C schemaName.att ¨C <path><filename>.xft*** * Will be auto-generated if not found when the main CSS file is auto-generated. If the main CSS file is found but this file is missing schemaName_structure.css will not be auto-generated. ** Recommend modifying toolbars and menus via script as delivery of updates to these settings through TBR files can be troublesome. *** Loaded according to <XFTReplacements> settings in the CTM file. ? 2010 JustSystems Inc.
  • 7. Document-Level Customizations (continued¡­) ? You may choose to distribute only the compiled form of a DTD or XSD (RLX/RLS or RLD file). ? Compiled form may be useful when the DTD or XSD references many other files (file management). ? You may wish to reduce chances of end users modifying the schema. ? 2010 JustSystems Inc.
  • 8. Locating a DTD ? 2010 JustSystems Inc.
  • 9. Locating an XSD (W3C Schema) ? 2010 JustSystems Inc.
  • 10. Locating Customization Files ? Look in same folder as schema (DTD / XSD / RLX / RLD / RLS) and load any of the following if found: schemaName.xac* schemaName.css schemaName_structure.css schemaName.ctm schemaName.mcr * XAC should take precedence. The XAC should be unpacked and the files it contains used. However, we do not support mixing XAC with a ¡°traditional¡± set of customization files so it is best to distribute one or the other. Note as well that the XAC file itself should normally contain the rules file (usually the compiled version in RLX or RLD form) so an external rules file is not necessary when a XAC file is used. ? 2010 JustSystems Inc.
  • 11. Locating Customization Files (continued¡­) ? If not found in same folder as schema then load*: <xmetal install>DisplayschemaName.css <xmetal install>DisplayschemaName_structure.css <xmetal install>RulesschemaName.ctm <xmetal install>MacrosschemaName.mcr * There are INI settings to alter these paths. Refer to the XMetaL Developer Customization Guide. ? 2010 JustSystems Inc.
  • 12. Locating Customization Files (continued¡­) ? If still not found: schemaName.css : auto-generate. schemaName.ctm : auto-generate. schemaName_structure.css : If schemaName.css was auto-generated then auto-generated, else if schemaName.css was found then this will not auto-generate. schemaName.mcr : fail to load. ? Auto-generated files should end up here: %appdata%SoftQuadXMetaL6.0gen<drive><recreate schema path> Example: C:Documents and SettingsdreadApplication DataSoftQuadXMetaL6.0genCmyDTDs*.* ? 2010 JustSystems Inc.
  • 13. Complex Customizations ? Customizations may consist of many files. ? Keep files close together whenever possible. ? Place files in well-known locations. ActiveDocument.ResourceSet provides information about all files loaded automatically (via XAC or otherwise). ? 2010 JustSystems Inc.
  • 14. Complex Customizations (continued¡­) ? For file types that are not automatically located there are APIs to help: ¨C ActiveDocument.RulesFile tells you the location of the active schema. Useful for finding files delivered in XAC file or otherwise located relative to the schema (DTD, XSD, RLX, RLD, RLS). ¨C Application.Path gives location to xmetal60.exe. Lets you do things like (JScript): Application.Path+"Rules" ? Use Windows Environment Variables to create ¡°limited- user savvy¡± customizations when constructing file paths. Examples: %temp%, %appdata%, %userprofile%, etc¡­ ? 2010 JustSystems Inc.
  • 15. On_Application_Resolve_Entity Example: <MACRO name="On_Application_Resolve_Entity" hide="false" lang="JScript"><![CDATA[ //Put this macro in StartupmyApplicationMacros.mcr var msg = ""; var entInfo = Application.ResolveEntityInfo; msg += "From doctype declaration (DTD or XSD?): "; msg += entInfo.IsDocType(); //Following properties are read/write. //This is where you would do any overrides. //Any ¡°read¡± comes from the XML file //a ¡°write¡± affects memory only. msg += "nSYSTEM id: " + entInfo.systemID; msg += "nPUBLIC id: " + entInfo.publicID; Application.Alert(msg); ]]></MACRO> ? 2010 JustSystems Inc.
  • 16. What About XFT Forms? ? Path to XFT is relative to the CTM file. If the CTM file is found then the XFT will be found. ? When using Application.CreateFormDlg() the XFT path should be a full path. ? To find the full path for any file delivered by XAC (including XFT) use script similar to this: //JScript Example: var rfPath = ActiveDocument.RulesFile; var xacFolder = rfPath.substr(0,rfPath.lastIndexOf("")); var myForm = xacFolder + "myform.xft"; Application.CreateFormDlg(myForm); ? 2010 JustSystems Inc.
  • 17. XAC Files ? XMetaL Developer builds both a XAC file and a ¡°traditional¡± customization (RLX + CSS + CTM + MCR + other). ? XAC file consists of a ZIP archive (renamed *.xac) containing all customization files and a manifest. ? Unpacked to a temp folder before being opened. ? 2010 JustSystems Inc.
  • 18. XAC Files (continued¡­) ? XMetaL Developer puts all files in the same folder when building. Distribute either XAC or ¡°traditional¡± files only. Do not distribute both. ? When designing complex customizations my personal preference is to avoid XAC files as the unpacking process can add a little bit of complexity. ? 2010 JustSystems Inc.
  • 19. XMetaL Developer ? Using F5 to debug XMetaL Author from within XMetaL Developer triggers some additional functionality that links the current project (schema and other files) directly to XMetaL Author (or XMAX). ? CSS and CTM files can be modified in XMetaL Developer and these changes are automatically reflected in the authoring tool. ? XMetaL Author adds two items to the Edit menu to allow you to jump back to a particular element in either the CSS or CTM editor. ? 2010 JustSystems Inc.
  • 20. XMetaL Developer (continued¡­) ? Usually macros can be modified with an ¡°edit and continue¡± feature. ¨C Exceptions are adding new macros and certain events. ? Always test customizations on a machine that does not have XMetaL Developer installed as a final step before distributing to end users. ? 2010 JustSystems Inc.
  • 21. CMS Systems ? Some CMS integrations require document-level customization files to be installed on the client machine. ? Some CMS integrations store document-level customization files in the CMS and push these files to the client machine when documents are checked out. ? In both cases the CMS integration provider should provide documentation on where XMetaL customization files should be placed and how to configure them to work with that particular CMS. ? 2010 JustSystems Inc.
  • 22. Settings for Troubleshooting ? Use the following xmetal60.ini settings to troubleshoot DTD and XSD look-up problems. make_log_file = yes * log_file = <path> ** * Default is ?no?. ** Default is the install folder for xmetal60.exe so on some systems (non- admins / UAC enabled) you will need to alter this. Specify the full path and filename of the file. Example: C:tempxm_lookup.log ? 2010 JustSystems Inc.
  • 23. Q&A Thank you for attending! Next ¡°37 Minute¡± Webinar: Watch for an announcement at http://forums.xmetal.com ? 2010 JustSystems Inc.