Migration Checklist 4.x to 5.x

System

• Update to node.js > 8 (if possible install node version manager like https://github.com/tj/n)

Configuration

• projectConfig.json rename to projectConfig.js and export data with module.exports = {}
• projectConfig.js unnecessary remove " around properties and rename all remaining from double to single quotation
• projectConfig.js change all /app/** paths to use /src
• edit /gulpfile.js (according to https://github.com/frontend-framework/frontend-framework/blob/master/gulpfile.js)
• package.json "gulp-build-framework"-Pfad anpassen (aktuellste Version setzen!): "build-framework": "https://github.com/frontend-framework/build-framework.git#5.x.x", => /node_modules löschen und yarn install ausführen

Folders

• /app nach /src umbenennen
• /layout in /layouts umbenennen, /includes nach /layouts kopieren
• create /src/pages and move all pages (except index.html) there
• move /components, /layouts, /scaffolding to /src
• move _icons to /resources and rename it to icons
• delete gulp folder

Template Engine

• rename /src/index.html to /src/index.hbs and copy new indexr source from repo (or edit file if Indexr was customized)
• rename all /pages to *.hbs and refactor content to match YAML structure and change partial include to HBS, see https://github.com/frontend-framework/frontend-framework/blob/master/src/pages/01layout.01grid.hbs for a demo
• rename all HTML files from /src, /layouts, /layouts/includes, /pages, /components into *.hbs (Mac Renamer: https://mrrsoftware.com/namechanger/) (Windows Renamer: https://gist.github.com/alxbenz/b302fa6cb74d241bdf151a1ea091eebc)

Search & Replace

Order of execution is critical!!!!! But should be able to be used globally (strg+shift+R on src folder [windows]).

1. Search & Replace Zetzer includes to HBS partials (WITH variables)

REPLACE: \{\{= *ftf\.include\( *"(\.\/)?(.*)\.html"([ ,]*(\{.*\}))? *\) *\}\}
INTO: {{bioInclude '$2' frontendFrameworkMigration='$4'}}

This might be better if there are includes with single quotes (needs verification):

REPLACE: \{\{= *ftf\.include\( *['"](\.\/)?(.*)\.html['"]([ ,]*(\{.*\}))? *\) *\}\}

2. Remove include helpers with empty variables

REPLACE: \{\{(.*)frontendFrameworkMigration=\'\'\}\}
INTO: {{$1}}

---

Combined alternative for 1. and 2. for frameworks with includes without variables

• Search & Replace Zetzer includes to HBS partials (WITHOUT variables ONLY!!!)

REPLACE: \{\{= *ftf\.include\( *"(\.\/)?(.*)\.html" *\) *\}\}
INTO: {{bioInclude '$2'}}

---

3. Search & Replace changed paths from {{bioInclude '...

• "framework/" -> "components/framework/"
• "includes/" -> "layouts/includes/"
• "../_mock/" -> "_mock/"

This can be done with plain Search&Replace function, no RegEx needed.

---

---

!!!! WATCH OUT FROM HERE !!!! There might be lots of special elements. You can't blindly replace everything from now on. Check before execution.

---

4. Search & Replace Zetzer to HBS expressions with default values

REPLACE: \{\{= *ftf\. *(.*?) *\|\| *[\'\"](.*?)[\'\"] *\}\}
INTO: {{bioDef $1 '$2'}}

Be careful with multiple occurences in one line! Skip expressions where default value is empty: "{{=ftf.cssClass || ''}}"

---

5. Search and replace expressions where default value is empty "{{=ftf.cssClass || ''}}"

REPLACE: \{\{= *ftf\. *(.*?) *\|\| *[\'\"](.*?)[\'\"] *\}\}
INTO: {{ $1 }}

6. Search & Replace Zetzer to HBS expressions without default values

REPLACE: \{\{ *\= *ftf\.(.*?\S) *\}\}
INTO: {{ $1 }}

Handcraft

!!! USE THIS ONLY ON FILE LEVEL, LOCALLY !!!

• /pages/*.hbs rewrite from Zetzer/JSON to Handlebars/FrontMatter(YAML). See example: https://github.com/frontend-framework/frontend-framework/blob/demo-5.x/src/pages/01layout.01default.hbs

• Rewrite partial context expressions like {{# partial.conditionalResources || ''}} to {{conditionalResources}} (empty default || '' not necessary anymore)

• Rewrite dynamic includes like {{= ftf.include(partial.contentMain) }} to lookup partial {{> (lookup . 'contentMain') }}

• search for "{{?" and rewite to handlebars {{#if ...}} {{else}} {{/if}}

• Simple conditionals Only {{?ftf.something }} not complex ones like {{? ftf.something || ftf.somethingElse }}

REPLACE: \{\{\?\s*?(!|)ftf\.(\S*?)\s*?\}\}
INTO: {{#if $1$2 }}

REPLACE: \{\{ *?\? *?\}\}
INTO: {{/if}}

REPLACE: \{\{ *?\?\? *?\}\}
INTO: {{else}}

• resolve frontendFrameworkMigration variables Use this regex multiple times until there are no more findings. !!! Careful with commas inside arrays !!!

frontendFrameworkMigration=["']\{\s*(.*?):\s*(.*?),[\s\r]*(.*?)\}['"]
$1=$2 frontendFrameworkMigration="{$3}"

Use this regex when there are no more findings above.

frontendFrameworkMigration=["']\{\s*(.*?):\s*(.*?)}['"]
$1 = $2

!!! HANDLE WITH CARE !!!

Scripts

SASS

Troubleshooting

• YAML description can not contain ':'

Noticable differences between 4.x and 5.x

passing variables

BS Templates pass variables automatically downwards. This may lead to some unwanted behaviour. When nesting components like accordions / tabs the variables must be unique.