Collections of structures and data can be embedded using the ［collection］ shortcode. A collection is most commonly a table that contains a column of molecules and some number of other columns with text, numbers, etc. Datastructures can be much more complex, though, which means that this embedding technique can display quite a variety of high level chemical concepts.
A collection can be embedded by provide a single attribute to refer to its source content:
which is rendered as:
There are two main formats that are supported: DataSheet XML (the native format of SketchEl and various products from Molecular Materials Informatics) and MDL SDfile. Note that while it is possible to embed the actual datastructure between the ［collection］.. ［/collection］ tags, both the XML datasheet and whitespace-sensitive SDfiles typically cause problems with editing. Also, collections tend to be unwieldy to deal with inside a document, and so storing as an external file is recommended.
The two formats vary considerably in their sophistication: the SDfile is limited to rows which each contain one molecule, with an arbitrary number of untyped non-molecular fields, and no additional metadata of any kind. The datasheet format is arranged as a table with typed columns, and may have more than one molecular column. It also supports aspect extensions, each of which provides some additional meaning to the tabular layout: some provide modest markup (e.g. the AssayProvenance aspect enforces the use of meaningful units for bioactivity data); some detail extensive capabilities but with relatively little impact on visualisation (e.g. the SAR Table aspect which splits molecules into scaffolds and substituents); while some provide a completely different viewpoint onto the data (e.g. the Experiment aspect defines an entire reaction scheme, which requires an entirely different layout strategy).
For most purposes, a collection can simply be embedded directly into the document without any major parametrisation. For datasheets containing aspects that are recognised by the underlying WebMolKit library, the rendering will honour the default presentation style. For aspects that are not recognised, the fallback rendering of rows, columns, molecules & data is usually reasonable.
Attributes that can be used with the collection shortcode are as follows:
- source: a URL to fetch the collection from, when the payload is not embedded. This is recommended over the embedding option. While any URL is valid, the content needs to be on the same server, since most web browsers forbid cross-domain lookup.
- format: an optional force-format. The content can usually be guessed or is implied by the file extension. The parameter can be a MIME type, or one of the shortcuts datasheet or sdfile.
- scheme: one of 4 available colouring schemes: wob = white on black, cob = colour on black, bow = black on white, cow = colour on white (default).
- scale: the natural size of molecules, in pixels-per-Angstrom. The default is 20. This applies to all molecule rendering, and is used as a baseline scale in cases when composite diagrams are created (e.g. for reaction schemes, the reactants and products will use this scale, while the reagents may be drawn proportionately smaller).
- padding: number of pixels to space around the content (refers to the entire collection, rather than individual components).
- border: indicate the border colour to draw around the entire collection; by default a faint border is drawn. The value should be provided as an HTML-style RGB string (#RRGGBB) or transparent to switch the border off.
- background: indicate the background, which can be transparent, and HTML-style RGB string (#RRGGBB) or two colours separated by a comma to achieve a shading effect.
- radius: the rounded corner effect, which is enabled by default. Specify 0 to make the enclosing box rectangular.
- tight: by default the collection is given a healthy amount of padding, but this can be disabled by setting the value to false.