[opencms-dev] Static Export

[Michael Moossen]

Hi, OC-World!
  the following 'tutorial' was the result of a support incident. it is given as
it is, no questions about it should be done directly to us.

Usage of the 'AfterPublish' handler. (Version 6.0.2 or greater)

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 asure that the workplace works.
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 export if it also match a
resourcetorender/regex regular expression.
- 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 to much resources you can try this configuration.
During publishing, it will delete the whole exportpath folder, and just export
the given site1 related resources.

now we add a 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 this 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).

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
/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:
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 as 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.

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>

important to mention that after changing the configuration you should exceute
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 folder, including all
resources) the /system/modules/com.iiwinc.site1/resources folder so that the
resources are exported.

the rules work just maintaining consistency in a already consistent exported
site.

you can read more about export- and rfs-rules in the 
com.alkacon.documentation.documentation_staticexport documentation module 
version 3.0.2 supplied in the 6.0.2 and 6.0.3 distros (not included in the 
updates distros)

-- 
Regards
Michael Moossen

Alkacon Software GmbH - The OpenCms Experts
http://www.alkacon.com


----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.