Hi Markus,

Thanks a lot for this update, and for the corresponding one on the SMW-user list. This clears up a lot. There's a lot more going in to the new version than I had thought. The performance improvements sound great - I never thought SMW 0.7 was/is that slow, but it's been an issue for some people.

My only concern about the new version is that I think the handling of n-ary relations, as I understand it, could be improved; but it'll still obviously be better than the current situation.

-Yaron


On 9/21/07, Markus Krötzsch <mak@aifb.uni-karlsruhe.de> wrote:
Hi developers,

as Yaron pointed out to me, there are quite some people now developing code on
top of SMW whom we ought to give much more details on the changes in SMW1.0.
Yes, we will increase our support for developers.

I will sum up the main internal changes (skip what you find uninteresting):

== Storage ==

SMW now has a completely new storage access implementation. No more
SQL-queries, just calls to some specific storage class. In this way, SMW is
becoming completely detached from the DB layout (and in fact from the whole
DB technology). For instance, there were some complaints that SMW's tables
use too much disk space due to extensive indexing. In order to change the DB
layout and index structures, one now would merely have to rewrite a single
(albeit long) file, while the rest of the code remains untouched. This would
also allow RDF-stores to be connected to SMW in a clean way.

The store has many methods for accessing data, and more will be added. The
file includes/store/SMW_Store.php gives an overview.

== Properties ==

There no longer is a distinction between attributes and relations. Basically,
all code now looks like the former attribute-code, i.e. relations now are a
special type of attribute (i.e. property). Usually this simplifies things a
lot since half of all code is obsolete.

== Datavalues ==

Values of properties in SMW are now internally represented by their own proper
containers. There has been SMWDataValue before, but it was now completely
rewritten and extended in functionality. The old typehandler code will
disappear, and implementing new datatypes will become easier (basically, you
just make a subclass of SMWDataValue).

Since relations now are a kind of property, there is also a datatype
for "relations", called Type:Page. It also has a special datavalue
implementation, called SMWWikiPageValue, which is used instead of the Title
objects that were representing values of relations in SMW0.7. Often this is
faster, and in any case it unifies the treatment.

Datavalues now also may hold a "caption", i.e. an alternative label to be used
for printouts. In annotations, this would be as follows:

[[property::value|caption]]

Few will need to know this, but you may see parameters called "caption" in the
code.

=== How do I check the type of some datavalue? ===

You can check the type of a datavalue by the method getTypeID(). All built-in
types have fixed, internal IDs that you can check for. For instance, '_wpg'
is for Wikipage and '_str' is for String. The wikipage type has some
nonstandard methods that emulate methods of former Title objects. If you
still need a title object, you can get one via SMWWikiPageValue::getTitle().
This should make code updates easier.

User-defined types use the DBKey of their Type-Pages as ID, so you would get
something like 'Geographic_length' there. But normally you do not want to
check for this within the code anyway.

In case of "composite types" (nary properties), you just get '__nry' as a type
id (the double "_" indicates that this is an internal type that has no
translation into user speak). To find out the exact structure of such an nary
datavalue container, you can call getType(). It returns to you a special kind
of value: the value used for the property "has type". So the value describes
an SMW datatype as specified by a user.

The file SMW_DV_Types.php contains the implementation of this datavalue. The
*type* of this container is '__typ', and the *value* of this container
describes a (unary or nary) type. Bascically, it holds just an array of one
or more types. You can use the method getTypeLabels() to get an array of the
user labels of all those types, or you can use getTypeValues() to get an
array of typevalues representing those types. You can check whether a
typevalue represents a unary type by using the method isUnary(). The ID of a
unary typevalue can be obtained with the method getXSDValue(), but for nary
values this is a string that represents all IDs, separated by ';'. Thus, for
nary typevalues, you should first call getTypeValues() and then getXSDValue
for each entry. There is currently no way of directly getting an array of IDs
from a typevalue. If this is handy to you, I will add it.

=== How can I create new datavalue objects? ===

Creating new datavalues is really easy. There is a static class
SMWDataValueFactory that has all kinds of convenient methods for making new
datatypes:

If you have the ID (e.g. '_wpg' or '_int') of a type, you can use the method
newTypeIDValue(), optionally with initial value and caption.

If you have a typevalue object for a type, you can use the method
newTypeObjectValue(), optionally with initial value and caption.

If you want a value for a certain property, you can use newPropertyObjectValue
(if you have the property's Title object) or newPropertyValue (if you just
have the name of the property). Wit newSpecialValue you can make a suitable
value for a special property.

The factory also does caching for faster response, and provides some
convenience methods to check the type of some property without making an
empty datavalue object for it.


== Tooltips ==

We now have a universal tooltipping facility. You just insert some HTML
anywhere and our JavaScript will make a pretty tooltip for you. There are two
kinds of tooltips:

* Nonessential, inline tooltips. These will not be visible if JavaScript is
disabled and they will go away when the mouse is moved. Do not use these for
long or important texts. To create such a tooltip, write something like:

<span class="smwttinline">Anchor Text<span
class="smwttcontent">Some<br/>Tooltip</span></span>

* Important, persistent tooltips. The conten of those will be visible if
JavaScript is turned off, and they are clicked and explicitly closed. They
can hold much content, since you can scroll down if needed (but do not overdo
it). To create such a tooltip, write something like:

<span class="smwttpersist">Anchor Text<span
class="smwttcontent">Some<br />Tooltip</span></span>

Instead of textual anchors, you can also use icons provided by SMW, e.g. as
follows:

<span class="smwttpersist"><span class="smwtticon">warning.png</span><span
class="smwttcontent">Some<br />Tooltip</span></span>

NOTE: although these tooltips can be used everywhere, we do not provide
support for their direct use in wikipages. You can insert these texts in any
page when editing, but it is likely that in the near future the required
JavaScript can only be requested programmatically, so that user-created
tooltips would fail.

== Queries ==

There is now a whole internal API for queries. You can issue a query as before
by giving a query string, but you can also construct a query from PHP
objects. These object-based query representations are found in the file
SMW_Description.php and SMW_Query.php.

The static methods of SMW_QueryPorcessor.php can convert a query string into
an object-based query, and it would be possible to work on those queries with
your own code (e.g. to add conditions or to optimise something). The
Ask-Special shows how to go from query string to printout now.

Simlilarly, results are not directly printed from SQL but have an intermediate
result representation that is accessed by query printers. All query printers
were rewritten to use this structure. Usually things get easier, but printing
queries still requires three nested loops (that's the results structure ...)
and so code tends to get messy.

Yet we think that the new internal interfaces are more convenient for issuing
queries from your own code, for instance since you do not need
language-specific strings as for the earlier query strings. Of course its
also more efficient if you do not need a query string to be parsed.


== What else? ==

I think this addresses most relevant changes. Feel free to ask questions on
how to port your code to SMW1.0. Yaron also asked me why the devel list is
not used for making design decisions. The reason is that SMW was developed
within the Halo project in the past months, and design decisions had to be
made during real world meetings. Also, the core developers at the moment are
only Denny and I, so we just talk during lunch breaks instead of starting
email threads. We will try to improve ;-)


Cheers,

Markus

--
Markus Krötzsch
Institut AIFB, Universät Karlsruhe (TH), 76128 Karlsruhe
phone +49 (0)721 608 7362        fax +49 (0)721 608 5998
mak@aifb.uni-karlsruhe.de        www   http://korrekt.org

-------------------------------------------------------------------------
This SF.net email is sponsored by: Microsoft
Defy all challenges. Microsoft(R) Visual Studio 2005.
http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/
_______________________________________________
Semediawiki-devel mailing list
Semediawiki-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/semediawiki-devel