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/11/07 17:45:21 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
The comment on the change is:
Have tidied up and de-personalised originally scribbled notes somewhat
------------------------------------------------------------------------------
#pragma section-numbers on
- = Overview for the impatient =
+ = Overview =
- Change four lines in usecase-bxeng.xmap:
+ Change four lines in usecase-bxeng.xmap (n.b., check the paths). This effectively allows us to specify the BXE parameters independently for each doctype. N.b., this will affect all your publications.
== BXE Namespaces ==
{{{
@@ -49, +49 @@
}}}
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,
+ 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. You will need to modify the namespaces file. You may want to edit the config file to change the BXE toolbar buttons or callbacks. You may want to modify the context menu to exclude elements from the context menu (otherwise just remove all the xhtml specific defaults). You're unlikely to need to modify the xsl file.
+ For a new doctype called, say, "wine", copy the four xhtml- files to wine-namespaces.xml, inc/wine-config.xml, wine-contextmenu.xml and wine-config-xml.xsl respectively and modify them to suit. The namespaces file will need modifying. The config file may need changing to change the BXE toolbar buttons or callbacks. You may want to modify the context menu to exclude elements from the context menu (otherwise just remove all the xhtml specific defaults). You're unlikely to need to modify the xsl file.
- Frankly, I don't know why Lenya isn't configured this way by default.
+ = How it all works =
-
- = 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.
+ When the "Edit"->"WYSIWYG Editor (BXE)" menu item is clicked:
- This menu item is defined in cellar/config/menus/generic.xsp.
+ This menu item is defined in {pub}/config/menus/generic.xsp.
{{{
<menu i18n:attr="name" name="Edit" label="Search"><!-- Start of definition of "Edit" menu-->
@@ -79, +74 @@
</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)".
+ The text "Edit with BXE" is a key in {pub}/../../resources/i18n/cmsui.xml and the other cmsui_nn.xml files where nn is the language code. In cmsui.xml this key is associated with the text you actually see on the menu, namely "WYSIWYG Editor (BXE)". This text is also in the other cmsui_nn.xml files in English by default.
- 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 them out of the way and makes sense.
+ The BXE item line in the code above tries to find a match inside the usecase-bxeng.xmap file for 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, the "Forms Editor" and Kupu) are. There're in {pub}/../../usecases. This makes sense as the one form editor works with any doctype and therefore doesn't need customising on a doctype or publication basis. Similarly, the only customisation likely to be needed for the multiple "Forms Editor" is in your custom doctypes' {pub}/lenya/xslt/formeditor/wine.xsl file. Kupu only supports XHTML so again is not likely to need customising. Keeping the usecases up the tree keeps them 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.
+ The usecase-bxeng.xmap file by contrast is in {pub} precisely because we (may) need to change it.
- 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 section in publication-sitemap.xmap begining with the comment <!-- BX Editor: RNG Schema, CSS --> is a helper section for BXE so that when it asks for 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 files appropriately.
= The usecase-bxeng.xmap file =
@@ -96, +91 @@
<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.
+ The usecase(="bxeng") and step (="open") match our menu item from before.
Check if BXE is installed
{{{
@@ -115, +110 @@
<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.
+ {pub}/../../resources/misc/bxeng/index.html sets up a basic BXE xhtml page that gets modified to fit with our doctype later. Again, the fact that this file is kept outside of our publication probably means we don't need to change it on a per publication basis.
- 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.
+ {pub}/../../resources/misc/bxeng/content-namespaces.xml 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 for new doctypes.
- 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) ...
+ Aggregate (i.e., 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.
+ ... but makes sense when you run xsl against it to insert the namespaces into meta elements (e.g., <meta name="bxeNS" content="{dc=http://purl.org/dc/elements/1.1/}"/>) to create an xhtml document with these meta elements inside the head element as expected by BXE
{{{
<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.
+ and add the configfile and context for our doctype to the xhtml file. (This is the important bit). N.b., The configfile and context is passed 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.
+ strip off the namespaces (not sure why).
{{{
<map:transform src="../../xslt/util/strip_namespaces.xsl"/>
}}}
- and chuck it out as xhtml, which it is.
+ and output as xhtml.
{{{
<map:serialize type="xhtml"/>
}}}
- the next line is indented incorrectly (in my version) but ends our "resource-exists" (i.e., BXE is installed) action
+ the next line is indented incorrectly (in my version) but ends the "resource-exists" (i.e., BXE is installed) action
{{{
</map:act>
}}}
@@ -156, +151 @@
<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".
+ We've not had to modify anything so far which is why other documentation on BXE says "start with the config step".
An image upload dialog box step ...
{{{
@@ -225, +220 @@
<map:call resource="style-cms-page"/>
</map:match>
}}}
- BXE will now call this step below as we told it to earlier (remember?).
+ BXE will now call this step below as set up earlier.
{{{
<map:match pattern="**/*.html">
<!-- configuration -->
@@ -235, +230 @@
{{{
<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.
+ An xsl file is run against the config.xml file with parameters to transform it into one suitable for our doctype.
{{{
<map:transform src="../../xslt/bxeng/config-xml.xsl">
}}}
@@ -335, +330 @@
</map:match> <!-- uri pattern -->
}}}
- = Conclusion =
-
- Just follow the steps above in Overview for the Impatient
= Questions =
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@lenya.apache.org
For additional commands, e-mail: dev-help@lenya.apache.org