WRD API 2017

There are 2 WRD APIs - the original 'legacy' API (from 2005) where you generally use OpenWRDSchemaByName/GetTypeByTag and the 'new' API where you use OpenWRDSchema and the hat '^' operator to access types. Going forward, new features will only be added to the new API and eventually the deprecated API may be removed.

This document gives some hints on how to convert 'old' API users to the new API:

Switching to the new API

• Replace LOADLIBs of "mod::wrd/lib/objectapi.whlib" with "mod::wrd/lib/api.whlib"
• Update code where necessary
• Rename your schema to the module:tag format.

Notable new features

• All the types in a WRD schema are added as members to the WRD schema object, with ^ added in front of their name. For example, wrdschema->^wrd_person can be used instead of wrdschema->GetTypeByTag("WRD_PERSON").
• Queries automatically assume matchtype := "IN" if no matchtype is specified and the value is an array
• A new 'RECORD' field type, storing RECORDS of arbitrary (HSON) length
• New 'ENUM_SINGLE' and 'ENUM_MULTIPLE' types, which are like 'FREE' but allow you to limit the set of allowed values

Incompatible changes in the new API

• CreateEntity now returns an object. The new API doesn't have a CreateEntity2. You'll need to fix all locations where you call CreateEntity and try to use the returned value

• wrdtype->CreateAttribute has changed its parameters

  • Type DOMAIN_SINGLE is now DOMAIN
  • Type DOMAIN_MULTIPLE is now DOMAINARRAY
  • All typenames lost their underscores

New API names

Freestanding APIs and WRDSchema

• OpenWRDSchemaByName -> OpenWRDSchema
• RunWRDQuery -> wrdscheam->RunQuery
• wrdschema->name -> wrdschema->tag
• wrdschema->CreateDomainType() -> wrdschema->CreateDomain(tag, title, ...)
• wrdschema->GetTypeByTag -> wrdschema->GetType

WRDType

• CreateEntity2 -> CreateEntity
• CreateAttribute -> CreateAttribute(tag, type, ...)
• LookupEntity -> Search(field, val)
• LookupEntity(...,FALSE) -> Search(field, val, [ matchcase := FALSE ])
• GetEntity(id)->UpdateFields(...) -> UpdateEntity(id, ...)
• GetAttributeInfoByTag -> GetAttribute
• GetAttributeInfo -> GetAttributeById
• SELECT AS INTEGER ARRAY id FROM RunQuery([outputcolumns := [ id := "WRD_ID", filters := ... ]]) -> FindIds([ filters := ... ]])
• GetDomVals -> ListDomVals
• GetEntitiesData(ids, ["field1","field2"]) -> GetBulkFields(ids, [ field1 := "field1", field2 := "field2" ])
• GenerateGuid -> GetNewEntityGUID()

WRDEntity

• UpdateFields -> UpdateEntity
• CloseEntity(TRUE) -> CloseOrDeleteEntity()
• CloseEntity(FALSE) -> CloseEntity()

wrdschema.xml changes

• <classification> -> <attachment>

Updates to components and Tollium

• Applications can register a wrdschema using this->contexts->wrdschema := <schema> in their initialization. Many WRD components will automatically pick this up as their wrdcontext (no wrdcontext="wrd" needed)
• <wrdentity> is a bit more efficient:
  • If you've set the wrdschema context, pass an wrdtype attribute in the XML to immediately select the type
  • Replace ->LoadEntity(type, id) with a simple ->Load(id) (if the wrdtype has been set)
  • Replace ->StoreEntity(work [, extradata]) with ->Store(work)
  • Any extradata you would pass to StoreEntity, can be assigned to the ->extradata property. You can do this immediately during initialization so you might no longer need to create your own properties to store this data