A very simple example (part I)

[Christian Stocker]

Hi

here's the promised very simple bxe example with some explinations, what
i've done with it.

All the needed files can be download from
http://trash.chregu.tv/bxe_simple.tgz for the time being (I will put
this howto somewhere more appropriate later, so the above link will also
change). The files can also be looked at online. go to
http://trash.chregu.tv/bxe/ and click through.
Ok, here we go:

First we need an xml file with the data. I took a very simple example
(not really docbook, but if I'd choose docbook, it would have been too
long again..) See http://trash.chregu.tv/bxe/xml/data.xml . Not much to
say about that ;)

Second, we need an xsl file
(http://trash.chregu.tv/bxe/xml/transform.xsl ). This needs some special
stuff. First, at the moment, we need always a <xsl:template match="*">
template, because otherwise not all needed nodes are transformed.
Besides that template, we only have one other template in this example,
which matches the root node and outputs all the needed HTML tags. The
main interest in this template should go into:

<article contentEditable="true">
<xsl:for-each select="article">
<xsl:apply-templates/>
</xsl:for-each>
</article>

This is at the moment the standard way of making a node and all his
subnodes editable (We will have more ways in the future aka BXE-NG).
This means, you write the node-name, you want to edit as above with the
attribute contentEditable="true", then you do for-each over exactly this
node and apply-templates for every subnote. This is it. The XPath query
in xsl:for-each can of course be more complex than it's here, but you
have to take care, that the node name with the contentEditable attribute
matches the nodenames, which are selected in the for-each. (It doesn't
need to be this way, but if you play around with it and see for
yourself, that it will have problems if you for example replace the
select with select="article/*", this will improve in BXE-NG, hopefully )

For the 2 other needed files (Schema and CSS), you have to wait until my
next mail, which should come in a few hours. I have some other stuff to
do for the moment, but I don't want to let you wait anymore for the
example files. Maybe they are of help for some out there ;)

'till later

chregu

[Troy Farrell]

Yes! Yes! This helps. This is good.

I looked at the files and the workings of the editor are making more
sense. I'll try to play with this soon. I, like you, have a few things
to do right now, but soon...

Thank you.

Troy

Post by Christian Stocker
Hi
here's the promised very simple bxe example with some explinations, what
i've done with it.
All the needed files can be download from
http://trash.chregu.tv/bxe_simple.tgz for the time being (I will put
this howto somewhere more appropriate later, so the above link will also
change). The files can also be looked at online. go to
http://trash.chregu.tv/bxe/ and click through.
First we need an xml file with the data. I took a very simple example
(not really docbook, but if I'd choose docbook, it would have been too
long again..) See http://trash.chregu.tv/bxe/xml/data.xml . Not much to
say about that ;)
Second, we need an xsl file
(http://trash.chregu.tv/bxe/xml/transform.xsl ). This needs some special
stuff. First, at the moment, we need always a <xsl:template match="*">
template, because otherwise not all needed nodes are transformed.
Besides that template, we only have one other template in this example,
which matches the root node and outputs all the needed HTML tags. The
<article contentEditable="true">
<xsl:for-each select="article">
<xsl:apply-templates/>
</xsl:for-each>
</article>
This is at the moment the standard way of making a node and all his
subnodes editable (We will have more ways in the future aka BXE-NG).
This means, you write the node-name, you want to edit as above with the
attribute contentEditable="true", then you do for-each over exactly this
node and apply-templates for every subnote. This is it. The XPath query
in xsl:for-each can of course be more complex than it's here, but you
have to take care, that the node name with the contentEditable attribute
matches the nodenames, which are selected in the for-each. (It doesn't
need to be this way, but if you play around with it and see for
yourself, that it will have problems if you for example replace the
select with select="article/*", this will improve in BXE-NG, hopefully )
For the 2 other needed files (Schema and CSS), you have to wait until my
next mail, which should come in a few hours. I have some other stuff to
do for the moment, but I don't want to let you wait anymore for the
example files. Maybe they are of help for some out there ;)
'till later
chregu

[Christian Stocker]

Re

Here we go with the second part:

Now comes the most difficult part: Creating the XML Schema
( http://trash.chregu.tv/bxe/schema/schema.xml )

At the moment, BXE has only limited support of XML Schema, therefore you
have to follow some special rules if you write it. This is one of the
major tasks we'd like to improve in BXE-NG. Nevertheless, the provided
XML Schema validates (see
http://www.w3.org/2001/03/webdata/xsv?docAddrs=http%3A%2F%2Ftrash.chregu.tv%2Fbxe%2Fschema%2Fschema.xml&style=offline
for details) and therefore it should be useable in later versions of BXE
as well. The provided data.xml also validates against the schema.xml, at
least with xsv...

We have 5 different elements in the XML, so we need 5 <xs:element> in
the schema. For the article element it looks like the following:
<xs:element name="article">
[...]
</xs:element>

After that, we have to declare which child-elements this element can
have. This is done with the <xs:complexType> tag. For article:

<xs:complexType>
<xs:choice minOccurs="0" maxOccurs="unbounded">
<xs:element ref="title" minOccurs="0" maxOccurs="unbounded"/>
<xs:element ref="para" minOccurs="0" maxOccurs="unbounded"/>
</xs:choice>
</xs:complexType>


At the moment, BXE only supports xs:choice in xs:complexType and it
doesn't care about the minOccurs, maxOccurs attributes. Therefore
basically you can just say, which elements can be a child of another one.
eg. in the above example, the "article" element can have "title" and
"para" as children.
Furthermore, if you want to allow character data within an element, you
should add the attribute mixed="true" to xs:complexType

Before we introduced our Schema based configuration, we used some kind of
Javascript config file to provide the needed information. Some traces of
this can still be found in the <xs:annotation> Element of each
element-declaration. The xs:annotation element can be used for providing
information, which is normally not used by an XML Schema parser, but by an
application. Within xs:annotation, we have xs:documentation, which is not
used by BXE, but serves documentation purposes. And there is xs:appinfo,
which we use quite intensively at the moment. We need it, because some
features are very hard to get out of a Schema, other stuff could be done
that way, but we were too lazy/busy to implement it till now ;)

Here is the xs:appinfo for the title element

<xs:appinfo>
<bxe:name>Title</bxe:name>
<bxe:returnelement>para</bxe:returnelement>
<bxe:insertafter>
<bxe:element>para</bxe:element>
</bxe:insertafter>
</xs:appinfo>

And here's the explanation:

bxe:name: this is the name, which appears in the bottom-xpath-bar and in
the right-mouse-click-popup-menus. it's optional (as everything in this
section), if you don't provide a name, it takes the element name.

bxe:returnelement: If you're editing an element and hit the return key,
this option defines, which element should be inserted. In the example, we
want automatically add a paragraph, if we hit return in a title. if it's
set to "none", nothing at all happens. You can also add more complex
xml-fragments.
<bxe:returnelement><![CDATA[<p><b></b></p>]]></bxe:returnelement> would
insert to new elements. The values of this option could be somehow taken
out of the schema (if the XML Schema has xs:sequence), but this won't
happen soon ;)

bxe:insertafter: This option defines, after which elements this elements
can be inserted. This is used in the right-mouse-button-popup for
displaying the "insert after .." entries. This option could (and should)
be taken out of the regular XML Schema definition. You can add more than
one bxe:element of course.

These are the most basic ones, there are more options, see the complex
example for some hints...

With all this info, we can write a very basic XML Schema file, which is
understood by BXE.

Last, but not least, we have to write the CSS files. BXE does not
translate the XML nodes from your input document to HTML, but it inserts
it just as they are. Therefore you have to write CSS rules for Mozilla,
otherwise Mozilla won't know, how to render them. This is not a very
difficult task and CSS in Mozilla is quite powerfull. The simple CSS
example at http://trash.chregu.tv/bxe/css/style.css shows the needed
instructions for the example. If you have to write more CSS rules, there's
a good overview of CSS rules for HTML elements at
http://www.w3.org/TR/REC-CSS2/sample.html . It should help you a lot in
providing styles for your common HTML elements

As a side note, in BXE-NG this will change slightly, we will convert the
input XML to real HTML (MSIE doesn't know much about XML within HTML) and
therefore we need a different CSS. But this basically means you have to
add a dot in front of the element names, so this can be quickly done.

That's about it. I hope it helped some people out there. If you have
questions, problems, comments, do not hesitate to write a mail here on
this list.

chregu