VideosWorking with Schematron Modules

Table of Contents
  • Introduction03:18
  • Edit the Schematron Module01:59
  • Detecting Schematron Master Files01:43
  • Master Files Support Benefits01:35
  • Search & Refactor Actions01:02


Duration: 09:39
This video covers several Oxygen features that are useful for developing Schematron modules, the use of the Content Completion Assistant, Master Files support, and search and refactoring actions.


00:00:08In this demonstration we'll cover several oXygen features useful for
00:00:12developing Schematron modules:
00:00:14the use of content completion assistant, master files support, and
00:00:19search and refactoring actions.
00:00:22A common case of using a Schematron modular system is when the abstract
00:00:26pattern mechanism is used.
00:00:29Abstract patterns allow a common definition mechanism for structures which use different
00:00:33names and paths,
00:00:35but are conceptually identical.
00:00:38To demonstrate this usecase, we'll use a modular system to define a set of best_practice-type
00:00:43rules over a table structure.
00:00:46The abstract rules definitions are kept in the abstract_patterns module,
00:00:51while the implementations are kept in separate modules: one for DITA and the other one for
00:00:58For our demonstration we have prepared a project which contains all the resources described
00:01:04Let's take a look at the "abstract_patterns" module.
00:01:07The first pattern is applicable in the context of a "table" element.
00:01:12The number of rows is computed, then it is checked that this number falls between a minimum
00:01:18and a maximum value.
00:01:20Note that this abstract pattern defines the following parameters:
00:01:23- $table and $row , matching names for elements defining tables and rows, respectively
00:01:29- $minRows and $maxRows, defining the minimum and maximum number of rows accepted as a best
00:01:37practice rule.
00:01:38The second abstract pattern checks that in the context of a table,
00:01:43the number of columns falls between a minimum and a maximum value.
00:01:47To keep the use case simple, the maximum number of columns is computed as being the maximum
00:01:52number of cells from each row,
00:01:55ignoring cases when a cell spans over multiple rows or columns.
00:02:00The following parameters are used:
00:02:02- table, row, cell, matching names for elements defining tables, rows and cells, respectively
00:02:09- $minCols and $maxCols, defining the minimum and maximum number of columns accepted as
00:02:17a best practice rule.
00:02:19Now we'll see how these abstract rules are used to enforce the best practice rules in
00:02:25an XHTML document.
00:02:28To check the number of rows in a table, we define a particular pattern as an instance
00:02:34of the "bp_table_rows_number" abstract pattern.
00:02:39XHTML tables and rows are defined using the "table" and 'tr' elements from XHTML namespace.
00:02:47As a best practice rule we consider that the number of rows should be between 3 and 20.
00:02:53Similarly, we instantiate the second abstract rule to check the number of table columns.
00:03:00In this case we verify that the number of columns is greater than 2 and less than 7.
00:03:06Now we open the DITA_table module.
00:03:09We see that both abstract patterns are also used in the DITA module to check the number
00:03:14of rows and columns of CALS tables.
00:03:21Next, we will edit instances of the two abstract patterns to deal with DITA's simpleTables.
00:03:29First, we will create the pattern that checks the number of rows by instantiating the 'bp_table_rows_number'
00:03:38abstract pattern.
00:03:41Note that the content completion assistant proposes the abstract patterns from the entire
00:03:52schema hierarchy when editing the value of "is-a" attribute.
00:04:00In this case we use 'simpleTable' and 'strow' for table and row elements,
00:04:08We consider that the simple table conforms with the best practices rules if the number
00:04:13of rows are between 3 and 10.
00:04:20The last abstract pattern limits the number of columns in a DITA simpleTable.
00:04:27Next we'll deal with some problems commonly found when developing Schematron modules.
00:04:32For example, to navigate to the definition of 'bp_table_rows_number' abstract pattern,
00:04:38hold the CTRL key and click the abstract pattern reference.
00:04:43Next we want to rename the pattern 'bp_table_rows_number' to 'best_practices_table_rows_number'.
00:04:54If we validate the module, it turns out to be valid.
00:04:58This is because the scope of the validation is limited to the current file only.
00:05:02However, the pattern which was renamed is referred in two Schematron files:
00:05:08DITA_table.sch and XHTML_table.sch, which become invalid because they refer components
00:05:15which are no longer defined.
00:05:21This is the main reason why a module should be edited in a broader context.
00:05:26To help developers achieve this, starting with version 15.2,
00:05:31oXygen implemented the master files support for Schematron schemas.
00:05:35A master file generally means the root of an import/include tree of modules.
00:05:42The master files are defined at project level and are automatically used by oXygen to determine
00:05:47the context for several operations such as validation, content-completion, refactoring
00:05:54or search.
00:05:56To enable the master files support, press the 'Enable' button in the Project view.
00:06:01The application displays an information dialog which allows us to determine the possible
00:06:05master files and set them as such.
00:06:08Here we choose to detect the possible master files for Schematron files.
00:06:14After the detection is complete, oXygen presents a tree with the hierarchy of the files from
00:06:20the project.
00:06:20On the first level we have the possible master files, which are the Schematron schemas that
00:06:27are not imported or included by other modules.
00:06:30We set the two files as master files.
00:06:34Note that the imported/included Schematron resources are marked as modules.
00:06:40The tooltip displays information about the resource type, its location and the master
00:06:44files set for this resource.
00:06:48In the last wizard page you can preview the master files that will be added in the project.
00:06:54oXygen added the selected resources in the Master Files folder from the Project view.
00:07:04So far we've seen how we can detect and set the master files to define the Schematron
00:07:10editing context.
00:07:12Next we'll see how oXygen helps you edit a Schematron module in the context defined by
00:07:17their master files.
00:07:19Let's validate the abstract_patterns module.
00:07:23The first thing we notice is that now the module is marked as invalid because it is
00:07:28validated in the context of the master files previously set.
00:07:32When a module is validated, oXygen will automatically identify the master files which include that
00:07:38module and validate all of them.
00:07:41Let's correct the errors from both master files and go back to the module to perform
00:07:45another validation, after renaming the patern.
00:07:48To rename a pattern in the context of the current file only, we invoke the "Rename Component"
00:07:54action from the Quick Assist helper.
00:08:06Similarly we'll correct the second master file.
00:08:21It becomes valid after we rename the pattern.
00:08:25Now... going back to the abstract_patterns module...
00:08:29we invoke the validate action.
00:08:32The module is now valid because both master files are valid.
00:08:40Another benefit of the master files support is the ability to search and refactor Schematron
00:08:45Search and refactoring actions, like search references or rename components operate in
00:08:51the scope defined by the current module's master files.
00:08:55Now let's rename the bp_table_columns_number pattern.
00:08:59To safely propagate the change in the entire structure, we'll use the "Rename Component
00:09:05In.." action from the Quick Assist helper.
00:09:09The new name is best_practices_table_columns_number.
00:09:15When previewing the modifications..., we can see that the pattern was renamed in all Schematron
00:09:21documents where it is referred from.
00:09:28And this concludes our demonstration.
00:09:35Thanks for watching.

Use Oxygen Feedback to ask us anything about this video.