Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a 'Tip of the day' feature #1636

Closed
TimLethbridge opened this issue Aug 27, 2020 · 5 comments
Closed

Add a 'Tip of the day' feature #1636

TimLethbridge opened this issue Aug 27, 2020 · 5 comments
Assignees
Labels
Component-UmpleOnline Related to the UmpleOnline website Component-UserDocs Related to the user manual Diffic-Med A non-trivial problem that may take over a week or may not be obvious how to fix or require analysis Priority-Medium This problem or request is likely to be of significant benefit if dealt with

Comments

@TimLethbridge
Copy link
Member

TimLethbridge commented Aug 27, 2020

Umple is getting quite powerful, and people are not taking the time to learn all of its features.

A 'Tip of the day' feature would contain a list of perhaps 200 quick hints, each displayable in a line or two, that would appear randomly on umpleonline startup. They would have pointers to relevant user manual pages for more information.

There should also be a button 'next tip' so people who want to explore tips could see them.

Perhaps this could be a user manual page, so they could be explored as a whole, and UmpleOnline would grab a line from the manual.

Example tip:

Did you know that in UmpleOnline you can refer to a class in another tab if you have a use statement refering to that tab?

This is medium difficulty because it would require careful work to come up with good tips.

@TimLethbridge TimLethbridge added Priority-Medium This problem or request is likely to be of significant benefit if dealt with Component-UmpleOnline Related to the UmpleOnline website Component-UserDocs Related to the user manual Diffic-Med A non-trivial problem that may take over a week or may not be obvious how to fix or require analysis labels Aug 27, 2020
@TimLethbridge TimLethbridge self-assigned this Aug 27, 2020
@TimLethbridge TimLethbridge added this to the Highest priority milestone Sep 1, 2020
@TimLethbridge
Copy link
Member Author

TimLethbridge commented May 5, 2021

Here are some suggested requirements. Being agile, we may want to change these.

I think we should have in the end up to 1000 tips.

They should appear on UmpleOnline in the same place as the aalertMessage.txt is displayed, but only if that is empty.

They should only appear on the first use of UmpleOnline each day (the first time there is no alert message). That means there would have to be a cookie to track that. See the other cookie handling features for settings and use the same mechanism.

The message should disappear quietly after about 2 minutes.

The message would always just be in one line. It would start. 'Tip: ' and be followed by the text of the message. It would end with 'Click for more'.

When clicked a box would appear (popping up, but not using browser popups). Hovering could also be used to display the text temporarily. The box would disapper if the user moved the cursor away from it. The box would almost always have links to the user manual, that would open the manual in a different tab.

The tips themselves would be in a user manual page, perhaps in its own 'group' called 'Tips of the day'. The tip titles could be h2 text blocks and the following html up to the next h2 could be the body of the tip.

Tips would be numbered, and the cookie used by users would track which tip the user has seen so far. Tips could be shown in order to ensure, so looking at the Cookie would tell Umpleonline which tip to grab next. It might be sensible for manual builder to pre-build a set of tip files ready for loading so searches of the manual don't have to happen every time

@TimLethbridge
Copy link
Member Author

TimLethbridge commented May 6, 2021

Some analysis in response to an offline question:

  • I wasn't expecting to be able to get away without writing or obtaining some new code. I don't think the tooltips type popups will be enough as they don't allow embedded links (I think). But many websites have little Javascript popups and there are likely several designs for this you can borrow (making sure their license allows it).
  • You are right that there is some design complexity here that may require requirements adjustment. The backend php is what currently finds the aAlertMessage. But until a user has actually loaded UmpleOnline, the Javascript won't be able to access the cookies that tell whether or not to display a TOTD and which one is next. So that would require, in turn, making a query. It might be that the javascript could send a query asynchronously to a new php script using Ajax that gets the n'th tip (and only does this if it needs to).

@TimLethbridge
Copy link
Member Author

TimLethbridge commented May 7, 2021

Sample tips of the day (early prototype). I think there should be three user manual files. I have drafted two below. h2 lines would appear following 'Tip:', and would be followed by 'Click for more'. Subsequebt lines pop up if the user clicks on this until the user moves the cursor out of the box, or hovers over it for a few seconds.


Important tips
Tips
noreferences
@@tooltip The top priority tips that will appear in the 'tip of the day' occasionally in UmpleOnline

@@description
<p>The tips below will appear as the tips of the day in UmpleOnline. You can read them all here.</p>

<h2>You can specify an association in a class or by itself.</h2>
<p>An association between two classes can be specified <a href="https://cruise.umple.org/umple/InlineAssociations.html">in either class (see an example in the user manual)</a> or <a href="https://cruise.umple.org/umple/IndependentlyDefinedAssociations.html">separately from either class</a>, using the <em>association</em> keyword</p>

<h2>You can generate code that ensures a class is a singleton (has only one instance)</h2>.
<p>If you specify <em>singleton;</em> in any class, then the <a href="https://cruise.umple.org/umple/SingletonPattern.html">singleton pattern</a> will be applied, meaning that there will only be one instance.</p>

<h2>Mark an attribute as lazy so it does not create a constructor argument</h2>.
<p>By default each attribute in a class becomes a constructor argument (along with associations that have a multiplicity of 1 at their other end).</p>

<p>If you want to avoid this, then add the keyword <em>lazy</em> before the association. The attribute will then be initialized with a null, empty or zero value.</p>

<h2>The default data type for attributes in Umple is String</h2>
<p>In Umple you can specify a data type before any attribute. But if you do not, then attribute will default to type <em>String</em>.

<h2>Core datatypes in umple include String, Integer, Boolean, Date, Time</h2>
<p>If you use the datatypes String, Double, Float, Integer, Boolean, Date or Time as the types of attributes, then Umple generates code tailored to the target language. For example, when generating Java, an Integer attribute is implemented as an int variable.</p>

<p>This is important to know since the methods Umple generates to access those variables will use the Java type. For example if you specify <pre>Integer id;</pre> in Umple, and generate Java, then the API will have a method with signature <em>setId(int)</em></p>

<p>Why does Umple then bother with an Integer datatype if it will be converted to int? Because we want key types to be independent of the target programming language.</p>


Secondary tips
Tips
noreferences
@@tooltip The second-priority tips that will appear in the 'tip of the day' occasionally in UmpleOnline

@@description
<h2>In the Umple User Manual, you can select Combined version at the bottom</h2>
<p>At the bottom-left of each user manual page is a link called <a href="https://cruise.umple.org/umple/UmpleUserManualCombined.html">Combined Version</a>. If you select this you can then use the built-in search function in your browser (control-f or command-f) to find information. Beware though that the combined version web page is extremely big. There is also a <a href="https://doi.org/10393/42044">pdf version of the manual</a> available.</p>

<h2>In Umple textual code the type comes before an attribute name, but in UML it comes afterwards</h2>
<p>Umple follows the Java, C and C++ approach of specifying the type of an attribute: The type is specified followed by the name. For example <pre>Integer count;</pre>. But class diagrams created in Umple follow the UML convention whereby the type follows the name of the attribute, with a colon separating them. So the above example in a diagram appears as: <pre>count: Integer</pre></p>

@TimLethbridge
Copy link
Member Author

TimLethbridge commented May 12, 2021

As of May 12th in branch Issue#1636_TOTD good progress is made. The image below is from when I download the branch.

I notice that there is a warning: Warning: Cannot modify header information - headers already sent by (output started at /Users/tcl/unix/github/umple/umpleonline/umple.php:132) in /Users/tcl/unix/github/umple/umpleonline/umple.php on line 215
And the content is not lining up as expected probably because of the warning. No actual tip appears yet.

The 'click for more' is also bringing up the content of a 404 page

For some reason when I build the manual, the Tips group shows up, but the actual pages within the group do not appear.

Screen Shot 2021-05-12 at 12 30 06

@TimLethbridge
Copy link
Member Author

TimLethbridge commented May 12, 2021

The reason the tips manual pages do not appear is that they don't have the .txt extension! You can use git mv to rename them

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Component-UmpleOnline Related to the UmpleOnline website Component-UserDocs Related to the user manual Diffic-Med A non-trivial problem that may take over a week or may not be obvious how to fix or require analysis Priority-Medium This problem or request is likely to be of significant benefit if dealt with
Projects
None yet
Development

No branches or pull requests

2 participants