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
Overview
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.
Transcript
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:56XHTML.
00:00:58For our demonstration we have prepared a project
which contains all the resources described
00:01:03earlier.
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:07respectively.
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:45components.
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.
Related Videos
|
Use Oxygen Feedback to ask us anything about this video.