Del

FirstMagic Updating Guide

The InstallerGuide.pdf contains a simple step-by-step guide for updating existing 1.3 websites to 1.4. The process only takes a few minutes per site, and the pdf lists everything you need to know in a few short paragraphs.

This FAQ is an expanded explanation of this procedure, in case you want to delve into details: it answers questions on why and how, and might be useful if you need to do the update with more confidence regarding what will happen "under the hood".

In this document:

Updating FAQ - 1.3 to 1.4
To-the-point - a quick overview [everything you need to do]
Ensemble - what´s new in Ensemble
Widgets - FirstMagic Preferences publishable objects are now Widgets
Index - if you want to update your index file
FirstMagic Preferences - what you need to do in FM Preferences
Skins - How to make sure your Skin transfers correctly to 1.4
If you use a Custom Skin
If you use a Built-In Skin
If you use an OTSW Skin
If you use a SkinDesigner Preset
Updating from 1.2 and older to 1.4


Updating FAQ - migrating from FirstMagic 1.3 to FirstMagic 1.4.
A detailed list of questions and answers on updating 1.3 sites to 1.4. This list expands on the information found on page 2 in the installerguide.pdf.

Updating existing 1.3 sites to 1.4 is easy, and is done in a few minutes:

- Re-select your Skin in FM Preferences after the update
- Re-select your website language in FM Preferences
- Set a value for Slideshow height in FM Preferences
- Add the folders "SiteWidgets" and "SignWidgets" to your Ensemble folder
- Add a new, empty FirstClass Document named "meta.inc" to your /Ensemble/Services/ folder

... Everything else is optional, and will have little to no impact on existing sites.

Read below for details.

Ensemble
Q
After updating, what do i need to do in the Ensemble folder?

A
FirstMagic introduces three new functions that will expect the following to be present in Ensemble:
  • In /Ensemble/, an empty folder named "SiteWidgets"
  • In /Ensemble/, an empty folder named "SignWidgets"
  • In /Ensemble/Services/, an empty FirstClass Document named "meta.inc"
... Simply create these three objects. Your site will work without them, but you won´t be able to take advantage of FirstMagic Widgets, or use the new metatag function if they are not present.
Widgets
Q
After the update, my Social buttons, Twitter , Sidebar Search and / or Comments are missing! Why?

A
These features was earlier choices in FirstMagic Preferences. They are now FirstMagic Widgets - stand-alone mini-apps for your web pages. To reinstate them, you have to add them as widgets to your pages.
Q
How do i get back Feature X as a Widget?

A
  • Open the /Ensemble/SiteWidgets/ folder. If it does not exist, read the entry above.
  • Open FirstMagic Preferences, and go to the Help Tab.
  • Click the large Widgets Library Button
  • Locate the function you want to add.
  • Press and hold ALT on your keyboard, and drag-drop the function you want into your SiteWidgets folder.
  • Open the new Widget, and configure it the way you want it to behave.
  • Repeat this process for each function you want.
Q
Why are these features now Widgets?

A
They are much more versatile as Widgets than they were as FM Preferences options:
  • You can now have multiple versions of each such function (for example, several different Twitter Feeds, or several differently configured Sidebar Search boxes).
  • You can specify each Widget to appear on particular pages only. Or have differently configured versions of the same widget appearing on different pages.
  • You can have them in different places: In the SiteWidgets folder [website footer], in the Sidebar folder, in your Digital Signs Calendars - or as stickies on your website´s left margin.
Index
Q
After updating, do i have to change my index.shtml file?

A
No. FM 1.4 just adds some new controls to index.shtml that:
  • Makes it easier to design a splash screen with CSS.
  • Auto-detects mobile devices and gives them the Mobile Interface automatically [if you have Mobile UI turned on].
... Not updating index.shtml will not affect your website in any way. It is entirely optional.
Q
How do i update index.shtml?

A
Index.shtml is an invisible document in your website root. To access it, do the following:
  • In the FirstMagic 1.4 installer package, go into /Extras/OldSite_updater/, and locate the folder named "___index.shtml; Redirect and Splash; 11-23-2012".
  • Drag this folder onto your FirstClass Desktop. It will create a new document there, named "index.shtml"
  • Open this document, and copy everything into your clipboard.
  • Open the Explorer pane in your website root.
  • Close the list in the Explorer pane.
  • Hold SHIFT on your keyboard, and re-open the list.
... Now index.shtml appears in the list. Click it, and it will open in the right-hand pane.
  • Delete everything inside it, and paste in the contents of your clipboard instead. Save and close.
  • Delete the index file on your FirstClass Desktop.
FirstMagic Preferences
Q
FirstMagic Preferences looks the same as before! I cannot find any new functions. Why?

A
The FirstClass Client will not always detect changes by itself. Simply flush your FC Client cache, and you will see the new features.
Q
After updating, what do i need to do in FirstMagic Preferences?

A
FirstMagic 1.4 introduces new functionality that will reset a few choices in FM Preferences. These must be re-selected:
  • On Tab 1, select your chosen website language - even though it appears to be selected already.
  • On the SkinDesigner Tab, re-select your chosen Skin or SkinDesigner Preset.
  • On the Advanced Tab, set a value for Slideshow heights, even if it appears to have one already.
Q
I used a Built-In Skin, and cannot find it in the SkinDesigner anymore. What do i do?

A
FirstMagic 1.4 ships with a new set of Built-In Skins. To re-install an 1.3 Skin, read about Built-In Skins below. It is an easy, one-minute procedure, you simply upload it into CustomCSS from the 1.4 installer Extras folder.
Skins
Custom Skins
Q
Will my custom 1.3 Skin continue to work with 1.4?

A
Yes. Anything you have in CustomCSS will continue to work as before. You can also move it to other sites created with the 1.3 installer, but installing it in new sites created with the 1.4 installer [Native 1.4 sites] will not work without some re-writing.
Q
Why will custom 1.3 Skins not work with native 1.4 installations?

A
FirstMagic´s rendering engine is completely rewritten for the purpose of making Skins easier to write in CSS. You can now write a Custom Skin with less than 50% the amount of code you would have had to use in FM 1.3, and still achieve the same result.

For this reason, 1.3 Skins are not compatible with native 1.4 installations. However, the CustomCSS folder has a backwards-compatibility feature built in, so that existing 1.3 sites can continue to use their Skins uninterrupted after the site is updated to 1.4. This compatibility feature will not be present in sites that is created with the 1.4 installer - i.e, native 1.4 sites.
Built-in Skins
Q
Will a Built-In Skin selected in 1.3 work with 1.4?

A
No. FirstMagic 1.4 delivers a different built-in set than 1.3. Some skins are similar, but if you want to retain a 1.3 skin Built-In Skin as is, you will need to move it into CustomCSS.
Q
How do i get a Built-In 1.3 Skin into 1.4?

A
  • In FirstMagic Preferences, set the SkinDesigner to use CustomCSS [Select the CustomCSS Preset].
  • Select the default option in all three dropmenus on the SkinDesigner >> CustomCSS pane.
  • Open the website´s /Ensemble/CustomCSS/ folder, and remove everything inside.
  • In the FirstMagic 1.4 Installer download, open Extras >> Skins >> 1.3  Skins, and locate your chosen 1.3 Skin. If you do not know the name of the Skin, each Skin folder contains a preview image [SkinPreview.png] to make it easier to identify.
  • Open the Skin folder, and drag-and-drop everything inside it into the website´s CustomCSS folder.
Note: this will only work for existing websites updated from 1.3 to 1.4, not for native 1.4 sites [see above].
OTSW [FirstClass Communities] Skins
Q
Will OTSW Skins selected in 1.3 continue to work with 1.4?

A
Yes. OTSW Skins is not affected by the update; any website will continue to use them as before, as long as OTSW is installed on the server in the first place.
SkinDesigner Presets
Q
Will my SkinDesigner Preset continue to work after updating to 1.4?

A
Yes. Though there may be some [very minor] changes to the output, due to bugfixes introduced with 1.4.
Q
Can i insure my 1.3 SkinDesigner Preset against such minor changes?

A
Yes. If you want to make absolutely sure your website is completely unaffected by the update, you can convert your Preset to a CustomCSS Skin. But note that, as with other custom Skins [read above], such converted CustomCSS Skins will only work properly with 1.3 sites that is updated to 1.4; they cannot be transferred to native 1.4 sites without rewriting.

Important: you must convert your Preset to a CustomCSS Skin before the update!
Q
How do i convert a SkinDesigner Preset to a CustomCSS Skin?

A
  • Visit your website, using this URL: http://yourwebsite.com/firstmagic [add /FirstMagic after your base URL]
  • This is a blank page. View the Page Source of this blank page.
  • Copy the entire page source.
  • In FirstMagic Preferences, set the SkinDesigner to use CustomCSS [Select the CustomCSS Preset].
  • Open the website´s /Ensemble/CustomCSS/ folder, and remove everything inside.  
  • create a New FirstClass Document, and name it "styles.css".
  • Paste in the code you copied from the page source above.
  • Delete the very first line of the page source, save and close.
... If you need help with this procedure, contact Support at this link.

How to update older [1.1x and 1.2x] FirstMagic installations to 1.4:
  • Run the installer, and get a clean 1.3 installation
  • Register the 1.4 installation in Multi-Site Setup, replacing the original domain entry there
  • Move your Content folder from the old installation into the new
  • If you have CustomCSS in active use, remember to copy it´s content into the new installaton
  • If you have custom HTML in use in the Services folder, copy it into the corresponding files of the new installation.
Activate the new installation:
  • If you are updating from a 1.2 installation: Copy your license code from the old FirstMagic Preferences Form to the new.
  • If you are updating from a 1.1 installation: Use the 1.2 activation code you have received by e-mail. If, by some reason, you have not received an 1.2 code, please contact Support to get a replacement immediately - 1.1 codes will not work on 1.2 or newer installations.