How to Use Keyboard CSS in PHP Help Page?

Keyman Keyman How To
1

Greetings,

I was just working on documentation updates and noticed that the PHP based Help page does not use the keyboard-included CSS file when generating the embedded mobile layouts. For example here: https://help.keyman.com/keyboard/gff_amharic/3.0/gff_amharic

The HTML of the tables looks pretty much identical to what the web tester interface produces. Perhaps getting the keyboard colors it’s just a matter of a missing css file import? If I were to add an css import statement to the .php help file, would it just work or is there more to it? If adding the import line on my end would be a solution, what is the relative path and filename to use?

Alternatively, if a solution might be some time away, I would shift to using screenshots in the interim.

[Side note in the gff_amharic example of the link, the puncutation-2 layout appears as a broken table for the tablet layout. This layer doesn’t exist, so I’ll make this fix with my update.]

2

Hi @dyacob - Maybe you can try what @Matthew_Lee did on the sil_cameroon help (include a copy of the css in the help/ folder).
e.g.

1 Like
3

Thanks @darcy, following up on your recommendation from @Matthew_Lee keyboard I tried something similar which appears to work (causes no .kmn build issues). I want to avoid duplicating and renaming the css file if possible and now have this file structure:

my_keyboard/
  source/
    my_keyboard.kmn
    help/
      my_keyboard.php
      my_keyboard.css

where the .css file has been moved into the help directory. The .php file can reference it locally with the link statement using its original name, and the .kmn file can likewise reference it with:

store(&KMW_EMBEDCSS) 'help/my_keyboard.css'

So far no issues, given what I can test locally. LMK please if there would be any unexpected consequences.

thanks!

-Daniel

4

This may work locally, but the help folder structure is not present in the package, so I suspect that this would not work for distribution.

As far as I can see, you’ll need two copies of the .css file, one in the help folder and one in the source folder. (But @Marc will correct me if I’m wrong!)

1 Like
5

@drowe is correct.

Addressing the duplication of documentation content between help and welcome is a difficult issue. Some of the things we want to solve:

  • having a single source file for both website and embedded doc
  • path issues like this one
  • embedding styles (merging with help site styles where possible for continuity and readability)
  • testing help site content before publication
  • including and excluding HTML headers as required
  • using the Keyman Engine for Web documentation generation tags – can we make them available in Keyman as well (greatly simplifying the help file if so)

Coming up with a solid solution is on our radar. I wonder if using Markdown may be the answer with header metadata for styles, something like:

---
title: My Keyboard Help
styles: my_keyboard.css
---

# Introduction

In the midst of my pursuit of life, liberty, and something else, I came up with this keyboard which vitally switches the position of the A and the B and in doing so ...

Pros:

  • It would compile down to html for the package build, and would mean a single source file for both site and package.
  • Markdown is lightweight, can embed html as needed
  • Styling is external to Markdown so should be able to inherit from welcome page structure and help.keyman.com more consistently
  • We use Markdown for metadata content already (README.md, etc)

Cons:

  • Markdown is less accessible for some users than exporting to HTML from Word
  • More infrastructure for us to build and maintain in the package compiler and IDE
  • No immediate and automatic pathway from welcome.htm to welcome.md, although tools do exist to help with transform.

All that said, this is a bug:

The CSS should be used. Could you write up an issue on this at New Issue · keymanapp/keyman:

  • CSS is not injected into the page when the documentation keyboard is embedded
  • .kmw-keyboard-gff_amharic class is not applied to the container div
  • Design issue: there are violations of the id attribute with multiple uses of the same id in different sections of the document. This particular one is hard to solve without shadow dom.

@joshua_horton FYI

6

Thanks @Marc, I will do the issue write-up today.

Tangentially related, I would like to show a different welcome.htm page in the keyman installer when the installation is on a mobile phone or tablet. The “welcome” info that I wrote for desktops is not so relevant for these other platforms, even misleading. Is there a special div class that can show/hide content based on the current platform?

thanks!

1 Like
7

You should be able to use CSS media queries to achieve this.

1 Like
8

One potential way to apply those queries may be seen at https://github.com/keymanapp/keyboards/blob/master/release/sil/sil_cameroon_qwerty/source/welcome/welcome.htm. It has two separate versions of the one page - one in French, the other in English.

As it is a rather large page, it may help to look for the <div> elements with the class="tab-content" attribute. There are two of them, and they’re the top-level elements for the two separate sections.

As long as only one of the two sections is visible at a time, the net effect should achieve what you want.

1 Like
9

A potential fix is now ready at https://github.com/keymanapp/keyman/pull/7694. Note that it still needs to undergo code review and testing before we publish it, of course.

1 Like
10

This topic was automatically closed after 14 days. New replies are no longer allowed.