Sorcerer's Map blocks are added to areas, pages and stacks in the usual way.
In the edit dialog, all parameters for the map block are entered using Magic Data expressions.
Where you don't want to use a more involved Magic Data expression, simply enter the text or value you want. If it contains spaces, enclose it in quotes. Depending on your Magic Data settings, you may also need to precede such text with SET.
All Magic Data enabled data entry fields of the block edit dialog have a built in symbol tester that you can use to test expressions against specific pages and users (you can also use the symbol tester in the dashboard).
The title and caption fields are optional. Leave them empty and nothing will be output.
Now we come to the important part. The location field must evaluate to location text that Google can translate into a map location. This can be a street address, a post code or zip code, or even a latitude and longitude, as long as it is text that your could enter into the Google Maps web site, you can use it here.
The zoom field must evaluate to a number between 1 and 21.
The real power of the Sorcerer's Map comes when you start to get more creative with Magic Data. How about showing a users local pub?
First, go to the dashboard user attributes page and create a new user text attribute called "Local Pub". Make that available and editable on user profiles.
Now go to your profile and edit it to enter the location of your favourite local watering hole as a street address.
Next, as site administrator, edit the profile page and add a Sorcerer's Map block. For the Location, enter PROFILE ATTRIBUTE "Local Pub". You could also enter a title and caption, but those are not actually required. For Zoom, the default 14 may be a bit small, so maybe enter 16.
PROFILE is an awkward symbol for developers because it depends on the actual profile single page address, so will not evaluate correctly in the symbol tester. If you need to test a PROFILE based expression it is usually easiest to start with UID ATTRIBUTE "Local Pub", test it, then swap UID to PROFILE before saving the block.
Even then, because PROFILE works from the single page path, you won't see the Magic Data evaluate correctly straight away. You need to navigate back to the profile page through the main menu Members -> Profile to see it with its full page path.
No matter who visits your profile, it will now show a map for your local. When other users enter the street address of their local pub into their profiles, visiting their profile pages will show maps to their respective favourite pubs.
Rather than directly editing the profile page, you could have created a whole set of blocks in a stack, including a map, all based on adapting their content to a profile. Then just add that stack to the profile page and see the user-specific information inserted to each user's profile.
You can adapt this to use on any page. Perhaps using PAGE OWNER to pick out the user data for the owner of a page or creator of a blog post, or using one of the IP lookup symbols to find a visitor's location. You can also use the geo-location symbols for Magic Data included with this package to show location information anywhere you can insert Magic Data symbols. You can see an example of that in the screenshots where I have used these symbols in the caption to also show a formatted latitude and longitude for my local pub.
Stepping away from user attributes, you can use Magic Data to evaluate location information from other sources. Do you have pages that show locations? If the location is kept in a page attribute, you can show maps and text for the location at multiple places in the page, all entered and updated from a single page attribute. You can now easily pull in a stack of common information that adapts to show maps relevant to the page based on page attributes.
If you have an eCommerce site with location based products, such as event or property sales, you can add a map to your product page defaults that will automatically adapt to show the location attribute associated with whatever product is shown.
Maybe you want to show manufacturer locations. Create a manufacturer select attribute for your products. You can now use a more complex expression to switch between addresses based on product manufacturer and show the appropriate map. Or you could create user accounts for each manufacturer to hold their addresses and use those to look up the addresses for the map.
All location lookups are cached to minimise calls to external APIs.
Other developers are welcome to use the techniques included in this addon to integrate Magic Data with their own addons.