Package: collective.vdexvocabulary
What this package do?IMS VDEXis a standard for exchanging vocabularies.collective.vdexvocabularybridges between vdex vocabularies and zope
vocabularies (zope.schema.vocabularies), so you can easily use it in
systems like Plone/ Zope, Pyramid or any other Zope-Toolkit supporting system.ContentsWhat this package do?Whats so special about it?How do I use it?ConfigurationUsage in CodeHow to use tree-vocabulariesHow to access relations (from code)Example VDEX fileFlat with with relationsHierachical TreeWhere can I complain / help / send rum?CreditTODOChangelog0.3 (2020-06-19)0.2.2 (2015-09-01)0.2.1 (2015-06-22)0.2 (2014-11-03)0.1.2 (2014-01-07)0.1.1 (2010-10-11)0.1 (2010-06-23)0.1a1 (2010-04-29)Whats so special about it?collective.vdexvocabularycontains two different types of vocabularies:If you have big vocabularies with a lot of relations, like +10.000
terms with +30.000 relations, so this would be perfect use case to use
theVdexVocabularytype ofcollective.vdexvocabulary.If you have tree-like vocabularies this is perfect too.TreeVocabularysupports nested/ hierachical vocabularies.Also there is other stuff which not supported by other vocabulary packages
(i.e. for Plone/Zope):i18n support. IMS VDEX supports translations within the VDEX-XML-File, both
vocabulary types are supporting this way of translations.proper order also with unicode characters (if zope.ucol is installed,
vdexvocabulary only). If VDEX is order-sigificant the order given by vdex
file is taken (supported by both vocabulary types).easy registration using zcmlrelations as it specified in IMS VDEX standard (for now only VdexVocabulary)How do I use it?ConfigurationIn your configure.zcml add:<configure
    ...
    xmlns:vdex="http://namespaces.zope.org/vdex"
    ...>

  <include package="collective.vdexvocabulary" file="meta.zcml" />
  <include package="collective.vdexvocabulary" />And to register a vdex vocabulary simply add line bellow pointing to file
containing vdex vocabulary:<configure
    ...
    xmlns:vdex="http://namespaces.zope.org/vdex"
    ...>

  <vdex:vocabulary file="path-to/very-interesting.xml" />or for tree vocabularies:<vdex:treevocabulary file="path-to/very-interesting-tree.xml" />To make registration of vocabularies even easier you can also register
several vocabularies and just point to directory:<configure
    ...
    xmlns:vdex="http://namespaces.zope.org/vdex"
    ...>

  <vdex:vocabulary directory="path-to/my-vdex-vocabularies" />or for tree vocabularies:<vdex:treevocabulary directory="path-to/my-vdex-vocabularies" />vdex files inpath-to/my-vdex-vocabulariesdirectory should have ending.vdexto be recognized byvdex:vocabularyZCML directive.Sometimes you dont want VDEX-files inside your code tree. Therefore an
environment variable can be given defining the base directory:<vdex:vocabulary file="my-vocabulary.vdex: environment="VDEX_BASE_DIR" />or for tree vocabularies:<vdex:treevocabulary file="my-vocabulary.vdex: environment="VDEX_BASE_DIR" />Before running the code with environment variable relative filenames/directories
one has to set the environmant variable, i.e. do anexportVDEX_BASE_DIR=/home/joe/vdex/in order to make it look for the vdex
at/home/joe/vdex/my-vocabulary.vdex.Usage in CodeVocabularies are named utiltiies in a zope-toolkit manner. The name is taken
from the vdex file, its thevocabIdentifier.Given a vocabulary with the namebeeeurope(see tree example below) one has
to get the utility using the zope component architecture way:>>> from zope.component import getUtility
>>> from zope.schema.interfaces import IVocabularyFactory
>>> factory = zope.component.getUtility(IVocabularyFactory, 'beeeurope')The factory returns on call a vocabulary. It expects a context, which can beNonein our case. If you are in an application server pass here your current
context. In case of flat vocabularies this is used to detect the language, for
tree vocabularies it is ignored, here an more advanced method is used to support
i18n:>>> context = None
>>> vocabulary = factory(context)Now you can use the vocabulary:>>> for term in vocabulary:
...     print term.value
...     print term.token
...     print term.title
...     print term.descriptionHow to use tree-vocabulariesOnce looked up as shown above traversing the tree is easy. It works as defined
inzope.schema.interfaces.ITreeVocabulary. Thetermis also the key for
the sublevel:>>> def printlevel(leveldict, ident=0):
...     for term in leveldict:
...         print indent * '  ' + term.title
...         printlevel(leveldict[term], indent+1)Hint:collective.dynatreeuses this kind of vocabularies and can be used as
an example for own implementations too.How to access relations (from code)Relations are defined byISO2788.To get listing of BMW car models from above VDEX example you have to:>>> from zope.schema.vocabulary import getVocabularyRegistry

>>> vr = getVocabularyRegistry()
>>> car_manufacturers = vr.get(self.context, 'your.package.car_manufacturers')
>>> car_models = vr.get(self.context, 'your.package.car_models')

>>> bmw = car_manufacturers.getTerm('bmw')
>>> bmw_car_models = bmw.related.get('NT', [])Example VDEX fileFlat with with relationsExample of car manufacturers list (car_manufacturers.vdex).:<?xml version="1.0" encoding="utf-8"?>
<vdex xmlns="http://www.imsglobal.org/xsd/imsvdex_v1p0"
      orderSignificant="false" language="en">
    <vocabIdentifier>your.package.car_manufacturers</vocabIdentifier>
    <term>
        <termIdentifier>ford</termIdentifier>
        <caption>
            <langstring language="en">Ford</langstring>
            <langstring language="es">Una miedra de coche</langstring>
        </caption>
    </term>
    <term>
        <termIdentifier>bmw</termIdentifier>
        <caption>
            <langstring language="en">BMW</langstring>
            <langstring language="es">Be-eMe-uWe, mierda</langstring>
        </caption>
    </term>

    <relationship>
        <sourceTerm>bmw</sourceTerm>
        <targetTerm vocabIdentifier="your.package.car_models">very-special-bmw-model</targetTerm>
        <relationshipType source="http://www.imsglobal.org/vocabularies/iso2788_relations.xml">NT</relationshipType>
    </relationship>

    ...

</vdex>List of car models (car_models.vdex).:<?xml version="1.0" encoding="utf-8"?>
<vdex xmlns="http://www.imsglobal.org/xsd/imsvdex_v1p0"
      orderSignificant="false" language="en">
    <vocabIdentifier>your.package.car_models</vocabIdentifier>

    <term>
        <termIdentifier>very-special-bmw-model</termIdentifier>
        <caption>
            <langstring language="en">Very special BMW model</langstring>
            <langstring language="es">Un modelo de Be-eMe-uWe</langstring>
        </caption>
    </term>

    <relationship>
        <sourceTerm>very-special-bmw-model</sourceTerm>
        <targetTerm vocabIdentifier="your.package.car_manufacturers">bmw</targetTerm>
        <relationshipType source="http://www.imsglobal.org/vocabularies/iso2788_relations.xml">BT</relationshipType>
    </relationship>

...

</vdex>Hierachical Treeexample of a tree vocabulary:<vdex xmlns="http://www.imsglobal.org/xsd/imsvdex_v1p0" orderSignificant="true">
  <vocabIdentifier>beeeurope</vocabIdentifier>
  <vocabName>
    <langstring language="en">European Honey Bees</langstring>
  </vocabName>
  <term>
    <termIdentifier>nwe</termIdentifier>
    <caption>
      <langstring language="en">North-west of Europe</langstring>
    </caption>
    <term>
      <termIdentifier>nwe.1</termIdentifier>
      <caption>
        <langstring language="en">A. m. iberica</langstring>
      </caption>
    </term>
    <term>
      <termIdentifier>nwe.2</termIdentifier>
      <caption>
        <langstring language="en">A. m. intermissa</langstring>
      </caption>
    </term>
    <term>
      <termIdentifier>nwe.3</termIdentifier>
      <caption>
        <langstring language="en">A. m. lihzeni</langstring>
      </caption>
    </term>
    <term>
      <termIdentifier>nwe.4</termIdentifier>
      <caption>
        <langstring language="en">A. m. mellifera</langstring>
      </caption>
    </term>
    <term>
      <termIdentifier>nwe.5</termIdentifier>
      <caption>
        <langstring language="en">A. m. sahariensis</langstring>
      </caption>
    </term>
  </term>
  <term>
    <termIdentifier>swe</termIdentifier>
    <caption>
      <langstring language="en">South-west of Europe</langstring>
    </caption>
    <term>
      <termIdentifier>swe.1</termIdentifier>
      <caption>
        <langstring language="en">A. m. carnica</langstring>
      </caption>
    </term>
    <term>
   <term>
      <termIdentifier>swe.2</termIdentifier>
      <caption>
        <langstring language="en">A. m. cecropia</langstring>
      </caption>
    </term>
    <term>
      <termIdentifier>swe.3</termIdentifier>
      <caption>
        <langstring language="en">A. m. ligustica</langstring>
      </caption>
    </term>
    <term>
      <termIdentifier>swe.4</termIdentifier>
      <caption>
        <langstring language="en">A. m. macedonica</langstring>
      </caption>
    </term>
    <term>
      <termIdentifier>swe.5</termIdentifier>
      <caption>
        <langstring language="en">A. m. ruttneri</langstring>
      </caption>
    </term>
    <term>
      <termIdentifier>swe.6</termIdentifier>
      <caption>
        <langstring language="en">A. m. sicula</langstring>
      </caption>
    </term>
  </term>
</vdex>Where can I complain / help / send rum?Home + Source:https://github.com/collective/collective.vdexvocabularyReport Issues:https://github.com/collective/collective.vdexvocabulary/issuesSend rum:contactrok@garbas.sifor more infoCreditRok Garbas,http://garbas.si, <rok@garbas.si>, AuthorSeantis gmbh,http://www.seantis.chThank you for initial idea with seantis.vdex where got the idea and then
reimplement and extend it.Jens W Klein,http://kleinundpartner.at, <jens@bluedynamics.com>,
Cleanup, Treevocabulary/ i18n-supportTODOfetch vocab(s) via url (new directive)load vocabs view entry_pointsstore vocabs (or changed vocabs in zodb), will probably also need diff and merge optionwrite test and get decent test coveragewrite documentationmake ZCML optionalmake through the web vdex editor (this would probably need sponsoring)add relation support to TreeVocabularyChangelog0.3 (2020-06-19)Support for Python 3.
[thet]Reformat the codebase using black and isort to meet current coding guidelines.
[thet]Removebootstrap.py. Buildout is installed via pip nowadays.
[thet]Adddefault_languageoption when registering vocabularies.
Default language is used when the site language is not available
in a vdex file. Not specifying this still means a default of ‘en’.
[tmog]0.2.2 (2015-09-01)Newer lxml doesn’t allow accessing_rootanymore.
This switches togetroot().
[pilz]0.2.1 (2015-06-22)Plone 4.3 compatibility
[ale-rt]lxml compatibility (imsvdex dropped elementtree in favour of lxml)
[ale-rt]entry point for z3c.autoinclude
[ale-rt]0.2 (2014-11-03)A bunch of refactoring in order to add a new vocab type: TreeVocabulary.
As the name suggests, treevocabulary supportszope.schema.interfaces.ITreeVocabulary. It has better i18n-support using
own i18n-domains for the caption and description of a term.
[jensens]0.1.2 (2014-01-07)don’t use context to determine current language, but use getSite.
context may be adapter or other object without acquisition
(eg. in forms with ignoreContext=True).
[naro]depend on “setuptools”, not “distribute”
[nutjob]0.1.1 (2010-10-11)addedHistory,How to access relations (from code)andExample
VDEX filesection to README.
[garbas]moved code tohttp://github.com/collective/collective.vdexvocabulary.
[garbas]BUG(Fixed): when vdex file was loaded it failed if there were not terms.
[garbas]0.1 (2010-06-23)add documentation and clean up code a little bit.
[garbas]0.1a1 (2010-04-29)initial release.
[garbas]