Tutorial
Usage of the advanced static export features.
All what we need is in the opencms/staticexport node of the opencms-importexport.xml configuration file .
First, leave everything with the standard values:
<staticexport enabled="true">
<staticexporthandler>org.opencms.staticexport.CmsOnDemandStaticExportHandler</staticexporthandler>
<exportpath>export</exportpath>
<defaultpropertyvalue>false</defaultpropertyvalue>
<defaultsuffixes>
<suffix key=".jpg"/>
<suffix key=".gif"/>
<suffix key=".png"/>
<suffix key=".doc"/>
<suffix key=".xls"/>
<suffix key=".ppt"/>
<suffix key=".pdf"/>
<suffix key=".txt"/>
<suffix key=".css"/>
<suffix key=".zip"/>
<suffix key=".swf"/>
</defaultsuffixes>
<rendersettings>
<rfs-prefix>${CONTEXT_NAME}/export</rfs-prefix>
<vfs-prefix>${CONTEXT_NAME}${SERVLET_NAME}</vfs-prefix>
<userelativelinks>false</userelativelinks>
<exporturl>http://127.0.0.1:8080/${CONTEXT_NAME}/handle404</exporturl>
<plainoptimization>true</plainoptimization>
<testresource uri="/system/shared/page.dtd"/>
<resourcestorender>
<regex>/sites/.*</regex>
<regex>/system/galleries/.*</regex>
<regex>/system/modules/.*/resources/.*</regex>
</resourcestorender>
</rendersettings>
</staticexport>
To assure that the OpenCms workplace works properly.
Now, change the staticexporthandler node value to org.opencms.staticexport.CmsAfterPublishStaticExportHandler and be aware of following during publishing:
- If just one resource is published that does not match any export-rule , all resources that match one of the resourcetorender/regex regular expressions will be exported. so if no rule is defined, everything you publish will lead to re-export everything.
- If a resource match a export-rule , it will be only exported if it also match a resourcetorender/regex regular expression. (This is only true for non-template resources. Please, do not ask why.)
So you should first change the resourcetorender/regex regular expressions so they embrace all resources of one of your sites, for which we will write our first export-rule .
Let say your site is under /sites/site1 , and that you have a module for this site like com.example.site1 (so, we will need to export also the module resources under /system/modules/com.example.site1/resources ).
Our first draft (without export-rule ) should look like:
<staticexport enabled="true">
<staticexporthandler>org.opencms.staticexport.CmsAfterPublishStaticExportHandler</staticexporthandler>
<exportpath>export</exportpath>
<defaultpropertyvalue>false</defaultpropertyvalue>
<defaultsuffixes>
<suffix key=".jpg"/>
<suffix key=".gif"/>
<suffix key=".png"/>
<suffix key=".doc"/>
<suffix key=".xls"/>
<suffix key=".ppt"/>
<suffix key=".pdf"/>
<suffix key=".txt"/>
<suffix key=".css"/>
<suffix key=".zip"/>
<suffix key=".swf"/>
</defaultsuffixes>
<rendersettings>
<rfs-prefix>${CONTEXT_NAME}/export</rfs-prefix>
<vfs-prefix>${CONTEXT_NAME}${SERVLET_NAME}</vfs-prefix>
<userelativelinks>false</userelativelinks>
<exporturl>http://127.0.0.1:8080/${CONTEXT_NAME}/handle404</exporturl>
<plainoptimization>true</plainoptimization>
<testresource uri="/system/shared/page.dtd"/>
<resourcestorender>
<regex>/sites/site1/.*</regex>
<regex>/system/modules/com.example.site1/resources/.*</regex>
</resourcestorender>
</rendersettings>
</staticexport>
If the site does not have too much resources you can try this configuration, as it is. During publishing, it will delete the whole exportpath folder, and just export the given site1 related resources.
Now, we can add an export-rule for the site:
An export-rule just defines following relation of dependency:
Which resources should be exported if a resource has been new created or modified. So, you define in the export-rule/modified-resources/regex nodes which resources will include this rule, and in the export-rule/export-resources/uri the resources to be exported if some of the given resources has been modified (or new created). See more details about export-rules here.
So the simpliest one will look like:
<export-rules>
<export-rule>
<name>rule for site one</name>
<description>description of rule for site one</description>
<modified-resources>
<regex>/sites/site1/.*</regex>
<regex>/system/modules/com.example.site1/.*</regex>
</modified-resources>
<export-resources>
<uri>/sites/site1/</uri>
</export-resources>
</export-rule>
</export-rules>
This rule will work like follows. The whole site will be exported (without resources) if:
- Any page in the site is changed, so for example navigation links will stay uptodate.
- Any template or any module resource is changed.
Please, note that we have not included the modules resources ( /system/modules/com.example.site1/resources/.* ) in the export-rule/export-resources node, so if you change or create a new resource only that resource (and the whole site) will be exported.
You could improve this by excluding the module's resources folder from the rule, instead of
<regex>/system/modules/com.example.site1/.*</regex>
use something like:
<regex>/system/modules/com.example.site1/[^resources/].*</regex>
So the first version of our configuration will look like:
<staticexport enabled="true">
<staticexporthandler>org.opencms.staticexport.CmsAfterPublishStaticExportHandler</staticexporthandler>
<exportpath>export</exportpath>
<defaultpropertyvalue>false</defaultpropertyvalue>
<defaultsuffixes>
<suffix key=".jpg"/>
<suffix key=".gif"/>
<suffix key=".png"/>
<suffix key=".doc"/>
<suffix key=".xls"/>
<suffix key=".ppt"/>
<suffix key=".pdf"/>
<suffix key=".txt"/>
<suffix key=".css"/>
<suffix key=".zip"/>
<suffix key=".swf"/>
</defaultsuffixes>
<rendersettings>
<rfs-prefix>${CONTEXT_NAME}/export</rfs-prefix>
<vfs-prefix>${CONTEXT_NAME}${SERVLET_NAME}</vfs-prefix>
<userelativelinks>false</userelativelinks>
<exporturl>http://127.0.0.1:8081/${CONTEXT_NAME}/handle404</exporturl>
<plainoptimization>true</plainoptimization>
<testresource uri="/system/shared/page.dtd"/>
<resourcestorender>
<regex>/sites/.*</regex>
<regex>/system/galleries/.*</regex>
<regex>/system/modules/.*/resources/.*</regex>
<export-rules>
<export-rule>
<name>rule for site one</name>
<description>description of rule for site one</description>
<modified-resources>
<regex>/sites/site1/.*</regex>
<regex>/system/modules/com.example.site1/.*</regex>
</modified-resources>
<export-resources>
<uri>/sites/site1/</uri>
</export-resources>
</export-rule>
</export-rules>
</resourcestorender>
</rendersettings>
</staticexport>
Of course that you can have several rules for a single site, and as more detailed your dependencies are described, less resources will be innecesary re-exported.
You can also add a staticexport/rendersettings/rfs-rules/rfs-rule node, if you want export site1 to another path than exportpath :
<rfs-rules>
<rfs-rule>
<name>rule for site one</name>
<description>description of the rule</description>
<source>/sites/site1/.*</source>
<rfs-prefix></rfs-prefix>
<exportpath>/apache/site1</exportpath>
<userelativelinks>false</userelativelinks>
<related-system-res>
<regex>/system/modules/com.example.site1/resources/.*</regex>
</related-system-res>
</rfs-rule>
</rfs-rules>
As you can see you can configure with the <source> node the resources to be exported (as a regular expression), and you can also set the related system resources ( <related-system-res> node) to be exported to that <exportpath> .
So the workplace will use all default settings and your site the settings given in the rfs-rule . See more details about rfs-rules here.
So our final configuration will look like:
<staticexport enabled="true">
<staticexporthandler>org.opencms.staticexport.CmsAfterPublishStaticExportHandler</staticexporthandler>
<exportpath>export</exportpath>
<defaultpropertyvalue>false</defaultpropertyvalue>
<defaultsuffixes>
<suffix key=".jpg"/>
<suffix key=".gif"/>
<suffix key=".png"/>
<suffix key=".doc"/>
<suffix key=".xls"/>
<suffix key=".ppt"/>
<suffix key=".pdf"/>
<suffix key=".txt"/>
<suffix key=".css"/>
<suffix key=".zip"/>
<suffix key=".swf"/>
</defaultsuffixes>
<rendersettings>
<rfs-prefix>${CONTEXT_NAME}/export</rfs-prefix>
<vfs-prefix>${CONTEXT_NAME}${SERVLET_NAME}</vfs-prefix>
<userelativelinks>false</userelativelinks>
<exporturl>http://127.0.0.1:8080/${CONTEXT_NAME}/handle404</exporturl>
<plainoptimization>true</plainoptimization>
<testresource uri="/system/shared/page.dtd"/>
<resourcestorender>
<regex>/sites/site1/.*</regex>
<regex>/system/modules/com.example.site1/resources/.*</regex>
<export-rules>
<export-rule>
<name>rule for site one</name>
<description>description of rule for site one</description>
<modified-resources>
<regex>/sites/site1/.*</regex>
<regex>/system/modules/com.example.site1/.*</regex>
</modified-resources>
<export-resources>
<uri>/sites/site1/</uri>
</export-resources>
</export-rule>
</export-rules>
</resourcestorender>
<rfs-rules>
<rfs-rule>
<name>rule for site one</name>
<description>description of the rule</description>
<source>/sites/site1/.*</source>
<rfs-prefix></rfs-prefix>
<exportpath>/apache/site1</exportpath>
<userelativelinks>false</userelativelinks>
<related-system-res>
<regex>/system/modules/com.example.site1/resources/.*</regex>
</related-system-res>
</rfs-rule>
</rfs-rules>
</rendersettings>
</staticexport>
Finally, important to mention is that, after changing the configuration you should execute once a full static export from the Administration View -> Database -> Static Export tool, so everything is exported. Or touch a file in the /sites/site1
folder so that the site is exported, and touch the /system/modules/com.example.site1/resources folder (the folder, including all resources) so that all the resources are exported. The rules work just maintaining consistency in an already consistent exported site.