chocoBRAIN

Appearance

Theme Development Pipeline ​

This Pipeline enables developers to write and test their Liquid, HTML and CSS code inside SectionTemplate and Layout Template locally to speed up the the development process.

Install ​

Theme designers can find a theme template on github. Use git to clone this repository and copy all files into a new git repository of your own. Alternatively you can fork the repository. Then use a package manager (npm or yarn) to install required dependencies (e.g. yarn install).

Usage ​

To see built sections locally use yarn dev. When SectionTemplate and Layout Template is to your satisfaction run yarn build and find the built contents inside the dist folder.

Layout Template ​

The built Layout Template for the App-field Content on Layout screen is put together from the following Pipeline files:

Files style.scss and script.ts are split up in optional but recommended subparts.

layout.liquid ​

  • Type: Liquid
  • Description: Used to construct the content of the Layout Template. Therefore file head.partial is included.
  • File: src/layouts/layout.liquid
  • Target build file: /dist/layout.liquid
  • Development function: {%- block content -%} is replaced by the built Section Template.
  • Build function: {%- block content -%} is removed.
  • Typical content:
    HTML
    <!DOCTYPE html>
<html lang="{{website.lang}}">
  {%- include 'partials/head.partial' -%}
  <body>
    {{content_for_layout}}
    {%- block content -%}Content Block is missing!{%- endblock -%}
  </body>
</html>

head.partial ​

  • Type: Liquid

  • Description: Content of the HTML tag <head> included into the Layout file

  • File: src/partials/head.partial

  • Part of target build file: /dist/layout.liquid

  • Development function: Scripts, css and HTMLforHead contents are included via HTML tags <script>, <link> and <include> inside the <!-- ___DELETE_FROM_BUILD_START___ --> section. is ignored.

  • Build function: <!-- ___DELETE_FROM_BUILD_START___ --> is removed. All CSS, including Bootstrap framework is included via <!-- ___INSERT_BUILD_CSS___ -->. Scripts from script.ts are included by commenting out the code enclosed in /* ___UNCOMMENT_JS_ON_BUILD___ ...___UNCOMMENT_JS_ON_BUILD___ */. The built and uploaded script file is reachable with ___INSERT_BUILD_JS_URL___ and ___INSERT_BUILD_JS_SRI___

  • Typical content:

    HTML
    <head>
  <!-- Meta tags you want in your project -->

  <!-- Examplary include of scripts from `script.ts` with chocoBRAIN's LegalSpeedLoader -->
  <script>
    window.themeLllConfig = {
      ...
      scripts: [
        /* ___UNCOMMENT_JS_ON_BUILD___{
          name: 'jQuery, BootstrapJS, various choco scripts BUILD',
          url: '___INSERT_BUILD_JS_URL___',
          content: null,
          service: 'Cloudinary CDN',
          attributes: [
            { key: 'async', value: null },
            { key: 'crossorigin', value: 'anonymous' },
            { key: 'integrity', value: '___INSERT_BUILD_JS_SRI___' }
          ],
          dependencies: []
        },___UNCOMMENT_JS_ON_BUILD___ */
        ...
      ]
    }
  </script>

  <!-- ___DELETE_FROM_BUILD_START___ -->
  <link rel="stylesheet" href="../style.scss" />
  <script src="../script.ts" async></script>
  <include src="html-head.html"></include>
  <!-- ___DELETE_FROM_BUILD_END___ -->

  <!-- ___INSERT_BUILD_CSS___ -->

  {%- comment -%} Sitespecific HTMLforHead include {%- endcomment -%}
  {{content_for_head}}
</head>

Style.scss ​

  • Type: CSS/SCSS

  • Description: Theme's CSS inlined into built Layout.

  • File: src/style.css

  • Part of target build file: /dist/layout.liquid

  • Build function: SCSS compiled to CSS.

  • Best practice: Use as container to import CSS/SCSS of used Framework, libraries and Theme CSS inside the style folder. Then the styling is split up into the following subparts:

  • Typical content:

    CSS
    /* Import CSS/SCSS. */
@import 'YOUR_FRAMEWORK_CSS_FILE';
@import './style/YOUR_THEME_NAME';

YOUR_THEME_NAME.scss ​

  • Type: CSS/SCSS

  • Description: Internal Theme's CSS inlined into built Layout.

  • Best practice: Part of style.scss.

  • File: src/style/YOUR_THEME_NAME.scss

  • Part of target build file: /dist/layout.liquid

  • Build function: Imported into style.scss and compiled to CSS.

  • Typical content:

    CSS
    /* Best practice: Import CSS/SCSS for used section templates. */
@import 'YOUR_SECTION_TEMPLATE_NAME';
...
/* Best practice: Put CSS/SCSS for whole website here */
...

YOUR_SECTION_TEMPLATE_NAME.scss ​

  • Type: CSS/SCSS

  • Description: Each SectionTemplate's CSS is part of internal Theme's CSS.

  • Best practice: Part of YOUR_THEME_NAME.scss.

  • File: src/style/YOUR_SECTION_TEMPLATE_NAME.scss

  • Part of target build file: /dist/layout.liquid

  • Build function: Imported into YOUR_THEME_NAME.scss and compiled to CSS.

  • Typical content:

    CSS
    /* Best practice: Put CSS/SCSS for YOUR_SECTION_TEMPLATE_NAME here */
.SECTION-TEMPLATE-CLASS {
  ...
}

HTML for Head ​

Each Website can have its own scripts, styling and structured data. This content is inserted into the HTMLforHead field of the chocoBRAIN App. When developing for more than one website it may be useful to rename the file html-head.html. In this case do not forget to also rename it in HTML include inside of head.partial].

html-head.html ​

  • Type: HTML

  • Description: For testing it is possible to put content of HTMLforHead field here and include it into the local development build with HTML tag <include> inside head.partial. When using LegalSpeedLoader it is required to finalize its config definition in this file.

  • File: src/website_head_htmls/html-head.html

  • Part of target build file: Testing only

  • Build function: Testing only

  • Typical content:

    HTML
    <script>
  // Website specific scripts
</script>

<style>
  /* Website specific style modifications with CSS/SCSS */
</style>

SectionTemplates ​

  • Type: HTML

  • Description: All code for section template development. The target build file is ready to be copied into the content field of SectionTemplate screen.

  • File: src/section_templates/YOUR_SECTION_TEMPLATE_NAME.scss

  • Development function: Insert Layout content with {%- layout 'layouts/layout.liquid' -%} into development pipeline and overwrite its {%- block content -%} definition with current SectionTemplate. The {%- schema -%} block is ignored and only used on production by the chocoBRAIN-App to build defined TDSL-fields. All required content which is given via Liquid-API on production needs to be mocked in the development process inside SECTION_TEMPLATE.json.

  • Target build file: dist/section_templates/YOUR_SECTION_TEMPLATE_NAME.liquid

  • Build function: Remove {%- layout 'layouts/layout.liquid' -%} and surrounding {%- block content -%} and {%- endblock -%}.

  • Typical content:

    Liquid
    {%- layout 'layouts/layout.liquid' -%}
{%- block content -%}

  {%- comment -%}
  YOUR_SECTION_TEMPLATE_NAME
  {%- endcomment -%}

  {% schema %}
  {
    "schema_name": "YOUR_SECTION_TEMPLATE_NAME",
    "css_class": "YOUR_SECTION_TEMPLATE_CLASS",
    "tag": "div",
    "settings": [
      ...
    ]
  }
  {% endschema %}

  {%- comment -%}
    Handle settings default values
  {%- endcomment -%}
  <!-- Your Liquid code. -->

  {%- comment -%}
    HTML
  {%- endcomment -%}
  <!-- Your HTML and Liquid code. -->

{%- endblock -%}

Mocked content for SectionTemplates testing ​

  • Type: JSON

  • Description: Filename needs to be the same as the SectionTemplates .liquid-file. It can hold any JSON key-value pairs. Used to mock all objects needed in the development pipeline and given via Liquid-API inside the App. By changing the content you can test your SectionTemplate locally.

  • File: liquid/section_templates/YOUR_SECTION_TEMPLATE_NAME.json

  • Development function: Mock the content of the data given by the App's Liquid-API.

  • Build function: none

  • Typical content:

    JSON
    {
  "website": {
    "lang": "de",
    "primary_domain": "www.x.de",
    "description": "Webseite Meta tag description",
    "title": "Webseite Meta tag title"
  },
  "page": {
    "title": "Seite Meta tag title",
    "description": "Seite Meta tag description",
    "kind": "page",
    "path": "/seiten-pfad"
  },
  "section": {
    "position": "1",
    "kind": "main",

    "settings": {
      "my_text": "Text unformatiert, einzeilig",
      "my_textarea": "Text unformatiert,\n mehrzeilig",
      "my_richtext": {
        "html": "<p>Formatierbarer HTML-Text.</p>",
        "plain": "Formatierbarer HTML-Text."
      }
    }
  }
}

Javascript ​

script.ts ​

  • Type: Javascript / Typescript

  • Description: All script code for section template development.

  • File: src/script.ts

  • Development function: Included locally as TypeScript file ../script.ts via HTML tag <script> and parsed by ParcelJS.

  • Target build file: dist/script.js

  • Build function: Compile TypeScript files into one javascript file, which is uploaded to a host and used in production build via ___INSERT_BUILD_JS_URL___ and ___INSERT_BUILD_JS_SRI___ as described in Head file.

  • Best practice: Import your script dependencies and your own scripts from src/scripts/init.ts here. Then the scripts are split up into the following subparts:

  • Typical content:

    JAVASCRIPT
    import { init } from './script/init'
import 'framework'

init()

init.ts ​

  • Type: Javascript / Typescript

  • Description: Your code imported into src/script.ts. Best practice is to keep a multitude of independent scripts in separate files and import them.

  • File: src/scripts/init.ts

  • Development function: Included locally as TypeScript ../script.ts via HTML tag <script>.

  • Part of target build file: dist/script.js

  • Build function: Imported and compiled into one Javascript file.

  • Typical content:

    JAVASCRIPT
    import { yourScript } from './yourScript'
import { yourScript } from './yourOtherScript'

export const init = () => {
  // console.log("Initialising Theme scripts.")
  yourScript()
  yourOtherScript()
}

Independent script files ​

  • Type: Javascript / Typescript

  • Description: Your independent scripts imported via src/scripts/init.ts into src/script.ts.

  • File: src/scripts/yourScript.ts

  • Development function: Included locally as TypeScript ../script.ts via HTML tag <script>.

  • Part of target build file: dist/script.js

  • Build function: Imported and compiled into one Javascript file.

  • Typical content:

    JAVASCRIPT
    export const yourScript = () => {
  // JavaScript/Typescript code
}

Remote deploy ​

  • Type: Env

  • Description: Your hosts upload credentials to directly push dist/script.js to server.

  • File: .env

  • Development function: none

  • Build function: Pushes dist/script.js to hosting service to be used in production build by the use of ___INSERT_BUILD_JS_URL___ and ___INSERT_BUILD_JS_SRI___ as described in Head file.

  • Typical content:

    erb
    CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=
CLOUDINARY_CLOUD_NAME=
CLOUDINARY_FOLDER_NAME=" "

Technologies ​