VideosWorking with Schematron Modules


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.