Re: Common library (feedback needed)

We are considering adding a lua-pgc library with common LUA functions that any script can use. As a proof of concept I implemented

PGC_GeocacheTypeIcon(type)

today (not available in production). It would return html to show a geocache type icon, with proper title and such.

I am looking for suggestions for other very common functions that are identical between many scripts, that we could adopt into such library. I am thinking we could make a list here.

• PGC_GeocacheTypeIcon(type)
• PGC_GeocacheSizeIcon(size)

We are also looking into creating css rules to help with styling. With two reasons.

1. Make it easier to style html output.
2. Make the output look more unified between the scripts.

The idea is here to be able to do things like

<p class="bg-success">...</p>

to get a "green" back background for example. The goal is that no challenge checker scripts should rely on css rules used by the site itself since they might not persist over updates of the site.

Some suggestions I thought of. Other suggestions are welcome.

• Coloring text.
• Coloring background.
• Bordered table.
• Smaller text.
• Monospaced text.
• Striped tables.
• Check icon.
• Stop icon.

The more data we have before a release, the better naming conventions we can start with.



Edited 2 time(s). Last edit at 08/10/2025 04:16PM by magma1447. (view changes)

I'm going to be a Debbie Downer here...

I'm not sure how many truely "new" scripts are written anymore? I'm not sure if I see the value of a common function library, since the most applicable use case would be to retrofit existing scripts (which, presumably are already working with type/size icons).

Kind of the same argument for a common CSS.

Over 1000 scripts created this year. :)

I also think quite a few script owners are maintaining their scripts to the level that they wouldn't mind reducing the amount of code by using such functions. But I could be wrong.

But based on the feedback here, it doesn't seem like many care about it. We have been getting pushed about this multiple times though, by more than one script developer.

1000 scripts created this year I think doesn't tell the whole story... I would guess that pretty much all of those get maximum 1 tag, and I'd bet a bunch get 0 (although, it's "hard" for me to get stats on that). If that's the case, having a common function library would only standardize the look for a very few number of new challenges checkers, and that assumes that the new scripts use them. My assertion is also that most of the "hardcore" volunteers are tagging the same set of 10-20 scripts (because, we're coming close to maximum coverage of the available challenges given the guidelines, and there aren't many grandfathered challenges left), so retrofitting the massively tagged scripts would go much further in the effort for standardization.

I would say a much more helpful feature would be allowing script writers could include other any other .lua file. I'd use this for example, if there's a one-off challenge that for some reason can't be handled by my uber script, I could include basically all its functionality and just implement the custom logic. Because when this happens now, I basically just copy the uber script and replace the "main" portion, making the remaining (unused) .lua much larger than it needs to be. It would also lower the bar for new scripts, because many of those functions are pretty broadly applicable (eg. post-database-query filtering, list/hash manipulation, etc). You could also use this to "embed" data in a new minimal script, instead of the kind of archaic way of emailing you a .json file :)

This is less about standardizing output and actually more about separating output from Project-GC. Last week’s release upgraded from Bootstrap 3 to Bootstrap 5, breaking a bunch of scripts relying on Bootstrap 3 CSS classes. Rather than encouraging scriptwriters to adjust their scripts to Bootstrap 5’s CSS classes, we’d much rather implement a common library so that scriptwriters don’t have to update their scripts a second time when Project-GC decides to redesign in “?” years’ time.

Since 2020, about 1600 scripts are created annually.

I'm aware of these functions that get copied quite a bit between scripts:
- testing for attributes / bit testing
- printing filters configuration in the output

For my scripts I have these helper functions, but I'm not sure if they would be useful for anybody else:
- Count() that works regardless whether you pass an indexed or an associative table
- converting keys from associative table to indexed table
- converting values from associative table to indexed table
- appending one indexed table to another one
- get country with most finds
- dump table to debug log

In my opinion at least some of those should be worth having in a common library.

There has been some progress on this task and I am hoping for a release next week. When the release has been made I will first have a single person test it out. After that I will post in the News section on this forum about it. When that has been live for some time I get back to you and ask for snippets for these I think:

- Count() that works regardless whether you pass an indexed or an associative table
- converting keys from associative table to indexed table
- converting values from associative table to indexed table
- appending one indexed table to another one
- dump table to debug log

Other snippets from others will be welcome. I think the functions will be made available with something like this:

`PGC.Contributed.*`, `PGC.Contr.*`, `PGC.Common.*`, `PGC.Util.*`
`PGC.PUB.*`, `PGC.CL.*` (Community Library), `PGC.CC.*` (Contributed Code)

Name suggestions are welcome since I don't think any of them are perfect. I want it to say that it's from the community. Therefore I currently lean towards CL. I also want it to be decently short (easy/fast to type) of course.

I also expect there to be LUA code reading those attribute values from the GetFinds data. Those functions would probably be worth having in a a library.

I still think that instead of a narrow library provided by the service, it would be way more beneficial to allow importing of other scripts... eg. just implement PGC.LoadScript(xxxx), where xxxx is the script number. That way, you're not just allowing anything to be imported, but you're also not explicitly dictating what the common functionality is.

For example, in my script (er scripts), I have all of the above functions, and a whole bunch more that could be considered "general purpose". If the ones provided in the common library don't exactly match what I am already using, I doubt I'm going to update my scripts to use them... or even if I write new scripts to use them, because I'm more comfortable with what I use already. I also assume there's no way for me to actually *see* what the implementation actually is - so if there's debugging to be done, that's also not possible if I use those functions. It also depends on you updating the implementations / functions, whereas, if it were just an import mechanism, then any script-writer could update or add new common functions.

I like the idea to have this in another script, so that everybody can still see the source code and to have more flexibility to easily extend the functionality when needed or to use different kinds of libraries as per personal preference.
I think the library script could look something like this:

local Utils = {}

function Utils.Foo()
  ...
end

function Utils.Bar()
  ...
end

return Utils

And the checker scripts could then require it to use those functions, i.e. like

local utils = require("Utils")

utils.Foo()
utils.Bar()

Details how to require the script of course depend on how you store them on your server.



Edited 1 time(s). Last edit at 09/19/2025 11:34AM by KaiserVonChina. (view changes)

That won't work with the sandbox. If that (require) worked you could include any file on the filesystem. That's why this is sandboxed and not all LUA functions are available. So whatever is made here will always be included. Therefore it will most likely belong under the "PGC namespace", to avoid collisions with anything else.

bmuzzin Wrote:
-------------------------------------------------------
> I still think that instead of a narrow library
> provided by the service, it would be way more
> beneficial to allow importing of other scripts...

While it's not a bad idea it's a lot more work to do it properly, depending on how it would be done. A correctly implemented way to do that would be about a thousand more times work than just adding more methods into the Sandbox.



Edited 1 time(s). Last edit at 09/23/2025 05:34AM by magma1447. (view changes)

I don't know PHP at all... But from what I see, it should be very little work...

You can expose any sandbox methods you want (just like any of the PGC functions that currently exist). So say "PGC.LoadScript(X)" It looks as though inside PHP, you could do Lua loadString and put that into the currently executing script. All you'd have to do is have the PHP open the file of script X, pass that to PHP's Lua loadString, and viola. The only question mark is how to locate that script in PHP, but I assume that's not that hard. It'd be up to the loading script to know what namespace the loadString gets put into... So it could either have an internal package, or, alternatively you could put a parameter in the LoadScript function.

Any progress on the CSS rules yet?

The most painful change since your design update are the missing borders for table cells.
Currently the only option is to add something like style="border: 1px solid black;" to every single <TD> and <TH> element, which massively blows up the HTML output.
Would be nice if I could add a class just once to the table element instead to get a table that has a border for its cells.

This was actually merged into `master` ~2 days ago, so it will go live with the next release.

It's not documented anywhere yet, but you'll find the css files at `/css/pgc-challenge-checkers.css` when released. Class `table-bordered` should solve the border thing, once releaesd.

Is there some sort of padding include? It makes the tables huge... I applied it, but reverted it, because it's harder to read.

Since the code isn't released yet, whatever you see now is irrelevant. The css file isn't there yet.

Okay, I see pgc-challenge-checkers.css has now shown up... and the look of everything has changed... and not for the better wrt tables - I think is it because of the padding on th/td?

#cc_HtmlFeedback table td,
#cc_HtmlFeedback table th {
    padding: 0.25rem 0.5rem; /* Condensed padding like Bootstrap 3 table-condensed */
    vertical-align: top;
    border: none; /* No borders by default */
}

I noticed as well that the tables in my output are more widespread than before and take up more screen space than before.
I'd prefer to have no padding by default.
You can keep padding as an independent class that can additionally be set when really desired.

Examples please. There is nothing we can do if you don't provide the needed information.

I have a reproduction case now. This is not how it looked months ago. Something must be missing.

I have updated https://project-gc.com/forum/read?6,117489,117491#msg-117491

There are three new css classes:
[*] table-condensed
[*] text-smaller (smaller than text-small)
[*] text-monospace-narrow (uses a narrower font than the text-monospace)

Does it work as you expect with class table-condsensed? Otherwise I would need links.

Yes, using class table-condensed makes the table look compact again.

I'll play around with the new features a bit more and let you know in case I observe something unexpected.

KaiserVonChina Wrote:
-------------------------------------------------------
> I'll play around with the new features a bit more
> and let you know in case I observe something
> unexpected.

:thumbs up:
(no such emoji, but you get the point)

https://project-gc.com/Challenges/GCBGCK5/109425
Venn diagrams are totally messed up.

https://project-gc.com/Challenges/GCBC2M8/109329
https://project-gc.com/Challenges/GCBHYBK/111215

The calendar/DT grids are still really huge compared to what they used to be (even using table-condensed). Unfortunately, there's no way for me to get the old behavior back, to see exactly what it used to look like.

If we're striving for consistency, could you just make available table styles for "jasmer" / "fizzy" / "calendar", exactly like they appear in the profile stats, and just leave everything else to what it was before?

A fast look at https://project-gc.com/Challenges/GCBGCK5/109425 shows uses of style and images with set width of 900x850px. I am not sure how those images can be expected to fit. In all honesty, it's very hard for us to make sure that checker output using this amount of customized styling keeps working. But that is also the point of removing inheritance from the site itself and more or less go back to web browser defaults.

I don't know what you want with the second and third to be honest. You don't appreciate the responsive design that it uses its full width? I would say that they look as one should expect. But if you want them less wide, you can set style width=auto; on the table element. Or a fixed width if you prefer. Using all width available is the common standard though.


> and just leave everything else to what it was before?

That is not possible. Challenge checkers were using CSS that they shouldn't. We must be able to change CSS of the website itself without changing how third party HTML renders. Our upgrade of Bootstrap proved this quite well. Many challenge checkers started breaking because users relied on the site's own CSS. Which is understandable, but not reasonable.

We are doing this to prevent that these things should happen in the future. Disconnecting the challenge checker output formatting from the site itself.



Edited 2 time(s). Last edit at 01/30/2026 08:30PM by magma1447. (view changes)

The venn diagrams are a travesty of table usage, I'll admit that... But, we can't (or at least we couldn't) use the SVG element. If that's changed with the bootstrap upgrade, I can convert it to be an SVG, because that would look waaaay better and be much easier to manage.

I mean, maybe it's my programmer esthetic, but I prefer very little blank space... I mean honestly, the grids in the profile stats are much more compact and visually pleasing to me, which is why I suggested exposing those styling to the checkers, and then it would be consistent with the rest of the site (and adapt, if the site changed).

I could just apply styles to every table/tr/td, but the issue there is that there is an HTML output limit, and when you do outputs of (for example) all attribute calendars, it already runs up against that. Adding style elements to every element in a table will get us there much more quickly. But unfortunately, we have no ability to author any CSS, we just need to rely on what's available... so not sure what the solution here is.

Profile stats has a fixed width or ~750px to fit the Geocaching profiles at Geocaching.com. Otherwise it wouldn't be that thin.

I am not really sure what exactly you want us to do to make it easier for you to get a table that suits your need here. We can render a table that looks in a certain way, but then it would be empty. We could make a super specific CSS, but then it would require that the table was created exactly as expected. We could make a callback function that creates the HTML and needed CSS which took several data inputs, but that feels out of scope.

This is a perfect case for what exactly this thread is about. Create the function in LUA once, and then put it in a common library for everyone to use. If such function is made, and well thought through, we could help out by making CSS rules that could replace style attributes. As you say, it makes no sense to add a certain style to every single `td` for example. That's better covered with a css class on the `table` or `tr`.