Serve PDF restroom sign files in multiple languages

[DeeDeeG]

Scope / difficulty

Not too difficult.

Should just have to either:

1. Add some ruby code to serve the language of file the user is viewing, OR
2. Put restroom sign PDFs of all languages on the page, regardless of viewing language.

Also need to make .png preview images to go with the new PDF signs.

Also also, we possibly want to generate new QR codes to correspond to the new signs' URLs.

Impact

Allows the PDF restroom signs to be downloaded and used for a French-speaking audience, in addition to the existing English-language signs. Establishes a workflow for adding PDFs in additional languages down the line.

Proposal

Option 1: Add some Ruby code to logically "branch" which PDF is served based on the site language being served overall.

Pseudocode:

# This if statement should act as a list of the PDFs we actually have,
# other than English which acts as the fallback if we don't have a PDF specific to that locale.
IF locale = (fr OR [some-other-locale-we-actually-have-PDF-signs-for] OR [another-locale-we-have-etc.] ); THEN {
  = [$locale]_restroom_sign
}
ELSE {
  = EN_restroom_sign
}
ENDIF

Option 2: Add all PDF signs we have to the PDF signs page, so they may all be viewed by any viewer of the site, regardless of language.

This is just adding additional image <img> tags inside of link <a> tags (with Rails image/link helpers...) leading to the FR PDF files. No branching logic required in this case.

Addendum for either plan: We should make some .png preview images for the new PDF signs. We can generate QR codes for the new signs' URLS as well.

How to actually do this:

• To generate .PNG previews, I think just opening the PDF in a PDF viewer of some kind and forcing the dimensions to match the existing preview .pngs (300px x 228px)4 would do.

• To generate QR codes from a given URL, there are multiple tools online. 1 2 3 etc. They can be validated using the open-source ZXing decoder: https://zxing.org/w/decode.jspx

(e.g. one of our current QR codes: https://zxing.org/w/decode?u=https%3A%2F%2Frefugerestrooms.org%2Fassets%2Fqrcode-sign-with-handi-130dbfcb039cd8374e68fc3834cae54624b2a291a3a096021aef0850beec58f1.png
has the "URI" data type, and actually leads to "http://refugerestrooms.com/rr-sign-with-handi.pdf". Maybe we should update the old ones to use HTTPS and go to our .org URL, rather than the .com one?

• See proposal above for how to add the signs themselves to the haml source of the restroom signs page.

[sophiabonsu]

Hi @DeeDeeG ! I'm interested in working on this!

[DeeDeeG]

Hi @sophiabonsu, sorry I did not notice your comment! My email inbox is overflowing!!

I will take a look at this, if you are still interested, and I will try to give some direction on how to proceed.

(Please do leave another comment here if you are still interested.)

[sophiabonsu]

Hello @DeeDeeG !!! I’m still very interested in working on the issue ! I’m having trouble with the installing the development environment. I installed the docker and my laptop has been much slower since. It’s an older MacBook(2009), so I suppose that the problem. Any additional guidance would be greatly appreciated.

[DeeDeeG]

Hi again, @sophiabonsu.

First thing, I think it would be good to ensure you have a workable development environment, so that is what I will comment about first.

• Regarding Docker, if you have "Docker for Mac" then that should be reasonably fast. But only recent machines can run this. If you have "Docker Toolbox", that is based off of VirtualBox and is expected to be somewhat slow.

  • For performance with Docker Toolbox, I would just suggest to close any applications or browser tabs you don't need, since VirtualBox uses a lot of system resources. If you have any difficulty with Docker and want help with getting past error messages or performance issues in Docker, I can try to help with that.

• It would probably give you better performance if you work outside of Docker. (Which involves installing Ruby and Rails on your Mac). If you are interested in this and want some pointers, I can help with that. (I have thought about documenting how to do this before, but I haven't quite gotten around to it yet.)

  • (Basically, for working outside of Docker, I would suggest installing rbenv. Then you should be able to cd to this project's repo, and install all the dependencies: run rbenv install --verbose to install our project's current version of Ruby (2.5.7) (rbenv compiles Ruby from source, which takes a long time. I prefer to do rbenv install with the --verbose flag, so I can see progress being made, and see any error messages that might come up), run gem install bundler -v "<2" and bundle install to install this project's dependencies.)
    • If you run rbenv install but get the error: rbenv: no such command 'install', then you need to install the ruby-build plugin, which is pretty easy. Just run this: git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
  • (Edit: You also need to have NodeJS installed -- you can download it here: https://nodejs.org/en/download/)
  • (Edit: PostgreSQL must also be installed. See this guide: https://launchschool.com/blog/how-to-install-postgresql-on-a-mac)
  • (Edit: forgot to mention: Finally, run rails s -b 0.0.0.0 in the project root directory (refugerestrooms folder) to start the Rails server. You should be able to visit the address localhost:3000 in a web browser on the same computer and see the app running. This should show any edits or changes you make to the code any time you refresh the page in your web browser.)

Either using Docker or working outside of Docker is fine, whichever you prefer.

---

Regarding technically fixing this issue (#563):

This should be the only file we need to edit to make PDF signs available in multiple languages: https://github.com/RefugeRestrooms/refugerestrooms/blob/develop/app/views/pages/signs.html.haml

It is written in Haml, which is a language designed to make HTML more concise, and the syntax is more like a programming language than HTML. But it is mostly just HTML written in a different coding style. (It gets interpreted and turned into HTML before it is sent to the site visitor's browser). It allows you to embed Ruby code (with the equals sign = ) as well. The ruby code runs, and produces HTML code that is placed in the part of the page where the equals sign = was.

We can dynamically choose which language of restroom sign PDF to put in the page based on the visitor's locale setting (en for English, fr for French, es for Spanish, etc.) Or we can just include the English signs like we already have, and add links to the signs/PDFs in other languages (Right now we just have English and French),

I would suggest looking at the page's haml code and the Restroom signs page at refugerestrooms.org (https://refugerestrooms.org/signs) to compare, and try to see where the parts of the haml page show up in the final HTML document.

The haml code includes some Rails framework helpers, especially for embedding images files and hyperlinks. They looked tricky to me at first, but they made sense to me eventually. I hope you will also find it makes enough sense to work with it.

---

Strategies for implementing this:

There are two ways to go about it:

1. Link to PDF signs in all languages we have (currently English and French) all the time, without dynamically changing the page based on the user's locale

(this would be simplest)

Just insert a hyperlink into the haml markup, linking to the French PDF signs under the existing links (to the English signs). Eventually it might be nice to make a preview PNG image of the French signs like we have for the English signs.

2. Link to the French PDF if the user is browsing the French page, otherwise use the English PDFs.

For this approach, it makes sense to me to program the page to get the user's locale (reading the Rails Internationalization API by reading the value of I18n.locale) and based on that, link to the appropriate language of PDF signs.

Lastly a note: I myself am not an expert programmer (I'm self-taught) but I think the level of programming will not be extremely difficult for this task. If you need info about Haml or Ruby, I am happy to link to documentation or give my own explanation of certain concepts, so if you need any help with the programming part, or if the structure/tech of this project/repo is unclear, I am happy to answer any questions. I enjoy teaching, and time permitting I will be glad to answer questions about anything that comes up.

[DeeDeeG]

That's a pretty sweeping overview, but if you have anything more specific you want answered, I can do that. Hope it's helpful (and not overwhelming).

Best Regards,

- DeeDeeG

[DeeDeeG]

For more help with Haml (I think this would be the trickiest part for someone not familiar with it) here are some resources:

• https://haml2erb.org/
  • Converts haml to HTML

Here's our Haml source for the restroom signs PDF page... turned into HTML with embedded Ruby code. (Click this text to expand/give this text keyboard focus and press "Enter" to expand.)

<div class="text-padding">
  <h1>
    <%= t('.title') %>
  </h1>
  <p>
    <%= t('.intro') %>
  </p>
  <div style="float:left;width:45%;text-align:center;margin:0 15px;">
    <h3>
      <%= t(".head-accessible") %>
    </h3>
    <a href="/rr-sign-with-handi.pdf">
      <%= image_tag('rr-sign-with-handi.png', :style => "padding:15px;border:1px solid #444;") %>
    </a>
    <p>
      <%= t(".download") %>
    </p>
    <%= image_tag('qrcode-sign-with-handi.png', :width => "200") %>
  </div>
  <div style="float:left;width:45%;text-align:center;margin:0 15px;">
    <h3>
      <%= t(".head-non-accessible") %>
    </h3>
    <a href="/rr-sign-no-handi.pdf">
      <%= image_tag('rr-sign-no-handi.png', :style => "padding:15px;border:1px solid #444;") %>
    </a>
    <p>
      <%= t(".download") %>
    </p>
    <%= image_tag('qrcode-sign-no-handi.png', :width => "200") %>
  </div>
  <div style="clear:both;">
    <br/>
  </div>
</div>

Should be easier to read, to understand how the Haml turns into HTML.

---

Ruby code explanations:

• All of the = t(".something") lines are pulling in our translation strings from here: https://github.com/RefugeRestrooms/refugerestrooms/blob/develop/config/locales/en/signs.en.yml
  • The Rails I18n ("Internationalization") API is briefly explained here: https://github.com/RefugeRestrooms/refugerestrooms/blob/develop/config/locales/about_translations.yml
• image_tag is a feature (provided by the Rails ActionView API) to turn a shorthand input string into a full HTML image tag. We use this because it integrates well with Rails' other features; Rails can automatically keep our image tags in order when we change our use of other Rails features.
  • Documentation for the image_tag feature of the Rails API: https://api.rubyonrails.org/classes/ActionView/Helpers/AssetTagHelper.html#method-i-image_tag
• Maybe you already know this, maybe not, so I will explain it here: Rails ("Ruby on Rails" is the full name, "Rails" is the nickname) is a web development framework for programming web applications in Ruby. It comes with "strong defaults" that work out of the box. It's easy to create the default Rails app by running rails new your-app-name-here. You can tweak things from there, and much of what you expect a webapp to do has already been programmed into Rails, or components (called gems) that are meant to work with Rails.

---

• http://haml.info/docs.html
  • More Haml documentation
  • http://haml.info/tutorial

    • The tutorial is a great place to start if you aren’t familiar with the language. It goes over the basic syntax for elements, as well as how to embed Ruby in the document.

  • http://haml.info/docs/yardoc/file.REFERENCE.html

    • The Haml reference is the most complete documentation for Haml. It contains information on every language feature, all the options, and how to install it as a Ruby gem.

  • http://haml.info/docs/yardoc/file.FAQ.html

    • If you’re having trouble or have a question, try the FAQs. If you don’t find what you’re looking for there, ask the Haml community.

[DeeDeeG]

Hmm, I have to correct my earlier comments about setting up the development environment outside of Docker. I mis-remembered how far I was able to get testing outside of Docker. My apologies for not testing the steps in my comment.

The webapp does not seem to work at all outside of Docker if PostgreSQL is not running locally. Also, NodeJS must be installed, or Rails will not run.

Here is a proper explanation posted by another contributor to Refuge Restrooms some time ago: #413 (comment) (Since this was posted, we have added NodeJS to our web app, so you must also install NodeJS. It can be downloaded and installed from here: https://nodejs.org/en/download/ We use NodeJS (LTS) v12, but v13 should also work -- the version you download should not matter.)

[DeeDeeG]

I got an email notification of an issue you had run into.

I can look into it, but I'm not familiar with that particular error message. Hopefully it has gone away by now/been resolved?

---

WebPacker is a sort of low-level, automated thing. I don't think this project has changed the configuration/setup of WebPacker in a bit, so it should be working. In order to make sure the docker image built correctly, I would suggest to try rebuilding the docker image with something like docker-compose build...

(If it finishes rebuilding very quickly, then it is using a cached version of a previous docker-compose build run. In that case, here are some good-to-know commands for cleaning up docker builds...)

Essential docker cleanup commands:

• docker images will list images you have downloaded (ruby, postgresql) and built refugerestrooms_web).
  • docker rmi [image-name-here] or docker rmi [image-hexadecimal-id-here] will delete that image.
    • (docker rmi might fail if the image is currently running. If so, open a new terminal (or "docker quickstart terminal" if using Docker Toolbox), navigate to the refugerestrooms project folder on your mac, and run docker-compose down to shut down the refugerestrooms images.)
  • You can list multiple images for deletion in one command if you like: docker rmi [image-1] [image-2] [image-3] and so on.

More-advanced stuff:

• docker system df will show you all artifacts/stuff you have on your system from your use of docker, grouped by type, and in terms of how much disk space they are using.
• docker system prune will remove most types of data, so long as they are not currently up and running or in use.
  • docker system prune --volumes will also remove temporary overlay "volumes," including the db/database/postgresql volume that spins up when you run docker-compose up for this project... As long as the db has been properly shut down first with docker-compose down.