You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@lenya.apache.org by Apache Wiki <wi...@apache.org> on 2006/08/13 15:56:33 UTC
[Lenya Wiki] Update of "HowToEditCustomDoctypesWithBXE" by drseuk
Dear Wiki user,
You have subscribed to a wiki page or wiki category on "Lenya Wiki" for change notification.
The following page has been changed by drseuk:
http://wiki.apache.org/lenya/HowToEditCustomDoctypesWithBXE
New page:
=HowToEditCustomDoctypesWithBXE=
==Overview for the impatient==
Change four lines in usecase-bxeng.xmap:
<!-- <map:part src="../../resources/misc/bxeng/content-namespaces.xml"/> -->
to
<map:part src="resources/misc/bxeng/{page-envelope:document-type}-namespaces.xml"/>
and
<!--<map:generate src="../../resources/misc/bxeng/inc/config.xml"/> -->
to
<map:generate src="resources/misc/bxeng/inc/{page-envelope:document-type}-config.xml"/>
and
<!-- <map:transform src="../../xslt/bxeng/config-xml.xsl"> -->
to
<map:transform src="xslt/bxeng/{page-envelope:document-type}-config-xml.xsl">
and
<!-- <map:parameter name="contextmenufile" value="../../resources/misc/bxeng/contextmenu.xml"/> -->
to
<map:parameter name="contextmenufile" value="resources/misc/bxeng/{page-envelope:document-type}-contextmenu.xml"/>
n.b. you'll have to create the resources/misc/bxeng/inc and xslt/bxeng directories.
Now, copy ../../resources/misc/bxeng/content-namespaces.xml to resources/misc/bxeng/xhtml-namespaces.xml,
../../resources/misc/bxeng/inc/config.xml to resources/misc/bxeng/inc/xhtml-config.xml and
../../resources/misc/bxeng/contextmenu.xml to resources/misc/bxeng/xhtml-contextmenu.xml
For new doctypes, simply copy the four xhtml- files to e.g., wine-namespaces.xml, inc/wine-config.xml, wine-contextmenu.xml and wine-config-xml.xsl etc. and modify them to suit your doctype.
Frankly, I don't know why Lenya isn't configured this way by default.
==Introduction==
I'll sometimes use "cellar" to mean the root directory of the publication with "wine" as the custom doctype.
You click on the "Edit"->"WYSIWYG Editor (BXE)" menu item.
This menu item is defined in cellar/config/menus/generic.xsp.
<menu i18n:attr="name" name="Edit" label="Search"><!-- Start of definition of "Edit" menu-->
<block info="false">
<item wf:event="edit" uc:usecase="kupu" uc:step="open" href="?"><i18n:text>Edit with Kupu</i18n:text></item>
<!-- Next line is the BXE item-->
<item wf:event="edit" uc:usecase="bxeng" uc:step="open" href="?"><i18n:text>Edit with BXE</i18n:text></item>
<item wf:event="edit" uc:usecase="edit" uc:step="open"><xsp:attribute name="href"><xsp:expr>"?form=" + docType</xsp:expr></xsp:attribute><i18n:text>Edit with Forms</i18n:text></item>
<item wf:event="edit" uc:usecase="1formedit" uc:step="open" href="?"><i18n:text>Edit with one Form</i18n:text></item>
...
</menu>
The text "Edit with BXE" is actually a key in cellar/../../resources/i18n/cmsui.xml and the other cmsui_nn.xml files where nn is the language code for the menu text etc. In cmsui.xml (and indeed, bizarrely, in all the other cmsui_nn.xml too!) this key is associated with the text you actually see on the menu, namely "WYSIWYG Editor (BXE)".
Anyway, so the BXE line in the code above says "go inside the usecase-bxeng.xmap file and start at the 'open' step with a href of '?' ". The usecase-bxeng.xmap file is in {pub}. You may wonder where the other usecase files for the other editors (the "One big form editor/ 1formeditor / Source editor" or whatever it's called this week, the "Forms Editor" and Kupu) are. There're in cellar/../../usecases. Strange? Well, not really. The one form editor works with all doctypes out of the box so why would you want to customise it on a per publication basis? Similarly, the only customisation likely to be needed for the multiple "Forms Editor" is in your custom doctypes' cellar/lenya/xslt/formeditor/wine.xsl file. Kupu only supports XHTML so again is not likely to need customising. Keeping the usecases up the tree just keeps the out of the way and makes sense.
The usecase-bxeng.xmap file by contrast is in cellar precisely because we (may) need to change it presumably.
You may (or may not!) have noticed the section in publication-sitemap.xmap begining with the comment <!-- BX Editor: RNG Schema, CSS -->. Essentially this is a helper section for BXE so that when it asks for the wine.rng (the wine doctype's grammar file) and bxeng-wine.css (how you want the wine doctype to appear within BXE) files, Lenya will give BXE the right files in a suitable way for BXE.
==The usecase-bxeng.xmap file==
The bit of the file where we start is:
<map:match type="usecase" pattern="bxeng">
<map:match type="step" pattern="open">
<!-- Check for BXENG -->
and as you can see, the usecase(="bxeng") and step (="open") match our menu item from before.
Check if BXE is installed
<map:act type="resource-exists" src="../../resources/bxeng/bxeLoader.js">
and if it is check out our document or throw an error
<map:act type="reserved-checkout">
<map:generate type="serverpages" src="../../content/rc/{exception}.xsp">
<map:parameter name="user" value="{user}"/>
<map:parameter name="filename" value="{filename}"/>
<map:parameter name="date" value="{date}"/>
<map:parameter name="message" value="{message}"/>
</map:generate>
<map:transform src="../../xslt/rc/rco-exception.xsl"/>
<map:call resource="style-cms-page"/>
</map:act>
Next we need look at cellar/../../resources/misc/bxeng/index.html. Essentially this sets up a basic BXE xhtml page that will get modified to fit with our doctype later. Again, the fact that this file is kept outside of our publication probably means we can ignore it and in fact, we can.
Now, let's peek at cellar/../../resources/misc/bxeng/content-namespaces.xml. This simply contains a list of the namespaces we wish to use. By default it's got xhtml, lenya, dc and dcterms defined in there. We'll need to change this file.
Glue the bxe xhtml page together with the namespaces which might seem weird (appending a bit of xml onto the end of an xhtml file) ...
<map:aggregate element="bxeng">
<map:part src="../../resources/misc/bxeng/index.xhtml"/>
<map:part src="../../resources/misc/bxeng/content-namespaces.xml"/>
</map:aggregate>
... but makes sense when you run xsl against it to shove the namespaces into meta elements (e.g., <meta name="bxeNS" content="{dc=http://purl.org/dc/elements/1.1/}"/>) and create a proper xhtml document with these meta elements inside the head element. This is a neat trick even though there are other ways to do this - see if you can spot why and how it's done this way.
<map:transform src="../../xslt/bxeng/aggregate.xsl"/>
and add the configfile and context for our doctype to the xhtml file. (This is the important bit). Ah, hang on, we're passing the configfile and context to the stylesheet! Again, the fact that the index-xhtml.xsl file is kept outside of our publication probably means we can ignore it and in fact, we can. What we're actually doing here is telling BXE to call Lenya whenever it wants a configfile or context. Note that Lenya will get called with usecase="bxeng" and step="config". I.e., call the appropriate bit of this (usecase-bxeng.xmap) file which we'll get to in a bit.
<map:transform src="../../xslt/bxeng/index-xhtml.xsl">
<map:parameter name="configfile" value="{request:requestURI}?lenya.usecase=bxeng&lenya.step=config"/>
<map:parameter name="context" value="{request:contextPath}"/>
</map:transform>
strip off the namespaces for some unknown reason ... does what it says on the tin.
<map:transform src="../../xslt/util/strip_namespaces.xsl"/>
and chuck it out as xhtml, which it is.
<map:serialize type="xhtml"/>
the next line is indented incorrectly (in my version) but ends our "resource-exists" (i.e., BXE is installed) action
</map:act>
else pop up a page to tell you how to download BXE.
<map:generate src="../../resources/misc/bxeng/download.xhtml"/>
<map:call resource="style-cms-page"/>
<map:serialize type="xhtml"/>
</map:match>
OK. So we've not had to modify anything so far which is why the other documentation on BXE says "start with the config step".
An image upload dialog box step ...
<map:match pattern="image-upload-show" type="step">
<map:call resource="cms-screen">
<map:parameter name="serverpage" value="info/assets.xsp"/>
<map:parameter name="stylesheet" value="bxeng/image.xsl"/>
</map:call>
</map:match>
An asset upload dialog box step ...
<map:match pattern="asset-upload-show" type="step">
<map:call resource="cms-screen">
<map:parameter name="serverpage" value="info/assets.xsp"/>
<map:parameter name="stylesheet" value="bxeng/asset.xsl"/>
</map:call>
</map:match>
Trigger an asset upload... (calls the asset upload dialog box step above)
<map:match type="step" pattern="asset-upload">
<map:act type="upload">
<map:redirect-to uri="{request:requestURI}?lenya.usecase=bxeng&lenya.step=asset-upload-show"/>
</map:act>
<map:generate src="../../content/info/assets.xsp" type="serverpages"/>
<map:transform src="../../xslt/bxeng/asset.xsl">
<map:parameter name="use-request-parameters" value="true"/>
<map:parameter name="error" value="true"/>
</map:transform>
<map:call resource="style-cms-page"/>
</map:match>
Trigger an image upload ... (calls the image upload dialog box step above)
<map:match type="step" pattern="image-upload">
<map:act type="upload">
<map:redirect-to uri="{request:requestURI}?lenya.usecase=bxeng&lenya.step=image-upload-show"/>
</map:act>
<map:generate src="../../content/info/assets.xsp" type="serverpages"/>
<map:transform src="../../xslt/bxeng/image.xsl">
<map:parameter name="use-request-parameters" value="true"/>
<map:parameter name="error" value="true"/>
</map:transform>
<map:call resource="style-cms-page"/>
</map:match>
Sort out links ...
<map:match pattern="link-show" type="step">
<!-- just a dummy xsp since we call the info area directly -->
<map:generate type="serverpages" src="../../content/info/assets.xsp"/>
<map:transform src="../../xslt/bxeng/link.xsl" label="content">
<map:parameter name="infoarea" value="true"/>
<map:parameter name="contextprefix" value="{request:contextPath}"/>
<map:parameter name="publicationid" value="{page-envelope:publication-id}"/>
<map:parameter name="area" value="authoring"/>
<map:parameter name="tab" value="en"/>
<map:parameter name="chosenlanguage" value="{page-envelope:document-language}"/>
<map:parameter name="documentid" value="{page-envelope:document-id}"/>
<map:parameter name="documenturl" value="/{page-envelope:document-url}"/>
<map:parameter name="documentextension" value="{page-envelope:document-extension}"/>
<map:parameter name="defaultlanguage" value="{page-envelope:default-language}"/>
<map:parameter name="languages" value="{page-envelope:publication-languages-csv}"/>
</map:transform>
<map:call resource="style-cms-page"/>
</map:match>
BXE will now call this step below as we told it to earlier (remember?).
<map:match pattern="**/*.html">
<!-- configuration -->
<map:match type="step" pattern="config">
Grab the config.xml file. This is a standard BXE config.xml file which tells BXE what input files to use (the xml document file we want to edit, the xhtml file we created earlier, the doctype's rng file and the xsl file to turn the xml file into the output file), what output we want, which bxe scripts to load and what buttons we want in our interface (e.g., lenya asset upload buttons are included here). Even though this file is outside our publication we'll need to change this to get buttons suitable for our doctype.
<map:generate src="../../resources/misc/bxeng/inc/config.xml"/>
Ahh, OK. It looks like we're going to run an xsl file against the config.xml file with some parameters to convert it into one suitable for our doctype.
<map:transform src="../../xslt/bxeng/config-xml.xsl">
Tell BXE to call Lenya usecase="bxeng", step="xml" whenever it wants the xml input file
<map:parameter name="BX_xmlfile" value="{request:requestURI}?lenya.usecase=bxeng&lenya.step=xml"/>
Chuck our default language in.
<map:parameter name="defaultlanguage" value="{page-envelope:default-language}"/>
<!-- Instead of an xsl we use the xhtml file to provide the basic layout
<map:parameter name="BX_xslfile" value="{2}.xsl"/>
-->
Not sure about this one, I think it gets matched in publication-sitemap.xmap(?). *Might need to change this(?)*
<map:parameter name="BX_xhtmlfile" value="{../2}.bxe.html"/>
Pull in the correct rng based on doctype (using the rng bit we mentioned earlier in publication-sitemap.xmap).
<map:parameter name="BX_validationfile" value="{request:contextPath}/{page-envelope:publication-id}/{page-envelope:area}/{page-envelope:document-type}.rng"/>
Pull in the correct css based on doctype (using the css bit we mentioned earlier in publication-sitemap.xmap).
<map:parameter name="css" value="{request:contextPath}/{page-envelope:publication-id}/{page-envelope:area}/css/{page-envelope:document-type}-bxeng.css"/>
<!-- The document is checked in when we exit from bx (in case of save&exit and in case of exit), so we use the usecase
for the checkin while we redirect to the document
-->
Tell BXE to call Lenya with usecase="checkin", step="checkin" when it exits.
<map:parameter name="BX_exitdestination" value="{request:requestURI}?lenya.usecase=checkin&lenya.step=checkin&backup=true"/>
Set up a context menu *(might want to change this)*
<map:parameter name="contextmenufile" value="../../resources/misc/bxeng/contextmenu.xml"/>
</map:transform>
<map:transform type="cinclude"/>
Chuck out our modified config file.
<map:serialize type="xml"/>
</map:match>
</map:match>
Whew!
OK here's the usecase="bxeng", step="xml" bit that we told BXE to call to get its xml input file
<!-- /GET and PUT -->
<map:match type="step" pattern="xml">
<map:select type="request-method">
<map:when test="PUT">
<!-- before we save, we must be sure that the document is well checked out
-->
Are we really checked out? Throw a wobbly if not.
<map:act type="reserved-checkout-test">
<map:generate type="serverpages" src="../../content/rc/{exception}.xsp">
<map:parameter name="user" value="{user}"/>
<map:parameter name="filename" value="{filename}"/>
<map:parameter name="date" value="{date}"/>
</map:generate>
<map:transform src="../../xslt/rc/rco-exception.xsl"/>
<map:call resource="style-cms-page"/>
</map:act>
<map:call function="editDocument">
<map:parameter name="sourceUri" value="cocoon:/request2document"/>
<map:parameter name="noCheckin" value="true"/>
</map:call>
</map:when>
<map:otherwise> <!-- GET -->
Fetch our document.
<map:generate src="content/authoring/{page-envelope:document-path}"/>
Do some voodoo with pesky xhtml:object elements.
<map:transform src="../../xslt/bxeng/change-object-path.xsl">
<map:parameter name="documentid" value="{page-envelope:document-id}"/>
</map:transform>
Hand it to BXE.
<map:serialize type="xml"/>
</map:otherwise>
</map:select>
</map:match>
<!-- /GET and PUT -->
</map:match> <!-- uri pattern -->
OK, so we need to change four lines in usecase-bxeng.xmap:
<!-- <map:part src="../../resources/misc/bxeng/content-namespaces.xml"/> -->
to
<map:part src="resources/misc/bxeng/{page-envelope:document-type}-namespaces.xml"/>
and
<!--<map:generate src="../../resources/misc/bxeng/inc/config.xml"/> -->
to
<map:generate src="resources/misc/bxeng/inc/{page-envelope:document-type}-config.xml"/>
and
<!-- <map:transform src="../../xslt/bxeng/config-xml.xsl"> -->
to
<map:transform src="xslt/bxeng/{page-envelope:document-type}-config-xml.xsl">
and
<!-- <map:parameter name="contextmenufile" value="../../resources/misc/bxeng/contextmenu.xml"/> -->
to
<map:parameter name="contextmenufile" value="resources/misc/bxeng/{page-envelope:document-type}-contextmenu.xml"/>
n.b. you'll have to create the resources/misc/bxeng/inc and xslt/bxeng directories.
Now, copy ../../resources/misc/bxeng/content-namespaces.xml to resources/misc/bxeng/xhtml-namespaces.xml,
../../resources/misc/bxeng/inc/config.xml to resources/misc/bxeng/inc/xhtml-config.xml and
../../resources/misc/bxeng/contextmenu.xml to resources/misc/bxeng/xhtml-contextmenu.xml
For new doctypes, simply copy the four xhtml- files to e.g., wine-namespaces.xml, inc/wine-config.xml, wine-contextmenu.xml and wine-config-xml.xsl etc. and modify them to suit your doctype.
Questions
1. Does Lenya actually pick up the relevant doctype-namespaces.xml file anyway (somehow)?
2. Why do the namespaces need to be stripped?
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org