I18NMixin

• Install the mixin via yarn or npm: yarn add @haxtheweb/i18n-manager
• create a folder in your element called /locales
• create a file called my-element.es.json for the spanish translation of your element. Japanese would be my-element.ja.json for example.

This invokes a dependency on our manager which you might not want to have in your element. If you want to do a similar approach but without dependencies, you just have to feed a custom event to our manager. You'll still have to use the convention for translatable text, but here's how you can invoke the event needed

Using the vanilla approach, you'll still need to have a /locales directory and the same naming convention. Our mixin just simplifies the integration a bit as well as the timing of what it's initiated but this event registration method will still work within any element that's going to arrive in HAX/HAXcms or any property you make that isn't using HAX at all.

Because of the simplicity and power of haxHooks this may not be an exhaustive list and the internal code documentation on this should be consulted (or open an issue to ensure we document a missing hook!). You can search the webcomponents monorepo for usage of haxHooks  in order to discover additional implementations beyond what is pointed to below.

Blog posts about this topic

• haxHooks(): How elements can supply their own editing experience in HAX now!
  
• haxHooks: webcomponents that ship their own editing UX
  

Code example

This is a basic example in which each of the strings you'd then implement as their own async callbacks. async / await allows HAX to safely defer to your element to do whatever it wants to the DOM / internal structure of that callback, without disrupting element activation or conversion of DOM structure to HAX Element Schema, what it uses to virtualize the body for sanitation  purposes at the time of save / adding new things to the page.

gizmoRegistration(store)

The most powerful hook in haxHooks. This fires whenever an element is read in via the appStore and it's definition loaded for use. This hook supplies an instance of the HAXStore which is the internal state management of HAX (written in MobX). You can use this object to do whatever you want to HAX. While seemingly too powerful, here are some examples of past things to leverage this super power for good

• code-sample - the code-sample tag uses this hook in order to inject additional shortcut logic. If the tag is supplied, things like ```js will convert to a JS based code-sample. It also hijacks the baked in support for ``` in order to inject a code-sample tag instead of the default code tag
• supplying "apps" based on tag - wikipedia-query and github-preview  supply custom public API search endpoints based on their tag being loaded. This way you can use the "Media" menu in order to search Github or Wikipedia in HAX just by including these tags in your autoloader block of the appstore.
• supplying translatable haxProperties - meme-maker and twitter-embed supply custom translations for their haxProperties. This means that if you were to edit these elements using the editor in Spanish (es), you would see the fields and example inputs in Spanish (es) as opposed to their English (en) default text supplied by the static get haxProperties() method.

activeElementChanged(element, value)

This runs whenever a user activates / selects an element to modify in HAX. This supplies an instance of the element / DOM node that is active as well as if we are active (true) or inactive (false). This hook can be used to modify state / functional aspects of your elements just prior to it receiving activation by hax. An example use-case for this could be preventing default behavior for an element that is a clickable link (see:  ebook-button ). Another possible usage is making pieces of the internal shadowRoot contenteditable , only while activated (see: meme-maker ).

editModeChanged(value)

This runs on all active nodes in the hax-body tag when the editing state of the HAX editor itself changes. If we are now editing, value is true , when we go to save / are no longer editing, it is false .

inlineContextMenu(ceMenu)

This hook runs after element activation in order to allow elements to supply custom editing buttons and operations to the in-context menu that hovers above active elements. You have access to the instance of the custom elements hax menu element (hax-ce-context) and can add whatever buttons you want at this time with custom callbacks. See multiple-choice for an example of how you can leverage this. multiple-choice uses this to add quick buttons for adding and removing potential answers quickly.

preProcessNodeToContent(node)

This runs right before nodes are converted to content in the entire hax-body. This happens when the user has triggered a save event and we are converting the DOM from real nodes into the HTML text that is to be saved / returned to a backend. This hook allows you to do any known data clean up to the element prior to it being converted to HTML. See multiple-choice for an example of taking a complex data property and converting it to innerHTML children at the time of save for progressive enhancement purposes.

progressiveEnhancement(element)

This hook runs WHILE the node is being converted to text and should return a string that will be appended into the innerHTML area of the element. This is an alternative to what you could accomplish during preProcessNodeToContent but want to work with a string based response. See meme-maker for an example of using this to inject innerHTML which only is for SEO purposes.

postProcessNodeToContent(content)

This hook runs after preProcessNodeToContent and progressiveEnhancement and before the element is returned in the hax-save event. This runs AFTER the node has been converted to content. This is useful for forcible content clean up like regex'ing output for specific words to not leak into output. See video-player for ensuring there are no internal empty arrays for data is not a required field.

preProcessInsertContent(detail)

This is a hax schema element, our virtual dom node, that is about to be inserted into the hax-body. This allows for custom modification to the data that's about to be converted to a DOM node. See multiple-choice for an example of ensuring that answer data doesn't bleed through to the page. This hook runs on duplication as well as inserting a node by the user selecting the block.

Create a new repository from hax11ty

It even has github actions support built in! Meaning you can check out the mini-doc site for HAX11ty which is self-updated when we update the docs / repo for HAX11ty.

This video shows early work on HAX11ty by Michael Potter

Normal HTML Paragraph Tag

Meme Tag

Notice with the meme element that it now has additional fields which when changed are reflected in the page instantly!

This roadmap illustrates all the projects related to HAX and ELMS:LN, which HAX comes from. The little settings gears found throughout illustrate enhancements and next steps for the different projects in our wheel house.

As you can see, there's a lot of planned enhancements to HAXeditor and HAXcms with a lot of additional future capabilities in ELMS:LN as a result of these projects. It's important to understand these relationships through and how innovations flow between them.

Relationships of major pieces

HAX has many different parts detailed here, so let's look at the relationship between these pieces before getting into the roadmap. HAX projects are part of the ELMS:LN organization and so ELMS:LN is also included in these roadmap details.

HAXiam, HAXcms, HAXeditor are three projects that make up the "HAX" name space, all of which benefit from being built on web components. HAXiam is a server technology while HAXcms is a mix of server and front end assets. HAXeditor is fully front-end code which then requires a backend to save and load pages from.

Below is an image consolidating information found on this site with arrows illustrating flow of innovation. Web components are always our building blocks, usually bubbling up as a need in either ELMS:LN, HAXcms or HAXeditor. From there, HAXeditor influences and improves ELMS:LN and HAXcms. ELMS:LN has a copy of HAXcms inside of it so sees improvements from both platforms. HAXiam just makes sure that copies of HAXcms are generated.

Now with this foundation you can dig into the different pieces of the project roadmaps.

1. Get the HAX plugin  from the wordpress registry
2. Go to edit / create a page/post and you are HAXing

Installation video

This shows installing it manually if you can't get it from the wordpress store!

HAXcms powers this website and is a hybrid static site generator, a new class of CMS. It's hybrid in that everything is written to static like a static site generator and it's 100% decoupled via web components.

Features

• Micro-site manager, so manage multiple sites from a single HAXcms install
• Each site is powered by static files which live in version control
• Every change is executed by the front end via HAX / Outline tools
• Every change is automatically tracked in version control (zip the folder and send it to a friend and it'll work)
• The "database" is powered by a site.json file that lives with the site
• All operations write to static files so every change is as if you editing HTML by hand (but you didn't... HAX did)
• Ability to serve up as a static site on CDNs (this site is on GH pages + a CDN) via Publishing which makes a purely static copy with a service worker and the whole jazz for offline / installable capability (0 config)
• Build your own themes via custom front end dev if you like or use one of our baked in ones

It is a flat file generator with a UI and the UI contextually loads based on if you should see it. It's weird, we know, and that's also why we have trouble describing what it is. It's a flat file CMS without tooling required. It's a sustainable way of building and maintaining a "CMS" as it has multiple pages, can handle custom fields, custom themes, but yet it doesn't require infrastructure to keep running beyond PHP / node / Beaker browser to act as a back end to edit the static files.

It's an organic CMS. A living yet permanent website. It's hacking the limitations of content authoring capabilities. It's why we say, we're HAX The Web.

Core Principles

• Support all platforms and devices (CMS, App, etc)
• Empower authors to write code without ever looking at code
• All content produced must work with or without HAXeditor available
• Support older markup, regardless of structure, as best we can
• HAX will learn the rules of producing elements, it won't dictate them
• Decentralize all the things, empower all the peoples

Cross platform

Because we've adopted the web component standard in the development of both HAX (authoring system) and HAXCMS (content management), everything we create and compile via our open tooling  can support about 98.4% of all browser traffic globally without server side rendering. HAXcms also employs a progressive enhancement methodology meaning that it can hit 100% of all browsing traffic with content.

This means that you can use the latest and greatest of the web and not have to constantly worry about a library changing! The dawn of the age of web components is now, join the revolution!

Platform support

• Evergreen browsers (93+% of traffic) - no polyfills!
  
• IE 11 / Edge <18 / legacy browsers - polyfills with simplified design
• See F.A.Q. for a more detailed break out of stats

No content lock-in

The elements that make up HAX can be delivered via a CDN or installed locally. This means that the functionality is tied to the browser  and NOT  to the platform itself (huh?). Well, think of all the complex functionality of any site you've ever built or used. Then add content to that site. Now move that site (in your mind) to another server. What has to be migrated to maintain the content functioning that isn't actually content?

For example, take this quiz:

We're building the greatest roster of people ever to HAX the complacency of our industry. Take the HAX scavenger hunt at the next event to join the movement!

Past winners rocking their merch from completing the hunt!

• @onelittlebecca - at DrupalGovCon '19
• @JProffitt - at DrupalGovCon '19
• @natefollmer - IRL Aug '19
  

• page load, should it be no-js or a web component delivered, preflight
• haxcms-site-builder loads site.json, reads JSON Outline Schema and starts to bootstrap that into a theme, items, title, etc
• Appends a haxcms-editor-builder tag which checks for "context"
• Context is established based on global values for php, nodejs, beaker, etc
  
• Uses a login end point to check if there's a JWT in the user's local data
• When it finds a backend, it injects a tag to bridge that backend
• HAXeditor gets injected into the correct place in the theme which then all of that unpacks and does its thing

Event driven architecture

HAXcms allows for jumping in at different core operational steps and reacting to these changes based on an event driven design pattern. This means that an event "fires" in PHP, much like it does in JavaScript and code written to react to it can make changes at that point in the operation.

Here is an example from HAXiam which implements custom configuration event listeners

Core listeners

Core listeners to influence how the data is constructed. You can add these to your _config/config.php file

• haxcms-init - just after HAXcms bootstraps its initial configuration
• haxcms-site-metadata - when constructing metadata block at the top of the document
• haxcms-connection-settings - for authorized users, this is the block of end points for connecting to and modifying HAXcms logic as far as where data flows.

Enterprise integrations and SSO

The following hooks allow for supplanting the HAXcms (intentionally) simplistic login system. This allows you to do custom integrations for your organization. HAXiam implements many of these if you need specific examples.

• haxcms-login-test - when a login didn't pass our simplistic built in checks. Useful for enterprise integrations and other SSO methods of access
• haxcms-validate-user - same as login-test except this fires to validate every transaction to ensure the user name matches when decoding the JWT
• haxcms-jwt-get - when we ask for the JWT. This allows SSO to supply the token manually via a different methodology than our core one
• haxcms-refresh-token-get - when our connection is deemed needing to refresh, this supplies the refresh token for when and what that looks like

I installed HAXcms and forgot my password

Your username and password can be found in _config/config.php on the server (assuming local development)

I clicked login and nothing happened and now I'm locked out.

• Clear your browser cache. A cookie is set that might be invalid.
• Open a new browser and try to login again

I clicked publish and nothing happened

• Publishing can take up to a minute or so at times since it's creating a commit, rewriting files and then the front end is waiting on the push to github before it triggers a successful response.
• If it did fail to publish, you might not have git setup. Click the gear icon on the dashboard (site listing) and ensure you've setup github / git integration correctly.

Realize that everything is just a file and that our json outline schema is very easy to read. So if there's an issue with something related to publishing, check _sites/mysite/site.json for publishing, then _config/config.json. All settings and variables cascade in this way. Settings are stored globally, then replicated locally to allow them to be pealed off and more easily imported / exported into other setups.

Workflow

1. Make a new site in the HAXcms UI
2. Select "Custom theme" as your theme
3. In the file system go to _sites/mynewsite /theme
4. Edit theme.html to modify the structure
5. Edit theme.css to modify the design

This is the easiest way to skin HAXcms to your liking. It's able to ship and work in CDNs and is the minimal barrier to entry for those used to seeing HTML and CSS files that they can touch and see the change. It requires no tooling to utilize either!

1. All custom theme work happens in your _config directory
2. Make my-theme.js, pull everything together, either in this directory or in a wcfactory catalog  of elements you've made
3. Reference this in you _config/my-custom-elements.js element
4. Update the _config/config.json block that says themes  to include something like...

This tells HAXcms UI that you can now select the theme (but don't yet, it won't be valid)

Local development workflow during theme development

We use polymer cli to serve up and work on web components locally and while you don't have to, it's recommended as part of the WCFactory workflow.

1. Make a new site in the HAXcms UI
2. Go to _sites/mynewsite and run polymer serve --npm --open --entrypoint dist/dev.html
3. Adjust the URL that opens to only be the IP address with no path after it
4. You'll see your site open up for local development work, which will be leveraging any assets referenced in your node_modules directory at the HAXcms project root.
5. To add / install new assets run yarn (or npm) add @what/ever-you-want --save , just like you would any other project you work on in FE dev
6. edit your site's site.json manually to update the theme to point to the theme location your actively working on
7. Develop away until it is to your liking

Shipping the theme

To ship the theme, you'll need to do a polymer build routine

important note

This currently forks you from the original source of HAXcms core (because it will recompile the assets). If you're ok with this cool, just know we're trying to find ways around this involving rollup .

1. Go to the HAXcms project root
2. run polymer build
3. Copy the build directory and go to your site
4. Delete the symlink and replace it with your build directory
5. Now you can publish via the UI so long as you do not leverage a CDN

The future

Admittedly, the full on custom theme / web component development workflow is rough. It's hard to maintain a built copy in a modular system without tooling. In the future we plan on having tooling workflows built directly into WCFactory that allow you to streamline the development and creation of HAXcms themes.

Current limitations

You can't leverage existing CDNs (like webcomponents.psu.edu and whatever else is out there) that are pegged to the HAXcms project's source. You'll be creating a custom theme which then creates a custom build in effect so you'll want to ensure that you have some place that you can host the assets in order to power your site.

A note about @apply

Unlike normal css variables, Polymer (the library we build our theme layer on) supports a convention for CSS variables that operate a bit more like Saas mixins. You can write blocks of code like @apply --my-variable-blob; which will then allow someone to mix in and apply whatever valid CSS attributes they want at that level. You can see several implemented below (both CSS variables and @apply blocks).

Example

This is an example from the haxcms-basic-theme which forms a clean baseline for most sites.

Ok ok, here's the deal. Queries are so important that they needed their own section. Calm down Dwight we'll handle that now. The site- query elements are incredibly powerful aspects of HAXcms theming that deserve their own section anyway.

site-query

Code Example