Digital
Digital copied to clipboard
hneemann
Language support for external jar components
Loading components written in Java from an external jar file is supported, but I don't see any way to hook into/extend the language definitions, as they are loaded from a single xml file inside the Digital jar file as far as I understand.
It would be great if these external jar files could provide translations/language definitions for their own components, which would extend the Digital language files. Ideally they would be loaded implicitly by scanning the 'lang' folder in the external jar, but having to manually register them with the ComponentManager from your ComponentSource also sounds workable.
I wouldn't have expected anyone to implement a Java component and then also go to the trouble of doing that multilingual. :smiley: I will think about it.
Multilingual is one reason, but currently this line will also generate some undesirable output for output pins (as the elem_X_pin_Y lang key does not exist, but is requested, even though I call setDescription on the ObservableValue of output pin Y , which does show up correctly in the help menu/hover tooltip). Perhaps this can be suppressed with some minor code changes on my end, but I did not manage to do this in the short time frame I had to try and fix it.
It also seems like there is no clear way to set every field/description in Java, such as the element description, which will just be derived from the element name. It's a bit annoying having to dig through the source code trying to figure out what you can and cannot set, and from where this has to be done.
To give some context: we provide a jar file with some custom components to our students, which they have to use to complete an assignment. We would therefore like these components to have useful descriptions so that they can use the built in help menu, rather than having to consult external documentation on these components.
All students are expected to be able to understand English, so not having translations is not a major issue by any means (although we do have a considerable number of foreign students). Hardcoding a single language (English) would be acceptable, but that still doesn't resolve the issue of hardcoding in Java being seemingly less expressive than the language files. Ideally we don't want to have to provide a modified Digital version, keeping all our needs self contained in the external jar.
The course is already underway now, so any changes would be for next year. We can certainly live without it, but it would be a nice feature to have.
This example shows how to add a description to an input, and this line shows, how to add a description to an output.
If you also want to add a description to the component itself, you have to overload the getDescription method like this:
public static final ElementTypeDescription DESCRIPTION
= new ElementTypeDescription(MyAnd.class,
input("a", "and input a"),
input("b", "and input b")) {
@Override
public String getDescription(ElementAttributes elementAttributes) {
return "A simple AND gate which shows the implementation of a custom component";
}
}
.addAttribute(Keys.ROTATE) // allows to rotate the new component
.addAttribute(Keys.BITS); // allows to set a bit number to the component
It's a bit annoying having to dig through the source code trying to figure out what you can and cannot set, and from where this has to be done.
This is always necessary if you want to understand code that you have not written yourself. :smiley:
Multilingual is one reason, but currently this line will also generate some undesirable output for output pins (as the elem_X_pin_Y lang key does not exist, but is requested, even though I call setDescription on the ObservableValue of output pin Y , which does show up correctly in the help menu/hover tooltip).
The inputs of a component, which are set via the setInputs method, are the outputs of the components which output this signal. So it makes no sense to set a description to this values.
It therefore only makes sense to add descriptions at the outputs of a component.
The description of the inputs can therefore not come from the component itself, but only from the description of the component (ElementTypeDescription), which also contains the factory required to create the instances of the components.
Overloading ElementTypeDescription::getDescription completely escaped my mind, and works as expected. I also noticed that the language key messages were being generated due to me calling both setPinDescription and setDescription. I probably copy pasted setPinDescription from one of the original components and never bothered to double check what it does, to then add setDescription.
I probably should've taken a bit more time, but as I said my time was rather limited and I was mainly looking at how / hoping that the built in language system could be used. I still maintain that having one unified system that allows self-contained multilingual support would be preferable and more intuitive, but the use case of hardcoding a single language seems satisfied for us now. Perhaps if I can find the time this spring/summer I'll open a pull request, but at the moment I cannot really justify spending time on this sadly.
Thank you for your help and this amazing program. We switched to it this year, so it's our first time using it, but so far we've been very impressed and it has definitely been an improvement for us.
As this is the first year using this tool we wanted to keep our assignment and grading model roughly the same. In terms of components we could translate/find alternatives for most, except the following:
- We need a mix of a Register and an asynchronous D-Flip-flop, as we need an enable input for the clock, but also an asynchronous reset. The interface is also a bit different (e.g. negated reset input), because this is what the old tool used. This component was our biggest problem, as not having it like this would require significant redesign. We also wanted proper GUI integration (because students have to think about the required number of bits for instance), so supplying (generic) sub-circuits was undesirable.
- In our old tool we had 'bitwise' and/or gates, which would compute a bitwise and/or of each bit in the N bit input, finally producing a 1 bit output. So for a 4bit input number a3a2a1a0 the output for the bitwise or would be a3 OR a2 OR a1 OR a0. This allowed us to use these gates to check if a signal is all zeros or all ones. For small input bit counts this is easy enough to implement with splitter/merges and and/or gates, but for larger values (i.e. up to 32 in our case) it becomes unfeasible. Our workaround for this is to use the Comparator with a constant 0 or 1 second input, which is of course equivalent, but does not quite connect with our course material. Ultimately this is a minor issue, and we could easily adapt our material around this in future years.
Our grading model was largely set up for manual testing of assignments, which was very tedious and time consuming. We explored some options to automate this with our old tool, but it was all very rudimentary. With Digital we want to move towards (almost) fully automated testing, but for this we have 2 issues:
- Students have to develop an assignment based on an incomplete specification/template, so there is some variance here in terms of input/output names/existence/bitsize/etc. This prevents us from using the built in testing (command line) method as is.
- Our tests mostly check for the integration of the assignment as a whole, instead of testing specific subcomponents. We really need to revise the whole grading model to better test components/sub-circuits in isolation, especially if we can automate it, but as I said we are keeping the grading model from last year for now (as we want to see the impact of changing to this new tool before making more major changes).
We are still exploring ways to automate our grading model, but we did add one component that simply passes through the input value, unless we specifically overwrite the value from our testing program. This component allows us to observe a signal no matter where it is placed in the (sub)circuit, as like a probe it has a label (which we provided in the template). We can observe the value, check if it is correct or not, and then enforce the correct value so that the rest of the simulation/tests will continue with the correct value. It's basically a sort of register, but controlled through external Java code.
Hi @gixslayer. Do you have a web site for your course? I, too, am planning on using Digital for the first time in my fall course and I could definitely use lessons learnt from others. Thanks!
