Developing an MVC Component/Using the database
From Joomla! Documentation
Could I suggest an improvement.
Where it says
create two files called admin/sql/install.mysql.utf8.sql and admin/sql/updates/mysql/0.0.6.sql. They should both have the same content
it is at best unhelpful.
As I understand it, the SQL install route is to set up the component's tables "from scratch" and the update route is to incrementally add to that with subsequent releases. Therefore, the install file needs to always represent the full definition of the component's tables, incorporating any changes that the complete set of update files have introduced "along the way". That way a fresh install is always correct, and any update from any released version also works correctly.
If the component developer adds database functionality after releasing version without it, then what the line above says is required, otherwise it isn't.
So what should it say? Here's my suggestion (can we drop the "with your favourite..."? It was funny many years ago, but now...)
Create a file called admin/sql/install.mysql.utf8.sql as follows (SQL as before) Decide what version you want to give to this schema and create an update file, so if you want to call this schema version 0.0.6 create an update file admin/sql/updates/mysql/0.0.6.sql. If you have already released versions of your component, as we have simulated in this tutorial series, then this update file must have exactly the same content as the install file. If you have not, then it should be empty. As you make subsequent releases of your component the database install file must always contain the full schema and the update files only need to contain any changes you have made to the schema. The schema numbers don't have to relate to the component version numbers at all, Joomla takes your schema numbers from the names of the update files. That's why it is vital that there should be an initial update file, even if it's empty. If you want to keep your schema numbers in step with the component version numbers when you update your code but not the database schema, you simply include an update file to go with the new release number, and that update file, too, will be empty.
Yes, I think there are a lot of places in this tutorial series where the explanation in the text could be improved, and I wondering whether to do that when I was doing the videos, but in the end didn't tackle it. So if you're up for doing any of that, then that would be great!
I haven't found any group of people who are actively maintaining and overseeing the technical descriptions in these tutorial pages, so it's not like an arrangement where you submit a change request for modifications; as far as I can see, you just go ahead and make the improvements yourself.
As far as your specific suggestion, would you fancy writing a short section below the code snippet which answers the question "How does Joomla handle schema versions?" And then include there your comments above, and to align with the "important note" text which is there already? I think if readers understood how Joomla handles the updates, then they're in a better position to appreciate why they need to or should do certain things. What do you think?
Hi Robbie, thanks for that. It somehow seems rude to just go changing other people's pages, which is why I opened the discussion page.
Yes, I think adding a schema section would be a good solution. I'll make that as a change. Feel free to change it if you want.
Ok, I've made those changes, but have I done something wrong with the translate markup tags? The JDOC help about translation says they (eg they look a bit like "< ! - - T:12-- >" [I had to put in spaces for it to display here]) shouldn't be entered manually because the system does it, but having saved the page they don't seem to be there.
I added a wee bit at the start, really to expand on that "important note", and replace it. I changed a couple of small points in your text - it's not quite alphabetical order, and I don't think it's vital that there's an initial update file as Joomla will take 0.0.0 as the default. Are you ok with this all then?
That looks pretty good to me. I understand it much better now ;) I wasn't sure what to do with the important note, what you've done with it makes good sense. I'd say.
Do you know about those translation tags, the ones with "T:<number>" in them? Is it important that the new text doesn't have them?
I think what you did with the translate tags was correct - don't put the "T:<number>" in text which you write. I'm not 100% per cent sure what way that all works, but there is this brilliant lady called Sandra who seems to get notified when pages change, and sorts everything out with regard to translations, and that's when the numbered T tags get put in.
You're right Robbie, I'm never far ;)
All is fine in the page.
Mark, do not hesitate with edits. That's the nice thing with the JDocs wiki, when you see that something needs an edit, you are free to do it. And for the translation tags, I check every single edit so you don't have to worry about them. As Robbie said, just do not add the "T:<number>", the system adds them automatically.