Black Magic Data User Guide

Before you begin

Black Magic Data is an advanced extension for Magic Data. Before attempting to use Black Magic Data you should already be familiar with Magic Data, with the dashboard Symbol Tester, and with any of the various Magic Data integrating blocks you want to use Black Magic Data to enhance.

Black Magic Data includes dashboard options for sandboxing to disable symbols from making changes to the database. Immediately after installation, symbols executed in the symbol tester are sandboxed so you can experiment without fear of damaging your database. Please refer to Dashboard > Magic Data > Symbols Settings.

30 bmd settings.png

Don't break your site

Some of the symbols in Black Magic Data make changes to a concrete5 site's database or files. Incorrect use can result in unwanted changes to your database. Please use a test site for development before copying Magic Data expressions using these symbols to a live site. Please read this documentation and the symbols' built in documentation carefully before trying to use them.

Good practice, safe practice

  1. Start on a test site. Do not start on your live site.
  2. Take a database backup before you start.
  3. Use the dashboard Symbol Tester to learn and experiment.
  4. Keep the sandbox enabled for the dashboard symbol tester.
  5. Read the diagnostic trace line by line to understand what your symbols and expressions are doing.

Only once you know what is happening you can remove the sandbox and allow the symbols to change your database.

An example: Extending the capabilities of Sorcerer's Map

First you need to install the Sorcerer's Map block, its free!

In the dashboard, create two new numeric page attributes, Latitude and Longitude. You will also need to set up a user attribute for a Local Pub as described in the Sorcerer's Map example.

Now create a test page on your site. This example will not work in a profile page like the example in Sorcerer's Map does.

Now add a Sorcerer's Map block, again mostly the same as the example in Sorcerer's Map, save the Magic Data expression for the Location, which now has the more complex expression below. As a developer already familiar with Magic Data you should be able to understand what most of this is doing.

20 bmg attributes md.png

SET "JohntheFish" AS_USER ATTRIBUTE "Local Pub"
GEO_LATLNG SAVE "latlng"
LAT_FROM_LATLNG ROUND_TO 4 SET_CURRENT_PAGE_ATTRIBUTE "Latitude"
"latlng" RETRIEVE
LNG_FROM_LATLNG  ROUND_TO 4 SET_CURRENT_PAGE_ATTRIBUTE "Longitude"
"latlng" RETRIEVE

We start by retrieving (my) user attribute for my local pub and use the GEO_LATLNG symbol from Sorcerer's Map to locate it, saving that to a temporary memory called latlng.

From that value, we then split out the Latitude and Longitude, round them to 4 decimal places and save them to the page attributes we created earlier.

Finally, we end by retrieving the latlng so the expression ends with the a map location that Sorcerer's Map will then use.

This is all pretty straight forward, save for the rounding. Before updating an attribute SET_CURRENT_PAGE_ATTRIBUTE will read it to see if it has changed. This saves unnecessary updates. However, numeric attributes in the concrete5 database are rounded. If we don't also round, the check within SET_CURRENT_PAGE_ATTRIBUTE will always fail and result in unnecessary updates to the database each time the page is viewed!

10 bmg attributes set.png

Taking it further

Rather than fixing a user associated with a page (JohntheFish in the above example), you could get the user from the page owner or from another page attribute.

Copy the test page a number of times. Each time change the attribute to select a different user (who also has a favourite pub).

Attributes are only really useful when you read them. So now pick your favourite advanced page list addon that can filter by attribute comparison to list those pages and filter by Latitude and Longitude within a box.

Getting more sophisticated, you could also use an Uber List to create a list and filter by the actual distance using the symbol LATLNG_DISTANCE_MILES. Or, if the origin is reasonably static, extend the Magic Data expression of the map pages to set another attribute containing the distance from the origin. You can then filter and sort the list by the distance attribute of each of the maps pages using any attribute filtering page list.

PAGE ATTRIBUTE "Selected User" AS_USER
ATTRIBUTE "Local Pub"
GEO_LATLNG SAVE "latlng"
LAT_FROM_LATLNG ROUND_TO 4 SET_CURRENT_PAGE_ATTRIBUTE "Latitude"
"latlng" RETRIEVE
LNG_FROM_LATLNG  ROUND_TO 4 SET_CURRENT_PAGE_ATTRIBUTE "Longitude"
"latlng" RETRIEVE
SET "Portland Oregon" GEO_LATLNG
GEO_LATLNG LATLNG_DISTANCE_MILES ( "latlng" RESTORE )
ROUND_TO 0 SET_CURRENT_PAGE_ATTRIBUTE "Distance from concrete5"
"latlng" RETRIEVE

Last updated: over a year ago