Molecular structures can be embedded one at a time using the ［molecule］ shortcode. A shortcode is a WordPress feature that is similar to HTML/XML tags, except using square brackets instead of angle brackets.
The quickest way to embed a molecule object is to embed it within the document, e.g.:
［molecule name="acetamide"］SketchEl!(4,3) C=-3.8000,3.5500;0,0,i3 C=-2.5010,4.3000;0,0,i0 N=-1.2019,3.5500;0,0,i2 O=-2.5010,5.8000;0,0,i0 1-2=1,0 2-3=1,0 2-4=2,0 !End［/molecule］
which is rendered as:
As an alternative to embedding the structure within the document, it can reference a file that has been uploaded, e.g.
［molecule name="acetamide" source="http://molpress.com/wp-content/uploads/2017/06/acetamide.mol"/］
The external referencing is more concise and less inclined to get in the way of writing the article, but it does involve an extra step (i.e. uploading the file and capturing the resulting URL). Also, because it is separate from the main document, there will be a brief rendering delay while it is fetched.
At the present time, two main file formats are supported: the SketchEl molecule format (shown in the embedded example) and the MDL Molfile format (shown in the separate file example). The SketchEl format is used by the eponymous editor (v1 and v2) as well as various products from Molecular Materials Informatics.
Molfile (.mol) is a legacy format that also happens to be an ad hoc industry standard which has partial compatibility with almost every cheminformatics product. Note that because of the tendency for WordPress to remove whitespace, Molfiles should generally be embedded externally because they use a Fortran-style column layout that requires whitespace padding.
The molecule object supports a number of configuration options that can be used to control the display of the molecule. These are processed within the shortcode using attributes that work just like HTML/XML (see the way name and source are used in the examples above).
- source: a URL to fetch the molecule from, if the payload is not embedded. This can be a directory relative to the current path, but it is generally easier to copy & paste the full URL from the upload facility. 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 molfile or sketchel.
- name: displays a name underneath the structure. Some Molfiles provide names in their header record, and these are displayed by default (name="" is a way to turn this off).
- invert: if set to true, the mirror image of the molecule will be presented (the coordinates will be inverted on the horizontal axis, and wedge bonds will be adjusted accordingly)
- rotate: rotates the molecule by a given number of degrees, in the anticlockwise direction; if combined with inversion, the rotation is applied afterward.
- padding: specify some number of pixels as a boundary around the edge of the molecule.
- border: indicate the border colour to draw around the molecule; 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.
- width, height: if either width or height is specified, their are both treated as maximum values: if the molecule is too large for either of them, it will be scaled down accordingly.
- box: a specific box size (comma separated) within which the molecule will be contained. Unlike specifying width and height, this is interpreted as an actual size, i.e. if the molecule is smaller than the box, it will be rendered at its natural size, and placed in the centre.
- 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 the molecule, in pixels-per-Angstrom. The default is 20, and it is often useful to decrease this when structures are large or many need to be crammed into a small space. This is sometimes preferable to specifying a maximum width or height, because a series of molecules will all be drawn to the same scale.
- tight: by default the molecule is given a healthy amount of padding, but this can be disabled by setting the value to false, which is often useful for lining up in grids.
The plugin also provides a sketcher for drawing molecules. The benzene logo invokes the editor:
The editor can be used to draw the molecular structure interactively, with a familiar user interface:
An active editing session can also be used as a target for paste or drag & drop, to capture data from other applications or files. Once the editing is complete, pressing the Save button will insert the molecular structure directly into the document, using the ［molecule］ shortcode.